@anchrd/intel 0.59.0

package/src/contract/contract.ts

@@ -0,0 +1,161 @@
+import { z } from "zod";
+
+export const IntelId = z.string().min(1).max(128);
+export const IsoDateTime = z.iso.datetime({ offset: true });
+
+// ⚠️ One described primitive rather than the same sentence on twenty-odd fields (#398). The word
+// `idempotencyKey` means exactly the same thing everywhere it appears, and a reader who learns it
+// once at `node_create` should not have to re-read it at `flow_publish`. Twenty copies of one
+// sentence is also twenty places for it to drift, and `tools/list` would carry every copy.
+//
+// The description says what the caller has to DO, because that is the part a model gets wrong: it
+// invents a fresh key on the retry and creates the thing twice.
+export const IdempotencyKey = z
+  .string()
+  .min(8)
+  .max(200)
+  .describe(
+    "A caller-chosen key that makes this call safe to retry: repeating the same key returns the first result instead of doing the work twice. Reuse the SAME key when retrying one attempt, and a new one for a genuinely new call.",
+  );
+
+/**
+ * The short name a document or a published flow is offered under as a slash command (#775).
+ *
+ * ⚠️ One described primitive rather than the same sentence in two files, for the reason
+ * `IdempotencyKey` above gives: a document and a flow take the same kind of name out of the same
+ * catalogue, and a copy would be a second place for one sentence to drift. It sits here rather than
+ * in `node.ts` because `flow.ts` states it too, and this is the file both may read.
+ *
+ * ⚠️ The refusal spells the GRAMMAR, not the verdict. Zod's own `Invalid` tells a caller who sent
+ * `CRM Outreach` that something was wrong and not what would have worked, and the one thing they
+ * need is that the answer is `crm-outreach`.
+ *
+ * ⚠️ Uniqueness is NOT in this schema and cannot be: it is a question about the whole installation,
+ * across documents and flows at once, and it is answered where the write happens. A name another
+ * node or flow already holds is refused by name there, never quietly turned into a second one.
+ */
+export const PromptName = z
+  .string()
+  .regex(/^[a-z0-9-]{1,40}$/, {
+    error:
+      "A prompt name is 1 to 40 characters of lowercase letters, digits and hyphens, and nothing else: `crm-outreach`.",
+  })
+  .describe(
+    "The slash command this is offered under, written without the leading slash: `crm-outreach` reaches a client as `/crm-outreach`. Lowercase letters, digits and hyphens only, and unique over every document and flow in the installation — a name one of them already holds is refused and names its holder, never silently changed into another one.",
+  );
+
+/**
+ * The version a write is made against, in the one form every writer of versioned content takes it.
+ *
+ * ⚠️ It lived beside the two node writers until #459 and moved here when the flow graph became the
+ * third — the point at which the repository stops copying and names the thing. It could not simply
+ * be imported: `flow.ts` may not depend on `node.ts` (the graph is `table → node`, `flow-run →
+ * flow`, and everything → here), and a copy would have been a second place for one sentence to
+ * drift, which is exactly what `IdempotencyKey` above exists to avoid.
+ *
+ * ⚠️ Nullable and required are not the same thing, and here they stand together (#437). `null` is
+ * how something that has no version yet is addressed, and it is the only way to write its first
+ * content; leaving the field out says nothing at all and is refused. Whoever leaves it out is
+ * almost always holding a node or a flow created one call earlier, and the plain type error they
+ * used to get — "expected string, received undefined" — reads as "this field must be an id", about
+ * a field that cannot have one yet. Both refusals therefore name both ways instead.
+ *
+ * ⚠️ It stays required once a version exists, and that is what it is for: a mismatch is answered
+ * with a `409` rather than by overwriting somebody else's newer version. Making it `optional()` to
+ * smooth the first write is the repair that breaks the guard — an absent field would then have to
+ * mean "there is none", and the forgetful caller silently replaces the newest one.
+ *
+ * ⚠️ The bounds remain `IntelId`'s. The repeated `min(1)` adds no rule — it only puts the sentence
+ * on the second value that gets tried after `undefined`, the empty string.
+ *
+ * ⚠️ The sentence says what the field TAKES, not what the caller did wrong. It answers a wrong type
+ * as well as an absent field, and "is required" would be false about the first — which would be
+ * this same ticket one corner further on. A value that is merely too long keeps Zod's own `Too
+ * big`: that one is already a true statement about what was sent.
+ *
+ * ⚠️ The JSON Schema it produces is the one `IntelId.nullable()` produced — an `anyOf` of the
+ * bounded string and `null`, still `required` — so nothing on the MCP surface moves when a field
+ * changes over to it.
+ */
+export function baseVersion(rule: string) {
+  return z.union([IntelId.min(1, { error: rule }), z.null()], { error: rule });
+}
+
+// The languages whose UI catalog ships inside the surface. They live here rather than only in the UI
+// because `intel build` has to know them: a built-in language may be chosen as `ui.defaultLanguage`
+// without the customer listing a copy under `ui.languages` that would rot at every UI update.
+//
+// ⚠️ The list is a claim about the contents of packages/intel/ui/src/i18n and cannot be checked here.
+// `i18n.unit.ts` compares it against the catalogs actually built in; a language listed here without
+// a file gives a red run there instead of a UI that starts on a catalog which does not exist.
+export const UI_LANGUAGES = ["en", "de", "es"] as const;
+export type UiLanguage = (typeof UI_LANGUAGES)[number];
+
+/**
+ * A set of things the reader is only partly entitled to see: the ones they may see BY NAME, the
+ * rest as a NUMBER (ADR-0004 §3). Never the titles of the rest, in any field, ever — a warning or a
+ * refusal must not become a way of reading the tree.
+ *
+ * ⚠️ It lives here rather than in `share.ts` because two domains state it: a grant says what it
+ * does not reach (`UnreadableNodes`), and a refusal says who is still calling in
+ * (`ProblemDetails.callers`, #448). `contract.ts` may not import from `share.ts` — the graph
+ * between these files has to stay acyclic — and a copy would be a second place for one rule to
+ * drift, which is what `IdempotencyKey` and `baseVersion` above exist against.
+ */
+export const NamedOrCounted = z.strictObject({
+  titles: z.array(z.string().min(1).max(240)),
+  hidden: z.number().int().nonnegative(),
+});
+export type NamedOrCounted = z.infer<typeof NamedOrCounted>;
+
+/**
+ * ⚠️ `callers` is the one member here that is not about every problem, and it is deliberate (#448).
+ * RFC 9457 allows extension members for exactly this: `folder_execute_in_use` refuses to narrow a
+ * library folder while flows from outside still call into it, and the CALLERS are the only thing
+ * that makes the refusal actionable. They used to exist only inside `detail` — an English sentence
+ * built on the server — so a German or Spanish surface could do nothing but print it verbatim, and
+ * no surface could shorten it or link the titles.
+ *
+ * The split is the point: the server decides WHAT is named and what is only counted, because that
+ * is an authorization answer nobody else can give; the surface decides how the sentence READS,
+ * because that is a language answer no server can give.
+ *
+ * `detail` keeps its sentence rather than emptying out — MCP hands a model prose and has nothing to
+ * formulate with, and an empty `detail` beside a new field would be the worst of the three states.
+ * It is absent on every other problem, so a reader must not treat its presence as guaranteed.
+ */
+export const ProblemDetails = z.strictObject({
+  type: z.string(),
+  status: z.number().int().min(400).max(599),
+  title: z.string(),
+  detail: z.string().optional(),
+  instance: z.string().optional(),
+  code: z.string().optional(),
+  callers: NamedOrCounted.optional(),
+});
+export type ProblemDetails = z.infer<typeof ProblemDetails>;
+
+// Who the caller is, as Gate resolved it from the bearer: no token, and no capability list.
+//
+// ⚠️ `isAdmin` is the one exception, and it is a DRAWING instruction rather than a permission
+// (#416). MCP hides what a caller may not do by never registering the tool, so a model never sees a
+// door it cannot open; the browser has no equivalent and would have to offer an admin action to
+// everybody and answer with a 403. One boolean is what the shell needs to not do that.
+//
+// Two things keep it from becoming a capability list by degrees: it says what the shell may DRAW,
+// never what the server may do — every door still asks Gate itself — and it is one field with one
+// consumer. A second one is a second reason, written down when it exists.
+export const SessionUser = z.strictObject({
+  id: IntelId,
+  email: z.email(),
+  name: z.string().min(1).max(240).nullable(),
+  isAdmin: z.boolean(),
+});
+export type SessionUser = z.infer<typeof SessionUser>;
+
+// One reference, never a list. The old `knowledge` node carried up to a hundred, plus a retrieval
+// mode and a query that nothing read — three things in one, and the last two describing a retrieval
+// Intel does not perform (D24: the agent fetches, Intel does not put anything into a context).
+// Splitting by kind is what makes "exactly one" sayable at all, and it lets the editor filter the
+// picker by what the node is for.
+export const LinkConfiguration = z.strictObject({ resourceId: IntelId });

