src/job-touches.ts

Functions

Imports

It imports no other module of this repo. Imported by src/jobs-holder.ts, src/jobs-seat.ts, src/provenance.ts.

Source

1// THE HUMAN-TOUCH LOG (migrations/0023, job_touches): one row every time a person, or a
2// policy acting for one, touched a job. Without it a job that needed four rescues and
3// one that needed none both end "merged", and human effort confounds any comparison of
4// agents.
5//
6// Each row rides in the same guarded batch as the transition it records (block, resume,
7// release, supersede, the seat's fail or complete, a review verdict acted on), so a transition the
8// guard refuses writes no touch, and a touch never describes a move that did not happen.
9
10// The CHECK on job_touches.kind (migrations/0023, widened by 0031). test/job-touches-migration.test.ts
11// reads the CHECK from the schema every migration builds and compares it with this list both ways.
12export const TOUCH_KINDS = ["gate", "resume", "approval", "correction", "note", "release", "supersede", "admin_fail", "admin_complete", "review"] as const;
13type TouchKind = (typeof TOUCH_KINDS)[number];
14
15export const ACTOR_KINDS = ["human", "seat", "driver", "policy", "reviewer", "system"] as const;
16export type ActorKind = (typeof ACTOR_KINDS)[number];
17
18// The seat's minted credentials, by agent name (scripts/mint-agents.ts: `seat`, and
19// `site-seat` for dustinedwards). A legacy operator key (`opkey:`) is the seat's too.
20const SEAT_AGENTS = new Set(["agent:seat", "agent:site-seat"]);
21// Credentials that act on a schedule rather than for a person: the watcher
22// (src/watcher.ts, WATCHER_ACTOR), the skills refresh (src/skills-refresh.ts) and the
23// tick's own document writes (src/doc-statements.ts, SYSTEM_ACTOR). Spelled here rather than imported,
24// so this stays a pure module the unit tests load without the Worker.
25const SYSTEM_ACTORS = new Set(["agent:watcher", "agent:skills-refresh", "improve-loop"]);
26
27export interface ActorContext {
28  // A driver's own resume under the signed gate policy (resumeJob's approved_by_policy
29  // by a caller that is not the seat). The approval is the policy's, not a person's.
30  policy?: boolean;
31  // The touch records a review verdict, whose actor is the login on the comment.
32  reviewer?: boolean;
33  // The caller is the seat by its flags (callerIsSeat: admin or can_merge), which a
34  // seat credential minted under another name still is.
35  seat?: boolean;
36}
37
38/**
39 * Who touched a job, as one of the six kinds job_touches.actor_kind allows. The one
40 * place this is decided, so the log and every reader agree.
41 *
42 * A person first: `access:` is the administrator's Access login (the MCP login and the
43 * Portal both), `github:` the same person on rows the old console wrote. Both are
44 * human even though they also pass callerIsSeat, because the question here is who
45 * acted, not what they were allowed to do.
46 */
47export function actorKind(actor: string, context: ActorContext = {}): ActorKind {
48  if (context.policy) return "policy";
49  if (context.reviewer) return "reviewer";
50  if (actor.startsWith("access:") || actor.startsWith("github:")) return "human";
51  if (actor.startsWith("opkey:") || SEAT_AGENTS.has(actor) || context.seat) return "seat";
52  if (actor === "agent:reviewer") return "reviewer";
53  if (SYSTEM_ACTORS.has(actor)) return "system";
54  // `<ns>-driver`. Any other minted agent that holds a job is working it, so it is a
55  // driver too.
56  if (actor.startsWith("agent:")) return "driver";
57  return "system";
58}
59
60export interface Touch {
61  job_id: string;
62  namespace: string;
63  kind: TouchKind;
64  actor: string;
65  actor_kind: ActorKind;
66  // JSON-serialised as given; undefined keys drop out.
67  detail?: Record<string, unknown> | null;
68  // The touch ends a wait: waited_ms is measured from the job's latest gate row.
69  sinceGate: boolean;
70  // ISO with milliseconds, from the same `now` the transition binds.
71  at: string;
72}
73
74/**
75 * The INSERT for one touch. `at` is bound, not defaulted, so waited_ms is the
76 * difference of two times from the same clock the transition used. waited_ms is
77 * computed in SQL from the latest gate row for the job (by id, which the append-only
78 * table keeps in insertion order), so a gate written earlier in the same batch counts,
79 * and NULL when the job never hit one or the touch does not end a wait.
80 */
81export function touchStatement(db: D1Database, touch: Touch): D1PreparedStatement {
82  return db
83    .prepare(
84      `INSERT INTO job_touches (job_id, namespace, kind, actor, actor_kind, waited_ms, detail, at)
85       VALUES (?1, ?2, ?3, ?4, ?5,
86         CASE WHEN ?8 = 1 THEN (SELECT CAST(ROUND((julianday(?7) - julianday(g.at)) * 86400000.0) AS INTEGER)
87           FROM job_touches g WHERE g.job_id = ?1 AND g.kind = 'gate' ORDER BY g.id DESC LIMIT 1) END,
88         ?6, ?7)`
89    )
90    .bind(
91      touch.job_id,
92      touch.namespace,
93      touch.kind,
94      touch.actor,
95      touch.actor_kind,
96      touch.detail ? JSON.stringify(touch.detail) : null,
97      touch.at,
98      touch.sinceGate ? 1 : 0
99    );
100}