wicked-crew-api-types 0.29.0 → 0.31.0

package/index.d.ts

@@ -802,7 +802,51 @@ export interface DataUsedEvent {
   files: string[];
 }
 
-/** §3 B1 — the gate's decision depth, emitted alongside `gateDecided`. */
+/**
+ * The layer that denied a unit — a stable token (wicked-core `UnitDenial.source`):
+ * - `governance` — the unit's own gate; `input_governance` — the tool-call hook / boundary;
+ * - `pinned_validator` — the deterministic re-verify; `agent_validator` — the LLM judge;
+ *   `evaluator` — the evaluator≠creator second pass;
+ * - `worker_failure` — the CLI process failed; `substance` — no reviewable substance;
+ *   `deliverables` — declared deliverables missing; `elicitation` — ACP elicitation ended;
+ * - `worktree_guard` — a def-driven, agent-executed `executes_code: false` phase changed the
+ *   worktree it was reviewing (wicked-core F-036, see {@link EvaluatorMutatedWorktreeEvent}) — or
+ *   the guard could not re-verify it (no baseline persisted at dispatch, comparison unverifiable),
+ *   which denies fail-closed WITHOUT that event; `reason` names the cause;
+ * - `repo_checks` — the repository's own checks failed in the worktree (wicked-core F-039, see
+ *   {@link RepoChecksEvaluatedEvent}).
+ * Open-ended (`string & {}`) so a newer engine's source parses in an older studio.
+ */
+export type UnitDenialSource =
+  | 'governance'
+  | 'input_governance'
+  | 'pinned_validator'
+  | 'agent_validator'
+  | 'evaluator'
+  | 'worker_failure'
+  | 'substance'
+  | 'deliverables'
+  | 'elicitation'
+  | 'worktree_guard'
+  | 'repo_checks'
+  | (string & {});
+
+/** The MACHINE-READABLE twin of `gateEvaluated.denialReason` (wicked-core `UnitDenial`, camelCase on
+ *  the wire): which layer denied, the prose reason, and — when the layer recorded them — the
+ *  conformance claim id, the firing rule ids, the refused tool and the unit-phase token. `null`
+ *  fields are the engine's `Option::None`, never absent. */
+export interface UnitDenial {
+  source: UnitDenialSource;
+  reason: string;
+  claimId: string | null;
+  ruleIds: string[];
+  deniedTool: string | null;
+  phase: string | null;
+}
+
+/** §3 B1 — the gate's decision depth, emitted alongside `gateDecided`. `denial` is the structured
+ *  twin of `denialReason`: `null` when the gate approved, else the winning layer (deny-dominates) —
+ *  `worktree_guard` and `repo_checks` are the two wicked-core F-036/F-039 layers. */
 export interface GateEvaluatedEvent {
   type: 'gateEvaluated';
   session: string;
@@ -813,7 +857,10 @@ export interface GateEvaluatedEvent {
   agentVerdict: string | null;
   agentReasoning: string | null;
   evaluatorPass: boolean | null;
+  /** Policy ids the evaluator≠creator pass applied (empty = vacuous default-allow, FINDING-025). */
+  evaluatorPolicies: string[];
   denialReason: string | null;
+  denial: UnitDenial | null;
   combined: boolean;
 }
 
@@ -979,6 +1026,109 @@ export interface GovernanceUnenforcedEvent {
   reason: string;
 }
 
+/** One path an `executes_code: false` phase changed, with git's one-letter status
+ *  (`A`dded, `M`odified, `D`eleted, `T`ype-changed). */
+export interface WorktreeChangedPath {
+  status: string;
+  path: string;
+}
+
+/** wicked-core F-036 — an `executes_code: false` phase (an evaluator, a recon rung, a review) CHANGED
+ *  the worktree it was working in. Scope: the guard governs a DEF-DRIVEN, AGENT-executed
+ *  `executes_code: false` phase (`WorkUnit.worktree_guarded`, derived at plan time); Tool phases —
+ *  crew's `deliver-pr` included — and prose-planned runs are not guarded. The engine snapshots the
+ *  tree at dispatch and takes the FINAL snapshot after everything the phase owned has run (seat
+ *  quiesced — its process group killed, a persistent session closed — judge rendered, repo checks
+ *  done), for EVERY seat and carrier regardless of governance adapter. `changed` is EVERY path that
+ *  differs, and every one DENIES the unit (its `gateEvaluated.denial.source` is `worktree_guard`):
+ *  there are NO exemptions — not documentation, not a declared `required_deliverables` entry, not
+ *  tool state (a phase whose deliverable must live in the tree is a code phase; the engine's own
+ *  `tmp/` scratch is excluded from the snapshot by construction). `headMoved`: the run branch was
+ *  committed/amended/reset. The event is emitted exactly when a MUTATION denies the unit (`changed`
+ *  non-empty and/or `headMoved`), so an operator always sees what an evaluator wrote. A
+ *  `worktree_guard` denial can also come from the guard's fail-closed paths — no baseline persisted
+ *  at dispatch, or the comparison unverifiable — and those carry NO `evaluatorMutatedWorktree`
+ *  event: the gate's `denial.reason` names the cause. Evaluator ≠ creator is no longer a promise the
+ *  seat keeps; it is a check.
+ *
+ *  `type` alias on purpose, not `interface`: only anonymous object types satisfy `CoreEvent`'s index
+ *  signature, which is what lets the frame flow through CoreEvent-typed broadcast seams. */
+export type EvaluatorMutatedWorktreeEvent = {
+  type: 'evaluatorMutatedWorktree';
+  session: string;
+  ord: number;
+  attempt: number;
+  /** The seat that ran the unit (`assigned_cli`; `''` when unassigned). */
+  cli: string;
+  /** The workflow phase id (`verify`, `adversarial-review`, …). */
+  phase: string;
+  beforeTree: string;
+  afterTree: string;
+  headMoved: boolean;
+  changed: WorktreeChangedPath[];
+};
+
+/** One repository check the engine ran in the run's worktree (wicked-core F-039). */
+export interface RepoCheckRun {
+  /** `install` | `typecheck` | `lint` | `test` | `cargo-test`. */
+  name: string;
+  argv: string[];
+  /** Provenance an operator can verify: `package.json scripts.test`, `Cargo.toml`, … */
+  source: string;
+  /** The process exit code; `null` when it produced none (timed out / could not spawn). */
+  exitCode: number | null;
+  timedOut: boolean;
+  /** The OS error when the command could not be started (binary not on PATH, …); `null` otherwise
+   *  — the key is always present on the wire. */
+  spawnError: string | null;
+  durationMs: number;
+  /** The last 4 KiB of each stream — the evidence, verbatim. */
+  stdoutTail: string;
+  stderrTail: string;
+}
+
+/** wicked-core F-039 — the engine ran the repository's OWN checks in the worktree for the def's
+ *  code-verifying unit (`verified_evidence` with an `executes_code` creator upstream: `bug/verify`,
+ *  `feature/test`, `migration/verify`) and folded them into the gate as a deterministic floor. Fires
+ *  once per fold, just before `gateEvaluated` (whose `hasDeterministicFloor`/`criterion` include this
+ *  floor). `checks` is what actually ran, in order (`package.json` `typecheck`/`lint`/`test` via the
+ *  lockfile's package manager, an `install` first when `node_modules/` is absent; `Cargo.toml` →
+ *  `cargo test`); `skipped` names detected checks not run because an earlier one failed. `passed:
+ *  false` ⇒ the unit is denied (`denial.source` is `repo_checks`).
+ *
+ *  The checks are repo-controlled code and run ONLY inside an OS write boundary (macOS
+ *  `sandbox-exec` / Linux `bwrap`: writes confined to the worktree, the curated secret directories
+ *  unreadable, network open for installs) with an isolated `HOME`, `npm_config_cache`, `CARGO_HOME`,
+ *  `CARGO_TARGET_DIR` and `XDG_*` under `<worktree>/tmp/wicked-checks/`, and with a MINIMAL
+ *  environment — the daemon's env is cleared and only `PATH`, locale (`LANG`/`LC_*`), `TERM`,
+ *  `USER`/`LOGNAME`, `RUSTUP_HOME`, the Windows shell essentials and those isolation overrides
+ *  (`CI=1` included) reach a check: no token, API key or `WICKED_*` variable does; installs are always
+ *  `--ignore-scripts` (`--no-package-lock` when the repo ships no lockfile). When NO boundary can be
+ *  armed (no sandbox tool on the host — Windows) the checks do NOT run and the floor FAILS
+ *  (`passed: false`, `checks: []`, the reason on the unit record) — repo-controlled scripts never
+ *  run unsandboxed. Detection is fail-closed the same way: a `package.json` that cannot be read or
+ *  parsed, or a symlinked manifest/lockfile/`node_modules` (every probe `lstat`s, opens `O_NOFOLLOW`
+ *  and `fstat`s the opened descriptor before reading — links are never followed), FAILS the floor.
+ *  Only a repo with NO DETECTABLE check is the disclosed vacuous pass (`checks: []`, `passed:
+ *  true`): no manifest at all, or a readable `package.json` with no string `typecheck`/`lint`/`test`
+ *  script and no `Cargo.toml`. A manifest that cannot be read or trusted still FAILS.
+ *  "Done" for a verify phase is now the exit code the engine observed, not the seat's account of
+ *  having run the suite. `type` alias on purpose — see {@link EvaluatorMutatedWorktreeEvent}. */
+export type RepoChecksEvaluatedEvent = {
+  type: 'repoChecksEvaluated';
+  session: string;
+  ord: number;
+  attempt: number;
+  passed: boolean;
+  criterion: string;
+  checks: RepoCheckRun[];
+  skipped: string[];
+};
+
+/** The gate-evidence events (wicked-core F-036/F-039) as a discriminated union for consumers that
+ *  narrow on `type`; they also flow through the permissive {@link CoreEvent}. */
+export type GateEvidenceEvent = EvaluatorMutatedWorktreeEvent | RepoChecksEvaluatedEvent;
+
 // ── P2 decisions-full observability events (wicked-core EVT-001/012/013) ────
 
 /** P2 — a structured workflow def was selected; fires once per session, after SessionStarted and before
@@ -2710,6 +2860,128 @@ export interface InteractiveDocDeleteResponse {
   ledger: InteractiveDocDeleteLedgerReport;
 }
 
+/** One hand-pinned demo step on a `kind: "demo"` create (api-types 0.30.0): the wizard's ordered
+ *  steps the governed run authors the spec from (ADR-0018: the agent authors, the service records). */
+export interface InteractiveDemoStepDraft {
+  index: number;
+  subject: string;
+  action: string;
+}
+
+/**
+ * The body of `POST /projects/:projectId/interactive/api/docs` as crew's proxy understands it
+ * (acceptance finding F-046; api-types 0.30.0 — the studio types its create from THIS declaration,
+ * no local mirror). The bridge's own fields (`name`, `kind`, `html`, `brief`, `source_paths`,
+ * `url`, `demo_steps`, `style`, `project`, `source_message_id`) are relayed as-is — this type
+ * documents the two things CREW adds at the proxy before forwarding:
+ *
+ *  - `repo_ref` / `repo_refs` — the repository (or repositories) this document is ABOUT, each a
+ *    registered repo id, its registry name, or its root directory's basename. Crew validates them
+ *    against the project's `crew.repo` members BEFORE the bridge sees the request (a miss is the
+ *    400 {@link InteractiveDocCreateRefusal}, nothing created), strips them from the forwarded
+ *    body, and remembers the binding so the governed draft/demo run is grounded on THOSE repos
+ *    (offline snapshot + the project graph) — never on the project's first member. Unfiled
+ *    (`default` mount) documents cannot name a repository.
+ *  - `style` — passed through when given; when ABSENT crew infers it from the brief's format
+ *    words (print-ready / A4 / brochure → `brochure`; slides / deck → `ppt`; memo / whitepaper →
+ *    `doc`) so the bridge's own print instructions apply to a print brief. No format words → the
+ *    bridge's `web` default.
+ */
+export interface InteractiveDocCreateRequest {
+  /** The doc name; the bridge slugifies it (409 when taken or retired). */
+  name?: string;
+  /** Omitted = a plain html doc (`html` required); `source` = generated from brief/sources; `demo` = a recording. */
+  kind?: 'source' | 'demo';
+  /** A plain html doc's content (or a `source` doc's seed). */
+  html?: string;
+  brief?: string;
+  source_paths?: string[];
+  /** `kind: "demo"` — the live app URL to record against. */
+  url?: string;
+  /** `kind: "demo"` — hand-pinned steps; omitted = the run authors them from the brief. */
+  demo_steps?: InteractiveDemoStepDraft[];
+  style?: 'web' | 'ppt' | 'brochure' | 'doc';
+  /** Crew project binding (DES-PROJECT-001 §2.3): registration is the authority. */
+  project?: string;
+  /** The thread message this generation came from (§7.6). */
+  source_message_id?: string;
+  /** ONE subject repository: a repo id, its name, or its root basename. */
+  repo_ref?: string;
+  /** SEVERAL subject repositories (at most 8); the union with `repo_ref`, de-duplicated. */
+  repo_refs?: string[];
+}
+
+/**
+ * The bridge's answer to a successful `POST /projects/:projectId/interactive/api/docs`, relayed
+ * verbatim by crew's proxy (api-types 0.30.0): interactive's `{ name, head, … }` — `generating`
+ * for a `kind: "source"` doc whose first draft a governed run now produces, `learning` for a demo,
+ * `project_id` echoed for a project-bound doc.
+ */
+export interface InteractiveDocCreateResult {
+  name: string;
+  head: number;
+  kind?: 'doc' | 'demo';
+  generating?: boolean;
+  learning?: boolean;
+  project_id?: string;
+}
+
+/**
+ * Crew's 400 on `POST /projects/:projectId/interactive/api/docs` when the request names a
+ * repository the document cannot be grounded on (F-046; api-types 0.30.0). Nothing was created
+ * on the bridge.
+ */
+export interface InteractiveDocCreateRefusal {
+  /** Human-readable, names the fix (attach the repo, pick one of `available`, name it by id, …). */
+  error: string;
+  /**
+   * `repo_not_in_project` — a ref matched no member repo; `unfiled_doc_repo` — a repo named on the
+   * Unfiled mount; `invalid_repo_ref` — junk spelling / shape / over the cap; `ambiguous_repo_ref`
+   * — a name or basename shared by several member repos (name it by id); `project_mismatch` — the
+   * body's `project` is not the route's project (or is present on the Unfiled mount). The proxy
+   * canonicalizes an OMITTED `project` from the route.
+   */
+  code: 'repo_not_in_project' | 'unfiled_doc_repo' | 'invalid_repo_ref' | 'ambiguous_repo_ref' | 'project_mismatch';
+  /** The refs the request named, as spelled (best-effort stringified when malformed). */
+  requested: string[];
+  /** The subset of `requested` that matched no member repo (`repo_not_in_project` only). */
+  missing?: string[];
+  /** `ambiguous_repo_ref`: each ambiguous ref with the member repos it names. */
+  ambiguous?: Array<{ ref: string; candidates: Array<{ id: string; name: string }> }>;
+  /** The project's `crew.repo` members the request could have named. */
+  available?: Array<{ id: string; name: string }>;
+}
+
+/**
+ * The 502 the create earns when the bridge dropped the connection AFTER the request had reached it
+ * (api-types 0.30.0): the document may already exist, so the proxy never replays the POST — list the
+ * project's documents before creating again.
+ */
+export interface InteractiveDocCreateUndetermined {
+  code: 'create_undetermined';
+  error: string;
+}
+
+/**
+ * The payload of `wicked.interactive.status.posted` as crew's own seams emit it (`producer_id:
+ * "wi-crew"`, relayed on `/ws` inside an `interactiveEvent` frame; api-types 0.30.0). Acceptance finding F-045: every
+ * seam emit — status narration, the terminal error/complete lines, and the closing
+ * `draft.completed` / `edit.completed` / `demo.requested` — now carries `project_id` for a
+ * project-bound document (omitted for an Unfiled one), exactly like the bridge's own emits, so a
+ * skin can file the frame under the right thread. A skin should ALSO match frames by
+ * `document_id` alone when the doc is open under exactly one mount (belt and braces).
+ */
+export interface InteractiveStatusPosted {
+  ts: string;
+  document_id: string;
+  /** Present for a project-bound document. */
+  project_id?: string;
+  state: 'processing' | 'working' | 'asking' | 'complete' | 'error';
+  message?: string;
+  /** The edit seam stamps the handoff version it is answering. */
+  version?: number;
+}
+
 /**
  * One row of `GET /projects/:projectId/interactive/api/docs` (crew#472) — the bridge's own
  * `GET /api/docs` row (interactive's `listDocs` shape, relayed field-for-field) stamped with the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-crew-api-types",
-  "version": "0.29.0",
+  "version": "0.31.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",