wicked-crew-api-types 0.170.0 → 0.172.0

package/index.d.ts

@@ -375,6 +375,13 @@ export interface HealthCapabilities {
    * body is strict there, so the field would be refused).
    */
   chatArtifacts?: ChatArtifactsCapabilities;
+  /**
+   * (api-types 0.172.0, DES-APPS-001) PRESENT means the app store is served: `GET|POST /apps`, `GET /apps/:app`, and
+   * the human-only edits, undo, redo and restore. The flags of {@link AppsCapabilities} are about the OTHER routes:
+   * each says whether that route serves for real yet (rather than `501`). A skin shows Apps only when this is
+   * present. ABSENT on an older daemon.
+   */
+  apps?: AppsCapabilities;
 }
 
 /** {@link HealthCapabilities.chatArtifacts} (api-types 0.169.0). */
@@ -393,9 +400,17 @@ export interface ChatArtifactsCapabilities {
   demo: boolean;
   /**
    * (api-types 0.170.0) The daemon runs the chat-artifacts TEST configuration (DES §13 A2): every operation resolves,
-   * and Go on a proposal records a stub dispatch and starts NOTHING. A skin says so on the card. ABSENT otherwise.
+   * and Go on a proposal of a kind in {@link stubOps} records a stub dispatch and starts NOTHING (a skin says so on that
+   * card). With `stubOps` absent (a daemon before 0.171.0), that is every kind. ABSENT in production.
    */
   stub?: true;
+  /**
+   * (api-types 0.171.0, slice A3) The operations whose Go records a stub dispatch and starts nothing under the TEST
+   * configuration; every other advertised operation starts real work (A3: `create` is real, `refine`, `theme` and
+   * `demo` stay stubs until their slices). ABSENT in production. A skin says "starts nothing" only for these kinds;
+   * before this field, `stub: true` meant every kind.
+   */
+  stubOps?: ArtifactProposalKind[];
 }
 
 // ── A run's working document (program DES-POWER-MODE §8.3, §9; api-types 0.148.0) ──────────────────
