@smthrs/control 0.0.0-stage → 1.0.0-rc.3

package/docs/troubleshooting.md

@@ -0,0 +1,208 @@
+---
+title: "Troubleshooting"
+description: "The refusals @smthrs/control reports, the symptom each one shows up as, what causes it, and what to change: typed failures, unexpected receipts, and empty projections."
+---
+
+Every failure this package reports is a typed class with a stable `code` a
+client may branch on. `ControlError.ControlErrorSchema` is the single
+membership list, and `ControlClient.isControlError` is derived from it.
+
+## Typed failures
+
+### `PlanNotFound` (`plan_not_found`)
+
+No plan or node approval token with this id. The message names the next action:
+create the plan again before approving or launching it.
+
+A common cause is a plane that restarted on `ControlRuntime.layerMemory`.
+Nothing that runtime decides survives the process. Move to
+[`SqlControlRuntime`](./guides/durable-storage.md).
+
+### `PlanDenied` (`plan_denied`)
+
+The plan was denied and cannot be launched. A denial is terminal: create and
+approve a new plan rather than trying to revive this one.
+
+### `PlanDigestMismatch` (`plan_digest_mismatch`)
+
+The submitted digest is not the stored one, and the failure carries both.
+Resubmit the card unchanged: `card.approval` and `card.digest` are the exact
+values the plan phase produced. Rebuilding an approval payload on the client is
+how the two drift apart.
+
+If the digests differ for the _same_ input, something in the plan changed:
+the envelope, the deploy-class flag, or the keyed node graph. That is the check
+working.
+
+### `EnvelopeMismatch` (`envelope_mismatch`)
+
+The submitted envelope is not the stored one. Envelopes are compared by
+canonical bytes, so key order does not matter but a missing or extra capability
+does. Pass `card.envelope` through unchanged.
+
+### `AlreadyResolved` (`already_resolved`)
+
+This approval token already carries a terminal decision. A second decision is
+refused rather than overwriting the first, so this is also the durable evidence
+that the first decision stuck.
+
+### `FlowNotFound` (`flow_not_found`)
+
+The runtime has no flow with this id. The control plane's catalog and the
+engine's registrations are separate on purpose: one is what may be planned, the
+other is what may be executed. Add the flow to the runtime's `flows` option, or
+to the registry the plane lists from.
+
+### `RunNotFound` (`run_not_found`)
+
+This plane has no such run. Two causes are worth separating:
+
+- The run id is wrong. Confirm it with [`list`](./guides/list-runs.md).
+- The run exists in the _engine's_ database and this plane keeps its own. See
+  [two run tables, one journal](./concepts/authority.md).
+
+### `ClaimLost` (`claim_lost`)
+
+A live peer holds the run, or the fence you presented has been superseded. A
+run at `running`, or at the `accepted` a claim writes, is being driven by
+another process, so there is nothing to restart.
+
+Do not retry in a loop. Read the run's `ownerId` and `parkedBy`, and see
+[Ownership, fences, and claims](./concepts/ownership.md).
+
+### `NoMatchingWait` (`no_matching_wait`)
+
+The signal named a wait point the run does not have open. The message says
+which run and which name; `smthrs runs show <run>` shows what it waits for. The run is
+parked on something else, so completing this wait would deliver nothing.
+
+### `InvalidInput` (`invalid_input`)
+
+The request did not satisfy its schema or a stated precondition. The `issue`
+field names the path. The ones you will actually meet:
+
+| `issue`                                                                                   | Fix                                                                                  |
+| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `afterSequence: a watch cursor resumes one run, so it requires runId`                     | Scope the watch. Sequences are partition-local.                                      |
+| `limit: must be an integer between 1 and 500, received 0`                                 | Use a page size in range, or omit it for 100.                                        |
+| `cursor: must be a cursor this listing returned, received "..."`                          | Pass back `nextCursor` verbatim.                                                     |
+| `message.runId: must be "run-17", received "run-18"`                                      | The steer's envelope and the call must name one run.                                 |
+| `<operation>: contains an accessor` (or a cycle, a non-plain object, a non-finite number) | Pass plain JSON data. The identity boundary refuses anything it cannot copy inertly. |
+| `<operation>.idempotencyKey: must be 1 to 1024 well-formed characters`                    | Shorten the key, or remove the lone surrogate or NUL.                                |
+| `webhook body: declared N bytes exceeds the M byte limit`                                 | Raise the mount's ceiling, or send less.                                             |
+
+### `Unauthorized` (`unauthorized`)
+
+No usable credential. The bearer authenticator fails closed the same way for a
+missing, malformed, empty, or incorrect token, so the response never says which.
+Check that the client's `credential` and the server's `token` are the same
+string.
+
+`Credential` also reports `Unauthorized` for a credential that does not exist,
+deliberately indistinguishable from one the caller may not have.
+
+### `Unavailable` (`unavailable`)
+
+The operation is not implemented in this composition. `feature` names the verb
+or capability that is missing, and `ticket` is a constant identifier for the
+integration behind it, stable enough to group reports by.
+
+| `feature`                                     | Cause                                                              |
+| --------------------------------------------- | ------------------------------------------------------------------ |
+| any `Control` verb                            | `Control.layerNoop` is provided. Provide `ControlLive.layer`.      |
+| `watch`                                       | The composition has no open journal.                               |
+| `credential storage`, `credential encryption` | A noop store or cipher is provided, or the host has no Web Crypto. |
+| `channel "<name>" is not registered`          | Call `channels.register` before the first request arrives.         |
+
+### `CredentialConflict` (`credential_conflict`)
+
+Two rotations raced, and this one read the older version. The failure carries
+`expectedVersion` and `actualVersion`. Re-read the record and rotate again.
+
+A `rotate` with `expected` also fails this way, with both versions equal, when
+the stored secret is no longer `expected`: another writer already replaced it.
+
+### `LaunchFailed` (`launch_failed`)
+
+The executor refused or could not start the run. The plane settles the run row
+as `failed` and journals `control.run.failed` with the cause, so the run does
+not survive as an unlaunched row no verb can end. The admission receipt remains;
+inspect that run before an explicit retry with a new idempotency key.
+
+### `PersistenceError` (`persistence_failed`)
+
+A store operation failed. `operation` names what was being attempted and
+`cause` keeps the driver's own error. A `<operation>.idempotency` operation
+means the mutation and its receipt could not be committed atomically.
+
+Operation `watch` means a journal read failed while serving a watch.
+Operation `credential.open` means a stored credential did not open: its nonce
+is malformed, or its ciphertext failed authentication because the key is not
+the one that sealed it, its metadata changed, or its bytes were tampered with.
+
+### `TransportError` (`transport_error`)
+
+The request failed before a declared control response reached the caller. Only
+`retryable` transport phases are worth resending, and only when the mutation
+carries an idempotency key that makes replay safe. See
+[Serve the control plane over RPC](./guides/serve-over-rpc.md).
+
+## Receipts that surprise people
+
+### `run` answered `Parked`, and nothing started
+
+The plan is undecided. That is the approval gate working: approve
+`card.approval` and call `run` again with the same key. See
+[Gate work behind an approval](./guides/approvals.md).
+
+### `cancel` answered `Terminal`, not `Accepted`
+
+The run settled. Either it had already finished, or this call interrupted it
+and it is now `cancelled`. Both are the true answer about the run;
+`Accepted` is what you get when a live peer will act on the durable request
+instead.
+
+### A retry answered `Conflict`
+
+The key already names a different mutation. The fingerprint is a digest of the
+operation, the actor, and the decoded request, so any change to the request
+under one key is a conflict. Use a new key for a new intent.
+
+### `resume` answered `Terminal` for a run that looks parked
+
+The plane read the run's terminality before the idempotency replay, so this is
+the run's current state rather than a recorded answer. If the plane's row
+disagrees with what you see elsewhere, the two are different databases.
+
+## Projections that come back empty
+
+### `waitingReason`, `origin`, and `cancellation` are always absent
+
+Those fields are read from the engine's own columns and journal entries, so
+they need the control runtime and the engine to share one database. The
+[`smthrs` CLI](/api/cli) keeps `.flows/control.db` and `.flows/engine.db`
+apart, and the fields are empty there by design. See
+[Store control state in a database](./guides/durable-storage.md).
+
+They are also absent on `ControlRuntime.layerMemory`, which has no engine to
+read.
+
+### `steering.pending` is absent
+
+The notification queue could not answer. The field is left absent rather than
+guessed, because "not known" is representable and it is the truth.
+
+### `watch` returned nothing for a run that exists
+
+A watch of an empty partition is empty, not an error. Check that the run id is
+the _execution_ id the engine journals under, which is the id the `Accepted`
+receipt carried.
+
+## Where to go next
+
+- [Receipts and idempotency](./concepts/receipts.md): why a second ask answers
+  what it answers.
+- [Ownership, fences, and claims](./concepts/ownership.md): the model behind
+  `ClaimLost` and `parkedBy`.
+- [Errors on smithers.sh](/docs/reference/errors/): the same codes as an
+  operator meets them.

