wicked-crew-api-types 0.178.0 → 0.186.0

package/index.d.ts

@@ -12316,7 +12316,61 @@ export interface PutDeliveryFreezeBody {
  * sources: registered through the same preview/save, but with NO tools — nothing of theirs is ever
  * offered to a governed run. Their preview answers {@link McpPreviewResponse.source} (the catalog).
  */
-export type McpUpstreamKind = 'mcp-stdio' | 'mcp-http' | 'rest' | 'sql' | 'graphql';
+export type McpUpstreamKind = 'mcp-stdio' | 'mcp-http' | 'rest' | 'sql' | 'graphql' | 'toolbox-source';
+
+// ── The one registry's entry (api-types 0.183.0, DES-KNOWLEDGE-DATA-001 §5) ─────────────────────
+
+/**
+ * (api-types 0.183.0, DES-KNOWLEDGE-DATA-001 §5.1) A database source as MCP Toolbox for Databases models it: its
+ * own source document (`kind: source`, `type`, that type's fields), which the registry stores as the source of
+ * truth for `kind: 'toolbox-source'`. Checked against crew's deployment policy for the pinned Toolbox release
+ * (v1.15.0) at preview and at save: a field that bypasses the address check (`connectionString`), names a host
+ * path, or tunes the driver is a 400 `refused_field`; a field only crew writes (`name`, `queryParams`,
+ * `connectTimeout`: the TLS settings, startup parameters and timeouts) a 400 `crew_written_field`; any other
+ * unknown field a 400 `unknown_field`. `password` is exactly `"${WICKED_SRC_1}"`, the placeholder naming
+ * `auth.ref`'s secret (a value is a 400 `secret_literal`); `${` anywhere else is a 400 `interpolation`.
+ */
+// A type alias (not an interface) so it is assignable to a plain record: the route takes any object and the
+// deployment policy judges each field.
+export type ToolboxSourceDocument = {
+  kind: 'source';
+  /** v1: `postgres` only (any other type is a 400 `unsupported_type`). */
+  type: 'postgres';
+  /** One host name or IP address. */
+  host: string;
+  /** Toolbox takes the port as a string, `"1"`-`"65535"`. */
+  port: string;
+  database: string;
+  user: string;
+  password?: string;
+};
+
+/**
+ * (api-types 0.183.0) How crew reads a database source: `native` (crew's own adapter: K1's driver, dialer and
+ * read policy; Postgres) or `toolbox` (one Toolbox process per source; a preview is a 501 `runtime_unavailable`
+ * on a daemon without the Toolbox runtime).
+ */
+export type McpSourceRuntime = 'native' | 'toolbox';
+
+/**
+ * (api-types 0.183.0, DES-KNOWLEDGE-DATA-001 §7.1) What a tool's answer discloses: `rows` (needs a source's
+ * "query" switch), `structure` (needs "see"), or `none`. Reviewed at preview, bound to the tool's saved schema
+ * hash; `null` = not reviewed, or reviewed against a schema that has since changed. A tool with no class in force
+ * is offered to no agent.
+ */
+export type McpToolDisclosure = 'none' | 'structure' | 'rows';
+
+/**
+ * (api-types 0.183.0, DES-KNOWLEDGE-DATA-001 §7.1) A data source's agent switches: `see` (on by default),
+ * `query` (off by default; needs `see`; turned off again by a descriptor change and by a restore), `projects`
+ * (none by default) and `everyProject` (an explicit choice). Set by a human operator only.
+ */
+export interface McpSourceAgents {
+  see: boolean;
+  query: boolean;
+  projects: string[];
+  everyProject: boolean;
+}
 /**
  * A tool's class, from its own `tools/list` annotations (never from a carrier): `read` when
  * `readOnlyHint` is true; else `destructive` unless `destructiveHint` is false; else `write`. A tool
@@ -12418,6 +12472,16 @@ export interface McpServerConfigBody {
    * from `POST /apps/uploads` (a snapshot digest), not from a preview.
    */
   sql?: SqlSourceConfigBody;
+  /**
+   * (api-types 0.183.0, DES-KNOWLEDGE-DATA-001 §5.1) `toolbox-source` only: Toolbox's own source document. Its
+   * password is the secret behind `auth.ref` (`auth` takes only `ref`). A `sql` body with Postgres settings is
+   * saved as the same document.
+   */
+  toolbox?: ToolboxSourceDocument;
+  /** (api-types 0.183.0) `toolbox-source` only: default `native`. */
+  runtime?: McpSourceRuntime;
+  /** (api-types 0.183.0) `toolbox-source` only: the TLS choice crew writes the driver's settings from; default `verify-full`. */
+  tls?: { mode: 'verify-full' | 'disable'; ca?: string };
   /**
    * (api-types 0.175.0) `sql` only: the views (and materialized views) a read may name, as
    * `schema.view` (MySQL `database.view`). A view not listed is refused by the read policy.
@@ -12488,9 +12552,16 @@ export interface McpTool {
   schemaHash: string | null;
   /** The hash the last probe saw. */
   observedSchemaHash: string;
+  /** (api-types 0.183.0) The disclosure class in force; `null` = none reviewed for the saved schema. */
+  disclosure: McpToolDisclosure | null;
 }
 
 export interface McpServer {
+  /**
+   * (api-types 0.183.0, DES-KNOWLEDGE-DATA-001 §5.1) The entry's immutable id. Estate's source documents, `deps`,
+   * grants and records key on it, never on the name: a name removed and registered again is a new id.
+   */
+  id: string;
   name: string;
   kind: McpUpstreamKind;
   command: string | null;
@@ -12518,6 +12589,19 @@ export interface McpServer {
    * `allowWrites`). Queries, actions and grants bind to it.
    */
   descriptorHash?: string;
+  /**
+   * (api-types 0.183.0, DES-KNOWLEDGE-DATA-001 §5.1, §5.4) A database source stored as its Toolbox document. A
+   * `native` one still answers `kind: 'sql'` and `sql` (the read-path projection every existing reader uses).
+   * `descriptorVersion` 1 = mapped from a K1 record, hashed with K1's function (locks and grants unchanged);
+   * 2 = written by a save, hashed over the canonical execution descriptor.
+   */
+  runtime?: McpSourceRuntime;
+  toolbox?: ToolboxSourceDocument;
+  descriptorVersion?: 1 | 2;
+  /** The deployment policy the document was checked under, e.g. `postgres/1@toolbox-v1.15.0`. */
+  policyVersion?: string;
+  /** (api-types 0.183.0) Data sources only: the agent switches (defaults filled in). */
+  agents?: McpSourceAgents;
   /**
    * (api-types 0.174.0) `mcp-http` and `rest` only: the ranges confirmed for this server's
    * connections. A server saved before 0.174.0 shows what crew re-derived for it: the IP literal or
@@ -12549,12 +12633,77 @@ export interface McpDiscoveredServer {
   managed: boolean;
 }
 
-/** `GET /mcp/servers`. */
+/**
+ * `GET /mcp/servers`, for a human actor. (api-types 0.183.0, DES-KNOWLEDGE-DATA-001 §5.2, crew#1310) Any other
+ * actor, and `?view=agent`, gets {@link McpServersAgentResponse} instead; so do the answers of a save, a
+ * `PATCH /mcp/servers/:name` and a test for a non-human actor.
+ */
 export interface McpServersResponse {
   servers: McpServer[];
   discovered: McpDiscoveredServer[];
 }
 
+/**
+ * (api-types 0.183.0, DES-KNOWLEDGE-DATA-001 §5.2) A server as an agent may know it: no host, port, database,
+ * login, url, command, arguments, path, address, secret reference or descriptor.
+ */
+export interface McpServerAgentView {
+  id: string;
+  name: string;
+  kind: McpUpstreamKind;
+  enabled: boolean;
+  health: { state: McpHealthState };
+  /** The tools that are not `gone`. */
+  tools: Array<{ name: string; subject: string; class: McpToolClass; disclosure: McpToolDisclosure | null; enabled: boolean; status: McpToolStatus }>;
+  /** Data sources only. */
+  agents?: { see: boolean; query: boolean };
+}
+
+/** (api-types 0.183.0) `GET /mcp/servers?view=agent`, and `GET /mcp/servers` for any non-human actor. */
+export interface McpServersAgentResponse {
+  view: 'agent';
+  servers: McpServerAgentView[];
+}
+
+/**
+ * (api-types 0.183.0, DES-KNOWLEDGE-DATA-001 §5.5) `GET /mcp/registry/generations` (human operator only). Every
+ * write keeps the registry it replaces; the last 10 are kept.
+ */
+export interface McpRegistryGenerationsResponse {
+  /** The generation in force. */
+  current: number;
+  /** Newest first. */
+  generations: Array<{ generation: number; savedAt: string }>;
+}
+
+/** (api-types 0.183.0) `POST /mcp/registry/restore`. */
+export interface McpRegistryRestoreBody {
+  generation: number;
+}
+
+/**
+ * (api-types 0.183.0, DES-KNOWLEDGE-DATA-001 §5.5) `POST /mcp/registry/restore`'s 200 (human operator only;
+ * audited `mcp.registry.restored`). A restore fails closed: every source's "query" switch and Allow writes come
+ * back OFF; a server whose secret reference resolves to nothing comes back DISABLED (`secret_missing`); MCP
+ * approvals whose tool schema differs from the restored one are withdrawn first (a failed withdrawal refuses the
+ * restore, 500 `withdraw_failed`). A generation that is not kept is a 404 `unknown_generation`; one that does not
+ * parse, or holds a record crew could not have written, a 409 `generation_unreadable`, and nothing changes. The
+ * withdrawal and the commit hold every affected server's lock; when servers keep being registered meanwhile the
+ * restore gives up with a 409 `registry_busy`, having changed nothing. The registry in force before the restore is
+ * kept as a generation too.
+ */
+export interface McpRegistryRestoreResponse {
+  restored: number;
+  /** The generation the restore wrote. */
+  generation: number;
+  servers: number;
+  disabled: Array<{ name: string; code: 'secret_missing' }>;
+  queryReset: string[];
+  writesReset: string[];
+  /** The approval tokens withdrawn first. */
+  withdrawnApprovals?: string[];
+}
+
 /** The difference between the registered tools and a probe, by tool name. */
 export interface McpToolDiff {
   added: string[];
@@ -12587,6 +12736,11 @@ export interface McpPreviewTool {
    * approving it: `MCP-FIRST-USE` still asks on its first call.
    */
   enabledOnSave: boolean;
+  /**
+   * (api-types 0.183.0) The disclosure class a save gives the tool when `disclosures` does not name it: its
+   * class while its schema is unchanged, crew's own class for a tool of crew's Toolbox configuration, else `null`.
+   */
+  disclosure: McpToolDisclosure | null;
 }
 
 /**
@@ -12611,6 +12765,11 @@ export interface McpPreviewResponse {
     /** (api-types 0.175.0) `sql` only. */
     sql?: SqlSourceView;
     viewsAllowed?: string[];
+    /** (api-types 0.183.0) A database source: the Toolbox document the save will store. */
+    runtime?: McpSourceRuntime;
+    toolbox?: ToolboxSourceDocument;
+    descriptorVersion?: 1 | 2;
+    policyVersion?: string;
   };
   /**
    * (api-types 0.175.0, DES-APPS-001 §5.1) `sql`/`graphql` only: what the describe found —
@@ -12659,6 +12818,13 @@ export interface SaveMcpServerBody {
    * `egress_not_rest` for a server that is not `rest`.
    */
   allowOrigin?: string;
+  /**
+   * (api-types 0.183.0, DES-KNOWLEDGE-DATA-001 §5.1) The operator's review of what each tool discloses, by tool
+   * name (`McpPreviewTool.disclosure` is what a tool not named here gets). A name the preview does not list is a
+   * 400 `unknown_tool`. Human operator only (403 `disclosure_review_human_only`); audited
+   * `mcp.tool.disclosure_reviewed`.
+   */
+  disclosures?: Record<string, McpToolDisclosure>;
 }
 
 /**
@@ -12712,6 +12878,25 @@ export interface PatchMcpServerBody {
 export interface PatchMcpToolBody {
   enabled?: boolean;
   classOverride?: McpToolClass | null;
+  /**
+   * (api-types 0.183.0) Review what the tool discloses, against its saved schema (409 `not_registered` when the
+   * schema changed since the save). Setting a class is a human operator's only (403
+   * `disclosure_review_human_only`), audited `mcp.tool.disclosure_reviewed`; `null` clears it (the tool is then
+   * offered to no agent).
+   */
+  disclosure?: McpToolDisclosure | null;
+}
+
+/**
+ * (api-types 0.183.0, DES-KNOWLEDGE-DATA-001 §5.2) `POST /mcp/servers/:name/test`'s 200 for a NON-HUMAN actor: the
+ * server as the agent-safe projection, and `error` reduced to `"the probe failed"` (a probe's words can name the host).
+ * A save and `PATCH /mcp/servers/:name` likewise answer an {@link McpServerAgentView} to a non-human actor.
+ */
+export interface McpServerTestAgentResponse {
+  ok: boolean;
+  error: string | null;
+  diff: McpToolDiff | null;
+  server: McpServerAgentView;
 }
 
 /** `POST /mcp/servers/:name/test`'s 200: a failed probe is `ok: false` and counts toward `failing`. */
