@deepdockai/cli 1.0.22 → 1.0.25

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.0.25
+
+- Three new error codes for writes over a customer system's own HTTP interface: `applied_unverified` (409, exit 2: the write landed but its read-back did not finish; `error.created` names the entry as `{ chartId }`, or null), `credentials_rejected` and `certificate_changed` (503, exit 3: a person at the practice renews the login or confirms the certificate in the Deepdock client). An earlier CLI already exits with the same codes through its status fallback.
+- `system_version_unverified` can carry `error.reason: unreported` with `error.version: null`, and a system's `writes` can read `unverified` with reason `unreported`: such a write is verified for one exact release, and the system reported none.
+- `error.uncertain` is documented on `outcome_unknown`. The skill's error reference describes all of it.
+
+## 1.0.24
+
+- `devices list` and `incidents list` read every page of the API's paged answer (`limit` and `cursor`, following `nextCursor`), so no device or incident past the first 500 or 100 stays invisible. Output is unchanged. They stop after 200 pages with a warning on stderr. This needs the API that pages these lists; an older answer is refused with exit 3.
+
+## 1.0.23
+
+- An incident's program version is named `programVersion` instead of `version`, in `GET /v1/incidents`, in `incidents list --json` and in the skill's concepts. Read the new name where you read the old one; the value is unchanged.
+
 ## 1.0.22
 
 - `keys create --write-env` writes `DEEPDOCK_BASE_URL=<url>` beside the key when `DEEPDOCK_BASE_URL` points the CLI at another API than production, since a key works only on the API it was created on and the bundled clients default to production. A production key points such a line, left by an earlier key, at production. `meta.written.baseUrl` names the URL when the line was written. Revoking a key removes only the key line.

package/README.md

@@ -154,14 +154,14 @@ your code will receive; `auth`, `org select` and `keys create` build it from nam
 failure is one document on stderr, `{ "error": { "code", "message" }, "meta": { "hint" } }`,
 with the API's error object unchanged. Switch on `code` or on the exit code, never on `message`.
 
-| Exit | Meaning                                                                                                                                                                                                                                                                        |
-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| 0    | done                                                                                                                                                                                                                                                                           |
-| 1    | something on the command line to fix (`invalid_usage`, `org_required`)                                                                                                                                                                                                         |
-| 2    | the API refused the request; do not repeat it unchanged (`invalid_request`, `not_found`, `forbidden`, `rate_limited` and the other refusals)                                                                                                                                   |
-| 3    | retry later (`device_offline`, `device_syncing`, `device_outdated`, `system_version_unverified`, `action_paused`, `access_outdated`, `access_missing`, `system_unavailable`, `target_busy`, `temporarily_unavailable`, `internal_error`, `outcome_unknown`, `connection_lost`) |
-| 4    | the CLI is too old for the API (`client_outdated`): run `npx @deepdockai/cli@latest`                                                                                                                                                                                           |
-| 5    | sign-in needed (`sign_in_needed`, `approval_denied`, `approval_expired`); `auth status` when nobody is signed in                                                                                                                                                               |
+| Exit | Meaning                                                                                                                                                                                                                                                                                                                       |
+| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 0    | done                                                                                                                                                                                                                                                                                                                          |
+| 1    | something on the command line to fix (`invalid_usage`, `org_required`)                                                                                                                                                                                                                                                        |
+| 2    | the API refused the request; do not repeat it unchanged (`invalid_request`, `not_found`, `forbidden`, `rate_limited` and the other refusals)                                                                                                                                                                                  |
+| 3    | retry later (`device_offline`, `device_syncing`, `device_outdated`, `system_version_unverified`, `action_paused`, `access_outdated`, `access_missing`, `credentials_rejected`, `certificate_changed`, `system_unavailable`, `target_busy`, `temporarily_unavailable`, `internal_error`, `outcome_unknown`, `connection_lost`) |
+| 4    | the CLI is too old for the API (`client_outdated`): run `npx @deepdockai/cli@latest`                                                                                                                                                                                                                                          |
+| 5    | sign-in needed (`sign_in_needed`, `approval_denied`, `approval_expired`); `auth status` when nobody is signed in                                                                                                                                                                                                              |
 
 The CLI never retries on its own: exit 3 says retry, you decide when. `deepdock commands --json`
 prints the whole command tree.