package/src/contract/feed.ts

@@ -0,0 +1,165 @@
+import { z } from "zod";
+import { IntelId, IsoDateTime } from "./contract.ts";
+
+// What a person did, in the words a person would use. This is a POSITIVE LIST and not the set of
+// actions the journal carries (#740).
+//
+// ⚠️ Two omissions are the point of the list, not an oversight. `node.version` is written by the
+// same batch as `node.save`, so admitting both would show every edit twice — and because this feed
+// does not group anything yet, twice means two cards. `node.link` and `node.import` are machine
+// traces of a save rather than something anybody did.
+//
+// ⚠️ And it stays a positive list. "Everything except" would silently admit whatever the next
+// migration starts writing, on a surface whose whole job is to be readable.
+export const FeedAction = z.enum([
+  "node.create",
+  "node.save",
+  "node.update",
+  "node.append",
+  "node.archive",
+  // ⚠️ The one event whose node no longer exists when it is read. Its visibility runs over the
+  // surviving folder, from `parentId` in the metadata, and its title comes from there too — the row
+  // it would have been read from is gone (#645).
+  "node.purge",
+  "node.share",
+  "node.revoke",
+  // The flow half (#763). Twelve kinds are written; these are the ones a person did rather than a
+  // machine bookkeeping step.
+  //
+  // ⚠️ **`flows.run` is deliberately NOT here, and its two siblings are** (#767, Jacks Entscheidung
+  // 2026-08-24). A run writes up to three events, and an agent runs often — without summarising,
+  // which #742 struck, twenty runs on one morning would be sixty cards and every human entry would
+  // lie buried under them.
+  //
+  // The END was chosen over the START, and not because it is cheaper: a finished run carries BOTH
+  // pieces — that it ran *and* how it went — while a start carries half of one. A run that hangs or
+  // fails looks exactly like one that sailed through, and that is the case somebody opens the feed
+  // for. What it costs is that a long run is invisible until it ends; that is the deliberate price
+  // of needing no merge over the run id, which is the only way a start-card could later be updated.
+  //
+  // ⚠️ These two are the only actions in this list written against `resource_type = 'flow-run'`,
+  // with the RUN's id — which is why `feedResourceTypeOf` exists below and why the query needs a
+  // third visibility walk (run → flow → folder) and a title read from the flow.
+  "flows.complete",
+  "flows.cancel",
+  "flows.create",
+  "flows.save",
+  "flows.update",
+  "flows.publish",
+  "flows.unpublish",
+  "flows.archive",
+  "flows.share",
+  "flows.revoke",
+  // ⚠️ The flow-side twin of `node.purge`, and it carries the same two consequences: its row is
+  // gone when the card is read, so both its visibility and its title come from the metadata of the
+  // event itself (#763, D73).
+  "flows.purge",
+]);
+export type FeedAction = z.infer<typeof FeedAction>;
+
+/**
+ * What an entry is about. Derived from the action rather than carried separately: the two can then
+ * never disagree, and a reader that has to draw a flow differently from a document does not depend
+ * on a second field being filled in correctly.
+ */
+export function feedKindOf(action: FeedAction): "node" | "flow" {
+  return action.startsWith("flows.") ? "flow" : "node";
+}
+
+/**
+ * Which `resource_type` the journal wrote an action against — a different question from
+ * `feedKindOf`, and the two answers disagree on purpose for exactly two actions (#767).
+ *
+ * A card about a finished run is a card about a **flow**: that is what it names, that is where it
+ * links, and `feedKindOf` says so. But the ROW it was written as carries `flow-run` and the run's
+ * id, so the query has to find it under a third kind and walk run → flow → folder to decide whether
+ * it may be seen.
+ *
+ * ⚠️ Derived here rather than written out beside the SQL. A second list that has to agree with this
+ * one is a second list too many — the same reason `NODE_ACTIONS` and `FLOW_ACTIONS` are filtered
+ * out of `FeedAction.options` instead of being typed again.
+ */
+export function feedResourceTypeOf(action: FeedAction): "node" | "flow" | "flow-run" {
+  if (action === "flows.complete" || action === "flows.cancel") return "flow-run";
+  return feedKindOf(action);
+}
+
+// One step on the way down to the node, from the root. It carries the id as well as the title
+// because the surface links each step, and two folders may share a name.
+export const FeedPathSegment = z.strictObject({
+  id: IntelId,
+  title: z.string().min(1),
+});
+export type FeedPathSegment = z.infer<typeof FeedPathSegment>;
+
+// One card's worth of journal.
+//
+// ⚠️ `resourceTitle` and `path` are read from `nodes` or `flows` at query time, so they are TODAY's
+// title and today's place — not the ones the thing had when the event happened. That is the right
+// answer for a feed (the reader wants to find it now) and the wrong one for an audit trail, which is
+// one more reason these are two doors and not one.
+//
+// ⚠️ The fields say `resource` and not `node` because half of them are not nodes (#763). Which half
+// is answered by `feedKindOf(action)` and by nothing on the card — a second field saying "flow"
+// beside an action that already says `flows.publish` is a second truth, and two truths disagree.
+//
+// `metadata` is whatever the write site recorded, untyped on purpose: a schema per action would
+// have to be kept in step with eleven write sites and would go stale in silence. What the surface
+// needs from it today is `sequence` on a `node.save`, which is the version number behind the card's
+// button.
+export const FeedEvent = z.strictObject({
+  id: IntelId,
+  actorId: z.string().min(1),
+  action: FeedAction,
+  resourceId: IntelId,
+  resourceTitle: z.string().min(1),
+  path: z.array(FeedPathSegment),
+  metadata: z.record(z.string(), z.unknown()),
+  occurredAt: IsoDateTime,
+});
+export type FeedEvent = z.infer<typeof FeedEvent>;
+
+// ⚠️ Opaque BY CONTRACT, like the audit cursor and for the same reason: it is a PAIR
+// (`occurredAt`, `id`), and a timestamp alone cannot separate two events written in the same
+// millisecond — the normal case inside one batch. A reader continuing on the timestamp alone skips
+// the second one with no error and no log.
+//
+// ⚠️ It is deliberately NOT interchangeable with an audit cursor, although both encode the same
+// pair. The two doors walk the journal in opposite directions, so handing one's position to the
+// other reads on from the wrong end — and would look like a feed that suddenly starts at the
+// beginning of time rather than like a mistake. The encoding therefore carries its own marker and
+// the other door's cursor is refused.
+export const FeedCursor = z.string().min(1).max(400);
+
+export const FeedListRequest = z.strictObject({
+  actor: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      "Show only what this person or agent did. Omit it for everybody whose work you may see anyway.",
+    ),
+  before: FeedCursor.optional().describe(
+    "Where to continue: the `nextCursor` of a previous answer, passed back unchanged. Omit it to start at the most recent event. Do not build one — it is opaque on purpose, and a cursor from `audit_list` is refused rather than followed backwards.",
+  ),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .default(30)
+    .describe("How many events to return at most. The answer may be shorter."),
+});
+export type FeedListRequest = z.infer<typeof FeedListRequest>;
+
+// `nextCursor` is present exactly when another page may exist, and it is the cursor of the LAST
+// returned row.
+//
+// ⚠️ Present does not promise the next page is non-empty: the rows a reader may see can shrink
+// between calls. Treating "cursor present" as "there is more" is fair; treating an empty answer as
+// "you have reached the beginning of the journal" is not.
+export const FeedListResponse = z.strictObject({
+  events: z.array(FeedEvent),
+  nextCursor: FeedCursor.nullable(),
+});
+export type FeedListResponse = z.infer<typeof FeedListResponse>;