@@ -13289,6 +13474,231 @@ export interface SourceAllowWritesResponse {
   withdrawnGrants: number;
 }
 
+/**
+ * (api-types 0.184.0, DES-KNOWLEDGE-DATA-001 §7.1) A live source's agent switches. Agents reach a source
+ * only through crew's data gate (`mcp:<source>/<tool>` through the broker); Apps units get none of its tools,
+ * whatever this says (D-7). Never a write, never a credential.
+ */
+export type SourceAgentAccess = McpSourceAgents;
+
+/** `PUT /sources/:name/agents` (human operator only; each change audited). At least one field. */
+export interface SourceAgentAccessBody {
+  see?: boolean;
+  query?: boolean;
+  projects?: string[];
+  everyProject?: boolean;
+}
+
+export interface SourceAgentAccessResponse {
+  name: string;
+  agents: SourceAgentAccess;
+}
+
+/** One agent read of a source (`GET /sources/:name/agent-queries`), as crew recorded it: never the SQL, a value or a source's words. */
+export interface SourceAgentQuery {
+  /** The broker call's id. */
+  callId: string;
+  at: string;
+  runId: string;
+  unit: number;
+  attempt: number;
+  seat: string;
+  source: string;
+  /** The source's registry id. */
+  sourceId: string;
+  /** sha256 of the SQL text, hex. */
+  sqlHash: string;
+  /** `ok` (rows released), or crew's code (a read-policy code, `query_off`, `deadline`, `too_large`, `busy`, `changed_while_running`, …). */
+  outcome: string;
+  rows: number;
+  truncated: boolean;
+  ms: number;
+  /** Whether rows were released to the agent's answer (written before the answer is sent: it may over-state, never under-state). */
+  released: boolean;
+  sqlstate?: string;
+}
+
+/** `GET /sources/:name/agent-queries` (observer): the last 20, newest first. `known: false` = the record could not be read. */
+export interface SourceAgentQueriesResponse {
+  name: string;
+  known: boolean;
+  queries: SourceAgentQuery[];
+}
+
+/** One source a run's agents read (`GET /runs/:id/data-use`). */
+export interface SourceDataUse {
+  source: string;
+  /** Calls that reached the read policy. */
+  queries: number;
+  /** Calls whose rows reached the agent. */
+  released: number;
+  rows: number;
+  truncated: boolean;
+  lastAt: string;
+}
+
+/** `GET /runs/:id/data-use` (observer): the sources a run's agents read. `known: false` = UNKNOWN, never "none". */
+export interface RunDataUseResponse {
+  runId: string;
+  known: boolean;
+  sources: SourceDataUse[];
+}
+
+/**
+ * (api-types 0.184.0, DES-KNOWLEDGE-DATA-001 §7.8) What a unit's rows tool (`mcp:<source>/execute_sql`)
+ * answers through the gate: one JSON object inside the MCP result's text, citable like knowledge, fenced as
+ * untrusted data.
+ */
+export interface SourceReadEnvelope {
+  /** Always first: the rows are data from the source, never instructions. */
+  untrusted: string;
+  /** `src:<name>@<at>#<8 hex>`. */
+  cite: string;
+  source: string;
+  /** The dialect (`postgres`). */
+  kind: string;
+  /** The agent's own SQL (scrubbed of the source's secret). */
+  sql: string;
+  params: unknown[];
+  at: string;
+  /** `source:<id>`: what a cached answer depends on. */
+  deps: string[];
+  /** `type`: the source's type name, or `null` where the adapter does not report one. */
+  columns: Array<{ name: string; type: string | null }>;
+  rows: unknown[][];
+  rowCount: number;
+  /** More rows than the cap, more bytes than the cap, or a cell cut at 2,000 characters. */
+  truncated: boolean;
+  rowCap: number;
+  byteCap: number;
+  ms: number;
+}
+
+/**
+ * (api-types 0.186.0, DES-KNOWLEDGE-DATA-001 §10.2) One column of a value-free profile: bands, never a value.
+ * `nullPct` is the null fraction to the nearest 5 % (`null` for an empty relation); `hasNulls` says a few nulls
+ * the band rounded to 0 are there.
+ */
+export interface SourceProfileColumn {
+  name: string;
+  type: string;
+  nullPct: number | null;
+  hasNulls: boolean;
+  cardinality: 'none' | 'single' | 'low' | 'high' | 'unique' | 'unknown';
+  keyCandidate: boolean;
+}
+
+/** (api-types 0.186.0) A relation's value-free profile; `rows` is an order-of-magnitude band, `null` when it was not read (`error` = a class). */
+export interface SourceProfileRelation {
+  /** `schema.table`, the catalog document's key. */
+  key: string;
+  rows: '0' | '1-99' | '100-9,999' | '10,000-999,999' | '1,000,000+' | null;
+  columns: SourceProfileColumn[];
+  error: string | null;
+  /** Columns not profiled (more than the profiler reads per relation). */
+  columnsNotListed?: number;
+}
+
+/** (api-types 0.186.0) A join the profiler found: a declared foreign key, or a name-and-type match the overlap band confirmed. */
+export interface SourceProfileJoin {
+  from: string;
+  columns: string[];
+  to: string;
+  references: string[];
+  basis: 'fk' | 'name_type';
+  /** How many of the referencing side's distinct values the other side holds (one-column joins); measured at the source. */
+  overlap: 'empty' | 'none' | 'some' | 'most' | 'all' | null;
+}
+
+/**
+ * (api-types 0.186.0) `POST /sources/:name/profile`, a human operator's only (403 `profile_human_only`). The
+ * value-free profile of a described native Postgres source, through the data gate's person read, and the data shapes
+ * it filed as `knowledge` proposals for the review (one per relation; an identical shape already in the queue is not
+ * filed again). 409 `not_in_knowledge`: estate holds no structure for the source yet.
+ */
+export interface SourceProfileResponse {
+  name: string;
+  /** The registry id. */
+  sourceId: string;
+  profiledAt: string;
+  relations: SourceProfileRelation[];
+  joins: SourceProfileJoin[];
+  /** Code entities named exactly like a relation, in the repos' code graphs. */
+  describes: Array<{ relation: string; repo: string; name: string; kind: string; file: string }>;
+  proposed: Array<{ id: string; relation: string }>;
+  alreadyProposed: number;
+  codeSearch: { searched: string[]; notSearched: string[] };
+  /** Catalog documents estate holds that crew's own catalog does not (or a view not allowed): not profiled. */
+  notInKnowledge?: number;
+  /** Relations beyond what one profile reads (too many): not profiled. */
+  notListed?: number;
+  /** Estate holds more catalog pages than one read takes: the rest were not profiled. */
+  catalogTruncated?: true;
+}
+
+/**
+ * (api-types 0.186.0) The crew-owned record a data-shape proposal carries in `payload.shape` (a `knowledge`
+ * proposal filed by the profiler). The review shows it; estate stores it as given.
+ */
+export interface KnowledgeShapeRecord {
+  format: 1;
+  sourceId: string;
+  source: string;
+  relation: string;
+  profile: SourceProfileRelation;
+  joins: SourceProfileJoin[];
+  describes: Array<{ repo: string; symbolId: string; name: string; kind: string; file: string }>;
+  /** Related tables whose join did not fit estate's 200 links per proposal (`joins` above keeps every one). */
+  linksNotListed?: number;
+}
+
+/** (api-types 0.186.0) A node of the Knowledge map. `key` is `<store>:<id>` (`source:`, `repo:`, `knowledge:`, `estate:`). */
+export interface KnowledgeMapNode {
+  key: string;
+  kind: 'source' | 'table' | 'shape' | 'code' | 'repo' | 'knowledge';
+  label: string;
+  /** A table's source name. */
+  source?: string;
+  /** A code entity's repo id. */
+  repo?: string;
+  /** A shape's proposal id. */
+  proposalId?: string;
+  /** A shape's value-free summary. */
+  summary?: string;
+}
+
+/**
+ * (api-types 0.186.0) A typed edge of the Knowledge map (`describes`, `joins`, `governed_by`, `derived_from`, …;
+ * `contains` is drawn structure). A `joins` edge's evidence is `{basis, on: [{columns, references, basis, overlap?,
+ * cut?}], more?}`: every condition between the two tables, held under estate's 1 KiB evidence bound.
+ */
+export interface KnowledgeMapEdge {
+  rel: string;
+  from: string;
+  to: string;
+  confidence: number | null;
+  evidence: Record<string, unknown> | null;
+  /** The node of the shape that asserts it (`kconcept synthetic proposal:<id>:`, estate's id); `null` for drawn structure. */
+  owner: string | null;
+}
+
+/**
+ * (api-types 0.186.0) `GET /knowledge/map`, a human operator's only. The source catalogs and the APPROVED data shapes
+ * estate holds live, with their typed edges; a pending or declined shape is never in it. Every source and repo is in
+ * the read's visible set; a repo is drawn when a shape links into it. A catalog estate replaced while it was read is
+ * left out with a note, never drawn half.
+ */
+export interface KnowledgeMapResponse {
+  nodes: KnowledgeMapNode[];
+  edges: KnowledgeMapEdge[];
+  sources: Array<{ id: string; name: string; described: boolean; inKnowledge: boolean; tables: number }>;
+  shapes: number;
+  /** Approved shapes estate no longer holds, or hides. */
+  skipped: number;
+  truncated: boolean;
+  notes: string[];
+}
+
 /**
  * `POST /sources/:name/test-call` (G6) — human operator only. Without `confirm` it sends NOTHING and
  * answers the exact request it would send and its `requestHash`; with `confirm` equal to that hash it
@@ -13341,6 +13751,106 @@ export interface CrewSourceCatalog {
   routes: Array<{ path: string; responseType: string; params: string[] }>;
 }
 
+// ── Test connection, and ask a question of a source (operator 2026-11-03; api-types 0.179.0) ─────────
+
+/**
+ * `POST /sources/:name/test` — "Test connection" on a saved `sql` or `graphql` source (it replaces
+ * "Describe again"). crew connects with the saved credentials resolved now, describes the source again
+ * and saves that description, then (SQL) checks a probe read of one table with the read policy and a
+ * prepare at the source; the probe is never executed. A failure is a result (`ok: false`, HTTP 200):
+ * crew's `code` and words (a source's own words reach a human only, scrubbed of the secret). No answer
+ * carries the secret.
+ */
+export interface SourceConnectionTestResponse {
+  name: string;
+  kind: 'sql' | 'graphql';
+  driver: 'postgres' | 'mysql' | 'sqlite' | null;
+  ok: boolean;
+  /** Connecting and describing, in milliseconds (a failure: until it failed). */
+  ms: number;
+  /** When crew ran the test (ISO 8601). */
+  testedAt: string;
+  /**
+   * How crew connects: `verified` (TLS, the certificate checked against the host: Postgres
+   * `verify-full`, MySQL `VERIFY_IDENTITY`, HTTPS), `off` (plaintext, allowed on this confirmed
+   * address), `local` (an upload: crew opens its own snapshot, there is no connection).
+   */
+  tls: 'verified' | 'off' | 'local';
+  /** `ok`: the fresh description (saved): structure, and for Postgres the login's privilege report. */
+  catalog?: SourceCatalogResponse;
+  /** `ok`, SQL: the read-policy check of the probe read (`null`: no table to probe). */
+  readCheck?: ({ ok: true; text: string; relation: string } | { ok: false; text: string; relation: string; code: string; detail: string }) | null;
+  /** `!ok`: why (`secret_missing`, a dialer refusal code, `source_connection`, `source_timeout`, `source_source`, `test_failed`, …). */
+  code?: string;
+  error?: string;
+}
+
+/** `POST /sources/:name/ask` — HUMAN operator only (403 `ask_human_only`). SQL sources. */
+export interface SourceAskBody {
+  /** The person's question, e.g. "How many tickets are open?" (1-1000 characters). */
+  question: string;
+}
+
+/**
+ * The draft: one seat wrote one read query from the question and the source's STRUCTURE only (what
+ * agents see: names, types, keys, declared enum literals, row estimates; never a row or a credential),
+ * and crew checked it with the read policy, then a prepare at the source. NOTHING RAN. `confirm` is
+ * crew's run token for exactly `sql` (only when the check passed): `POST /sources/:name/query` with it
+ * runs that text. Audited `apps.source.asked` (no question, no SQL).
+ */
+export interface SourceAskResponse {
+  /** The query the seat wrote (`''`: it said the structure cannot answer the question). */
+  sql: string;
+  /** The seat's one line: what the query returns and how to read it (or why there is no query). */
+  explanation: string;
+  /** The seat that drafted it. */
+  seat: string;
+  /** The check of `sql` (`null` when there is no query). */
+  check: SourceCheckResponse | null;
+  confirm: string | null;
+}
+
+/** `POST /sources/:name/query` — HUMAN operator only (403 `query_human_only`). SQL sources. */
+export interface SourceQueryBody {
+  /** The SQL to check (or run): a draft, an edited draft, or the person's own. */
+  sql: string;
+  /** crew's run token for exactly `sql` (from the ask, or from this route without `confirm`). */
+  confirm?: string;
+}
+
+/**
+ * Without `confirm`: the check only (`ran: false`; nothing reaches the source but a prepare) and, when
+ * it passed, the run token. With `confirm`: crew verifies the token is its own for exactly this text
+ * and this source as it is now (`409 query_changed` otherwise), then runs it: the read policy again,
+ * a `READ ONLY` transaction, the 10 s deadline cancelled at the source (`504 source_timeout`), at most
+ * {@link SourceQueryRan.rowCap} rows. The rows go to this answer only: never to a seat, a log or the
+ * audit trail (`apps.source.queried` records the relations, counts and time).
+ */
+export type SourceQueryResponse = SourceQueryChecked | SourceQueryRan;
+
+export interface SourceQueryChecked {
+  ran: false;
+  check: SourceCheckResponse;
+  confirm: string | null;
+}
+
+export interface SourceQueryRan {
+  ran: true;
+  columns: Array<{ name: string; type: string }>;
+  /**
+   * Cells as the source's driver reads them, as JSON carries them: Postgres and MySQL dates, times,
+   * numerics and 64-bit integers as the source's own text (`2026-01-01 01:00:00+00`, in the session's
+   * time zone), bytes as `\x` hex (the first 32,767 bytes, `…` past them; Postgres `bytea` arrives as the source's `\x`
+   * text and is cut like any text), JSON values as JSON; text past 64 KB
+   * is cut.
+   */
+  rows: unknown[][];
+  /** More rows than the cap, or past 1 MB of rows as encoded: only the first are shown. */
+  truncated: boolean;
+  rowCap: number;
+  ms: number;
+}
+
 // ── Decision capture (DES-decision-capture §4.2.1 / §4.6; DC-S4a, api-types 0.80.0) ──────────────
 
 /** The laya codebook's decision types. `none` is crew's label for "no decision". */