package/package.json

@@ -1,6 +1,408 @@
 {
   "name": "@smthrs/control",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "type": "module",
+  "version": "1.0.0-rc.3",
+  "license": "MIT",
+  "smthrs": {
+    "group": "agent"
+  },
+  "description": "Control services and RPC projections for flows",
+  "homepage": "https://github.com/smithersai/smithers",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/smithersai/smithers.git",
+    "directory": "packages/smithers/control"
+  },
+  "bugs": {
+    "url": "https://github.com/smithersai/smithers/issues"
+  },
+  "tags": [
+    "typescript",
+    "effect",
+    "control",
+    "flow"
+  ],
+  "keywords": [
+    "typescript",
+    "effect",
+    "control",
+    "flow"
+  ],
+  "engines": {
+    "node": ">=26.4.0"
+  },
+  "sideEffects": [],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./internal/*": null,
+    "./migrations/*": null,
+    "./*/index": null,
+    "./ApprovalAuthority": {
+      "import": {
+        "types": "./dist/esm/ApprovalAuthority.d.ts",
+        "default": "./dist/esm/ApprovalAuthority.js"
+      },
+      "require": {
+        "types": "./dist/cjs/ApprovalAuthority.d.ts",
+        "default": "./dist/cjs/ApprovalAuthority.js"
+      }
+    },
+    "./Cancellation": {
+      "import": {
+        "types": "./dist/esm/Cancellation.d.ts",
+        "default": "./dist/esm/Cancellation.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Cancellation.d.ts",
+        "default": "./dist/cjs/Cancellation.js"
+      }
+    },
+    "./Channels": {
+      "import": {
+        "types": "./dist/esm/Channels.d.ts",
+        "default": "./dist/esm/Channels.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Channels.d.ts",
+        "default": "./dist/cjs/Channels.js"
+      }
+    },
+    "./Control": {
+      "import": {
+        "types": "./dist/esm/Control.d.ts",
+        "default": "./dist/esm/Control.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Control.d.ts",
+        "default": "./dist/cjs/Control.js"
+      }
+    },
+    "./ControlClient": {
+      "import": {
+        "types": "./dist/esm/ControlClient.d.ts",
+        "default": "./dist/esm/ControlClient.js"
+      },
+      "require": {
+        "types": "./dist/cjs/ControlClient.d.ts",
+        "default": "./dist/cjs/ControlClient.js"
+      }
+    },
+    "./ControlError": {
+      "import": {
+        "types": "./dist/esm/ControlError.d.ts",
+        "default": "./dist/esm/ControlError.js"
+      },
+      "require": {
+        "types": "./dist/cjs/ControlError.d.ts",
+        "default": "./dist/cjs/ControlError.js"
+      }
+    },
+    "./ControlExecutor": {
+      "import": {
+        "types": "./dist/esm/ControlExecutor.d.ts",
+        "default": "./dist/esm/ControlExecutor.js"
+      },
+      "require": {
+        "types": "./dist/cjs/ControlExecutor.d.ts",
+        "default": "./dist/cjs/ControlExecutor.js"
+      }
+    },
+    "./ControlLive": {
+      "import": {
+        "types": "./dist/esm/ControlLive.d.ts",
+        "default": "./dist/esm/ControlLive.js"
+      },
+      "require": {
+        "types": "./dist/cjs/ControlLive.d.ts",
+        "default": "./dist/cjs/ControlLive.js"
+      }
+    },
+    "./ControlRpcs": {
+      "import": {
+        "types": "./dist/esm/ControlRpcs.d.ts",
+        "default": "./dist/esm/ControlRpcs.js"
+      },
+      "require": {
+        "types": "./dist/cjs/ControlRpcs.d.ts",
+        "default": "./dist/cjs/ControlRpcs.js"
+      }
+    },
+    "./ControlRuntime": {
+      "import": {
+        "types": "./dist/esm/ControlRuntime.d.ts",
+        "default": "./dist/esm/ControlRuntime.js"
+      },
+      "require": {
+        "types": "./dist/cjs/ControlRuntime.d.ts",
+        "default": "./dist/cjs/ControlRuntime.js"
+      }
+    },
+    "./ControlSchema": {
+      "import": {
+        "types": "./dist/esm/ControlSchema.d.ts",
+        "default": "./dist/esm/ControlSchema.js"
+      },
+      "require": {
+        "types": "./dist/cjs/ControlSchema.d.ts",
+        "default": "./dist/cjs/ControlSchema.js"
+      }
+    },
+    "./ControlServer": {
+      "import": {
+        "types": "./dist/esm/ControlServer.d.ts",
+        "default": "./dist/esm/ControlServer.js"
+      },
+      "require": {
+        "types": "./dist/cjs/ControlServer.d.ts",
+        "default": "./dist/cjs/ControlServer.js"
+      }
+    },
+    "./Credential": {
+      "import": {
+        "types": "./dist/esm/Credential.d.ts",
+        "default": "./dist/esm/Credential.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Credential.d.ts",
+        "default": "./dist/cjs/Credential.js"
+      }
+    },
+    "./CredentialCipher": {
+      "import": {
+        "types": "./dist/esm/CredentialCipher.d.ts",
+        "default": "./dist/esm/CredentialCipher.js"
+      },
+      "require": {
+        "types": "./dist/cjs/CredentialCipher.d.ts",
+        "default": "./dist/cjs/CredentialCipher.js"
+      }
+    },
+    "./CredentialStore": {
+      "import": {
+        "types": "./dist/esm/CredentialStore.d.ts",
+        "default": "./dist/esm/CredentialStore.js"
+      },
+      "require": {
+        "types": "./dist/cjs/CredentialStore.d.ts",
+        "default": "./dist/cjs/CredentialStore.js"
+      }
+    },
+    "./DispatchReader": {
+      "import": {
+        "types": "./dist/esm/DispatchReader.d.ts",
+        "default": "./dist/esm/DispatchReader.js"
+      },
+      "require": {
+        "types": "./dist/cjs/DispatchReader.d.ts",
+        "default": "./dist/cjs/DispatchReader.js"
+      }
+    },
+    "./Lineage": {
+      "import": {
+        "types": "./dist/esm/Lineage.d.ts",
+        "default": "./dist/esm/Lineage.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Lineage.d.ts",
+        "default": "./dist/cjs/Lineage.js"
+      }
+    },
+    "./Migrations": {
+      "import": {
+        "types": "./dist/esm/Migrations.d.ts",
+        "default": "./dist/esm/Migrations.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Migrations.d.ts",
+        "default": "./dist/cjs/Migrations.js"
+      }
+    },
+    "./Monitor": {
+      "import": {
+        "types": "./dist/esm/Monitor.d.ts",
+        "default": "./dist/esm/Monitor.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Monitor.d.ts",
+        "default": "./dist/cjs/Monitor.js"
+      }
+    },
+    "./ScopedToken": {
+      "import": {
+        "types": "./dist/esm/ScopedToken.d.ts",
+        "default": "./dist/esm/ScopedToken.js"
+      },
+      "require": {
+        "types": "./dist/cjs/ScopedToken.d.ts",
+        "default": "./dist/cjs/ScopedToken.js"
+      }
+    },
+    "./SqlControlRuntime": {
+      "import": {
+        "types": "./dist/esm/SqlControlRuntime.d.ts",
+        "default": "./dist/esm/SqlControlRuntime.js"
+      },
+      "require": {
+        "types": "./dist/cjs/SqlControlRuntime.d.ts",
+        "default": "./dist/cjs/SqlControlRuntime.js"
+      }
+    },
+    "./SqlCredentialStore": {
+      "import": {
+        "types": "./dist/esm/SqlCredentialStore.d.ts",
+        "default": "./dist/esm/SqlCredentialStore.js"
+      },
+      "require": {
+        "types": "./dist/cjs/SqlCredentialStore.d.ts",
+        "default": "./dist/cjs/SqlCredentialStore.js"
+      }
+    },
+    "./Steering": {
+      "import": {
+        "types": "./dist/esm/Steering.d.ts",
+        "default": "./dist/esm/Steering.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Steering.d.ts",
+        "default": "./dist/cjs/Steering.js"
+      }
+    },
+    "./SystemFlows": {
+      "import": {
+        "types": "./dist/esm/SystemFlows.d.ts",
+        "default": "./dist/esm/SystemFlows.js"
+      },
+      "require": {
+        "types": "./dist/cjs/SystemFlows.d.ts",
+        "default": "./dist/cjs/SystemFlows.js"
+      }
+    },
+    "./WebCryptoCipher": {
+      "import": {
+        "types": "./dist/esm/WebCryptoCipher.d.ts",
+        "default": "./dist/esm/WebCryptoCipher.js"
+      },
+      "require": {
+        "types": "./dist/cjs/WebCryptoCipher.d.ts",
+        "default": "./dist/cjs/WebCryptoCipher.js"
+      }
+    },
+    "./WebhookChannel": {
+      "import": {
+        "types": "./dist/esm/WebhookChannel.d.ts",
+        "default": "./dist/esm/WebhookChannel.js"
+      },
+      "require": {
+        "types": "./dist/cjs/WebhookChannel.d.ts",
+        "default": "./dist/cjs/WebhookChannel.js"
+      }
+    },
+    "./index": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./test/TestControl": {
+      "import": {
+        "types": "./dist/esm/test/TestControl.d.ts",
+        "default": "./dist/esm/test/TestControl.js"
+      },
+      "require": {
+        "types": "./dist/cjs/test/TestControl.d.ts",
+        "default": "./dist/cjs/test/TestControl.js"
+      }
+    },
+    "./Health": {
+      "import": {
+        "types": "./dist/esm/Health.d.ts",
+        "default": "./dist/esm/Health.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Health.d.ts",
+        "default": "./dist/cjs/Health.js"
+      }
+    }
+  },
+  "files": [
+    "src/**/*.ts",
+    "dist/**/*.js",
+    "dist/**/*.js.map",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "dist/**/package.json",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "docs/"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "tag": "next"
+  },
+  "dependencies": {
+    "@smthrs/model": "1.0.0-rc.3",
+    "@smthrs/canonical": "1.0.0-rc.3",
+    "@smthrs/crypto": "1.0.0-rc.3",
+    "@smthrs/database": "1.0.0-rc.3",
+    "@smthrs/journal": "1.0.0-rc.3",
+    "@smthrs/notifications": "1.0.0-rc.3",
+    "@smthrs/plan": "1.0.0-rc.3",
+    "@smthrs/registry": "1.0.0-rc.3",
+    "@smthrs/run-store": "1.0.0-rc.3",
+    "@smthrs/flow": "1.0.0-rc.3"
+  },
+  "devDependencies": {
+    "@effect/language-service": "0.87.2",
+    "@effect/vitest": "4.0.0-rc.115",
+    "@eslint/js": "9.39.5",
+    "@smthrs/core": "1.0.0-rc.3",
+    "@smthrs/engine-store": "1.0.0-rc.3",
+    "@smthrs/jj": "1.0.0-rc.3",
+    "@smthrs/plan-store": "1.0.0-rc.3",
+    "@smthrs/step-cache": "1.0.0-rc.3",
+    "@smthrs/time-travel": "1.0.0-rc.3",
+    "@types/node": "26.4.1",
+    "@vitest/coverage-v8": "5.0.0",
+    "dprint": "0.57.1",
+    "effect": "4.0.0-rc.115",
+    "esbuild": "0.28.2",
+    "eslint": "9.39.5",
+    "eslint-import-resolver-typescript": "4.4.5",
+    "eslint-plugin-import": "2.32.0",
+    "eslint-plugin-jsdoc": "64.3.4",
+    "eslint-plugin-unicorn": "65.0.0",
+    "madge": "8.0.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.69.0",
+    "vitest": "5.0.0"
+  },
+  "peerDependencies": {
+    "effect": "4.0.0-rc.115"
+  },
+  "scripts": {
+    "lint": "eslint src --max-warnings=0 && dprint check",
+    "format": "dprint fmt",
+    "build": "node scripts/build.mjs",
+    "check": "tsc -b tsconfig.json && tsc -p tsconfig.test.json --noEmit",
+    "circular": "node scripts/circular.mjs",
+    "test": "vitest",
+    "coverage": "node ../flows/database/scripts/test-matrix.mjs",
+    "test:matrix": "node ../flows/database/scripts/test-matrix.mjs"
+  }
 }