@deepdockai/cli 0.0.0-stage → 1.0.0

package/skill/references/clients/deepdock.ts

@@ -0,0 +1,244 @@
+/**
+ * Minimal Deepdock /v1 client. No dependencies beyond fetch (Node 18+, Bun, Deno, browsers).
+ *
+ * It does the four things the OpenAPI document cannot tell you: the bearer header, the envelope
+ * unwrap, the Idempotency-Key header with replay detection, and a typed error carrying the code.
+ * Everything action-specific (paths, fields, methods) comes from the live OpenAPI document.
+ */
+
+export class DeepdockError extends Error {
+  constructor(
+    readonly status: number,
+    readonly code: string,
+    message: string,
+    readonly requestId?: string,
+    readonly systems?: string[],
+  ) {
+    super(message)
+    this.name = 'DeepdockError'
+  }
+}
+
+/** No answer, or not Deepdock's envelope (timeout, network, a proxy page): a write may still have landed. */
+export class DeepdockTransportError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'DeepdockTransportError'
+  }
+}
+
+type ErrorBody = { code: string; message: string; requestId?: string; systems?: string[] }
+type Envelope<T> = { data: T } | { error: ErrorBody }
+
+export type Page<Item> = { items: Item[]; nextCursor: string | null }
+export type WriteResult<T> = { data: T; replayed: boolean }
+export type WriteMethod = 'POST' | 'PATCH'
+
+export type Device = {
+  id: string
+  label: string | null
+  hostname: string
+  os: string
+  clientVersion: string
+  status: 'connected' | 'offline' | 'inactive'
+  lastSeenAt: string | null
+  claimedAt: string
+  systems: string[]
+  updateAvailable?: string
+}
+
+export type ActionState =
+  | { state: 'active' }
+  | { state: 'paused'; reason: string; pausedAt: string }
+
+export type DeviceSystem = {
+  label: string | null
+  version: string
+  status: 'running' | 'stopped' | 'missing'
+  actions: Record<string, ActionState>
+}
+
+export type DeepdockOptions = {
+  base?: string
+  /** Above Deepdock's 20 s device wait, so you receive device_offline instead of timing out first. */
+  timeoutMs?: number
+  fetch?: typeof fetch
+}
+
+export class Deepdock {
+  private readonly base: string
+  private readonly timeoutMs: number
+  private readonly fetchImpl: typeof fetch
+
+  constructor(
+    private readonly apiKey: string,
+    { base = 'https://api.deepdock.ai', timeoutMs = 30_000, fetch: fetchImpl = fetch }: DeepdockOptions = {},
+  ) {
+    this.base = base.replace(/\/$/, '')
+    this.timeoutMs = timeoutMs
+    this.fetchImpl = fetchImpl
+  }
+
+  private async send<T>(
+    path: string,
+    init: { method: string; headers?: Record<string, string>; body?: string },
+  ): Promise<{ data: T; headers: Headers }> {
+    let res: Response
+    try {
+      res = await this.fetchImpl(`${this.base}${path}`, {
+        method: init.method,
+        headers: { Authorization: `Bearer ${this.apiKey}`, ...init.headers },
+        body: init.body,
+        signal: AbortSignal.timeout(this.timeoutMs),
+      })
+    } catch (err) {
+      // TimeoutError from AbortSignal.timeout, AbortError, or a network TypeError.
+      throw new DeepdockTransportError(`no answer from Deepdock: ${(err as Error).name}`)
+    }
+    let body: Envelope<T>
+    try {
+      body = (await res.json()) as Envelope<T>
+    } catch {
+      throw new DeepdockTransportError(`non-JSON answer with status ${res.status}`)
+    }
+    if (body !== null && typeof body === 'object' && 'error' in body) {
+      const { code, message, requestId, systems } = body.error
+      throw new DeepdockError(res.status, code, message, requestId, systems)
+    }
+    if (body === null || typeof body !== 'object' || !('data' in body)) {
+      throw new DeepdockTransportError(`unexpected body with status ${res.status}`)
+    }
+    return { data: body.data, headers: res.headers }
+  }
+
+  private actionPath(deviceId: string, system: string, action: string): string {
+    return `/v1/devices/${encodeURIComponent(deviceId)}/systems/${encodeURIComponent(system)}/actions/${encodeURIComponent(action)}`
+  }
+
+  /** Runs a read action. Pass `nextCursor` back as `cursor` for the next page. */
+  async read<Item>(
+    deviceId: string,
+    system: string,
+    action: string,
+    input: Record<string, string>,
+    page: { limit?: number; cursor?: string } = {},
+  ): Promise<Page<Item>> {
+    const query = new URLSearchParams(input)
+    if (page.limit !== undefined) query.set('limit', String(page.limit))
+    if (page.cursor !== undefined) query.set('cursor', page.cursor)
+    const suffix = query.size > 0 ? `?${query}` : ''
+    return (await this.send<Page<Item>>(`${this.actionPath(deviceId, system, action)}${suffix}`, { method: 'GET' })).data
+  }
+
+  /** Reads every page of a read action, in order. */
+  async *readAll<Item>(
+    deviceId: string,
+    system: string,
+    action: string,
+    input: Record<string, string>,
+    limit?: number,
+  ): AsyncGenerator<Item> {
+    let cursor: string | undefined
+    do {
+      const page = await this.read<Item>(deviceId, system, action, input, { limit, cursor })
+      for (const item of page.items) yield item
+      cursor = page.nextCursor ?? undefined
+    } while (cursor !== undefined)
+  }
+
+  /**
+   * Runs a write action. `method` comes from the action index or the OpenAPI document; `input`
+   * values are all strings. `idempotencyKey` is new per intended write and the same on every retry.
+   */
+  async write<Result>(
+    deviceId: string,
+    system: string,
+    action: string,
+    method: WriteMethod,
+    idempotencyKey: string,
+    input: Record<string, string>,
+  ): Promise<WriteResult<Result>> {
+    const { data, headers } = await this.send<Result>(this.actionPath(deviceId, system, action), {
+      method,
+      headers: { 'Content-Type': 'application/json', 'Idempotency-Key': idempotencyKey },
+      body: JSON.stringify(input),
+    })
+    return { data, replayed: headers.get('Idempotent-Replayed') === 'true' }
+  }
+
+  /** The device's systems and each action's state. A live call to the device: can answer device_offline. */
+  async systems(deviceId: string): Promise<Record<string, DeviceSystem>> {
+    return (await this.send<Record<string, DeviceSystem>>(`/v1/devices/${encodeURIComponent(deviceId)}/systems`, { method: 'GET' })).data
+  }
+
+  /** Claims a device by the pairing code it shows. Keep the returned `id`. */
+  async pair(code: string, label?: string): Promise<Device> {
+    return (
+      await this.send<Device>('/v1/devices', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(label === undefined ? { code } : { code, label }),
+      })
+    ).data
+  }
+
+  async release(deviceId: string): Promise<void> {
+    await this.send<unknown>(`/v1/devices/${encodeURIComponent(deviceId)}`, { method: 'DELETE' })
+  }
+}
+
+/* ------------------------------------------------------------------------------------------------
+ * Pending writes: one attempt against persisted state. Persist the row BEFORE the first send, so a
+ * crash between send and answer cannot produce a second record under a new key. A job retries rows
+ * left in `sent` with backoff (seconds, then minutes, for hours if the device stays offline).
+ * ---------------------------------------------------------------------------------------------- */
+
+export type PendingStatus = 'pending' | 'sent' | 'done' | 'unknown' | 'refused'
+
+export type PendingWrite = {
+  /** 8 to 128 chars of A-Z a-z 0-9 _ -, stable per business event. */
+  key: string
+  deviceId: string
+  system: string
+  action: string
+  method: WriteMethod
+  input: Record<string, string>
+  status: PendingStatus
+  conflictRetries: number
+  result?: unknown
+  requestId?: string
+  refusedCode?: string
+}
+
+/** A running write finishes within seconds; beyond this, treat a conflict as an unknown outcome. */
+export const CONFLICT_RETRIES = 5
+
+const RETRY_SAME_KEY = new Set([
+  'device_offline',
+  'target_busy',
+  'temporarily_unavailable',
+  'internal_error',
+  'action_paused',
+  'system_unavailable',
+])
+
+/** One attempt; returns the row with its new status. The caller persists it. */
+export const attempt = async (dd: Deepdock, row: PendingWrite): Promise<PendingWrite> => {
+  try {
+    const { data } = await dd.write(row.deviceId, row.system, row.action, row.method, row.key, row.input)
+    return { ...row, status: 'done', result: data }
+  } catch (err) {
+    if (err instanceof DeepdockTransportError) return { ...row, status: 'sent' }
+    if (!(err instanceof DeepdockError)) throw err
+    if (RETRY_SAME_KEY.has(err.code)) return { ...row, status: 'sent', requestId: err.requestId }
+    if (err.code === 'idempotency_conflict') {
+      return row.conflictRetries < CONFLICT_RETRIES
+        ? { ...row, status: 'sent', conflictRetries: row.conflictRetries + 1 }
+        : { ...row, status: 'unknown' }
+    }
+    if (err.code === 'outcome_unknown') return { ...row, status: 'unknown', requestId: err.requestId }
+    // invalid_input, target_rejected, action-specific 422s, not_found, check_failed, auth and
+    // resolution codes: nothing was written. Fix the cause; a changed input gets a new key.
+    return { ...row, status: 'refused', refusedCode: err.code, result: { message: err.message } }
+  }
+}