package/dist/deepdock.js

@@ -10866,6 +10866,7 @@ var EXIT_CODES = {
   rate_limited: 2,
   target_rejected: 2,
   readback_failed: 2,
+  applied_unverified: 2,
   idempotency_conflict: 2,
   conflict: 2,
   already_member: 2,
@@ -10880,6 +10881,8 @@ var EXIT_CODES = {
   action_paused: 3,
   access_outdated: 3,
   access_missing: 3,
+  credentials_rejected: 3,
+  certificate_changed: 3,
   system_unavailable: 3,
   target_busy: 3,
   temporarily_unavailable: 3,
@@ -11429,7 +11432,7 @@ import { spawn } from "node:child_process";
 import { homedir, hostname } from "node:os";
 
 // src/version.ts
-var VERSION = "1.0.22";
+var VERSION = "1.0.25";
 
 // src/runtime.ts
 var DEFAULT_BASE_URL = "https://api.deepdock.ai";
@@ -12160,6 +12163,7 @@ var EXIT_CODES_HELP = `Exit codes
   2  the API refused the request; do not repeat it unchanged
   3  retry later (device_offline, device_syncing, device_outdated,
      system_version_unverified, action_paused, access_outdated, access_missing,
+     credentials_rejected, certificate_changed,
      system_unavailable, target_busy, temporarily_unavailable, internal_error,
      outcome_unknown, connection_lost)
   4  the CLI is too old for the API (client_outdated)
@@ -12828,6 +12832,40 @@ var registerAuth = (program, run) => {
   auth.command("logout").description("Revoke the sign-in and the API keys this CLI created").option("--keep-keys", "revoke only the sign-in and leave the API keys active").action((options, cmd) => run(cmd, (ctx) => logout(ctx, options)));
 };
 
+// src/commands/pages.ts
+var PAGE_LIMIT = 500;
+var MAX_PAGES = 200;
+var unreadable = () => new CliError({
+  code: "connection_lost",
+  message: "The API answered a list in a shape this CLI does not read.",
+  hint: "Update the CLI with `npm install -g @deepdockai/cli@latest`, then retry."
+});
+var readAllPages = async (ctx, path, org) => {
+  const items = [];
+  let cursor = null;
+  let requestId;
+  for (let page = 1;page <= MAX_PAGES; page++) {
+    const query = new URLSearchParams({ limit: String(PAGE_LIMIT) });
+    if (cursor !== null)
+      query.set("cursor", cursor);
+    const url = `${path}?${query.toString()}`;
+    const response = org ? await ctx.call({ method: "GET", path: url, org }) : await ctx.callInOrg({ method: "GET", path: url });
+    const data = response.data;
+    if (!isRecord(data) || !Array.isArray(data.items))
+      throw unreadable();
+    const next = data.nextCursor;
+    if (next !== null && (typeof next !== "string" || next === ""))
+      throw unreadable();
+    items.push(...data.items);
+    requestId ??= response.requestId;
+    if (next === null)
+      return { items, requestId };
+    cursor = next;
+  }
+  ctx.note(`Warning: stopped after ${MAX_PAGES} pages; the list is longer than the ${items.length} rows shown.`);
+  return { items, requestId };
+};
+
 // src/commands/devices.ts
 var meta = (requestId) => requestId ? { requestId } : {};
 var updateNotes = (ctx, devices) => {
@@ -12840,19 +12878,18 @@ var updateNotes = (ctx, devices) => {
   }
 };
 var list = async (ctx) => {
-  const response = await ctx.callInOrg({ method: "GET", path: "/partner/devices" });
-  const devices = Array.isArray(response.data) ? response.data : [];
+  const { items: devices, requestId } = await readAllPages(ctx, "/partner/devices");
   if (devices.length === 0) {
     return {
-      data: response.data,
-      meta: meta(response.requestId),
+      data: devices,
+      meta: meta(requestId),
       text: "No devices are paired. Pair one with `deepdock devices pair <code>`."
     };
   }
   updateNotes(ctx, devices);
   return {
-    data: response.data,
-    meta: meta(response.requestId),
+    data: devices,
+    meta: meta(requestId),
     text: deviceTable(devices, ctx.rt.now(), ctx.out)
   };
 };
@@ -12906,8 +12943,8 @@ var release = async (ctx, id) => {
   if (!ctx.opts.yes) {
     let label = "";
     try {
-      const response = await ctx.call({ method: "GET", path: "/partner/devices", org: org.slug });
-      const found = Array.isArray(response.data) ? response.data.filter(isRecord).find((device) => field(device, "id") === deviceId) : undefined;
+      const { items } = await readAllPages(ctx, "/partner/devices", org.slug);
+      const found = items.filter(isRecord).find((device) => field(device, "id") === deviceId);
       label = found ? field(found, "label") : "";
     } catch {}
     const named = label ? ` (${stripControl(label)})` : "";
@@ -12966,10 +13003,9 @@ var registerDevices = (program, run) => {
 var registerIncidents = (program, run) => {
   const incidents = program.command("incidents").description("Incidents that paused an action on one of your devices");
   incidents.command("list").description("List open incidents and those closed within 30 days").action((_options, cmd) => run(cmd, async (ctx) => {
-    const response = await ctx.callInOrg({ method: "GET", path: "/partner/incidents" });
-    const items = Array.isArray(response.data) ? response.data : [];
+    const { items, requestId } = await readAllPages(ctx, "/partner/incidents");
     const text = items.length === 0 ? "No incidents." : genericTable(items, ctx.out, INCIDENT_COLUMNS);
-    return { data: response.data, meta: { requestId: response.requestId }, text };
+    return { data: items, meta: { requestId }, text };
   }));
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepdockai/cli",
-  "version": "1.0.22",
+  "version": "1.0.25",
   "description": "Deepdock partner CLI: pair devices, see systems and actions, create the API key your code runs them with.",
   "type": "module",
   "license": "MIT",

package/skill/references/cli.md

@@ -84,7 +84,7 @@ A failure is one document on stderr: the API's error object unchanged plus what
 | 0 | done | |
 | 1 | something on the command line to fix | `invalid_usage` (a bad flag, an unknown slug, a question with no terminal and no `--yes`, an env file git does not ignore), `org_required` |
 | 2 | the API refused the request; do not repeat it unchanged | `invalid_request`, `not_found`, `device_not_found`, `pairing_code_invalid`, `other_partner_build`, `rate_limited`, `forbidden`, `conflict` and the other refusals (not `access_outdated` and `access_missing`, see exit 3) |
-| 3 | retry later (`access_outdated` and `access_missing`: after the customer repeats "Erneut einrichten" in the Deepdock client) | `device_offline`, `device_syncing`, `device_outdated`, `system_version_unverified`, `action_paused`, `access_outdated`, `access_missing`, `system_unavailable`, `target_busy`, `temporarily_unavailable`, `internal_error`, `outcome_unknown`, `connection_lost` |
+| 3 | retry later (`access_outdated` and `access_missing`: after the customer repeats "Erneut einrichten" in the Deepdock client) | `device_offline`, `device_syncing`, `device_outdated`, `system_version_unverified`, `action_paused`, `access_outdated`, `access_missing`, `credentials_rejected`, `certificate_changed`, `system_unavailable`, `target_busy`, `temporarily_unavailable`, `internal_error`, `outcome_unknown`, `connection_lost` |
 | 4 | the CLI is too old for the API: run `npx @deepdockai/cli@latest` | `client_outdated` |
 | 5 | sign-in needed: run `deepdock auth login` | `sign_in_needed`, `approval_denied`, `approval_expired` |
 

package/skill/references/clients/deepdock.py

@@ -20,14 +20,17 @@ class DeepdockError(Exception):
 
     def __init__(self, status: int, code: str, message: str, request_id: Optional[str] = None,
                  systems: Optional[List[str]] = None, version: Optional[str] = None,
-                 reason: Optional[str] = None):
+                 reason: Optional[str] = None, created: Optional[Dict[str, Any]] = None,
+                 uncertain: Optional[bool] = None):
         super().__init__(message)
         self.status = status
         self.code = code
         self.request_id = request_id
         self.systems = systems
-        self.version = version  # system_version_unverified: the version the system last reported
-        self.reason = reason  # system_version_unverified: unverified_version or unparseable
+        self.version = version  # system_version_unverified: the version the system last reported, None when it reported none
+        self.reason = reason  # system_version_unverified: unverified_version, unparseable or unreported
+        self.created = created  # applied_unverified, outcome_unknown with no rollback: {"chartId"} or None
+        self.uncertain = uncertain  # outcome_unknown: True when the write may or may not have landed
 
 
 class DeepdockTransportError(Exception):
@@ -67,7 +70,7 @@ class Deepdock:
         if isinstance(body, dict) and "error" in body:
             e = body["error"]
             raise DeepdockError(r.status_code, e["code"], e["message"], e.get("requestId"), e.get("systems"),
-                                e.get("version"), e.get("reason"))
+                                e.get("version"), e.get("reason"), e.get("created"), e.get("uncertain"))
         if not isinstance(body, dict) or "data" not in body:
             raise DeepdockTransportError(f"unexpected body with status {r.status_code}")
         return body["data"], r.headers
@@ -166,8 +169,11 @@ def attempt(dd: Deepdock, row: PendingWrite) -> PendingWrite:
             if row.conflict_retries < CONFLICT_RETRIES:
                 return replace(row, status="sent", conflict_retries=row.conflict_retries + 1)
             return replace(row, status="unknown")
-        if e.code == "outcome_unknown":
-            return replace(row, status="unknown", request_id=e.request_id)
+        # applied_unverified: the entry exists but was not verified; never write it again under a new
+        # key. result["created"] names it for the check.
+        if e.code in ("outcome_unknown", "applied_unverified"):
+            return replace(row, status="unknown", request_id=e.request_id,
+                           result={"created": e.created, "uncertain": e.uncertain})
         # invalid_input, target_rejected, action-specific 422s, not_found, readback_failed, auth and
         # resolution codes: nothing was written. Fix the cause; a changed input gets a new key.
         return replace(row, status="refused", refused_code=e.code, result={"message": str(e)})

package/skill/references/clients/deepdock.ts

@@ -13,15 +13,21 @@ export class DeepdockError extends Error {
   readonly code: string
   readonly requestId?: string
   readonly systems?: string[]
-  /** system_version_unverified: the version the system last reported. */
-  readonly version?: string
-  /** system_version_unverified: `unverified_version` or `unparseable`. */
+  /** system_version_unverified: the version the system last reported, `null` when it reported none. */
+  readonly version?: string | null
+  /** system_version_unverified: `unverified_version`, `unparseable` or `unreported`. */
   readonly reason?: string
+  /** applied_unverified, outcome_unknown on a system with no rollback: the entry, or `null` when not known. */
+  readonly created?: { chartId?: string } | null
+  /** outcome_unknown: `true` when the write may or may not have landed. */
+  readonly uncertain?: boolean
 
   constructor(status: number, code: string, message: string, requestId?: string,
     systems?: string[],
-    version?: string,
+    version?: string | null,
     reason?: string,
+    created?: { chartId?: string } | null,
+    uncertain?: boolean,
   ) {
     super(message)
     this.name = 'DeepdockError'
@@ -31,6 +37,8 @@ export class DeepdockError extends Error {
     this.systems = systems
     this.version = version
     this.reason = reason
+    this.created = created
+    this.uncertain = uncertain
   }
 }
 
@@ -42,7 +50,7 @@ export class DeepdockTransportError extends Error {
   }
 }
 
-type ErrorBody = { code: string; message: string; requestId?: string; systems?: string[]; version?: string; reason?: string }
+type ErrorBody = { code: string; message: string; requestId?: string; systems?: string[]; version?: string | null; reason?: string; created?: { chartId?: string } | null; uncertain?: boolean }
 type Envelope<T> = { data: T } | { error: ErrorBody }
 
 export type Page<Item> = { items: Item[]; nextCursor: string | null }
@@ -56,11 +64,12 @@ export type SystemAccess = 'ok' | 'outdated' | 'missing' | 'password_missing' |
 /**
  * Whether writes on the system run. `unverified` makes writes answer system_version_unverified:
  * `unverified_version` clears once Deepdock verifies the version; `unparseable` does not clear by
- * waiting (contact Deepdock).
+ * waiting (contact Deepdock); `unreported` clears once the device reports the system's version (a
+ * write verified for one exact release needs it).
  */
 export type SystemWrites =
   | { state: 'verified' | 'unknown' | 'partial' }
-  | { state: 'unverified'; reason: 'unverified_version' | 'unparseable' }
+  | { state: 'unverified'; reason: 'unverified_version' | 'unparseable' | 'unreported' }
 
 export type Device = {
   id: string
@@ -165,8 +174,8 @@ export class Deepdock {
       throw new DeepdockTransportError(`non-JSON answer with status ${res.status}`)
     }
     if (body !== null && typeof body === 'object' && 'error' in body) {
-      const { code, message, requestId, systems, version, reason } = body.error
-      throw new DeepdockError(res.status, code, message, requestId, systems, version, reason)
+      const { code, message, requestId, systems, version, reason, created, uncertain } = body.error
+      throw new DeepdockError(res.status, code, message, requestId, systems, version, reason, created, uncertain)
     }
     if (body === null || typeof body !== 'object' || !('data' in body)) {
       throw new DeepdockTransportError(`unexpected body with status ${res.status}`)
@@ -305,7 +314,15 @@ export const attempt = async (dd: Deepdock, row: PendingWrite): Promise<PendingW
         ? { ...row, status: 'sent', conflictRetries: row.conflictRetries + 1 }
         : { ...row, status: 'unknown' }
     }
-    if (err.code === 'outcome_unknown') return { ...row, status: 'unknown', requestId: err.requestId }
+    // applied_unverified: the entry exists but was not verified; never write it again under a new
+    // key. `result.created` names it for the check.
+    if (err.code === 'outcome_unknown' || err.code === 'applied_unverified')
+      return {
+        ...row,
+        status: 'unknown',
+        requestId: err.requestId,
+        result: { created: err.created, uncertain: err.uncertain },
+      }
     // invalid_input, target_rejected, action-specific 422s, not_found, readback_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

@@ -95,7 +95,8 @@ Each pause opens an **incident** (`GET /v1/incidents`). Only Deepdock lifts a pa
 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`,
+An incident has `id`, `system`, `programVersion` (the version of the vendor's program its devices
+run, `null` when they reported none), `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/errors.md

@@ -62,10 +62,12 @@ dashboard-only.
 | `device_offline` | 503 | the device is not connected, is shutting down, did not answer within 20 s, or the call was cut off inside Deepdock by a restart or deploy. **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" |
 | `device_syncing` | 503 | the device has not reported its Deepdock client yet (just paired, or its report did not come through); Deepdock asks it again. Nothing was written | yes, after `Retry-After` (5 s); a write with the same key | "the customer PC is connecting; retrying" |
 | `device_outdated` | 409 | the device's Deepdock client is too old for this call. It updates itself when a newer version is released for your organisation, once nobody is signed in on the PC. Nothing was written | after the update (`outdated` on `GET /v1/devices/{deviceId}` turns `false`); retrying before it gets the same answer. A write keeps its key | "the Deepdock client on the customer PC needs an update" |
-| `system_version_unverified` | 409 | a write on a system whose vendor version Deepdock has not verified yet. Nothing was sent to the device; reads still work. `error.version` is the version the system last reported and `error.reason` is `unverified_version`, or `unparseable` when that version is not dotted digits | `unverified_version`: after Deepdock has verified that version (`writes` on the system in `GET /v1/devices/{deviceId}` turns `verified`); retrying before it gets the same answer. `unparseable`: retrying does not help, contact Deepdock; only a different reported version changes it. A write keeps its key | "the customer's system was updated to a version Deepdock has not yet verified; changes will work once it has" |
+| `system_version_unverified` | 409 | a write on a system whose vendor version Deepdock has not verified yet. Nothing was sent to the device; reads still work. `error.version` is the version the system last reported (null when it reported none) and `error.reason` is `unverified_version`, `unparseable` when that version is not dotted digits, or `unreported` when the system reported no version: a write over the system's own HTTP interface is verified for one exact release and needs it | `unverified_version`: after Deepdock has verified that version (`writes` on the system in `GET /v1/devices/{deviceId}` turns `verified`); retrying before it gets the same answer. `unparseable`: retrying does not help, contact Deepdock; only a different reported version changes it. `unreported`: later, once the device reports the system's version. A write keeps its key | "the customer's system was updated to a version Deepdock has not yet verified; changes will work once it has" |
 | `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" |
+| `credentials_rejected` | 503 | the customer's system refused the device's login. Nothing was sent | later, after a person at the customer has renewed the access in the Deepdock client; do not loop. A write keeps its key | "the connection to the customer's software needs to be renewed at the practice" |
+| `certificate_changed` | 503 | the customer's system shows a certificate other than the one the device trusts. Nothing was sent | later, after a person at the customer has confirmed the new certificate in the Deepdock client; do not loop. A write keeps its key | "the connection to the customer's software needs to be confirmed at the practice" |
 | `temporarily_unavailable` | 503 | Deepdock could not check the key or reach its own database (sent with `Retry-After: 5`) | yes, with backoff | "temporary problem; retrying" |
 
 ## Write outcomes
@@ -73,8 +75,9 @@ dashboard-only.
 | Code | Status | Meaning | Retry | Show |
 |---|---|---|---|---|
 | `readback_failed` | 409 | the write's result did not match what the action expects, so nothing was saved; **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" |
+| `applied_unverified` | 409 | a write on a system with no rollback was applied, but its read-back did not finish. The entry exists: `error.created` names it as `{ chartId }`, or is null when the entry is not known | **no.** The entry is there; writing again creates a second one. Check it in the customer system | "the change was saved but could not be confirmed; please check it in 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" |
+| `outcome_unknown` | 500 | the system did not confirm the write; it may or may not have landed. The key stays blocked. On a system with no rollback, `error.uncertain` is true and `error.created` names the entry when one is known | **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
@@ -104,6 +107,8 @@ const REACTION: Record<string, Reaction> = {
   payload_too_large: 'fix-code',
   access_outdated: 'wait-setup',
   access_missing: 'wait-setup',
+  credentials_rejected: 'wait-setup',
+  certificate_changed: 'wait-setup',
   device_offline: 'retry-same-key',
   device_syncing: 'retry-same-key',
   device_outdated: 'retry-later',
@@ -113,6 +118,7 @@ const REACTION: Record<string, Reaction> = {
   target_busy: 'retry-same-key',
   temporarily_unavailable: 'retry-same-key',
   readback_failed: 'wait-paused',
+  applied_unverified: 'check-then-decide', // the entry exists; reading it back shows it
   idempotency_conflict: 'retry-same-key', // bounded; then 'check-then-decide'
   outcome_unknown: 'check-then-decide',
   internal_error: 'retry-same-key',
@@ -120,7 +126,7 @@ const REACTION: Record<string, Reaction> = {
 const reactionFor = (code: string): Reaction => REACTION[code] ?? 'stop'
 ```
 
-Action-specific 422 codes beyond the ones above (any the OpenAPI description lists) map to `fix-input`. Add them from the document, not from memory. `wait-setup` means a person at the customer must repeat the database access setup ("Erneut einrichten") in the Deepdock client first; there is no `Retry-After`, so do not loop. Check `access` on the system in `GET .../systems` (`ok` again), then retry; a write keeps its key. `retry-same-key` means the
+Action-specific 422 codes beyond the ones above (any the OpenAPI description lists) map to `fix-input`. Add them from the document, not from memory. `wait-setup` means a person at the customer must act in the Deepdock client first: repeat the database access setup ("Erneut einrichten") for `access_*`, renew the login for `credentials_rejected`, confirm the new certificate for `certificate_changed`; there is no `Retry-After`, so do not loop. Check `access` on the system in `GET .../systems` (`ok` again), then retry; a write keeps its key. `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.

package/skill/references/idempotency.md

@@ -74,6 +74,7 @@ pending ──send──▶ sent ──2xx (fresh or replayed)──────
                    │  ──idempotency_conflict, retries left ───▶ sent     (retry, same key, same input)
                    │  ──idempotency_conflict, retries spent ──▶ unknown  (read back before anything else)
                    │  ──outcome_unknown ──────────────────────▶ unknown  (read back before anything else)
+                   │  ──applied_unverified ───────────────────▶ unknown  (the entry exists: check it by result.created, never write it again)
                    │  ──invalid_input, target_rejected, action-specific 422, not_found, readback_failed ▶ refused  (key is free; new input gets a new key)
                    │  ──action_paused, system_unavailable ────▶ sent     (retry once the action is active again)
 ```