@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/src/levers.ts

@@ -0,0 +1,393 @@
+// The dispatch levers: `drain` and `pause-pr`, and who may hold them for how
+// long.
+//
+// Both levers stop new review work — the drain all of it, a pause one PR's;
+// a round already running finishes either way. An LLM session must never
+// hold an uncapped availability lever, so the SESSION's hold is bounded and
+// the OPERATOR's is not:
+//
+//   * An OPERATOR lever is the deploy flow's valve. `qcr drain on` engages it,
+//     the new boot's first healthy reconcile pass lifts it (daemon.ts), and it
+//     has no expiry — a broken deploy must not resume work blind.
+//   * The operator's HOLD (`qcr drain on --hold`) is the one drain the
+//     boot does NOT lift: it stands until an explicit operator `drain off`.
+//     The cutover uses it, so no round starts until the owner has triggered
+//     and checked one worker round. Only the operator can set one — a
+//     session's ask for a hold is refused, never shortened into a plain drain.
+//   * A SESSION lever ALWAYS carries an expiry and ALWAYS draws on a per-day
+//     minute budget. The grant type below has no member that spells a session
+//     hold without an expiry, and `boundSessionGrant` refuses or shortens
+//     anything past the configured cap. A session cannot lift an operator's
+//     hold and cannot widen one; an operator's grant upgrades a session's.
+//
+// WHO is deciding is never read from the command file. It is decided by which
+// command directory the file arrived in (`src/commands.ts`): the operator's
+// directory is root-owned and unwritable by the daemon's uid — the uid every
+// session runs as — so a session cannot put a file there, and a file that
+// arrives there without that seal is treated as a session's. See
+// `operatorSealVerdict` in commands.ts.
+import { atomicCommandEffect, commandEffectKey } from "./commandeffects.js";
+import type { LeversConfig } from "./config.js";
+import { opsDay } from "./eod.js";
+import type { FileOutcome } from "./improvements.js";
+import type { StateStore } from "./state.js";
+
+export type LeverIssuer = "operator" | "session";
+export type LeverKind = "drain" | "pause";
+
+/**
+ * A hold as granted. The union is the brace: a session grant carries an
+ * `expires_at` STRING, never null — there is no way to write a session hold
+ * that lasts until lifted.
+ */
+export type LeverGrant =
+  | { issuer: "operator"; expires_at: string | null; hold?: false }
+  /** The operator's no-auto-lift drain: no expiry, ever, and no session member. */
+  | { issuer: "operator"; expires_at: null; hold: true }
+  | { issuer: "session"; expires_at: string };
+
+/** A hold as stored: the same shape, read back. `hold` is set only on the
+ * operator's no-auto-lift drain (never on a pause, never on a session's). */
+export interface LeverHold {
+  issuer: LeverIssuer;
+  expires_at: string | null;
+  hold?: true;
+}
+
+export type HoldOutcome = "engaged" | "upgraded" | "extended" | "unchanged";
+
+/** Later of two expiries, where `null` (until lifted) is the latest of all. */
+function widerExpiry(a: string | null, b: string | null): string | null {
+  if (a === null || b === null) return null;
+  return a > b ? a : b;
+}
+
+/** The stored shape of a grant: `hold` only when the grant is the operator's hold. */
+function holdOf(grant: LeverGrant): LeverHold {
+  return grant.issuer === "operator" && grant.hold === true
+    ? { issuer: "operator", expires_at: null, hold: true }
+    : { issuer: grant.issuer, expires_at: grant.expires_at };
+}
+
+/**
+ * Fold a new grant onto the hold that stands. Pure, and the one place the
+ * precedence lives:
+ *   nothing standing         → engaged with the grant;
+ *   operator over session    → upgraded (the operator's terms replace);
+ *   session over operator    → unchanged (a session never narrows an operator);
+ *   operator hold over a plain operator drain → upgraded to the hold;
+ *   plain operator drain over a hold → unchanged (only `drain off` ends a hold);
+ *   same issuer over itself  → extended when the grant reaches later, else unchanged.
+ */
+export function mergeHold(
+  current: LeverHold | null,
+  grant: LeverGrant,
+): { hold: LeverHold; outcome: HoldOutcome } {
+  if (!current) return { hold: holdOf(grant), outcome: "engaged" };
+  if (current.issuer === "operator" && grant.issuer === "session")
+    return { hold: current, outcome: "unchanged" };
+  if (current.issuer === "session" && grant.issuer === "operator") {
+    return { hold: holdOf(grant), outcome: "upgraded" };
+  }
+  if (current.hold === true) return { hold: current, outcome: "unchanged" };
+  if (grant.issuer === "operator" && grant.hold === true)
+    return { hold: holdOf(grant), outcome: "upgraded" };
+  const expires_at = widerExpiry(current.expires_at, grant.expires_at);
+  if (expires_at === current.expires_at) return { hold: current, outcome: "unchanged" };
+  return { hold: { issuer: current.issuer, expires_at }, outcome: "extended" };
+}
+
+/** May `by` lift `current`? An operator lifts anything; a session lifts only a session's hold. */
+export function mayLift(current: LeverHold, by: LeverIssuer): boolean {
+  return by === "operator" || current.issuer === "session";
+}
+
+/** Is the hold still in force at `nowIso`? A null expiry never lapses. */
+export function holdActive(hold: LeverHold | null, nowIso: string): hold is LeverHold {
+  return hold !== null && (hold.expires_at === null || hold.expires_at > nowIso);
+}
+
+export function minutesFromNow(now: Date, minutes: number): string {
+  return new Date(now.getTime() + minutes * 60_000).toISOString();
+}
+
+export type SessionGrantVerdict =
+  { ok: true; minutes: number; expires_at: string } | { ok: false; reason: string };
+
+/**
+ * Bound a session's ask. The bound is applied whether or not the session
+ * stated a duration — an omitted `for_min` gets the largest grant the cap and
+ * the day's remaining budget allow, never "until lifted". An explicit ask past
+ * the cap or past the remaining budget is refused with the number, so the
+ * session can ask again smaller instead of silently getting less than it
+ * planned around.
+ */
+export function boundSessionGrant(input: {
+  kind: LeverKind;
+  requestedMin: number | undefined;
+  maxMin: number;
+  budgetMin: number;
+  usedMin: number;
+  now: Date;
+}): SessionGrantVerdict {
+  const { kind, requestedMin, maxMin, budgetMin, usedMin, now } = input;
+  const remaining = Math.max(0, budgetMin - usedMin);
+  if (remaining === 0) {
+    return {
+      ok: false,
+      reason: `${kind}: the session's ${budgetMin}-minute ${kind} budget for today is spent; the lever is the operator's for the rest of the day`,
+    };
+  }
+  if (requestedMin === undefined) {
+    const minutes = Math.min(maxMin, remaining);
+    return { ok: true, minutes, expires_at: minutesFromNow(now, minutes) };
+  }
+  if (requestedMin > maxMin) {
+    return {
+      ok: false,
+      reason: `${kind}: for_min ${requestedMin} exceeds the session cap of ${maxMin} minutes`,
+    };
+  }
+  if (requestedMin > remaining) {
+    return {
+      ok: false,
+      reason: `${kind}: for_min ${requestedMin} exceeds the ${remaining} minutes left of today's ${budgetMin}-minute session budget`,
+    };
+  }
+  return { ok: true, minutes: requestedMin, expires_at: minutesFromNow(now, requestedMin) };
+}
+
+// ---- the daemon-side handlers -----------------------------------------------
+
+export interface LeverDeps {
+  /** Trusted watcher delivery identity, stable across retries. */
+  deliveryKey?: string;
+  store: StateStore;
+  levers: LeversConfig;
+  /** `[ops] timezone` — the day the session budget is counted in. */
+  timezone: string;
+  now?: () => Date;
+}
+
+/** Resolve the grant a caller may have: the operator's is taken verbatim, a session's is bounded and charged to the day. */
+function grantFor(
+  deps: LeverDeps,
+  kind: LeverKind,
+  pr: number | null,
+  issuer: LeverIssuer,
+  forMin: number | undefined,
+  hold = false,
+): { ok: true; grant: LeverGrant; charge: () => void } | { ok: false; reason: string } {
+  const now = (deps.now ?? (() => new Date()))();
+  if (hold) {
+    // The channel decides, never the file: a hold asked through the session
+    // directory — or through an operator directory without its seal — is a
+    // SESSION's ask, and a session holds nothing it cannot be bounded on.
+    if (issuer !== "operator") {
+      return {
+        ok: false,
+        reason: `${kind}: a hold is the operator's alone (qcr drain on --hold, through the sealed commands/operator/); a session's drain is always bounded`,
+      };
+    }
+    if (kind !== "drain") return { ok: false, reason: `${kind}: only the drain has a hold` };
+    if (forMin !== undefined)
+      return {
+        ok: false,
+        reason: "drain: a hold has no expiry; 'for_min' and 'hold' exclude each other",
+      };
+    return {
+      ok: true,
+      grant: { issuer: "operator", expires_at: null, hold: true },
+      charge: () => {},
+    };
+  }
+  if (issuer === "operator") {
+    return {
+      ok: true,
+      grant: {
+        issuer: "operator",
+        expires_at: forMin === undefined ? null : minutesFromNow(now, forMin),
+      },
+      charge: () => {},
+    };
+  }
+  const day = opsDay(deps.timezone, now);
+  const maxMin =
+    kind === "drain" ? deps.levers.session_drain_max_min : deps.levers.session_pause_max_min;
+  const budgetMin =
+    kind === "drain"
+      ? deps.levers.session_drain_budget_min_per_day
+      : deps.levers.session_pause_budget_min_per_day;
+  const verdict = boundSessionGrant({
+    kind,
+    requestedMin: forMin,
+    maxMin,
+    budgetMin,
+    usedMin: deps.store.leverMinutesUsed(kind, day, pr),
+    now,
+  });
+  if (!verdict.ok) return verdict;
+  return {
+    ok: true,
+    grant: { issuer: "session", expires_at: verdict.expires_at },
+    charge: () => deps.store.recordLeverGrant(kind, pr, verdict.minutes, day, verdict.expires_at),
+  };
+}
+
+/**
+ * The `drain` handler. ON engages (or upgrades/extends) the drain; OFF lifts
+ * it — a session's OFF is refused while the operator holds it. `hold` asks for
+ * the operator's no-auto-lift drain, refused for a session. Never touches
+ * GitHub, never goes near the gate.
+ */
+export async function drainLever(
+  deps: LeverDeps,
+  on: boolean,
+  issuer: LeverIssuer,
+  forMin: number | undefined,
+  afterLift: () => Promise<void>,
+  hold = false,
+): Promise<FileOutcome> {
+  const { store } = deps;
+  if (!on) {
+    const standing = store.drainState();
+    const res = store.liftDrain(issuer);
+    if (res.refused) {
+      return {
+        ok: false,
+        reason:
+          standing.draining && standing.hold
+            ? "drain is HELD by the operator (qcr drain on --hold); only the operator lifts it (qcr drain off) — no boot lifts a hold"
+            : "drain is held by the operator (qcr drain on); only the operator lifts it (qcr drain off), or the next boot's first reconcile pass if that pass is healthy",
+      };
+    }
+    if (res.changed)
+      store.logEvent("drain_off", null, { by: issuer, dropped_deliveries: res.dropped });
+    await afterLift();
+    return { ok: true, draining: false, issuer, dropped_deliveries: res.dropped };
+  }
+  return atomicCommandEffect(
+    store,
+    commandEffectKey("drain", deps.deliveryKey, {
+      on,
+      issuer,
+      forMin,
+      ...(hold ? { hold: true } : {}),
+    }),
+    () => {
+      const resolved = grantFor(deps, "drain", null, issuer, forMin, hold);
+      if (!resolved.ok) return { ok: false, reason: resolved.reason };
+      const res = store.engageDrain(resolved.grant);
+      const state = res.state;
+      if (!state.draining) {
+        // Structurally unreachable — a grant that merged has a holder — but the
+        // union does not know that, and a lie here ("draining") would be worse
+        // than a loud refusal.
+        return {
+          ok: false,
+          reason: "drain did not take: the store reads not draining after the grant",
+        };
+      }
+      if (res.outcome !== "unchanged") {
+        resolved.charge();
+        store.logEvent("drain_on", null, {
+          by: issuer,
+          outcome: res.outcome,
+          expires_at: state.expires_at,
+          ...(state.hold ? { hold: true } : {}),
+        });
+      }
+      return {
+        ok: true,
+        draining: true,
+        outcome: res.outcome,
+        issuer: state.issued_by,
+        expires_at: state.expires_at,
+        hold: state.hold,
+        running_rounds: store.runningRounds().length,
+      };
+    },
+  );
+}
+
+/** The `pause-pr` handler: hold one PR out of dispatch and re-trigger. */
+export function pauseLever(
+  deps: LeverDeps,
+  pr: number,
+  reason: string,
+  issuer: LeverIssuer,
+  forMin: number | undefined,
+): FileOutcome {
+  return atomicCommandEffect(
+    deps.store,
+    commandEffectKey("pause", deps.deliveryKey, { pr, reason, issuer, forMin }),
+    () => {
+      const { store } = deps;
+      if (!store.getPr(pr)) return { ok: false, reason: `unknown PR #${pr}` };
+      const resolved = grantFor(deps, "pause", pr, issuer, forMin);
+      if (!resolved.ok) return { ok: false, reason: resolved.reason };
+      const res = store.pausePr(pr, resolved.grant, reason);
+      if (res.outcome !== "unchanged") {
+        resolved.charge();
+        store.logEvent("pr_paused", pr, {
+          reason,
+          by: issuer,
+          outcome: res.outcome,
+          expires_at: res.hold.expires_at,
+        });
+      }
+      return {
+        ok: true,
+        paused: pr,
+        outcome: res.outcome,
+        issuer: res.hold.issuer,
+        expires_at: res.hold.expires_at,
+      };
+    },
+  );
+}
+
+/** The `resume-pr` handler: a session cannot lift an operator's pause. */
+export async function resumeLever(
+  deps: LeverDeps,
+  pr: number,
+  issuer: LeverIssuer,
+  afterResume: () => Promise<void>,
+): Promise<FileOutcome> {
+  const { store } = deps;
+  if (!store.getPr(pr)) return { ok: false, reason: `unknown PR #${pr}` };
+  const res = store.resumePr(pr, issuer);
+  if (res.refused) {
+    return {
+      ok: false,
+      reason: `PR #${pr} is paused by the operator; only the operator resumes it`,
+    };
+  }
+  store.promoteSuccessor(pr);
+  // Only a pause actually lifted is a transition worth a ledger row.
+  if (res.changed) store.logEvent("pr_resumed", pr, { by: issuer });
+  await afterResume();
+  return { ok: true, resumed: pr };
+}
+
+/**
+ * Retire holds whose expiry has passed and say so in the event ledger. The
+ * readers (`drainState`, every PR row) already fold expiry themselves, so a
+ * lapsed hold stops binding the moment it lapses — this sweep is the record,
+ * not the enforcement. Runs from the dispatch pump.
+ */
+export function sweepExpiredLevers(
+  store: StateStore,
+  log: (line: string) => void,
+): { drain: boolean; pauses: number[] } {
+  const expired = store.expireLevers();
+  if (expired.drain) {
+    store.logEvent("drain_expired", null, {});
+    log("drain_expired — the drain's expiry passed; dispatch resumes");
+  }
+  for (const pr of expired.pauses) {
+    store.logEvent("pr_pause_expired", pr, {});
+    log(`pr_pause_expired — #${pr}'s pause lapsed; dispatch and re-trigger may act on it again`);
+  }
+  return expired;
+}