@detergent-software/conductor 1.0.0-dev.2 → 1.0.0-dev.20

package/build/rules.js

@@ -0,0 +1,850 @@
+import { parseLocalTime } from "./clock.js";
+import { CHANNELS } from "./config.js";
+import { ConductorError } from "./errors.js";
+import { INBOX_KINDS } from "./store.js";
+// The rules engine (design note, section 9): `when` / `do` rules in a fixed vocabulary. This
+// module is pure: it reads rule text into rules, checks them against the guardrails, and picks
+// the rules that fire for a subject. rules-service.ts loads the files and reloads them on save.
+// What happened, as a rule names it. An event rule fires when one of its events is seen; a rule
+// with none is a state rule, checked on each scheduler tick.
+export const EVENT_ATOMS = [
+    'inbox.raised',
+    'item.closed',
+    'item.unblocked',
+    'note',
+    'plan',
+    'pr.comment',
+    'queue.drained',
+    'queue.pick',
+    'queue.ready-to-release',
+    'run.failed',
+    'wait.resolved',
+    'worker.exited',
+    'worker.idle',
+    'worker.permission',
+    'worker.waiting',
+];
+const DAY_NAMES = ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday'];
+const TIERS = ['S', 'M', 'L'];
+// A wait by the gate it holds (plan, merge, npm-otp) when it holds one, else by its condition.
+export const WAIT_KINDS = ['plan', 'merge', 'npm-otp', 'approval', 'health', 'item', 'npm', 'pr', 'run', 'time'];
+const UNIT_MINUTES = { d: 24 * 60, h: 60, m: 1, s: 1 / 60 };
+const PRIORITIES = { high: 2, low: 4, medium: 3, none: 0, urgent: 1 };
+// Every field a condition can read, by type. A field the subject doesn't have makes its
+// comparison false (`conduct rules test` names it).
+export const FIELDS = {
+    day: { type: 'day' },
+    'inbox.age': { type: 'duration' },
+    'inbox.kind': { type: 'enum', values: INBOX_KINDS },
+    'item.area': { type: 'text' },
+    'item.id': { type: 'text' },
+    'item.labels': { type: 'labels' },
+    'item.priority': { type: 'int' },
+    // The size tier of the item's newest Plan note, once it has one.
+    'item.tier': { type: 'enum', values: TIERS },
+    'note.kind': { type: 'text' },
+    'note.phase': { type: 'text' },
+    'notify.profile': { type: 'text' },
+    // The tier of the Plan note being posted; reading it makes the rule a `plan` event rule.
+    'plan.tier': { type: 'enum', values: TIERS },
+    project: { type: 'text' },
+    'spend.item': { type: 'tokens' },
+    'spend.project': { type: 'tokens' },
+    'spend.today': { type: 'tokens' },
+    'spend.worker': { type: 'tokens' },
+    time: { type: 'clock' },
+    'wait.age': { type: 'duration' },
+    'wait.kind': { type: 'enum', values: WAIT_KINDS },
+    'worker.phase': { type: 'text' },
+    'worker.retries': { type: 'int' },
+};
+// The fields only one event has: a rule that reads them fires on that event, so
+// `plan.tier == S` needs no `plan and`.
+const IMPLIED_EVENTS = { 'note.': 'note', 'plan.': 'plan' };
+// The labels a rule may add or remove. `human` is the profile's human label.
+export const RULE_LABELS = ['human', 'triage', 'shipped-open'];
+// Verbs that look like actions but that the conductor never takes (design note, section 14).
+const FORBIDDEN = new Set([
+    'approve',
+    'cancel',
+    'close',
+    'delete',
+    'deploy',
+    'exec',
+    'execute',
+    'git',
+    'merge',
+    'npm',
+    'promote',
+    'publish',
+    'push',
+    'release',
+    'remove',
+    'rm',
+    'run',
+    'shell',
+]);
+const NEVER = 'the conductor never merges, publishes, approves prod, deletes or runs commands';
+const VERBS = 'launch, retire, park, resume, retry, pause, unpause, focus, auto-approve after, inbox, remind jason, notify, notify profile, label add|remove, flag shipped-open, escalate console, none';
+// What a state rule is checked against, from the fields it reads: each open wait, each open inbox
+// item, each worker, each project, or the machine once.
+export const SCOPES = ['wait', 'inbox', 'worker', 'project', 'machine'];
+class RuleSyntaxError extends Error {
+}
+// The clock fields of a subject: minutes after local midnight, and the day (0 is sunday).
+export function clockFields(now) {
+    return { day: now.getDay(), time: now.getHours() * 60 + now.getMinutes() };
+}
+// Reads rules into Rules, checking each against the vocabulary and the guardrails. Throws one
+// ConductorError that lists every problem, each with the rule's position and id.
+export function compileRules(inputs, origin, limits) {
+    const problems = [];
+    const rules = [];
+    const ids = new Set();
+    inputs.forEach((input, index) => {
+        const name = `rule ${index + 1}${input.id ? ` (${input.id})` : ''}`;
+        try {
+            if (input.id !== undefined) {
+                if (ids.has(input.id))
+                    throw new RuleSyntaxError(`id "${input.id}" is used twice in this file`);
+                ids.add(input.id);
+            }
+            rules.push(compileRule(input, index, origin, limits));
+        }
+        catch (error) {
+            if (!(error instanceof RuleSyntaxError))
+                throw error;
+            problems.push(`${name}: ${error.message}`);
+        }
+    });
+    if (problems.length > 0)
+        throw new ConductorError(`${origin.file ?? `${origin.source} rules`} has rules the conductor refuses`, problems);
+    return rules;
+}
+// conduct-atk's behavior written as rules (design note, section 9), so a machine or project file
+// holds only the differences. Each has an id that a rule elsewhere replaces or switches off.
+export function defaultRules({ dailyTokens, runawayTokens }) {
+    return [
+        { do: 'launch', id: 'launch', note: "start the queue's picks, as conduct-atk's tick did", when: 'queue.pick' },
+        { do: 'retire', id: 'retire-closed', note: 'retire a worker once its item is Done or Canceled', when: 'item.closed' },
+        { do: 'park', id: 'park-on-wait', note: 'stop a worker whose turn has ended while it waits', when: 'worker.waiting' },
+        { do: 'resume worker', id: 'resume-on-wait', note: 'wake a parked worker when its wait holds', when: 'wait.resolved' },
+        { do: 'inbox runaway', id: 'runaway', note: 'a worker past this many tokens, cache reads aside', when: `spend.worker > ${tokenLiteral(runawayTokens)}` },
+        { do: 'pause all launches until tomorrow', id: 'daily-cap', note: 'the daily soft cap: no new launches past it', when: `spend.today > ${tokenLiteral(dailyTokens)}` },
+        { do: 'inbox ready-to-release', id: 'ready-to-release', note: 'a conducted project with no open item: hand over to the release', when: 'queue.ready-to-release' },
+        { do: 'inbox queue-drained', id: 'queue-drained', note: 'nothing left to start or watch', when: 'queue.drained' },
+        {
+            do: 'escalate console "a worker asks the console for something: read its newest Handoff note on the item and do it within your remit"',
+            id: 'conductor-handoff',
+            note: "a worker's `Handoff · conductor` note, which went to conduct-atk's session by SendMessage before the console",
+            when: 'note.kind == conductor',
+        },
+    ];
+}
+// An action as `conduct rules` prints it.
+export function describeAction(action) {
+    const ends = (until) => until === null ? '' : until.kind === 'at' ? ` until ${until.text}` : ` for ${formatMinutes(until.minutes)}`;
+    const who = (target) => target.kind === 'all' ? 'all launches' : target.kind === 'named' ? `launches in ${target.project}` : 'launches';
+    switch (action.verb) {
+        case 'auto-approve':
+            return `auto-approve after ${formatMinutes(action.afterMinutes)}`;
+        case 'escalate':
+            return `escalate console "${action.text}"`;
+        case 'focus':
+            return `focus ${action.project === null ? '' : `${action.project} `}${action.setting} ${action.value}${ends(action.until)}`;
+        case 'inbox':
+            return `inbox ${action.kind}${action.text === null ? '' : ` "${action.text}"`}`;
+        case 'label':
+            return `label ${action.op} ${action.label}`;
+        case 'launch':
+        case 'none':
+        case 'park':
+        case 'retire':
+        case 'retry':
+            return action.verb;
+        case 'notify':
+            return `notify ${action.channel}${action.text === null ? '' : ` "${action.text}"`}`;
+        case 'notify-profile':
+            return `notify profile ${action.profile}${ends(action.until)}`;
+        case 'pause':
+            return `pause ${who(action.target)}${ends(action.until)}`;
+        case 'remind':
+            return 'remind jason';
+        case 'resume':
+            return 'resume worker';
+        case 'unpause':
+            return `unpause ${who(action.target)}`;
+    }
+}
+// 30s, 15m, 2h, 1d as minutes; a bare 0 too.
+export function durationMinutes(text) {
+    if (text === '0')
+        return 0;
+    const match = /^(\d+(?:\.\d+)?)(s|m|h|d)$/.exec(text);
+    const unit = match?.[2] === undefined ? undefined : UNIT_MINUTES[match[2]];
+    return unit === undefined ? null : Number(match?.[1]) * unit;
+}
+// True when the expression holds for the subject. A comparison on a field the subject lacks is
+// false, and the field is added to `missing`.
+export function evaluate(expr, subject, missing = []) {
+    switch (expr.kind) {
+        case 'and':
+            return evaluate(expr.left, subject, missing) && evaluate(expr.right, subject, missing);
+        case 'compare': {
+            const actual = subject.fields[expr.field];
+            if (actual === undefined || isList(actual))
+                return (missing.push(expr.field), false);
+            return compare(actual, expr.op, expr.value);
+        }
+        case 'event':
+            return subject.events.includes(expr.name);
+        case 'has': {
+            const actual = subject.fields[expr.field];
+            if (actual === undefined || !isList(actual))
+                return (missing.push(expr.field), false);
+            return actual.some((l) => l.toLowerCase() === expr.value.toLowerCase());
+        }
+        case 'in': {
+            const actual = subject.fields[expr.field];
+            if (actual === undefined || isList(actual))
+                return (missing.push(expr.field), false);
+            return expr.values.some((v) => compare(actual, '==', v));
+        }
+        case 'not':
+            return !evaluate(expr.expr, subject, missing);
+        case 'or':
+            return evaluate(expr.left, subject, missing) || evaluate(expr.right, subject, missing);
+    }
+}
+// A field by its name, any case; null when there's none.
+export function fieldOf(text) {
+    const lower = text.toLowerCase();
+    return isFieldName(lower) ? lower : null;
+}
+export function isFieldName(name) {
+    return Object.hasOwn(FIELDS, name);
+}
+// A literal as a field's value: minutes for a duration, tokens for spend, minutes after midnight for
+// a time, 0 (sunday) to 6 for a day, the canonical spelling for an enum. Null when it isn't one.
+export function literal(field, text) {
+    const spec = FIELDS[field];
+    switch (spec.type) {
+        case 'clock': {
+            const match = /^([01]?\d|2[0-3]):([0-5]\d)$/.exec(text);
+            return match ? Number(match[1]) * 60 + Number(match[2]) : null;
+        }
+        case 'day': {
+            const lower = text.toLowerCase();
+            const index = DAY_NAMES.findIndex((d) => d === lower || d.slice(0, 3) === lower);
+            return index === -1 ? null : index;
+        }
+        case 'duration':
+            return durationMinutes(text);
+        case 'enum':
+            return spec.values.find((v) => v.toLowerCase() === text.toLowerCase()) ?? null;
+        case 'int': {
+            if (field === 'item.priority' && Object.hasOwn(PRIORITIES, text.toLowerCase()))
+                return PRIORITIES[text.toLowerCase()] ?? null;
+            return /^-?\d+$/.test(text) ? Number(text) : null;
+        }
+        case 'labels':
+        case 'text':
+            return text;
+        case 'tokens': {
+            const match = /^(\d+(?:\.\d+)?)([kKmM]?)$/.exec(text);
+            if (!match)
+                return null;
+            const scale = match[2] === '' ? 1 : match[2]?.toLowerCase() === 'k' ? 1_000 : 1_000_000;
+            return Math.round(Number(match[1]) * scale);
+        }
+    }
+}
+export function parseAction(text, limits) {
+    const tokens = tokenize(text);
+    const words = tokens.map((t) => (t.kind === 'string' ? t.text : t.text.toLowerCase()));
+    const raw = tokens.map((t) => t.text);
+    const quoted = (i) => (tokens[i]?.kind === 'string' ? (tokens[i]?.text ?? null) : null);
+    const [verb = '', ...rest] = words;
+    const fail = (message) => {
+        throw new RuleSyntaxError(message);
+    };
+    const end = (i) => {
+        if (i < words.length)
+            fail(`unexpected "${raw[i] ?? ''}" in "${text}"`);
+    };
+    // `until <when>` or `for <duration>` from position i; returns the until and the next position.
+    const until = (i, required) => {
+        if (words[i] === 'until') {
+            // A date and a time are two words: 2026-10-12 17:00.
+            const pair = /^\d{4}-\d{2}-\d{2}$/.test(raw[i + 1] ?? '') && /^\d{1,2}:\d{2}$/.test(raw[i + 2] ?? '');
+            const when = pair ? `${raw[i + 1] ?? ''}T${(raw[i + 2] ?? '').padStart(5, '0')}` : raw[i + 1];
+            if (when === undefined || !untilReadable(when))
+                fail(`until takes 17:00, tomorrow, a day such as monday, or a date and time (in "${text}")`);
+            return [{ kind: 'at', text: when ?? '' }, i + (pair ? 3 : 2)];
+        }
+        if (words[i] === 'for') {
+            const minutes = durationMinutes(words[i + 1] ?? '');
+            if (minutes === null || minutes <= 0)
+                fail(`for takes a duration, such as 2h (in "${text}")`);
+            if ((minutes ?? 0) > 14 * 24 * 60)
+                fail(`for ${raw[i + 1] ?? ''} is over the 14-day limit of an override (in "${text}")`);
+            return [{ kind: 'for', minutes: minutes ?? 0 }, i + 2];
+        }
+        if (required)
+            fail(`"${text}" needs until <when> or for <duration>: an override always ends`);
+        return [null, i];
+    };
+    // `launches`, then `in <project>`, or `all launches`.
+    const target = (i) => {
+        if (words[i] === 'all' && words[i + 1] === 'launches')
+            return [{ kind: 'all' }, i + 2];
+        if (words[i] !== 'launches')
+            fail(`write "${verb} launches", "${verb} launches in <project>" or "${verb} all launches"`);
+        if (words[i + 1] === 'in') {
+            const project = raw[i + 2];
+            if (project === undefined)
+                fail(`"${verb} launches in" needs a project`);
+            return [{ kind: 'named', project: project ?? '' }, i + 3];
+        }
+        return [{ kind: 'subject' }, i + 1];
+    };
+    if (FORBIDDEN.has(verb))
+        fail(`"${raw[0] ?? verb}" is not in the vocabulary: ${NEVER}`);
+    switch (verb) {
+        case 'auto-approve': {
+            if (rest[0] !== 'after')
+                fail('write "auto-approve after <duration>", such as auto-approve after 15m');
+            const minutes = durationMinutes(rest[1] ?? '');
+            if (minutes === null || minutes < 1 || minutes > 24 * 60)
+                fail('auto-approve after takes 1m to 24h');
+            end(3);
+            return { afterMinutes: minutes ?? 0, verb: 'auto-approve' };
+        }
+        case 'escalate': {
+            const i = words[1] === 'console' ? 2 : 1;
+            const ask = quoted(i);
+            if (ask === null || ask.trim() === '')
+                fail('write escalate console "<what to look at>"');
+            end(i + 1);
+            return { text: ask ?? '', verb: 'escalate' };
+        }
+        case 'flag':
+            if (rest[0] !== 'shipped-open')
+                fail('flag takes shipped-open');
+            end(2);
+            return { label: 'shipped-open', op: 'add', verb: 'label' };
+        case 'focus': {
+            let i = 1;
+            let project = null;
+            if (words[i] !== 'weight' && words[i] !== 'slots')
+                project = raw[i++] ?? null;
+            const setting = words[i];
+            if (setting !== 'weight' && setting !== 'slots')
+                fail('write focus [<project>] weight <n> | slots <n> until <when>');
+            const value = Number(words[i + 1]);
+            if (!Number.isInteger(value))
+                fail(`focus ${setting ?? ''} takes a whole number`);
+            if (setting === 'slots' && value < 0)
+                fail(`focus slots takes 0 or more, not ${value}`);
+            if (setting === 'slots' && value > limits.slots) {
+                fail(`focus slots ${value} is over the limit: no project gets more than scheduler.slots (${limits.slots}) in config.json`);
+            }
+            if (setting === 'weight' && (value < -100 || value > 100))
+                fail(`focus weight ${value} is outside -100 to 100`);
+            const [ends, after] = until(i + 2, true);
+            end(after);
+            return { project, setting: setting === 'slots' ? 'slots' : 'weight', until: ends ?? { kind: 'for', minutes: 0 }, value, verb: 'focus' };
+        }
+        case 'inbox': {
+            const kind = INBOX_KINDS.find((k) => k === words[1]);
+            if (!kind)
+                fail(`inbox takes a kind: ${INBOX_KINDS.join(', ')}`);
+            const note = quoted(2);
+            end(note === null ? 2 : 3);
+            return { kind: kind ?? 'failed', text: note, verb: 'inbox' };
+        }
+        case 'label': {
+            const op = words[1];
+            const label = RULE_LABELS.find((l) => l === words[2]);
+            if ((op !== 'add' && op !== 'remove') || !label)
+                fail(`write label add|remove ${RULE_LABELS.join('|')}: rules edit those labels only`);
+            end(3);
+            return { label: label ?? 'human', op: op === 'remove' ? 'remove' : 'add', verb: 'label' };
+        }
+        case 'launch':
+        case 'none':
+        case 'park':
+        case 'retire':
+            end(1);
+            return { verb };
+        case 'notify': {
+            if (words[1] === 'profile') {
+                const profile = raw[2];
+                if (profile === undefined || !limits.profiles.includes(profile)) {
+                    fail(`notify profile takes one of ${limits.profiles.join(', ')}`);
+                }
+                const [ends, after] = until(3, false);
+                end(after);
+                return { profile: profile ?? '', until: ends, verb: 'notify-profile' };
+            }
+            const channel = CHANNELS.find((c) => c === words[1]);
+            if (!channel)
+                fail(`notify takes a channel (${CHANNELS.join(', ')}) or profile <name>`);
+            const note = quoted(2);
+            end(note === null ? 2 : 3);
+            return { channel: channel ?? 'remote-control', text: note, verb: 'notify' };
+        }
+        case 'pause': {
+            const [who, after] = target(1);
+            const [ends, next] = until(after, false);
+            end(next);
+            return { target: who, until: ends, verb: 'pause' };
+        }
+        case 'remind':
+            if (rest.length > 0 && rest[0] !== 'jason')
+                fail('write remind jason');
+            end(rest.length > 0 ? 2 : 1);
+            return { verb: 'remind' };
+        case 'resume':
+            if (rest.length > 0 && rest[0] !== 'worker')
+                fail('write resume worker');
+            end(rest.length > 0 ? 2 : 1);
+            return { verb: 'resume' };
+        case 'retry':
+            if (rest.length > 0 && rest[0] !== 'once')
+                fail('write retry (it retries once)');
+            end(rest.length > 0 ? 2 : 1);
+            return { verb: 'retry' };
+        case 'unpause': {
+            const [who, after] = target(1);
+            end(after);
+            return { target: who, verb: 'unpause' };
+        }
+        default:
+            return fail(`unknown action "${raw[0] ?? ''}"; actions: ${VERBS}`);
+    }
+}
+export function parseWhen(text) {
+    const tokens = tokenize(text);
+    let next = 0;
+    const peek = () => tokens[next];
+    const where = (token) => (token ? `at column ${token.at + 1}` : 'at the end');
+    const keyword = (word) => {
+        const token = peek();
+        return token?.kind === 'word' && token.text.toLowerCase() === word;
+    };
+    const expect = (text) => {
+        const token = peek();
+        if (token?.text !== text)
+            throw new RuleSyntaxError(`expected "${text}" ${where(token)}`);
+        next++;
+    };
+    const or = (negated) => {
+        let left = and(negated);
+        while (keyword('or')) {
+            next++;
+            left = { kind: 'or', left, right: and(negated) };
+        }
+        return left;
+    };
+    const and = (negated) => {
+        let left = unary(negated);
+        while (keyword('and')) {
+            next++;
+            left = { kind: 'and', left, right: unary(negated) };
+        }
+        return left;
+    };
+    const unary = (negated) => {
+        if (keyword('not')) {
+            next++;
+            return { expr: unary(!negated), kind: 'not' };
+        }
+        if (peek()?.text === '(' && peek()?.kind === 'punct') {
+            next++;
+            const inner = or(negated);
+            expect(')');
+            return inner;
+        }
+        return atom(negated);
+    };
+    const atom = (negated) => {
+        const token = peek();
+        if (!token || (token.kind !== 'word' && token.kind !== 'string'))
+            throw new RuleSyntaxError(`expected a condition ${where(token)}`);
+        next++;
+        const field = token.kind === 'word' ? fieldOf(token.text) : null;
+        const following = peek();
+        const comparing = following?.kind === 'op' || (following?.kind === 'word' && ['has', 'in'].includes(following.text.toLowerCase()));
+        if (field && comparing)
+            return comparison(field);
+        const event = EVENT_ATOMS.find((e) => e === token.text.toLowerCase());
+        if (event && !comparing) {
+            if (negated)
+                throw new RuleSyntaxError(`an event can't be negated (${event}) ${where(token)}`);
+            return { kind: 'event', name: event };
+        }
+        // `human in item.labels`: a value, then `in` and a label field.
+        if (following?.kind === 'word' && following.text.toLowerCase() === 'in') {
+            next++;
+            const list = peek();
+            const target = list?.kind === 'word' ? fieldOf(list.text) : null;
+            if (target && FIELDS[target].type === 'labels') {
+                next++;
+                return { field: target, kind: 'has', value: token.text };
+            }
+        }
+        if (field)
+            throw new RuleSyntaxError(`expected ==, !=, <, <=, >, >=, in or has after ${token.text} ${where(following)}`);
+        throw new RuleSyntaxError(`"${token.text}" is neither a field nor an event ${where(token)}; fields: ${Object.keys(FIELDS).join(', ')}; events: ${EVENT_ATOMS.join(', ')}`);
+    };
+    const comparison = (field) => {
+        const spec = FIELDS[field];
+        const token = peek();
+        next++;
+        const op = token?.kind === 'op' ? token.text : (token?.text.toLowerCase() ?? '');
+        if (op === 'has') {
+            if (spec.type !== 'labels')
+                throw new RuleSyntaxError(`${field} isn't a list: "has" reads item.labels ${where(token)}`);
+            return { field, kind: 'has', value: word() };
+        }
+        if (spec.type === 'labels')
+            throw new RuleSyntaxError(`${field} is a list: write "${field} has <label>" or "<label> in ${field}" ${where(token)}`);
+        if (op === 'in') {
+            expect('[');
+            const values = [value(field)];
+            while (peek()?.text === ',') {
+                next++;
+                values.push(value(field));
+            }
+            expect(']');
+            return { field, kind: 'in', values };
+        }
+        const ordered = ['clock', 'duration', 'int', 'tokens'].includes(spec.type);
+        if (!ordered && op !== '==' && op !== '!=')
+            throw new RuleSyntaxError(`${field} takes ==, != or in, not ${op} ${where(token)}`);
+        return { field, kind: 'compare', op: toOp(op), value: value(field) };
+    };
+    const word = () => {
+        const token = peek();
+        if (!token || (token.kind !== 'word' && token.kind !== 'string'))
+            throw new RuleSyntaxError(`expected a value ${where(token)}`);
+        next++;
+        return token.text;
+    };
+    const value = (field) => {
+        const token = peek();
+        const text = word();
+        const parsed = literal(field, text);
+        if (parsed === null)
+            throw new RuleSyntaxError(`"${text}" is not a value of ${field} (${describeType(FIELDS[field])}) ${where(token)}`);
+        return parsed;
+    };
+    const expr = or(false);
+    if (next < tokens.length)
+        throw new RuleSyntaxError(`unexpected "${tokens[next]?.text ?? ''}" ${where(tokens[next])}`);
+    return expr;
+}
+// The time an override ends: the next 17:00, local midnight tomorrow, the next monday at 00:00, a
+// date and time, or a duration from now.
+export function resolveUntil(until, now) {
+    if (until.kind === 'for')
+        return new Date(now.getTime() + until.minutes * 60_000);
+    const lower = until.text.toLowerCase();
+    const day = DAY_NAMES.findIndex((d) => d === lower || d.slice(0, 3) === lower);
+    if (lower === 'tomorrow' || day !== -1) {
+        const at = new Date(now);
+        at.setHours(0, 0, 0, 0);
+        const ahead = lower === 'tomorrow' ? 1 : (day - now.getDay() + 7) % 7 || 7;
+        at.setDate(at.getDate() + ahead);
+        return at;
+    }
+    const at = parseLocalTime(until.text, now);
+    if (!at)
+        throw new ConductorError(`"${until.text}" is not a time`);
+    return at;
+}
+// What a state rule is checked against, from the fields it reads.
+export function scopeOf(fields) {
+    const reads = (prefix) => fields.some((f) => f.startsWith(prefix));
+    if (reads('wait.') && reads('inbox.'))
+        throw new RuleSyntaxError('a state rule reads waits or inbox items, not both');
+    if (reads('wait.'))
+        return 'wait';
+    if (reads('inbox.'))
+        return 'inbox';
+    if (reads('worker.') || reads('item.') || fields.includes('spend.worker') || fields.includes('spend.item'))
+        return 'worker';
+    if (fields.includes('project') || fields.includes('spend.project'))
+        return 'project';
+    return 'machine';
+}
+// The rules that fire for a subject, in order: the subject's project's rules, then machine rules,
+// then defaults. A rule with an id shadows the same id further down, matching or not. Of the rules
+// that match, the first of each action (by verb, and inbox kind or label) fires; later ones are
+// superseded.
+export function selectRules(rules, subject) {
+    const ordered = [
+        ...rules.filter((r) => r.source === 'project' && r.project === subject.project),
+        ...rules.filter((r) => r.source === 'machine'),
+        ...rules.filter((r) => r.source === 'default'),
+    ];
+    const ids = new Map();
+    const taken = new Map();
+    const fired = [];
+    const trace = [];
+    for (const rule of ordered) {
+        const shadow = rule.id === null ? undefined : ids.get(rule.id);
+        if (rule.id !== null && shadow === undefined)
+            ids.set(rule.id, rule.ref);
+        // A `none` rule never fires itself: it only shadows.
+        const trigger = subject.events.length > 0 ? rule.events.some((e) => subject.events.includes(e)) : rule.events.length === 0 && rule.scope === subject.scope;
+        if (!trigger || rule.when === null || rule.actions.every((a) => a.verb === 'none')) {
+            trace.push({ missing: [], outcome: 'other trigger', over: null, ref: rule.ref });
+            continue;
+        }
+        if (shadow !== undefined) {
+            trace.push({ missing: [], outcome: 'shadowed', over: shadow, ref: rule.ref });
+            continue;
+        }
+        const missing = [];
+        if (!evaluate(rule.when, subject, missing)) {
+            trace.push({ missing: [...new Set(missing)], outcome: 'no match', over: null, ref: rule.ref });
+            continue;
+        }
+        let superseded = null;
+        for (const action of rule.actions) {
+            const key = actionKey(action);
+            const earlier = taken.get(key);
+            if (earlier !== undefined) {
+                superseded = earlier;
+                continue;
+            }
+            taken.set(key, rule.ref);
+            fired.push({ action, rule });
+        }
+        trace.push({ missing: [], outcome: superseded !== null && !fired.some((f) => f.rule === rule) ? 'superseded' : 'fired', over: superseded, ref: rule.ref });
+    }
+    return { fired, trace };
+}
+// A token count as a rule literal that reads back exactly: 2M, 750k, 1234567.
+export function tokenLiteral(tokens) {
+    if (tokens >= 1_000_000 && tokens % 1_000_000 === 0)
+        return `${tokens / 1_000_000}M`;
+    if (tokens >= 1_000 && tokens % 1_000 === 0)
+        return `${tokens / 1_000}k`;
+    return String(tokens);
+}
+function actionKey(action) {
+    switch (action.verb) {
+        case 'inbox':
+            return `inbox:${action.kind}`;
+        case 'label':
+            return `label:${action.label}`;
+        case 'notify':
+            return `notify:${action.channel}`;
+        case 'pause':
+        case 'unpause':
+            return 'pause';
+        default:
+            return action.verb;
+    }
+}
+// The guardrails an action needs from its trigger: what it acts on must be there.
+function checkAction(action, events, scope) {
+    const on = (allowed, scopes, what) => {
+        if (events.some((e) => allowed.includes(e)) || (scope !== null && scopes.includes(scope)))
+            return;
+        throw new RuleSyntaxError(`do: ${action.verb} acts on ${what}, which this rule's when doesn't give it`);
+    };
+    const ITEM_EVENTS = ['inbox.raised', 'item.closed', 'item.unblocked', 'note', 'plan', 'pr.comment', 'queue.pick', 'run.failed', 'wait.resolved', 'worker.exited', 'worker.idle', 'worker.permission', 'worker.waiting'];
+    switch (action.verb) {
+        case 'auto-approve':
+            return on(['plan'], [], 'a plan (the plan event)');
+        case 'label':
+            return on(ITEM_EVENTS, ['wait', 'inbox', 'worker'], 'an item');
+        case 'launch':
+            return on(['item.unblocked', 'queue.pick'], [], 'a queued item (queue.pick or item.unblocked); the scheduler still checks slots, Areas, blockers and quiet hours');
+        // The session manager parks a worker whose turn ended while it waits, and resumes it when a
+        // wait resolves; it asks the rules then, and at no other time.
+        case 'park':
+            return on(['worker.waiting'], [], 'a worker whose turn ended while it waits (worker.waiting)');
+        case 'remind':
+            return on(['inbox.raised', 'worker.idle', 'worker.permission'], ['wait', 'inbox'], 'an open inbox item or wait');
+        case 'resume':
+            return on(['pr.comment', 'wait.resolved'], [], 'a worker whose wait resolved (wait.resolved or pr.comment)');
+        case 'retire':
+            // Retiring removes a worktree, so only an item that is closed may cause it; it still refuses unfinished work.
+            return on(['item.closed'], [], 'a closed item (item.closed): the conductor retires only finished work');
+        case 'retry':
+            return on(['run.failed'], [], 'a failed run (run.failed)');
+        default:
+            return;
+    }
+}
+function compare(actual, op, expected) {
+    if (typeof actual === 'string' || typeof expected === 'string') {
+        const equal = String(actual).toLowerCase() === String(expected).toLowerCase();
+        return op === '==' ? equal : op === '!=' ? !equal : false;
+    }
+    switch (op) {
+        case '!=':
+            return actual !== expected;
+        case '<':
+            return actual < expected;
+        case '<=':
+            return actual <= expected;
+        case '==':
+            return actual === expected;
+        case '>':
+            return actual > expected;
+        case '>=':
+            return actual >= expected;
+    }
+}
+function compileRule(input, index, origin, limits) {
+    const does = typeof input.do === 'string' ? [input.do] : input.do;
+    let actions;
+    try {
+        actions = does.map((d) => parseAction(d, limits));
+    }
+    catch (error) {
+        if (error instanceof RuleSyntaxError)
+            throw new RuleSyntaxError(`do: ${error.message}`);
+        throw error;
+    }
+    const off = actions.every((a) => a.verb === 'none');
+    if (actions.some((a) => a.verb === 'none') && !off)
+        throw new RuleSyntaxError('do: "none" stands alone');
+    if (off && input.id === undefined)
+        throw new RuleSyntaxError('do: "none" switches off the rule with the same id, so it needs an id');
+    if (input.when === undefined && !off)
+        throw new RuleSyntaxError('when is missing');
+    let when = null;
+    try {
+        when = input.when === undefined ? null : parseWhen(input.when);
+    }
+    catch (error) {
+        if (error instanceof RuleSyntaxError)
+            throw new RuleSyntaxError(`when: ${error.message}`);
+        throw error;
+    }
+    const implied = when === null ? [] : fieldsOf(when).flatMap((f) => Object.entries(IMPLIED_EVENTS).flatMap(([prefix, e]) => (f.startsWith(prefix) ? [e] : [])));
+    const events = when === null ? [] : [...new Set([...eventsOf(when), ...implied])];
+    const scope = events.length > 0 || when === null ? null : scopeOf(fieldsOf(when));
+    if (!off)
+        for (const action of actions)
+            checkAction(action, events, scope);
+    const key = input.id ?? `#${index + 1}`;
+    return {
+        actions,
+        events,
+        file: origin.file,
+        id: input.id ?? null,
+        index,
+        note: input.note ?? null,
+        project: origin.project,
+        ref: `${origin.source === 'project' ? `project.${origin.project ?? '?'}` : origin.source}:${key}`,
+        scope,
+        source: origin.source,
+        text: { do: does, when: input.when ?? null },
+        when,
+    };
+}
+function describeType(spec) {
+    switch (spec.type) {
+        case 'clock':
+            return 'a local time, such as 22:00';
+        case 'day':
+            return 'a day, such as saturday';
+        case 'duration':
+            return 'a duration, such as 15m or 2h';
+        case 'enum':
+            return `one of ${spec.values.join(', ')}`;
+        case 'int':
+            return 'a whole number';
+        case 'labels':
+            return 'a label';
+        case 'text':
+            return 'a word or a "quoted string"';
+        case 'tokens':
+            return 'a token count, such as 500k or 2M';
+    }
+}
+function eventsOf(expr) {
+    switch (expr.kind) {
+        case 'and':
+        case 'or':
+            return [...eventsOf(expr.left), ...eventsOf(expr.right)];
+        case 'event':
+            return [expr.name];
+        case 'not':
+            return eventsOf(expr.expr);
+        default:
+            return [];
+    }
+}
+function fieldsOf(expr) {
+    switch (expr.kind) {
+        case 'and':
+        case 'or':
+            return [...fieldsOf(expr.left), ...fieldsOf(expr.right)];
+        case 'compare':
+        case 'has':
+        case 'in':
+            return [expr.field];
+        case 'event':
+            return [];
+        case 'not':
+            return fieldsOf(expr.expr);
+    }
+}
+function formatMinutes(minutes) {
+    if (minutes >= 24 * 60 && minutes % (24 * 60) === 0)
+        return `${minutes / (24 * 60)}d`;
+    if (minutes >= 60 && minutes % 60 === 0)
+        return `${minutes / 60}h`;
+    return minutes < 1 ? `${Math.round(minutes * 60)}s` : `${minutes}m`;
+}
+function isList(value) {
+    return typeof value !== 'number' && typeof value !== 'string';
+}
+function tokenize(text) {
+    const tokens = [];
+    const pattern = /\s+|("(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*')|(==|!=|>=|<=|>|<)|([()[\],])|([A-Za-z0-9_.:@/+-]+)/y;
+    let at = 0;
+    while (at < text.length) {
+        pattern.lastIndex = at;
+        const match = pattern.exec(text);
+        if (!match)
+            throw new RuleSyntaxError(`unexpected "${text[at] ?? ''}" at column ${at + 1}`);
+        if (match[1] !== undefined)
+            tokens.push({ at, kind: 'string', text: match[1].slice(1, -1).replace(/\\(.)/g, '$1') });
+        else if (match[2] !== undefined)
+            tokens.push({ at, kind: 'op', text: match[2] });
+        else if (match[3] !== undefined)
+            tokens.push({ at, kind: 'punct', text: match[3] });
+        else if (match[4] !== undefined)
+            tokens.push({ at, kind: 'word', text: match[4] });
+        at = pattern.lastIndex;
+    }
+    return tokens;
+}
+function toOp(text) {
+    switch (text) {
+        case '!=':
+        case '<':
+        case '<=':
+        case '==':
+        case '>':
+        case '>=':
+            return text;
+        default:
+            throw new RuleSyntaxError(`"${text}" is not a comparison`);
+    }
+}
+function untilReadable(text) {
+    const lower = text.toLowerCase();
+    return lower === 'tomorrow' || DAY_NAMES.some((d) => d === lower || d.slice(0, 3) === lower) || parseLocalTime(text, new Date()) !== null;
+}
+//# sourceMappingURL=rules.js.map