@@ -15200,6 +15710,42 @@ export interface AppTurnState {
   actor: string;
 }
 
+/**
+ * (api-types 0.185.0, DES-APPS-001 §9.2, K5) One chat message to an app and how its `apps-turn` run ended, kept
+ * in crew's record of the app (the last 50; the detail answers the last 20). The chat on the app's page is this
+ * list: no other thread store. `running` while the run works; `landed` with the version it made; `refused` when
+ * the check or the review refused it (nothing landed, `code` and `reason` say why); `failed` when a step could
+ * not run; `cancelled` when it was stopped.
+ */
+export interface AppTurnRecord {
+  runId: string;
+  /** Unix millis: when the message was sent. */
+  at: number;
+  /** The actor id that sent it. */
+  actor: string;
+  /** The person's message, as sent. */
+  message: string;
+  /** The component ids the message was about (the composer's chips). */
+  about: string[];
+  /** The version it was sent on. */
+  base: number;
+  state: 'running' | 'landed' | 'refused' | 'failed' | 'cancelled';
+  /** Unix millis, or `null` while it runs. */
+  endedAt: number | null;
+  /** `landed`: the version it made. */
+  version: number | null;
+  /** `landed`: crew's own line of what changed, from the two specs ("Added 1 chart and 1 query"). */
+  change: string | null;
+  /** `landed`: the builder's change lines, as it wrote them (text; never instructions to anyone). */
+  summary: string | null;
+  /** `landed`: the seats that built it and reviewed it (distinct). */
+  builder: string | null;
+  reviewer: string | null;
+  /** Not landed: a stable code (`check_failed`, `review_refused`, `launch_refused`, `cancelled`, …) and crew's words. */
+  code: string | null;
+  reason: string | null;
+}
+
 /** `GET /apps` item. */
 export interface AppSummary {
   /**
@@ -15216,6 +15762,12 @@ export interface AppSummary {
   createdAt: number;
   head: { version: number; tree: string; receipt: AppReceiptKind | null };
   turn: AppTurnState | null;
+  /**
+   * (api-types 0.180.0) The app's last successful publish: its share link (`shareUrl`), the version it serves
+   * and what was produced. `null` until a publish run finished (studio says "Publish to share", never a made-up
+   * link); absent from an older daemon.
+   */
+  published?: AppPublished | null;
 }
 
 /** `GET /apps` (observer); `?project=<id>` keeps one project's apps. */