@@ -1257,6 +1272,22 @@ export interface AgentSession {
    * before the field: check `GET /health.capabilities.runChatId` before grouping runs by chat.
    */
   chat_id?: string;
+  /**
+   * (api-types 0.171.0, DES-CHAT-ARTIFACTS-001 §4.3, slice A3) The chat proposal this run answers
+   * (`<chatId>:<turnId>`, or a crew-made `<chatId>:retry:<runId>`), read back from the `run.launched`
+   * entry after a restart. ABSENT on a run no proposal started.
+   */
+  proposal_id?: string;
+  /** (api-types 0.171.0) The artifact a proposal-bound run makes (`<mount>/<doc>`, the mount a project id or `_unfiled`),
+   *  so a skin finds an Unfiled run's document. ABSENT on a run no proposal started. */
+  artifact_ref?: string;
+  /**
+   * (api-types 0.171.0, §6.2) A proposal-bound attempt ended without landing: the engine run failed or was stopped,
+   * crew's landing check failed (no file, the document floor, the announce), or a daemon restart interrupted it
+   * ("interrupted by a restart"). The chat and the document are released, and the chat holds a retry proposal
+   * (`<chatId>:retry:<runId>`: Try again into the same document). ABSENT when the attempt landed or is still going.
+   */
+  landing_failed?: { reason: string; at: number };
   /**
    * (crew#552) The onboarding run this run was CHAINED from (a `capture-learnings` run the daemon
    * launched when that onboarding completed) — read back from the `run.launched` entry after a
@@ -7619,6 +7650,16 @@ export interface InteractiveDemoStepDraft {
 export interface InteractiveDocCreateRequest {
   /** The doc name; the bridge slugifies it (409 when taken or retired). */
   name?: string;
+  /**
+   * (api-types 0.171.0, DES-CHAT-ARTIFACTS-001 §5.2) The chat a proposal's create comes from. Accepted ONLY with
+   * `proposal_id`, and only when that chat holds a `proposal_accepting` record of the caller's whose identity names
+   * this document in this mount and whose stored resolution lists every `repo_ref(s)`: then an Unfiled document may
+   * name those repositories (`unfiled_doc_repo` is lifted through the record, nothing else). Anything else is a 400
+   * `proposal_grant_refused` and nothing is created. Crew sends these itself on a proposal's Go.
+   */
+  chat_id?: string;
+  /** (api-types 0.171.0) The proposal (`<chatId>:<turnId>` or `<chatId>:retry:<runId>`); see `chat_id`. */
+  proposal_id?: 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). */
@@ -7680,9 +7721,11 @@ export interface InteractiveDocCreateRefusal {
    * 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.
+   * canonicalizes an OMITTED `project` from the route. `proposal_grant_refused` (api-types 0.171.0) — `chat_id`
+   * without `proposal_id` (or the reverse), or no `proposal_accepting` record of the caller's in that chat that names
+   * this document, this mount and every requested repository.
    */
-  code: 'repo_not_in_project' | 'unfiled_doc_repo' | 'invalid_repo_ref' | 'ambiguous_repo_ref' | 'project_mismatch';
+  code: 'repo_not_in_project' | 'unfiled_doc_repo' | 'invalid_repo_ref' | 'ambiguous_repo_ref' | 'project_mismatch' | 'proposal_grant_refused';
   /** 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). */
@@ -8488,6 +8531,11 @@ export interface ArtifactProposal {
   sources: ProposalSource[];
   /** Repositories (names), each in the chat's scope. */
   repos: string[];
+  /** (api-types 0.171.0) The same repositories by registry id, in the same order (two checkouts may share a name). */
+  repoRefs?: string[];
+  /** (api-types 0.171.0) A crew-made retry (`sourceRunId`): the document it fills again (`<mount>/<doc>`), the same
+   *  artifact as the failed attempt's. ABSENT on a turn's proposal (its document name derives from the pid). */
+  artifactRef?: string;
   /** `null` for a theme (no run). */
   helpers: ProposalHelpers | null;
   /** `null` for a theme. */
@@ -8509,12 +8557,15 @@ export interface ArtifactProposal {
 }
 
 /**
- * What a person may change before Go (typed per kind; crew re-checks every edit with the rules of §4.2). In this
- * release (slice A2) crew takes `title`, `brief`, `sources` and `helpers` on a create, `ask` and `helpers` on a refine,
- * `name` and `patch` on a theme, and `audience`, `show` and `helpers` on a demo; `project`, `repos`, `url` and `allow`
- * are refused (400 `edits_invalid`) until the slices whose forms edit them. A source the person adds that cannot be used
- * is refused too, never dropped. An interrupted (accepting) proposal resumes with its accepted choices: only its
- * `helpers` may change.
+ * What a person may change before Go (typed per kind; crew re-checks every edit with the rules of §4.2). Crew takes
+ * `title`, `brief`, `sources`, `helpers`, `repos` and `project` on a create (api-types 0.171.0, slice A3: New document's
+ * "answer this proposal" mode), `ask` and `helpers` on a refine, `name` and `patch` on a theme, and `audience`, `show`
+ * and `helpers` on a demo; `url` and `allow` are refused (400 `edits_invalid`) until the slices whose forms edit them.
+ * `project` changes only in a chat filed in no project: then every source, repository and turn of the conversation is
+ * re-checked against the target project, and what is outside it is struck (a `message:` source whole, when any of its
+ * records is outside). `repos` must be in the chat's scope (and, with a target project, members of it). A source or
+ * repository the person adds that cannot be used is refused, never dropped. An interrupted (accepting) proposal
+ * resumes with its accepted choices: only its `helpers` may change.
  */
 export interface ProposalEdits {
   /** create */
@@ -8619,6 +8670,15 @@ export type ChatProposalFrame = {
   project_id?: string;
 };
 
+/**
+ * `/ws` (api-types 0.171.0, DES-CHAT-ARTIFACTS-001 §6.2, slice A3): a proposal-bound attempt ended without landing — the
+ * engine run failed or was stopped, crew's landing check refused it (no draft file, the document floor, a source file
+ * changed during the run, the announce), or a daemon restart interrupted it. The run's DTO carries the same
+ * `landing_failed`, the chat and the document are released, and the chat holds a retry proposal
+ * (`<chatId>:retry:<session>`, a `chatProposal` frame).
+ */
+export type RunLandingFailedFrame = { type: 'landingFailed'; session: string; artifact_ref: string; reason: string };
+
 // ── System chat: history, close, attachments (api-types 0.137.0, DES-SYSTEM-CHAT "Crew") ────────
 //
 // The floating system chat's past-chats rail, its Close, and its uploads. Capabilities:
@@ -14265,3 +14325,716 @@ export interface PutVoiceDashboardBody {
   layout: string[];
   widgets: VoiceWidgetManifest[];
 }
+
+// ── Apps (DES-APPS-001 rev 11, slice K2a; api-types 0.172.0) ──────────────────────────────────────
+//
+// An app is a git repo crew owns under `~/.wicked/apps/<slug>`: `apps.json` (an {@link AppSpec}),
+// `queries/<id>.<sql|graphql|json>` (each query's text) and `apps.lock.json` (an {@link AppLock},
+// written by crew's check, never by an agent or a person). Every version is one commit on the repo's
+// `main`; crew keeps, outside the repo, a RECEIPT per (app, tree) saying how the tree was accepted, and
+// only a tree holding one ever runs against a source.
+
+/** The `schema` value of every v1 `apps.json`. */
+export type AppSpecSchemaId = 'wicked.apps/v1';
+
+/**
+ * `apps.json`, the whole app: pages of components on a 12-column grid, the named queries and actions
+ * they bind, the theme and the hosts a link may open. No app code: the `wicked-apps` runtime interprets
+ * this document and nothing else (DES §7.1).
+ *
+ * Identifiers: page and component ids match `^[A-Za-z][A-Za-z0-9_-]{0,63}$` and are unique across the
+ * app; query and action ids match `^[a-z][a-z0-9_]{0,63}$` (a query id is a file name, so lower case
+ * only) and are unique among queries and among actions. crew refuses an unknown key anywhere in the
+ * document, so a field a newer studio writes reaches an older daemon as a refused edit, never as a
+ * silently dropped one.
+ *
+ * The whole document is at most 2 MB of JSON, nests at most 16 deep, holds no list longer than its stated
+ * limit (200 for any list not given one) and no object with more than 256 keys, and never uses the key
+ * `__proto__`.
+ */
+export interface AppSpec {
+  schema: AppSpecSchemaId;
+  /** The app's title (1-120 characters). */
+  name: string;
+  /** At most 2,000 characters. */
+  description?: string;
+  theme?: AppTheme;
+  /** 1-20 pages; the first is the one an app opens on. */
+  pages: AppPage[];
+  /** At most 100. */
+  queries: AppQuery[];
+  /** At most 50. */
+  actions: AppAction[];
+  /**
+   * Exact host names (lower case, no scheme, no port) a link component may open, over https only. The
+   * host shows the full URL before opening it (DES §7.1). At most 50.
+   */
+  linkHosts: string[];
+}
+
+/** Colours are `#rrggbb`. */
+export interface AppTheme {
+  /** `auto` follows the viewer's setting (the default). */
+  mode?: 'light' | 'dark' | 'auto';
+  accent?: string;
+  /** Chart series colours in order (at most 12). */
+  palette?: string[];
+  density?: 'comfortable' | 'compact';
+}
+
+export interface AppPage {
+  id: string;
+  /** 1-80 characters. */
+  title: string;
+  /** At most 100 per page. */
+  components: AppComponent[];
+}
+
+/**
+ * A component's place on its page's 12-column grid: column `x` (0-11), row `y` (0-999), `w` columns
+ * (1-12, `x + w <= 12`) and `h` rows (1-50). Below 640 px the runtime stacks components by (`y`, `x`).
+ */
+export interface AppBox {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/** What every component carries. */
+export interface AppComponentBase {
+  id: string;
+  box: AppBox;
+  /** At most 120 characters; shown above the component. */
+  title?: string;
+  /** Hidden below 640 px. */
+  hideOnPhone?: boolean;
+}
+
+export type AppComponent =
+  | AppTableComponent
+  | AppChartComponent
+  | AppKpiComponent
+  | AppTextComponent
+  | AppFilterComponent
+  | AppFormComponent
+  | AppButtonComponent
+  | AppImageComponent
+  | AppLinkComponent;
+
+export type AppComponentType = AppComponent['type'];
+
+/**
+ * Where a query or action parameter's value comes from on the page (DES §4 "Binding"):
+ *  - `filter.<id>`: the value of filter component `<id>` (a `date-range` filter gives
+ *    `filter.<id>.from` and `filter.<id>.to`);
+ *  - `form.<field>`: a field of the form the binding sits on;
+ *  - `row.<column>`: a column of the row a table's row action was pressed on;
+ *  - `url.<name>`: a parameter of the page's URL.
+ * Viewer values are never bindings: a parameter declared `from: 'viewer.*'` is filled by the server.
+ */
+export type AppBindingRef = `filter.${string}` | `form.${string}` | `row.${string}` | `url.${string}`;
+// The template type is the shape; crew's grammar is the rule: `filter.<component id>` with an optional
+// `.from`/`.to`, `form.<field name>`, `row.<output column>`, `url.<^[A-Za-z_][A-Za-z0-9_]{0,63}$>`.
+
+/** A component reading a query: the query's id, and a binding for any of its parameters. */
+export interface AppQueryBinding {
+  query: string;
+  params?: Record<string, AppBindingRef>;
+}
+
+/** A control that runs an action: its label, the action's id, and a binding for any of its parameters. */
+export interface AppActionBinding {
+  /** 1-60 characters. */
+  label: string;
+  action: string;
+  params?: Record<string, AppBindingRef>;
+}
+
+/** How a value is shown. `decimals` is 0-10; a currency names its ISO 4217 code. */
+export type AppFormat =
+  | { kind: 'currency'; currency: string; decimals?: number }
+  | { kind: 'text' | 'number' | 'percent' | 'date' | 'datetime' | 'duration'; decimals?: number };
+
+export interface AppTableColumn {
+  /** A declared output column of the table's query. */
+  column: string;
+  label?: string;
+  format?: AppFormat;
+}
+
+export interface AppTableComponent extends AppComponentBase {
+  type: 'table';
+  data: AppQueryBinding;
+  /** Shown columns in order; absent = every declared output column. */
+  columns?: AppTableColumn[];
+  /** A button on every row (at most 4); its parameters may bind `row.<column>`. */
+  rowActions?: AppActionBinding[];
+  /** Rows per page, 5-500. */
+  pageSize?: number;
+}
+
+export interface AppChartSeries {
+  /** A declared output column of the chart's query. */
+  column: string;
+  label?: string;
+  color?: string;
+}
+
+export interface AppChartComponent extends AppComponentBase {
+  type: 'chart';
+  chart: 'line' | 'bar' | 'area' | 'pie';
+  data: AppQueryBinding;
+  /** The category (x axis, or pie slice) column. */
+  x: string;
+  /** 1-12 series; a pie has exactly one. */
+  series: AppChartSeries[];
+  stacked?: boolean;
+}
+
+export interface AppKpiComponent extends AppComponentBase {
+  type: 'kpi';
+  data: AppQueryBinding;
+  /** The column of the first row shown as the figure. */
+  value: string;
+  format?: AppFormat;
+  /** A column of the first row shown as the change beside the figure. */
+  delta?: string;
+  /** A line under the figure, at most 120 characters ("vs previous 90 days"). */
+  caption?: string;
+}
+
+/** Author text, always rendered as text (never HTML or markdown). At most 4,000 characters. */
+export interface AppTextComponent extends AppComponentBase {
+  type: 'text';
+  text: string;
+  style?: 'heading' | 'body' | 'caption';
+}
+
+/** `value` and `label` are at most 200 characters each. */
+export interface AppFilterOption {
+  value: string;
+  label?: string;
+}
+
+/** A select filter's choices: a query's columns, or a fixed list of at most 200. */
+export type AppFilterOptions =
+  | { kind: 'query'; query: AppQueryBinding; value: string; label?: string }
+  | { kind: 'values'; values: AppFilterOption[] };
+
+export interface AppFilterComponent extends AppComponentBase {
+  type: 'filter';
+  filter: 'select' | 'date-range' | 'search';
+  label?: string;
+  /** `select` only: the choices, from a query (its `value` and optional `label` columns) or a fixed list. */
+  options?: AppFilterOptions;
+  /** The value before the viewer picks one: a `select`/`search` string, or `{ lastDays }` for a `date-range`. */
+  default?: string | { lastDays: number };
+}
+
+export interface AppFormField {
+  /** `^[a-z][a-z0-9_]{0,63}$`; bound as `form.<name>`. */
+  name: string;
+  label?: string;
+  input: 'text' | 'textarea' | 'number' | 'date' | 'checkbox' | 'select';
+  required?: boolean;
+  /** `select` only (at most 200). */
+  options?: AppFilterOption[];
+}
+
+export interface AppFormComponent extends AppComponentBase {
+  type: 'form';
+  /** 1-30 fields. */
+  fields: AppFormField[];
+  /** The action the form submits; its parameters bind `form.<name>`. */
+  submit: AppActionBinding;
+}
+
+export interface AppButtonComponent extends AppComponentBase {
+  type: 'button';
+  action: AppActionBinding;
+}
+
+/**
+ * An image carried in the spec: `src` is a `data:image/(png|jpeg|gif|webp);base64,…` URI whose DECODED
+ * payload is at most 256 KB (262,144 bytes; the URI itself is about a third longer); `alt` is at most
+ * 300 characters. No network images (the frame's CSP has none) and no SVG.
+ */
+export interface AppImageComponent extends AppComponentBase {
+  type: 'image';
+  src: string;
+  alt: string;
+}
+
+/**
+ * Where a link goes: another page of the app (with URL parameters bound like a query's), or out to an
+ * `https://` URL whose host is in {@link AppSpec.linkHosts} (no credentials, no port).
+ */
+export type AppLinkTarget = { kind: 'page'; page: string; params?: Record<string, AppBindingRef> } | { kind: 'href'; href: string };
+
+export interface AppLinkComponent extends AppComponentBase {
+  type: 'link';
+  label: string;
+  to: AppLinkTarget;
+}
+
+/** A source kind a query reads; it names the text file: `sql` `.sql`, `graphql` `.graphql`, else `.json`. */
+export type AppQueryKind = 'sql' | 'graphql' | 'rest' | 'mcp' | 'crew';
+
+/** A declared output column's type. A value the source cannot confirm is validated on every row (DES §7.2). */
+export type AppColumnType = 'string' | 'number' | 'integer' | 'boolean' | 'date' | 'datetime';
+
+export interface AppOutputColumn {
+  /** `^[A-Za-z_][A-Za-z0-9_-]{0,127}$` (alias an SQL expression, e.g. `AS order_total`). */
+  name: string;
+  type: AppColumnType;
+  nullable?: boolean;
+}
+
+/** `load` (the default; cached 5 s), `every` N seconds (an integer, 15-86,400), or `events` (the built-in `crew` source only). */
+export type AppRefresh = { mode: 'load' } | { mode: 'every'; seconds: number } | { mode: 'events' };
+
+/**
+ * One parameter, a JSON Schema subset (no `pattern`: an agent-written regular expression would run on
+ * the server). Names match `^[A-Za-z_][A-Za-z0-9_]{0,63}$`. `from` makes it VIEWER-BOUND: the server fills
+ * it from verified claims and refuses a client value for it, and no component may bind it.
+ *
+ * Constraints apply to their type only: `format`, `minLength` and `maxLength` to strings, `minimum` and
+ * `maximum` to numbers and integers; an `array` takes neither `enum` nor `default`. Bounds are not
+ * reversed; lengths count Unicode code points, as JSON Schema does. A `default` and every `enum` value
+ * satisfy the whole declaration (a `date` is a real calendar date, years 0001-9999; a `date-time` is
+ * RFC 3339 with seconds 00-59, any fraction, `Z` or an offset); strings in a `default` or an `enum` are at
+ * most 1,000 and 200 characters. A REQUIRED parameter with neither `from` nor a `default` must be bound at every
+ * component that uses its query or action.
+ */
+export interface AppParamSchema {
+  type: 'string' | 'number' | 'integer' | 'boolean' | 'array';
+  /** `array` only. */
+  items?: { type: 'string' | 'number' | 'integer' };
+  format?: 'date' | 'date-time' | 'uuid' | 'email';
+  enum?: Array<string | number>;
+  minimum?: number;
+  maximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  default?: string | number | boolean;
+  description?: string;
+  from?: 'viewer.email' | 'viewer.name' | 'viewer.id' | 'viewer.groups';
+}
+
+/** A query's or action's parameters: a JSON Schema object (at most 30 properties). */
+export interface AppParamsSchema {
+  type: 'object';
+  properties: Record<string, AppParamSchema>;
+  required?: string[];
+}
+
+/**
+ * A named read (DES §4 "Query"). Its text is `queries/<id>.<ext>` ({@link AppQueryKind}); the browser
+ * only ever sends the id and parameter values.
+ */
+export interface AppQuery {
+  id: string;
+  /** The source's name in crew's registry, or `crew` (the built-in source). */
+  source: string;
+  kind: AppQueryKind;
+  description?: string;
+  params?: AppParamsSchema;
+  /** 1-200 declared output columns; the result is projected to exactly these. */
+  output: AppOutputColumn[];
+  /** REST, GraphQL, MCP and crew (never SQL): where the rows are (a JSONPath subset, e.g. `$.items[*]`). */
+  rowPath?: string;
+  /** REST, GraphQL, MCP and crew (never SQL): where "another page exists" is read. */
+  morePath?: string;
+  refresh?: AppRefresh;
+  /** A public app may hold only public queries (DES §9.3). */
+  public?: boolean;
+}
+
+/** A value an action sends: a parameter, a literal fixed by the app (a string of at most 1,000 characters), a viewer claim, or crew's `now` or new uuid. */
+export type AppValue =
+  | AppParamValue
+  | { kind: 'literal'; value: string | number | boolean | null }
+  | { kind: 'viewer'; claim: 'email' | 'name' | 'id' }
+  | { kind: 'crew'; value: 'now' | 'uuid' };
+
+/** A declared parameter of the action. */
+export interface AppParamValue {
+  kind: 'param';
+  name: string;
+}
+
+/**
+ * An API action (DES §4 "Action"): one REST operation or MCP write tool by its registry tool name, or
+ * one GraphQL mutation document with one root field (at most 16 KB of UTF-8).
+ */
+export interface AppApiAction {
+  id: string;
+  kind: 'api';
+  source: string;
+  /** The mutation's single root field is the source stage's check. */
+  call: { kind: 'tool'; tool: string } | { kind: 'mutation'; mutation: string };
+  /** At most 50. */
+  args: Record<string, AppValue>;
+  params?: AppParamsSchema;
+  /** Shown on the card as "The app says" (at most 500 characters). */
+  description?: string;
+}
+
+/**
+ * A declared Postgres row write (DES §7.4): crew generates the one statement. `table` is
+ * schema-qualified (`support.tickets`, plain identifiers); `key` binds every primary-key column to a
+ * REQUIRED parameter; `set` is every column for an insert (each key column set from its own key
+ * parameter), the changed columns for an update (never a key column), and absent for a delete. Whether
+ * the columns are the table's real ones is the source stage's check.
+ */
+export interface AppRowWriteAction {
+  id: string;
+  kind: 'row-write';
+  source: string;
+  table: string;
+  op: 'insert' | 'update' | 'delete';
+  /** At most 200 columns. */
+  set?: Record<string, AppValue>;
+  /** 1-16 columns. */
+  key: Record<string, AppParamValue>;
+  params?: AppParamsSchema;
+  description?: string;
+}
+
+export type AppAction = AppApiAction | AppRowWriteAction;
+
+/**
+ * `apps.lock.json`, written by crew's check and committed with the tree it checked; never by an agent or
+ * a person (an edit that names it is refused). It pins what each query and action USES (DES §4):
+ * per source the kind, connection descriptor and its hash; per query the hash of its text and its
+ * contract hash; per action its declaration hash and contract hash; per upload the snapshot digest.
+ * Never a secret, never snapshot bytes. Hashes are lower-case hex SHA-256.
+ */
+export interface AppLock {
+  schema: 'wicked.apps.lock/v1';
+  sources: Record<string, AppLockSource>;
+  queries: Record<string, AppLockQuery>;
+  actions: Record<string, AppLockAction>;
+  uploads: Record<string, { digest: string }>;
+}
+
+export interface AppLockSource {
+  kind: string;
+  /** The non-secret connection descriptor (DES §4 "Source"). */
+  descriptor: Record<string, unknown>;
+  descriptorHash: string;
+}
+
+export interface AppLockQuery {
+  source: string;
+  textHash: string;
+  contractHash: string;
+}
+
+export interface AppLockAction {
+  source: string;
+  actionHash: string;
+  contractHash: string;
+}
+
+// ── Apps: the store and its routes (DES §6.4, §7.6, §9.1) ────────────────────────────────────────
+
+/**
+ * How a tree was accepted (DES §9.1). Only `you`, `reviewed` and `restored` make a tree part of the
+ * app's ACCEPTED HISTORY (undo, redo and restore move only within it); `published` binds a tree that
+ * already held one of those to a publish manifest.
+ */
+export type AppReceiptKind = 'you' | 'reviewed' | 'restored' | 'published';
+
+/**
+ * crew's record that a tree of THIS app passed a check and was accepted. Keyed by (app, tree): the same
+ * tree in another app holds nothing there. Minted only by crew: on a human actor's edit, undo, redo or
+ * restore, on an `apps-turn` run whose review by a distinct seat named the tree, and on a consented
+ * publish. Never stored in the app repo (agent seats mount it).
+ */
+export interface AppReceipt {
+  kind: AppReceiptKind;
+  tree: string;
+  /** The version that landed with it. */
+  version: number;
+  /** Unix millis. */
+  at: number;
+  /** Who accepted it: the person, or for `reviewed` the actor who launched the turn. */
+  actor: Actor;
+  /**
+   * `restored`: the version restored, and that version's own provenance followed through any chain of
+   * restores (`originKind` is `you` or `reviewed`, `originVersion` the version that first held it).
+   */
+  restoredFrom?: { version: number; originKind: 'you' | 'reviewed'; originVersion: number };
+  /** `reviewed`: the turn's run and the seats that built and reviewed it (always distinct). */
+  review?: { runId: string; builder: string; reviewer: string };
+  /** `published`: the publish run, the manifest digest and each produced artifact's digest. */
+  publish?: { runId: string; manifestDigest: string; artifacts: Record<string, string> };
+}
+
+/** Which checks ran before a version landed (DES §6.2 "Checks are staged by what changed"). */
+export interface AppCheckSummary {
+  /**
+   * `spec`: schema, bindings, link hosts and file confinement only (a layout, prop, theme or label
+   * change). `data`: those plus the read policy and the per-kind source check for what changed.
+   * `full`: those for every query and action (an undo, redo or restore, against today's sources).
+   */
+  level: 'spec' | 'data' | 'full';
+  /** Queries and actions the source stage checked (empty at `spec`). */
+  checked: string[];
+}
+
+/** One version: one commit on the app repo's `main`. */
+export interface AppVersion {
+  /** 1, 2, 3, … per app (the strip's `v14`). */
+  version: number;
+  commit: string;
+  tree: string;
+  /** The version it was made on; `null` for the first. */
+  base: number | null;
+  /** Unix millis. */
+  at: number;
+  /** A person (`human`), a seat that built a turn (`seat`), or crew itself (`crew`, an app's first version). */
+  author: { kind: 'human' | 'seat' | 'crew'; id: string };
+  /** The receipt it landed with; `null` = this tree never runs against a source. */
+  receipt: AppReceipt | null;
+  /** One line for the strip ("Moved the KPIs above the charts"), at most 200 characters. */
+  summary: string;
+  check: AppCheckSummary;
+}
+
+/**
+ * The undo pointer (DES §6.4), kept per app by crew so every tab agrees. `states` are the versions of
+ * the accepted history in order and `pointer` indexes the current one. Undo lands `states[pointer-1]`'s
+ * tree as a new version and moves the pointer back; redo lands `states[pointer+1]`'s; a new edit,
+ * landed turn or restore drops everything after the pointer and appends itself.
+ */
+export interface AppHistory {
+  states: number[];
+  pointer: number;
+  canUndo: boolean;
+  canRedo: boolean;
+}
+
+/** A turn in flight: the app is read-only for edits, undo, redo and restore until it ends (`409 turn_in_flight`). */
+export interface AppTurnState {
+  runId: string;
+  /** Unix millis. */
+  startedAt: number;
+  /** The version the turn builds on. */
+  base: number;
+  /** The actor id that launched it. */
+  actor: string;
+}
+
+/** `GET /apps` item. */
+export interface AppSummary {
+  /** `^[a-z][a-z0-9-]{0,47}$`; `check` and `uploads` are reserved. */
+  slug: string;
+  name: string;
+  projectId: string;
+  /** The app repo's id in crew's repo registry. */
+  repoId: string;
+  /** Unix millis. */
+  createdAt: number;
+  head: { version: number; tree: string; receipt: AppReceiptKind | null };
+  turn: AppTurnState | null;
+}
+
+/** `GET /apps` (observer); `?project=<id>` keeps one project's apps. */
+export interface AppsListResponse {
+  apps: AppSummary[];
+}
+
+/** `POST /apps` (operator): a new app, an empty repo in the project with crew's first version. */
+export interface CreateAppBody {
+  slug: string;
+  /** The app's title; defaults to the slug. */
+  name?: string;
+  projectId: string;
+}
+
+/** The app at head: the spec, the lock, every query's text, the versions and the undo pointer. */
+export interface AppDetail extends AppSummary {
+  spec: AppSpec;
+  lock: AppLock;
+  /** Query id → its text at head. */
+  queryText: Record<string, string>;
+  /** Oldest first. */
+  versions: AppVersion[];
+  history: AppHistory;
+}
+
+/** `GET /apps/:app` (observer), and `POST /apps` (201). */
+export interface AppDetailResponse {
+  app: AppDetail;
+}
+
+/**
+ * One change in an edit burst. `spec` replaces `apps.json`; `query-text` writes the text of a query the
+ * resulting spec declares (crew removes the text of a query the spec no longer declares). Nothing else
+ * in the repo can be written: `apps.lock.json` is crew's.
+ */
+export type AppEditOp = { op: 'spec'; spec: AppSpec } | { op: 'query-text'; query: string; text: string };
+
+/**
+ * `POST /apps/:app/edits` (HUMAN operator only): one `you` version from one edit burst (1-50 ops). `base`
+ * is the head version the edit was made on: a stale one is `409 stale_base`, and while a turn runs every
+ * edit is `409 turn_in_flight`.
+ */
+export interface AppEditsBody {
+  base: number;
+  ops: AppEditOp[];
+  /** The strip's line; crew writes one when absent. */
+  summary?: string;
+}
+
+/** `POST /apps/:app/undo` and `/redo` (HUMAN operator only). */
+export interface AppHistoryMoveBody {
+  base: number;
+}
+
+/**
+ * `POST /apps/:app/restore` (HUMAN operator only): land `version` (a version number, or a commit of the
+ * app repo) as a new version, only when its tree holds an accepted receipt for this app.
+ */
+export interface AppRestoreBody {
+  base: number;
+  version: number | string;
+}
+
+/** The answer to an edit, undo, redo or restore that landed: the app after it, and the version it made. */
+export interface AppLandedResponse {
+  app: AppDetail;
+  landed: AppVersion;
+}
+
+/**
+ * `POST /apps/:app/turns` (operator): one chat message becomes one governed `apps-turn` run (Build → Check →
+ * Review) on the head version. While it runs the app is read-only for edits, undo, redo and restore, and a second
+ * turn is `409 turn_in_flight`.
+ */
+export interface AppTurnBody {
+  /** The head version the message was written on; a stale one is `409 stale_base`. */
+  base: number;
+  /** 1-8,000 characters. */
+  message: string;
+  /** Component ids the message is about (the composer's chips), at most 20. */
+  about?: string[];
+}
+
+/** `POST /apps/:app/turns` 202. */
+export interface AppTurnResponse {
+  runId: string;
+  turn: AppTurnState;
+}
+
+/** `POST /apps/:app/query` (observer): run one named query of an accepted version (DES §7.2). */
+export interface AppQueryBody {
+  /** A version number, or a commit of the app repo; its tree must hold an accepted receipt. */
+  version: number | string;
+  query: string;
+  params?: Record<string, unknown>;
+}
+
+/** One cell: values are rendered as text by the runtime. */
+export type AppCell = string | number | boolean | null;
+
+/** `POST /apps/:app/query` 200 (DES §7.2). `rows` are aligned with `columns`. */
+export interface AppQueryResponse {
+  columns: AppOutputColumn[];
+  rows: AppCell[][];
+  truncated: boolean;
+  hasMore: boolean;
+  ms: number;
+  /** Unix millis of the cached answer, `null` when it ran now. */
+  cachedAt: number | null;
+}
+
+/** One reason a check refused a tree. `path` is a JSON path into `apps.json`, or a repo path. */
+export interface AppCheckFinding {
+  stage: 'spec' | 'files' | 'policy' | 'source';
+  code: string;
+  path: string;
+  message: string;
+}
+
+/**
+ * Every refusal the app routes answer, by `code`:
+ *  - 400 `bad_request`; 403 `human_only` (the route needs a human operator: an agent-kind token is refused);
+ *  - 404 `unknown_app`, `unknown_version`, `unknown_query`, `unknown_project`;
+ *  - 409 `stale_base` (with `head`), `turn_in_flight` (with `turn`), `not_accepted` (the tree holds no
+ *    accepted receipt for this app), `nothing_to_undo`, `nothing_to_redo`, `slug_taken` (with
+ *    `suggestion`), `source_check_unavailable` (the tree has queries or actions and this daemon cannot
+ *    run the source stage yet, so nothing lands);
+ *  - 422 `check_failed` (with `findings`), `reserved_slug`;
+ *  - 429 `rate_limited` (with `retryAfterMs`: a query queue or a per-viewer rate is full, DES §7.5);
+ *  - 501 `not_implemented` (a route a later slice serves; nothing happened);
+ *  - 503 `apps_unavailable`.
+ */
+export interface AppErrorBody {
+  code:
+    | 'bad_request'
+    | 'human_only'
+    | 'unknown_app'
+    | 'unknown_version'
+    | 'unknown_query'
+    | 'unknown_project'
+    | 'stale_base'
+    | 'turn_in_flight'
+    | 'not_accepted'
+    | 'nothing_to_undo'
+    | 'nothing_to_redo'
+    | 'slug_taken'
+    | 'source_check_unavailable'
+    | 'check_failed'
+    | 'reserved_slug'
+    | 'not_implemented'
+    | 'rate_limited'
+    | 'apps_unavailable';
+  error: string;
+  /** `rate_limited`: when to try again (also sent as `Retry-After`). */
+  retryAfterMs?: number;
+  head?: number;
+  turn?: AppTurnState;
+  findings?: AppCheckFinding[];
+  suggestion?: string;
+}
+
+/**
+ * {@link HealthCapabilities.apps} (api-types 0.172.0): present when crew serves the app store
+ * (`/api/v1/apps`, list, add, read, edits, undo, redo, restore); each flag is true only once its slice
+ * serves that route for real rather than answering `501`.
+ */
+export interface AppsCapabilities {
+  /** `POST /apps/:app/query` runs queries (until then it checks the receipt, then answers `501`). */
+  query: boolean;
+  /** `POST /apps/:app/actions/:id/prepare|run|grant`, `GET …/actions/records/:id`. */
+  actions: boolean;
+  /** `POST /apps/:app/turns` launches `apps-turn` runs. */
+  turns: boolean;
+  /** `POST /apps/:app/publish`. */
+  publish: boolean;
+  /** `POST /apps/uploads`. */
+  uploads: boolean;
+  /** The read policy and the per-kind source check run, so a change to queries or actions can land. */
+  sourceCheck: boolean;
+}
+
+/**
+ * `POST /repos` body. `create: true` (api-types 0.172.0, DES-APPS-001): crew makes `<apps root>/<name>`
+ * (`~/.wicked/apps` by default), runs `git init` with one empty commit and registers it; no onboarding
+ * run starts (`onboardRunId: null`), and `rootPath`/`gitUrl` are refused beside it. A taken name is
+ * `409 slug_taken` with a `suggestion`.
+ */
+export interface RegisterRepoBody {
+  name: string;
+  rootPath?: string;
+  gitUrl?: string;
+  create?: true;
+  projectId?: string;
+  channel?: 'studio' | 'cli' | 'api';
+  actor?: string;
+  autoCapture?: boolean;
+}

package/package.json

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