src/controls-base.ts

Functions

Imports

It imports src/canon.ts, src/jobs-schema.ts, src/ops-types/portal.ts, src/outcome-prs.ts. Imported by src/controls-perform.ts, src/controls-plan.ts, src/controls-token.ts, src/controls.ts, src/tools/controls.ts.

Source

1import type { SweepItem } from "./canon";
2import type { JobRow } from "./jobs-schema";
3import type { PortalAction } from "./ops-types/portal";
4import { prUrlsFromJob } from "./outcome-prs";
5
6// The admin controls' shared vocabulary (src/controls.ts is the core): the action list,
7// the audit row names, and the helpers both the plan and the perform read.
8
9export const PORTAL_ACTIONS: readonly PortalAction[] = [
10  "overnight",
11  "resume_job",
12  "fail_job",
13  "release_job",
14  "close_shipped",
15  "supersede_job",
16  "park_job",
17  "unpark_job",
18  "pr_close",
19  "approve_pr",
20  "revoke_agent",
21  "site_add",
22  "site_edit",
23  "site_remove",
24  "reset_breaker",
25  "package_add",
26  "package_edit",
27  "package_remove",
28  "canon_approve",
29  "canon_reject",
30  "canon_approve_all",
31  "site_repair",
32  "sign_policy_change",
33  "sign_policy_from_repo",
34  "unit_resume",
35  "automerge_resume",
36];
37
38export type ActionParams = Record<string, string | undefined>;
39
40// The click's own audit row is `<prefix><action>`. Rows written before the move to
41// /portal say console-<action>; a query across that date names both (docs/schema.md).
42const CLICK_AUDIT_PREFIX = "portal-";
43
44// The automation switch (overnight) takes a reason in both directions, and an Undo
45// from the Portal's result message sends the reverse change with undo: "true". Its click row is then `portal-undo-<action>`, so an undo reads as its
46// own row, never as a fresh decision (ruled 2026-09-30, DECIDE 5).
47export const SWITCHES: ReadonlySet<PortalAction> = new Set<PortalAction>(["overnight"]);
48const UNDO_INFIX = "undo-";
49
50// Which front door an action came in by. A click in the Portal and a call to the
51// controls tool are the same control; the audit row says which (controls design,
52// section 2): portal-<action> from the Portal as it always was, control-<action>
53// from chat.
54export type Surface = "portal" | "chat";
55const CHAT_AUDIT_PREFIX = "control-";
56export const auditPrefix = (surface: Surface) => (surface === "portal" ? CLICK_AUDIT_PREFIX : CHAT_AUDIT_PREFIX);
57
58/** The click row's action name: portal-<action>, or portal-undo-<action> for an Undo
59 *  (control- for chat). */
60export function clickAuditAction(action: PortalAction, params: ActionParams, surface: Surface = "portal"): string {
61  return `${auditPrefix(surface)}${params.undo === "true" ? UNDO_INFIX : ""}${action}`;
62}
63
64/** What a switch without a reason is told, at preview and again at perform. */
65export function switchReasonRefusal(action: PortalAction): string {
66  switch (action) {
67    case "overnight":
68      return "overnight needs a reason: why the overnight run goes on, off, or changes what it runs on. It is recorded in the audit row with the change.";
69    default:
70      return `${action} needs a reason, recorded in the audit row with the change.`;
71  }
72}
73
74export const UNKNOWN_ACTION = (action: string) =>
75  `unknown Portal action '${action}'. The Portal does: ${PORTAL_ACTIONS.join(", ")}. Merging a pull request and minting a credential are deliberately not among them: a merge can start a deploy and stays behind can_merge, and a mint hands out a key.`;
76
77export function isPortalAction(value: unknown): value is PortalAction {
78  return typeof value === "string" && (PORTAL_ACTIONS as readonly string[]).includes(value);
79}
80
81/** A revision param as a positive integer, or null. */
82export function revisionOf(raw: string | undefined): number | null {
83  if (!raw || !/^[1-9][0-9]{0,9}$/.test(raw)) return null;
84  return Number(raw);
85}
86
87export const UNIT_RESUME_REASON = "unit_resume needs a reason: why the rollback that suspended the unit is answered. It is recorded in the audit row.";
88export const AUTOMERGE_RESUME_REASON = "automerge_resume needs a reason: why the rollbacks or reverts that paused the namespace are answered. It is recorded in the audit row.";
89export const CANON_REJECT_REASON = "canon_reject needs a reason: the proposer reads it, and a rejection with no reason is one nobody can act on.";
90
91// canon_approve_all's preview, one line per proposal in the order the perform runs them:
92// every rejection, then every approval, each by id.
93export function sweepOrder(items: readonly SweepItem[]): SweepItem[] {
94  return [...items.filter((i) => i.outcome !== "approve"), ...items.filter((i) => i.outcome === "approve")];
95}
96
97// close_shipped's complete (stale jobs D4, ruled 2026-10-09: the existing admin_complete
98// path, crediting the holder). The pull requests the job names, from result_ref and the
99// summary, become the evidence the outcome verifies, at most the 10 the capsid_work_jobs tool takes.
100const CLOSE_SHIPPED_MAX_PRS = 10;
101export function shippedEvidence(job: JobRow): { result_ref?: string; prs: string[]; more: number } {
102  const all = prUrlsFromJob(job);
103  const prs = all.slice(0, CLOSE_SHIPPED_MAX_PRS);
104  const ref = job.result_ref && prs.includes(job.result_ref) ? job.result_ref : prs[0];
105  return { ...(ref ? { result_ref: ref } : {}), prs, more: all.length - prs.length };
106}