package/src/contract/flow-run.ts

@@ -0,0 +1,241 @@
+import { z } from "zod";
+import { IdempotencyKey, IntelId, IsoDateTime } from "./contract.ts";
+import { FlowNode, FlowNodeId } from "./flow.ts";
+
+// ⚠️ No `waiting`. It was written for the approval node and never set by anything — the two places
+// that tested for it only ever saw `running` (#73). The column's CHECK constraint still allows the
+// value, deliberately: rewriting it means rebuilding the table in D1 for a value nothing writes,
+// and migration 0007 turns any row that somehow carries it into `failed` rather than leave a status
+// the contract cannot parse.
+export const FlowRunStatus = z.enum(["queued", "running", "completed", "failed", "cancelled"]);
+export type FlowRunStatus = z.infer<typeof FlowRunStatus>;
+export const FlowRun = z.strictObject({
+  id: IntelId,
+  flowId: IntelId,
+  versionId: IntelId,
+  status: FlowRunStatus,
+  currentNodeId: FlowNodeId.nullable(),
+  input: z.record(z.string(), z.unknown()),
+  output: z.unknown().nullable(),
+  error: z.string().max(2_000).nullable(),
+  initiatedBy: IntelId,
+  // The subflow node this run was called from, and the run that node belongs to. A called run is a
+  // run of its own: it has its own version, its own steps and its own authorization, and only these
+  // two fields say where its result goes back to.
+  parentRunId: IntelId.nullable().default(null),
+  parentNodeId: FlowNodeId.nullable().default(null),
+  createdAt: IsoDateTime,
+  updatedAt: IsoDateTime,
+  completedAt: IsoDateTime.nullable(),
+});
+export type FlowRun = z.infer<typeof FlowRun>;
+
+// Which step of which flow is running, outermost caller first. Readable rather than reconstructed
+// from `parentRunId` by whoever is looking (#17).
+export const FlowRunTrailEntry = z.strictObject({
+  runId: IntelId,
+  flowId: IntelId,
+  flowTitle: z.string().min(1).max(240),
+  nodeId: FlowNodeId.nullable(),
+  nodeLabel: z.string().max(160).nullable(),
+});
+export type FlowRunTrailEntry = z.infer<typeof FlowRunTrailEntry>;
+
+export const FlowRunStep = z.strictObject({
+  run: FlowRun,
+  node: FlowNode.nullable(),
+  trail: z.array(FlowRunTrailEntry).default([]),
+});
+export type FlowRunStep = z.infer<typeof FlowRunStep>;
+export const StartFlowRunInput = z.strictObject({
+  flowId: IntelId.describe(
+    "Flow to run. It has to be published; the run takes the published version, not the newest one.",
+  ),
+  input: z
+    .record(z.string(), z.unknown())
+    .default({})
+    .describe(
+      "The values the flow's trigger node declares. An empty object is right for a flow that asks for nothing.",
+    ),
+  // Present when this run is the call a subflow node makes. It names a place, never a permission:
+  // the callee's `execute` is asked of the user exactly as it is for a run they start themselves,
+  // and the parent run must be the caller's own and standing on that very node.
+  parent: z
+    .strictObject({
+      runId: IntelId.describe("The calling run."),
+      nodeId: FlowNodeId.describe("The subflow node in that run which is making the call."),
+    })
+    .nullable()
+    .default(null)
+    .describe(
+      "Leave at `null`. It is set only when a subflow node makes this call, and it names a place rather than a permission: the callee's `execute` is still asked of the user.",
+    ),
+  idempotencyKey: IdempotencyKey,
+});
+export type StartFlowRunInput = z.infer<typeof StartFlowRunInput>;
+export const GetFlowRunInput = z.strictObject({
+  runId: IntelId.describe(
+    "Run to read. A run has an address of its own because it outlives its flow; the id comes from flow_run_start or flow_run_list.",
+  ),
+});
+export type GetFlowRunInput = z.infer<typeof GetFlowRunInput>;
+// Ending a run on purpose (#145). Until this existed the only way off a parked manual step was
+// `completeStep` with `outcome: "failed"` — which recorded a step failure that never happened.
+// Cancelling records nothing into the step history: the run ends, the history stays true.
+export const CancelFlowRunInput = z.strictObject({
+  runId: IntelId.describe(
+    "Run to end on purpose. This is the way off a run parked on a manual step — it records nothing into the step history, unlike completing the step as `failed`, which would report a failure that never happened.",
+  ),
+  idempotencyKey: IdempotencyKey,
+});
+export type CancelFlowRunInput = z.infer<typeof CancelFlowRunInput>;
+export const CompleteFlowRunStepInput = z.strictObject({
+  runId: IntelId.describe("Run that is waiting."),
+  nodeId: FlowNodeId.describe(
+    "The node the run is standing on, from flow_run_get. Answering any other node is refused: this completes the step that is waiting, not a step of one's choosing.",
+  ),
+  outcome: z
+    .enum(["completed", "failed"])
+    .describe("Whether the step is done or could not be done. `failed` ends the run at this node."),
+  branch: z
+    .string()
+    .min(1)
+    .max(120)
+    .nullable()
+    .default(null)
+    .describe(
+      "Which way out of a branching node the run takes, by the label on the edge. `null` for a node with one way out.",
+    ),
+  output: z
+    .unknown()
+    .nullable()
+    .default(null)
+    .describe(
+      "What the step produced, for the nodes after it to read. `null` when it produced nothing.",
+    ),
+  error: z
+    .string()
+    .max(2_000)
+    .nullable()
+    .default(null)
+    .describe(
+      'Why it could not be done. Belongs with `outcome: "failed"` and is what the run\'s failure will say.',
+    ),
+  idempotencyKey: IdempotencyKey,
+});
+export type CompleteFlowRunStepInput = z.infer<typeof CompleteFlowRunStepInput>;
+
+// Why a run started. Derived when it is read and deliberately not a column: `subflow` when the run
+// is the call another run made, otherwise the mode of the trigger node in the immutable version the
+// run took. A stored copy would be a second answer that could disagree with the graph that ran.
+//
+// ⚠️ `webhook` and `schedule` stood here until #39 took them out of the trigger node. Being derived
+// rather than stored is exactly what makes that safe: no run carries a trigger of its own, so once
+// the 0005 migration has rewritten every stored trigger to `manual`, there is nowhere left for the
+// old values to come from. Had this been a column, the enum would have had to keep reading them or
+// every old run would have failed to parse the moment somebody opened the list.
+export const FlowRunTrigger = z.enum(["manual", "subflow"]);
+export type FlowRunTrigger = z.infer<typeof FlowRunTrigger>;
+
+// Which step ended a run, and why, in the words the failure already used (#20).
+//
+// ⚠️ A call that failed carries its reason in the *called* run, and that run is a run of its own
+// with its own authorization. `calledRunId` is therefore filled only when the asking user may see
+// that run through the very rule every other run answer uses; otherwise the failure is named by the
+// calling step alone — the caller's own label — and `detail` says no more than that it did not
+// finish. Naming a callee's step or document here would be the leak #17, #19 and #20 each closed.
+export const FlowRunFailure = z.strictObject({
+  nodeId: FlowNodeId,
+  nodeLabel: z.string().max(160),
+  detail: z.string().max(2_000),
+  calledRunId: IntelId.nullable(),
+});
+export type FlowRunFailure = z.infer<typeof FlowRunFailure>;
+
+// One run as a list shows it: what it did, never what it produced.
+//
+// ⚠️ Neither `input` nor `output` is in here, on purpose. A run reaches its nodes and its tools
+// with the rights of whoever started it, so its result is a way to content the next reader of this
+// list may have no claim to. Whoever wants a result asks for the run itself, where the same rule
+// decides again.
+export const FlowRunSummary = z.strictObject({
+  id: IntelId,
+  flowId: IntelId,
+  // The version the run took. Together with the run's stored input it is what a later "run this
+  // again with the old data" would need; replaying is a separate ticket, this only keeps it possible.
+  versionId: IntelId,
+  status: FlowRunStatus,
+  trigger: FlowRunTrigger,
+  startedAt: IsoDateTime,
+  completedAt: IsoDateTime.nullable(),
+  durationMs: z.number().int().nonnegative().nullable(),
+  initiatedBy: IntelId,
+  parentRunId: IntelId.nullable(),
+  failure: FlowRunFailure.nullable(),
+});
+export type FlowRunSummary = z.infer<typeof FlowRunSummary>;
+
+// One filter and nothing else: "only the failed ones" is the question asked in almost every case,
+// and every further facet is a report rather than a search for a fault.
+export const ListFlowRunsInput = z.strictObject({
+  /**
+   * ⚠️ `nullable` since #774, and the null case is the point rather than a convenience.
+   *
+   * With a flow named, this answers "what did THIS flow do". Without one it answers "did anything
+   * run at all" — the question somebody actually has, and the one that used to take one call per
+   * flow. An installation with sixteen flows made that sixteen calls, so in practice nobody asked
+   * it and a working agent was indistinguishable from a silent one.
+   *
+   * The visibility does not change with it: `runVisible` decides per ROW either way — their own
+   * runs, plus every run of a flow they may read.
+   */
+  flowId: IntelId.nullable()
+    .default(null)
+    .describe(
+      "Flow whose runs to list, newest first. `null` lists the runs of every flow you may read — the answer to `did anything run`, which otherwise takes one call per flow. Each row carries its flowId; the titles come from flow_list in one call.",
+    ),
+  failedOnly: z.boolean().default(false).describe("List only the runs that failed."),
+  limit: z.number().int().min(1).max(50).default(20).describe("How many runs per page."),
+  // The `nextCursor` of the previous page. Keyset rather than an offset, because runs arrive while
+  // someone reads and an offset would skip or repeat rows exactly when a flow is busy.
+  cursor: z
+    .string()
+    .min(1)
+    .max(400)
+    .nullable()
+    .default(null)
+    .describe(
+      "The `nextCursor` of the previous page, or `null` for the first. It is a keyset rather than an offset, so runs arriving while someone reads neither skip nor repeat a row.",
+    ),
+});
+export type ListFlowRunsInput = z.infer<typeof ListFlowRunsInput>;
+
+export const FlowRunList = z.strictObject({
+  items: z.array(FlowRunSummary),
+  nextCursor: z.string().max(400).nullable(),
+});
+export type FlowRunList = z.infer<typeof FlowRunList>;
+
+// One completed step of one run. `detail` is the step's own error text; an output is absent for the
+// same reason it is absent from the summary.
+export const FlowRunStepRecord = z.strictObject({
+  nodeId: FlowNodeId,
+  nodeLabel: z.string().max(160),
+  outcome: z.enum(["completed", "failed"]),
+  branch: z.string().max(120).nullable(),
+  detail: z.string().max(2_000).nullable(),
+  calledRunId: IntelId.nullable(),
+  completedAt: IsoDateTime,
+});
+export type FlowRunStepRecord = z.infer<typeof FlowRunStepRecord>;
+
+// What one run did, step by step, oldest first, with the call chain it belongs to (#17). The trail
+// is what makes a nested run readable: which step of which flow this run is.
+export const FlowRunHistory = z.strictObject({
+  runId: IntelId,
+  flowId: IntelId,
+  status: FlowRunStatus,
+  steps: z.array(FlowRunStepRecord),
+  trail: z.array(FlowRunTrailEntry),
+});
+export type FlowRunHistory = z.infer<typeof FlowRunHistory>;