wicked-crew-api-types 0.130.0 → 0.132.0

package/index.d.ts

@@ -1231,21 +1231,45 @@ export interface RosterSeat {
   [k: string]: unknown;
 }
 
-/** `RosterSeat.version` (api-types 0.115.0). */
-export interface SeatVersion {
+/** Why a pinned seat reads `unproven` (api-types 0.131.0, crew#1004): `no_answer` — the pin's own
+ *  `--version` check got no answer, so nothing confirms the build (it was not shown to differ);
+ *  `different_build` — the check answered naming a build other than the pinned one (`observed`);
+ *  `invalid_answer` — the check answered, but in a shape it cannot confirm (its first line is not
+ *  the pinned build byte for byte) and without naming another build. A build is named by its id
+ *  alone, pre-release and build suffixes included (`1.18.31`, `1.17.18-rc.1`), only as a whole
+ *  token (`1.18.31.4` names none), never by the presentation around it: `opencode (1.17.18)`, a
+ *  colour-coded `1.17.18` and `v1.17.18,` name only the pinned build; `1.17.18-beta` names another. */
+export type SeatVersionUnprovenWhy = 'no_answer' | 'different_build' | 'invalid_answer';
+
+/**
+ * `RosterSeat.version` (api-types 0.115.0; `why` and `observed` 0.131.0). `status`: `proven` — the
+ * pin's check answered with the pinned build; `unproven` — it did not, and governance fails closed,
+ * with `why` saying which case and, on `different_build`, `observed` naming the build the check
+ * saw; `no_pin` — the seat pins no build.
+ *
+ * `status` comes from the pin's check alone (it mirrors the engine's spawn-time check), never from
+ * `installed`. The two are separate snapshots: the seat's own `--version` reading (`installed`,
+ * `checked_at`) and the pin's check are cached apart, each with its own TTL, so for up to one TTL
+ * after an upgrade `installed` may still read the pinned build while `why` is already
+ * `different_build`. The build the check saw is `observed`, never `installed`; `installed` equal to
+ * `proven` says nothing about the pin holding (crew#1004).
+ */
+export type SeatVersion = {
   /** The first non-empty line of the seat's `--version`, home written `~`; `null` when it did not answer. */
   installed: string | null;
-  /** The build the seat's governance was proven on (`acp.verified_version`); `null` when it pins none. */
-  proven: string | null;
-  /** `proven` — the installed build is the pinned one; `unproven` — it is not (governance fails
-   *  closed); `no_pin` — the seat pins no build. */
-  status: 'proven' | 'unproven' | 'no_pin';
-  /** ISO-8601 of the reading. */
+  /** ISO-8601 of the `installed` reading. */
   checked_at: string;
   /** How the binary on PATH was installed, from its resolved path: under `node_modules` = `npm`, a
    *  Homebrew prefix = `brew`, else `other`; `null` when it is not on PATH. */
   install_source: 'npm' | 'brew' | 'other' | null;
-}
+} & (
+  // `proven`: the build the seat's governance was proven on (`acp.verified_version`), `null` only
+  // when it pins none. `observed`: the build the pin's check saw, on `different_build` only.
+  | { status: 'no_pin'; proven: null }
+  | { status: 'proven'; proven: string }
+  | { status: 'unproven'; proven: string; why: 'no_answer' | 'invalid_answer' }
+  | { status: 'unproven'; proven: string; why: 'different_build'; observed: string }
+);
 
 /** `RosterSeat.account` (api-types 0.115.0). */
 export interface SeatAccount {
@@ -1304,7 +1328,10 @@ export type SeatQeReviewer =
 /**
  * One `RosterSeat.issues` entry (api-types 0.115.0). Today's codes: `signed_out`, `qe_blocked`
  * (problems); `quota`, `usage_limit`, `benched`, `codex_worktree`, `host_floor` and `host_floor_unknown`
- * (unreleased, wicked-core#976), `version_unproven`,
+ * (unreleased, wicked-core#976), `version_unproven` (`params.why`: `no_answer` | `different_build` | `invalid_answer`,
+ * api-types 0.131.0 — the same as `RosterSeat.version.why`; `params.observed`, on `different_build`
+ * only: the build the pin's check saw, the same as `RosterSeat.version.observed`; `params.proven`;
+ * `params.installed` when the seat's own `--version` answered),
  * `unchecked` (`params.why`: `no_governance` | `no_host_boundary`), `fence_scoped`,
  * `live_check_failed` (warnings); `opt_in`, `no_qe`, `unverified` (notes). A client must tolerate
  * an unknown code.
@@ -1530,7 +1557,15 @@ export interface RunDiff {
   base?: string;
 }
 
-/** The daemon's cached open-gate record (`GET /runs/:id/gate`, DES-STUDIO-001 §3.3). */
+/**
+ * The daemon's cached open-gate record (`GET /runs/:id/gate`, DES-STUDIO-001 §3.3).
+ *
+ * (api-types 0.132.0) The read answers **503** `{ error, code: 'gate_unstable' }` when live gate
+ * events kept landing while the daemon read the run's record and nothing could be verified — retry
+ * — and **409** `{ error, code: 'gate_unknown' }` when the engine's open gate rows disagree on the
+ * ord. It serves the newest of the agreeing rows: the one a decision is judged by.
+ * A decision is never authorized from this record: see {@link GateDecision.ord}.
+ */
 export interface GateInfo {
   runId: string;
   ord: number;
@@ -1551,6 +1586,20 @@ export interface GateInfo {
    * kind, never infer it from the unit. ABSENT on an older daemon and when the engine did not say.
    */
   gateKind?: string;
+  /**
+   * (api-types 0.132.0; issue #969) The answer tokens the engine offered on this gate — mirrors the
+   * opening `awaitingHuman.choices` (e.g. a `team_dispute` gate's
+   * `['approve', 'request_changes', 'reject']`), so a client that missed the live frame (reload,
+   * late join, second tab) renders the same answers. ABSENT on an older daemon and when the engine
+   * offered none; never empty.
+   */
+  choices?: string[];
+  /**
+   * (api-types 0.132.0; issue #969) The index into {@link GateInfo.choices} of the engine's
+   * recommended answer — mirrors `awaitingHuman.recommended`. ABSENT on an older daemon, when the
+   * engine recommended none, and whenever `choices` is absent.
+   */
+  recommended?: number;
   /** (crew ≥ 0.9.0) The gated unit's persisted receipt (`WorkUnit.assurance`) — what assured the
    *  work this gate asks about. `null` when the unit carries none (no gate evaluated it yet, or an
    *  older engine); ABSENT on an older daemon. */
@@ -1647,7 +1696,16 @@ export interface GateDecision {
    * mismatch, confirming nothing: the gate was answered elsewhere or replaced while the decision
    * waited (a skin's undo window). When the daemon cannot tell which gate is open it answers
    * **409** `{ error, code: 'gate_unknown' }` — refresh the gate and decide again. Absent = today's
-   * behaviour (no gate check).
+   * behaviour (no gate check). (api-types 0.132.0) The comparison is made against the engine's
+   * durable open gate rows, read under the run's decision lock immediately before the confirm —
+   * never the daemon's gate cache — and judged by ORD AGREEMENT, not row count:
+   * - no open gate row → **409** `gate_unknown`;
+   * - open rows that disagree on the ord (the record is ambiguous) → **409** `gate_unknown`;
+   * - the rows agree on an ord other than this one → **409** `gate_changed` with `openOrd`;
+   * - the rows agree on this ord — one row or several (a keyed plan gate plus its recovery row) →
+   *   authorized.
+   * The same reading judges a decision without `ord` (ambiguous rows → `gate_unknown`) and a gated
+   * `POST /runs/:id/resume` or `/reassign`.
    */
   ord?: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-crew-api-types",
-  "version": "0.130.0",
+  "version": "0.132.0",
   "description": "The wire contract of the wicked-crew daemon's /api/v1 REST surface and /ws CoreEvent frames \u2014 types only, zero runtime",
   "type": "module",
   "types": "./index.d.ts",