package/skill/references/concepts.md

@@ -0,0 +1,95 @@
+# Concepts
+
+The words the API, the CLI and the dashboard use. Use them unchanged in code and copy.
+
+## Organisation and partner
+
+You, the partner, are an **organisation** in Deepdock. Everything you own (keys, devices,
+incidents) is scoped to it. Members of your organisation see the dashboard; admins manage keys,
+release devices.
+
+## Keys
+
+- **API key** (`ddk_live_` on production; a `ddk_test_` key belongs to a test deployment): your product's
+  credential on `/v1`. It runs actions, pairs and releases devices, and reads incidents. Created by an
+  admin in the dashboard (shown once) or from the CLI, which writes it straight into the app's env
+  file, keeps no copy and shows it to nobody; optionally expiring.
+- **CLI sign-in**: one person's credential, used only by the `deepdock` CLI after `deepdock auth
+  login`. Valid 90 days. It manages (devices, keys, listing systems) and never runs an action.
+
+Details: [auth-and-keys.md](auth-and-keys.md).
+
+## Device
+
+The Deepdock client installed on the customer's Windows PC next to their system. It connects
+outwards to Deepdock; nothing in the customer's network is opened to the internet. A device is
+identified by a UUID (`id`), carries a `label`, `hostname`, `os`, `clientVersion`, `status`
+(`connected`, `offline` or `inactive`), `lastSeenAt`, `claimedAt` and the `systems` it reported.
+
+- **Pair**: claim a device for your organisation with the 6-character code it shows while unpaired.
+- **Release**: `DELETE /v1/devices/{deviceId}` gives the device back; it shows a new code.
+- **Inactive**: a paired device that has not connected for 7 days. It stays yours and is active again
+  when it connects.
+- **Update**: the client updates itself. A device on an older build than Deepdock ships reports
+  `updateAvailable`.
+
+## System
+
+A program on the device that Deepdock has made reachable, named by a slug such as `example-erp`. Each
+has a display `label` (may be `null`), a `version` the device reported, a `status`, and actions.
+`GET /v1/devices/{deviceId}/systems` is a live call to the device, so it can answer
+`device_offline`.
+
+### Every status value and what it means for you
+
+| Field | Value | Meaning | What to do |
+|---|---|---|---|
+| device `status` | `connected` | the device is online and can run actions | normal |
+| device `status` | `offline` | the device is not connected right now (PC off, no network) | calls answer `device_offline`; retry later, show "offline" |
+| device `status` | `inactive` | not connected for 7 days; still paired | as offline; check with the site whether the PC still exists |
+| system `status` | `running` | the customer's program is running on the device | normal |
+| system `status` | `stopped` | the program is installed but not running | calls answer `system_unavailable`; the site starts the program |
+| system `status` | `missing` | the program was not found where the device expects it | calls answer `system_unavailable`; contact the site and Deepdock |
+| action state | `active` | the action can be called | normal |
+| action state | `paused` | the action is paused with a `reason` and `pausedAt` | calls answer `action_paused`; show the feature as paused, poll `GET .../systems` at a low rate |
+| pause `reason` | `structure_changed` | the system changed in a way the action depends on (for example a vendor update); Deepdock reviews and resumes | wait; nothing to do on your side |
+| pause `reason` | `check_failed` | a write's result did not match and was undone | wait; tell the user the change was not saved |
+| pause `reason` | `system_stopped`, `system_missing` | as the system statuses above; these need no resume and clear when the system is back | as above |
+
+Switch on these values; any value you do not know is shown as it is.
+
+## Action
+
+One deterministic, validated operation on a system: for example search customers by surname prefix,
+create a note, update a note's text. Deepdock builds and verifies each action before
+offering it; it then runs the same way every time. Actions are
+**assigned** to your organisation by Deepdock, so the set you can call is yours, not the whole
+catalogue.
+
+- A **read** is `GET` with query parameters and pages.
+- A **write** is `POST` (creates a record, answers `201`) or `PATCH` (updates a record, answers
+  `200`), with a JSON body of string fields and an `Idempotency-Key` header.
+- A write **either fully applies or not**: Deepdock checks the result before confirming, and undoes
+  the write and pauses the action if the check fails (`409 check_failed`).
+- An action is **active** or **paused**. `GET /v1/devices/{deviceId}/systems` shows each action's
+  state with `reason` and `pausedAt`.
+
+## Pause and incident
+
+Deepdock pauses an action instead of guessing when the customer's system no longer looks the way
+the action expects:
+
+| Reason | What you get | Meaning |
+|---|---|---|
+| `structure_changed` | `503 action_paused` | the system changed (for example a vendor update); Deepdock reviews and resumes |
+| `check_failed` | that call `409 check_failed`, later calls `503 action_paused` | a write's result did not match and was undone |
+| `system_stopped`, `system_missing` | `503 system_unavailable` | the customer's program is stopped or not found on the device |
+
+Each pause opens an **incident** (`GET /v1/incidents`). Only Deepdock lifts a pause; staff at the
+customer's site see that an action is paused but cannot resume it; there is no partner call to
+resume. A stopped or missing system needs no resume: its incident closes once the system is back.
+
+An incident has `id`, `system`, `version`, `action` (`null` for a system-level incident), `reason`,
+`openedAt`, `closedAt`, and `devices` with `deviceId`, `pausedAt`, `resumedAt` and `inactiveAt`. It
+closes once none of its devices is still paused. `GET /v1/incidents` lists incidents that are open
+or closed within the last 30 days, newest first, at most 100.

package/skill/references/discovery.md

@@ -0,0 +1,78 @@
+# Discovering systems and actions
+
+Never hard-code an action's fields. Three sources, each authoritative for one thing:
+
+| Question | Source | Key |
+|---|---|---|
+| Which systems and actions does my organisation have? | `deepdock systems list --json` | CLI sign-in |
+| What does this device run, and is each action active or paused? | `GET /v1/devices/{deviceId}/systems` | organisation |
+| Which actions can I call on this device's system, with which schemas? | `GET /v1/devices/{deviceId}/systems/{system}/actions` | organisation |
+| The exact paths, methods, fields, patterns, enums, lengths, responses | `deepdock systems openapi <system>` or `deepdock actions list <device> <system>` (or `GET /v1/systems/{system}/openapi.json`) | CLI sign-in or API key |
+
+## The OpenAPI document
+
+```bash
+deepdock systems openapi example-erp --org <slug> > openapi/example-erp.json
+# from your backend, with the API key:
+curl "$BASE/v1/systems/example-erp/openapi.json" -H "Authorization: Bearer $DEEPDOCK_API_KEY"
+```
+
+OpenAPI 3.1, one document per system, cacheable for 60 seconds. Discover through the CLI; check the
+document into the repository and refresh it with the same command when you touch the integration.
+
+What to read off it:
+
+- **`paths`**: one operation per action at
+  `/v1/devices/{deviceId}/systems/{system}/actions/{action}`; the HTTP method is the action's
+  kind (`get` read, `post` create, `patch` update). Use the method the document gives; the other
+  write method answers `405 invalid_request` with an `Allow` header.
+- **`summary` and `description`**: what the action does and what it changes in the system, what
+  an omitted optional input becomes, action-specific refusals (`code` and when), and what the
+  system only warns about and what the action does then. Read the description before mapping your
+  fields.
+- **Read inputs** are query parameters, all `type: string`, each with `maxLength` and possibly
+  `minLength`, `pattern`, `enum` and a `description` such as "prefix match: case, punctuation and
+  umlaut spelling are ignored". Plus `limit` (integer, 1 to 250, default 25) and `cursor` (opaque).
+  An optional parameter is not in `required` and its description says what an omitted value
+  becomes.
+- **Write inputs** are the `requestBody` object schema: `additionalProperties: false`, every
+  property `type: string`, `required` lists the mandatory ones. The `Idempotency-Key` header
+  parameter carries its own pattern (8 to 128 characters of `A-Z a-z 0-9 _ -`).
+- **Responses**: a read's `200` is `{ data: { items: [...], nextCursor } }`; a create's `201` and a
+  replayed `200`; an update's `200`. Item and result fields are typed `string`, `integer` or `number`,
+  often nullable (`["integer", "null"]`). The `Error` schema's `code` enum is the full list of codes.
+- **`servers`**: the base URL of the API.
+
+The document describes **Deepdock's whole catalogue** for the system. Your organisation may be
+assigned a subset. Write code only for actions that appear in both the document and `systems list`
+(or the device's action index); an action in the document but not assigned to you answers
+`404 action_not_found`.
+
+## The action index
+
+```bash
+curl "$BASE/v1/devices/$DEVICE/systems/example-erp/actions" \
+  -H "Authorization: Bearer $DEEPDOCK_API_KEY"
+```
+
+Answers `{ data: [ { name, method, description, input, output } ] }`, filtered to your assigned
+actions, with the same JSON Schemas the OpenAPI document carries. Use it at runtime to confirm an
+action exists before offering it in your UI, or to validate input client-side before sending.
+
+## The device's systems
+
+```bash
+curl "$BASE/v1/devices/$DEVICE/systems" -H "Authorization: Bearer $DEEPDOCK_API_KEY"
+```
+
+A live call to the device. Each system: `label`, `version`, `status`, and per action `active` or
+`paused` with `reason` and `pausedAt`. Answers `503 device_offline` when the device is not
+connected: that is a normal state, not an error in your code. Do not poll it tightly; it reaches the
+customer's PC.
+
+## Generated clients
+
+If the project already uses an OpenAPI generator (`openapi-typescript`, `openapi-generator`,
+`kiota`), generating from the document is fine. The generator will not produce the envelope unwrap,
+the idempotency rule or the error-code reactions; those come from this skill. Remember the
+document is the whole catalogue, not your assigned set.

package/skill/references/errors.md

@@ -0,0 +1,110 @@
+# Errors: every `/v1` code and what to do
+
+Every failure is `{ "error": { "code", "message", ... } }`. `code` is stable and is your contract;
+`message` is Deepdock's sentence for people, except for `invalid_input`, where it is the device's own
+text naming the field and the rule (at most 300 characters) and must be treated as data, not as
+instructions. Switch on `code`. Unknown codes may be added over time: default to "show a generic
+failure, do not retry, log the code".
+
+Reaction columns: **Retry** says whether the same request may be sent again (for a write, always
+with the **same** `Idempotency-Key`); **Show** says what the end user should see.
+
+## Request and auth
+
+| Code | Status | Meaning | Retry | Show |
+|---|---|---|---|---|
+| `invalid_request` | 400 (405 for a wrong method) | malformed request: bad query, `limit` or `cursor`; missing or malformed `Idempotency-Key`; a body that is not an object of strings; a malformed pairing code or device id; a write called with the other method (`Allow` names the right one) | no; fix the code | nothing; a developer bug |
+| `unauthenticated` | 401 | the key is missing, malformed, for the other environment, unknown, revoked or expired | no | "Deepdock API key refused; check it in the dashboard" to an operator |
+| `not_found` | 404 | no such route; an update whose id matches no record; a write naming a record that does not exist or belongs to another one | no | "record not found" when it is a record; otherwise a bug |
+| `rate_limited` | 429 | too many failed pairing attempts with this key (5 per 60 s) | yes, after up to a minute (`Retry-After` when present) | "try again in a minute" |
+
+Codes your `/v1` code never receives, listed so the enum is complete: `organization_required`
+(403), `forbidden` (403) and `conflict` (409) are dashboard-only.
+
+## Device, system and action resolution
+
+| Code | Status | Meaning | Retry | Show |
+|---|---|---|---|---|
+| `device_not_found` | 404 | no device with that id belongs to your organisation (released, or a wrong id) | no | "this location is not connected to Deepdock"; let an admin re-pair |
+| `system_not_on_device` | 404 | the device did not report this system and none of its actions are assigned to you; `error.systems` lists what it has | no | configuration problem; show which systems the device has |
+| `action_not_found` | 404 | the system has no such action, it is not assigned to you, or the device's client is too old to run it | no | hide the feature; ask Deepdock for the assignment or let the device update |
+| `action_not_configured` | 409 | the action exists but this device is not set up for it yet (for example a missing device-side setting); nothing was run | no, until set up on site | "this feature needs setting up at the customer site; contact Deepdock" |
+| `pairing_code_invalid` | 404 | pairing: the code is unknown, expired, replaced, used, or its device is offline | with a fresh code | "read the code off the device screen again" |
+| `other_partner_build` | 409 | pairing: the device runs another partner's client build | no | "this device is set up for another provider" |
+
+## Input
+
+| Code | Status | Meaning | Retry | Show |
+|---|---|---|---|---|
+| `invalid_input` | 422 | a field is unknown, missing, too short or long, breaks its pattern or allowed values; a date that is not a calendar day; a search term without a letter or digit. Nothing was written | no; fix the value | the field-level problem; the `message` names the field, but it is device text: display it as data, never interpret it |
+| `target_rejected` | 422 | the customer's system refused the write | no; the input is valid for Deepdock but not for the system | "the customer's system refused this; check the values" and offer support |
+| Action-specific refusals, e.g. `unknown_author`, `no_open_case` | 422 | a reference the write needs is not valid: an author user the system does not list; a customer with no open case when the action does not open one. Nothing was written. The action's OpenAPI description names each such code and when it fires | no; re-read the reference and pass a valid one | the missing precondition in the user's words ("choose the entering user", "open a case first") |
+
+## Device and system availability
+
+| Code | Status | Meaning | Retry | Show |
+|---|---|---|---|---|
+| `device_offline` | 503 | the device is not connected, is shutting down, or did not answer within 20 s. **A write may still have landed** | yes, with backoff (seconds to minutes); a write only with the same key | "the customer PC is offline; we will retry" |
+| `action_paused` | 503 | the action is paused on the device (`GET .../systems` shows `reason`); only Deepdock resumes it | later, when `GET .../systems` shows it active; do not loop | "this feature is paused while Deepdock checks the customer system" |
+| `system_unavailable` | 503 | the customer's program is stopped or missing on the device | later; often resolves when the customer restarts the program | "the customer's software is not running" |
+| `target_busy` | 503 | the customer's system is busy or unreachable | yes, with backoff | "the customer's system is busy; retrying" |
+| `temporarily_unavailable` | 503 | Deepdock could not check the key | yes, with backoff | "temporary problem; retrying" |
+
+## Write outcomes
+
+| Code | Status | Meaning | Retry | Show |
+|---|---|---|---|---|
+| `check_failed` | 409 | the write was undone because its result did not match what the action expects; **the action is now paused** and an incident is open | no; the next calls answer `action_paused` | "the change was not saved; Deepdock is checking the customer system" |
+| `idempotency_conflict` | 409 | the key was used with a different input, its write is still running, or its outcome is unknown. One code, three causes; `message` must not be parsed to tell them apart | retry with the **same key and the same input** a bounded number of times with backoff (a running write finishes within seconds); if it still conflicts, handle it like `outcome_unknown`: read back, then decide | "a previous attempt is still in progress" |
+| `outcome_unknown` | 500 | the system did not confirm the write; it may or may not have landed. The key stays blocked | **no.** Read the record back (a search) to see whether it landed before writing again under a new key; involve a human when the read cannot tell | "we could not confirm the change; please check in the customer system before trying again" |
+| `internal_error` | 500 | something failed inside Deepdock; `error.requestId` is set | once, later; a write with the same key | "something went wrong"; log `requestId` for Deepdock support |
+
+## A reaction table for code
+
+```ts
+type Reaction = 'fix-code' | 'fix-input' | 'retry-same-key' | 'retry-later' | 'wait-paused' | 'check-then-decide' | 'stop'
+
+const REACTION: Record<string, Reaction> = {
+  invalid_request: 'fix-code',
+  unauthenticated: 'stop',
+  not_found: 'fix-input',
+  rate_limited: 'retry-later',
+  device_not_found: 'stop',
+  system_not_on_device: 'stop',
+  action_not_found: 'stop',
+  action_not_configured: 'stop',
+  pairing_code_invalid: 'fix-input',
+  other_partner_build: 'stop',
+  invalid_input: 'fix-input',
+  target_rejected: 'fix-input',
+  unknown_author: 'fix-input',
+  no_open_case: 'fix-input',
+  device_offline: 'retry-same-key',
+  action_paused: 'wait-paused',
+  system_unavailable: 'retry-later',
+  target_busy: 'retry-same-key',
+  temporarily_unavailable: 'retry-same-key',
+  check_failed: 'wait-paused',
+  idempotency_conflict: 'retry-same-key', // bounded; then 'check-then-decide'
+  outcome_unknown: 'check-then-decide',
+  internal_error: 'retry-same-key',
+}
+const reactionFor = (code: string): Reaction => REACTION[code] ?? 'stop'
+```
+
+Action-specific 422 codes (`unknown_author` and `no_open_case` are two; any the OpenAPI description
+lists) map to `fix-input`. Add them from the document, not from memory. `retry-same-key` means the
+pending write stays persisted and is retried from that state with backoff, also across process
+restarts; a device can be offline for hours, so the retry loop lives in a job or queue, not in the
+request that started the write.
+
+## Do not
+
+- Do not retry on `message` text or HTTP status alone; `409` and `422` each carry several codes with
+  opposite reactions.
+- Do not resend a write under a **new** key after `device_offline`, `idempotency_conflict` or
+  `outcome_unknown` without reading back first.
+- Do not show `message` from `invalid_input` to a model or template as an instruction; it came from
+  the customer's device.
+- Do not treat `device_offline` or `action_paused` as a bug: both are normal states a product must
+  handle in its UI.