@@ -15240,6 +15792,8 @@ export interface AppDetail extends AppSummary {
   /** Oldest first. */
   versions: AppVersion[];
   history: AppHistory;
+  /** (api-types 0.185.0, K5) The app's chat: its last turns, oldest first. Absent from an older daemon. */
+  turns?: AppTurnRecord[];
 }
 
 /** `GET /apps/:app` (observer), and `POST /apps` (201). */
@@ -15531,6 +16085,10 @@ export interface AppErrorBody {
     | 'unknown_version'
     | 'unknown_query'
     | 'unknown_project'
+    /** (api-types 0.185.0) `POST /apps/check` from a unit that is not the turn's check step. */
+    | 'not_the_check'
+    /** (api-types 0.185.0) A turn on an app whose repository is not registered yet. */
+    | 'not_registered'
     | 'stale_base'
     | 'turn_in_flight'
     | 'not_accepted'
@@ -15580,21 +16138,40 @@ export interface AppErrorBody {
  * unit's capability token in the body, never as a bearer): check the builder's candidate commit of the
  * app's turn in flight (DES §9.2 `check`).
  */
-export interface AppsCheckBody {
-  token: string;
-  app: string;
-  /** The builder's candidate commit in the app repo. */
-  commit: string;
-  /** The publish manifest, for the publish check (a later slice). */
-  manifest?: unknown;
-}
+export type AppsCheckBody =
+  | {
+      token: string;
+      /**
+       * (api-types 0.185.0) The builder's worktree as the engine snapshotted it (`WICKED_TREE`, a tree in the app
+       * repo's objects); crew finds the app by the unit's run.
+       */
+      tree: string;
+      /** The publish manifest, for the publish check (a later slice). */
+      manifest?: unknown;
+    }
+  | {
+      token: string;
+      app: string;
+      /** The builder's candidate commit in the app repo (the older form). */
+      commit: string;
+      /** The publish manifest, for the publish check (a later slice). */
+      manifest?: unknown;
+    };
 
 /**
  * (api-types 0.173.0) `POST /apps/check` 200: on a pass, the commit crew made on the candidate with its lock (the only tree the
  * turn's review can land) and what the check ran; on a refusal, why.
  */
 export type AppsCheckResponse =
-  | { ok: true; commit: string; tree: string; summary: AppCheckSummary }
+  | {
+      ok: true; commit: string; tree: string; summary: AppCheckSummary;
+      /**
+       * (api-types 0.185.0) The checked tree's files as text (`apps.json`, `apps.lock.json`, `queries/<id>.<ext>`):
+       * `wicked-crew apps-check` writes exactly these into the turn's worktree, so the review is dispatched on the
+       * tree that can land.
+       */
+      files?: Array<{ path: string; text: string }>;
+    }
   | { ok: false; code: 'check_failed' | 'source_check_unavailable'; findings: AppCheckFinding[] };
 
 /**
@@ -15613,7 +16190,7 @@ export interface AppsCapabilities {
    * since api-types 0.178.0 (K2b, the write path: API actions and Postgres row writes).
    */
   actions: boolean;
-  /** `POST /apps/:app/turns` launches `apps-turn` runs. */
+  /** `POST /apps/:app/turns` launches `apps-turn` runs (true since api-types 0.185.0 on a daemon whose engine runs them). */
   turns: boolean;
   /** `POST /apps/:app/publish`. */
   publish: boolean;
@@ -15644,3 +16221,164 @@ export interface RegisterRepoBody {
   actor?: string;
   autoCapture?: boolean;
 }
+
+// ── Apps: publish and the standalone site (api-types 0.180.0, DES-APPS-001 §8.1-8.2, §9.3, slice K6) ──────────
+//
+// Publish turns an accepted version into a container image the deployer runs: `wicked-apps-server` with the
+// runtime, the checked `apps.json`, `queries/`, `apps.lock.json`, the snapshots by digest and the manifest
+// below. The SHARE LINK is the site's own address, the base URL the deployer gives in the publish settings
+// (`site.origin`): after a successful publish it is `AppPublished.shareUrl`, and anyone in the app's audience
+// (anyone at all, for a public app) opens it. crew never invents one and pushes nothing anywhere.
+
+/** Where a publish puts the app. `studio` is always on; `embed` needs a public app; `teams` needs the Entra profile. */
+export type AppPublishTarget = 'studio' | 'site' | 'embed' | 'teams';
+
+/**
+ * Who may open the site, judged on the verified token (DES §8.2). `public`: anyone, read-only (every query
+ * public, no action). `oidc-groups`: a group claim value (`claim`, default `groups`). `oidc-email-domain`: the
+ * email's domain, only with `email_verified: true` (a Boolean). `entra-roles`: an app-role VALUE in `roles`
+ * (recommended). `entra-groups`: a group object id in `groups` (a token with a groups overage marker is refused).
+ */
+export type AppAudienceRule =
+  | { kind: 'public' }
+  | { kind: 'oidc-groups'; groups: string[]; claim?: string }
+  | { kind: 'oidc-email-domain'; domains: string[] }
+  | { kind: 'entra-roles'; roles: string[] }
+  | { kind: 'entra-groups'; groups: string[] };
+
+/**
+ * The site's one issuer, fixed at publish. `oidc`: the page signs in with authorization code + PKCE and sends
+ * the ID token (`aud` = `clientId`). `entra`: the page sends a v2 ACCESS token for the app's own
+ * `access_as_user` scope (`aud` = `clientId`, `scp` has `access_as_user`, `tid` = `tenantId`); app-only tokens and
+ * ID tokens are refused. The issuer is `https://` (Entra: `https://login.microsoftonline.com/<tenantId>/v2.0`).
+ */
+export interface AppPublishIdentity {
+  profile: 'oidc' | 'entra';
+  issuer: string;
+  clientId: string;
+  /** `entra` only. */
+  tenantId?: string;
+  /** The scope the page asks for. Default: `openid email profile groups` (oidc), `api://<site host>/<clientId>/access_as_user openid profile` (entra). */
+  scope?: string;
+  /**
+   * Loopback or private CIDR ranges the issuer may be reached at when it is a NAME on a private network (crew's
+   * `OidcConfig.allowRanges`); an IP-literal issuer confirms itself. Never metadata or link-local.
+   */
+  allowRanges?: string[];
+}
+
+/** `POST /apps/:app/publish` (HUMAN operator): launch an `apps-publish` run bound to the head tree and this manifest. */
+export interface AppPublishBody {
+  /** The head version the person is publishing (`409 stale_base` if head moved). */
+  base: number;
+  targets: AppPublishTarget[];
+  /**
+   * The site's address: `https://<host>[:port]`, or `http://localhost:<port>` / `http://127.0.0.1:<port>` for a
+   * local run. No path, query or credentials. It is the share link, the redirect URI's origin
+   * (`<origin>/auth/callback`), and the only origin a POST to the site may come from.
+   */
+  site: { origin: string };
+  /** `null` = a public app (no sign-in). */
+  identity: AppPublishIdentity | null;
+  audience: AppAudienceRule;
+  /** `embed`: the origins that may frame the public site (`https://…`, no path). `teams` adds the Teams origins itself. */
+  embedOrigins?: string[];
+}
+
+/** One source as the person consents to shipping it (DES §9.3 step 3). */
+export interface AppManifestSource {
+  name: string;
+  kind: 'sql' | 'graphql' | 'rest' | 'mcp-http';
+  descriptorHash: string;
+  /** Where the container must reach it (`db.support.internal:5432`, a URL's origin), or `null` for a snapshot. */
+  reach: string | null;
+  /** The address is loopback or private: the container's network must reach it. */
+  privateAddress: boolean;
+  /** The environment variable the deployer passes its secret in, or `null` when it has none. */
+  env: string | null;
+  /** A Postgres source's Allow writes switch at publish. */
+  allowWrites: boolean;
+  /** An upload: the snapshot's digest, shipped in the image. */
+  snapshot?: string;
+}
+
+/** The manifest a publish run is bound to (its digest is on the run, the QE verdict and the `published` receipt). */
+export interface AppPublishManifest {
+  schema: 'wicked.apps.manifest/v1';
+  app: { slug: string; name: string; version: number; tree: string; commit: string };
+  targets: AppPublishTarget[];
+  site: { origin: string };
+  /**
+   * The issuer, with the endpoints its discovery document named at publish (the page's `connect-src`) and the ID
+   * token signing algorithms it named (`id_token_signing_alg_values_supported`; the page checks the ID token's).
+   */
+  identity: (AppPublishIdentity & { endpoints: { authorization: string; token: string; idTokenAlgs?: string[] } }) | null;
+  audience: AppAudienceRule;
+  embedOrigins: string[];
+  sources: AppManifestSource[];
+  queries: Array<{ id: string; source: string; public: boolean }>;
+  /** Each action with the grant the image enforces (revoking = publishing again without it). */
+  actions: Array<{ id: string; kind: 'api' | 'row-write'; source: string; grant: AppActionGrant; table?: string; columns?: string[] }>;
+  /** Every environment name the image needs, sorted. A missing one fails the server's start, by name. */
+  env: string[];
+  /** `/data` must be a mounted volume when the app has an action (its action records and logs live there). */
+  volume: '/data' | null;
+}
+
+/** An app's last successful publish (`AppSummary.published`, so also on `AppDetail`): the share link and what was produced. */
+export interface AppPublished {
+  version: number;
+  tree: string;
+  /** The `apps-publish` run. */
+  runId: string;
+  /** Unix millis, when the image was produced. */
+  at: number;
+  /** Who consented. */
+  actor: Actor;
+  targets: AppPublishTarget[];
+  /** The share link: `site.origin` + `/`. What studio's Copy link copies. */
+  shareUrl: string;
+  /** Who can open it, in one line ("People in group support-ops who sign in at dex.apps.test"). */
+  audience: string;
+  /** The image in the local container engine (never pushed): its tag and its id (`sha256:…`). */
+  image: { tag: string; id: string };
+  /** `embed`: the iframe snippet (a public app only); otherwise `null`. */
+  snippet: string | null;
+  /** `teams`: the Teams app package, at `GET /api/v1/apps/:app/published/teams.zip`; otherwise `null`. */
+  teamsPackage: { url: string; sha256: string } | null;
+  manifestDigest: string;
+  /** How the deployer runs it: the environment names, the volume (or `null`), the port the server listens on. */
+  run: { env: string[]; volume: '/data' | null; port: number };
+}
+
+// The standalone site's own routes (`wicked-apps-server`; the page's in-process host calls them). Bearer only,
+// no cookies; every POST needs `Origin` = the site's origin and `Content-Type: application/json`.
+
+/** `GET /spec` (a token in the audience, or a public app): the published version and who is viewing. */
+export interface AppSiteSpecResponse {
+  app: { slug: string; name: string; version: number };
+  spec: AppSpec;
+  /** What the server took from the verified token; `null` on a public site. */
+  viewer: { email: string | null; name: string | null } | null;
+  /** Actions run on this site (a mounted `/data`, `APPS_READ_ONLY` unset). The page still refuses them in a frame. */
+  actions: boolean;
+  /**
+   * Queries and actions the server refuses NOW, each with its reason. They are judged again at every refresh (every
+   * 10 minutes, and after a failed read): a source back as it was published clears them; a source that really
+   * changed needs the app checked and published again.
+   */
+  refused: Array<{ kind: 'query' | 'action'; id: string; reason: string }>;
+}
+
+/**
+ * `GET /healthz` (no sign-in): up, and what it refuses, by kind, id and a code only (`contract_changed`,
+ * `table_changed`, `source_unavailable`, …). The reasons, which can name a source or a table, are on `GET /spec`
+ * behind the sign-in.
+ */
+export interface AppSiteHealth {
+  ok: boolean;
+  app: string;
+  version: number;
+  refused: Array<{ kind: 'query' | 'action'; id: string; code: string }>;
+  actions: boolean;
+}

package/package.json

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