bareloop 0.42.0 → 0.44.0

package/types/rubricstep.d.ts

@@ -35,6 +35,13 @@ export function rubricGoal({ jobLines, files, confirmedGoal, closeDecl }: {
     confirmedGoal?: string | null;
     closeDecl?: any;
 }): string;
+/**
+ * The sentence the person confirmed, out of a goal text: for a rubric brief the rest of the `CONFIRMED_GOAL_PREFIX` line,
+ * or null when the brief has none; any other goal (a code job's) comes back unchanged.
+ * @param {string} goal
+ * @returns {string|null}
+ */
+export function confirmedGoalOf(goal: string): string | null;
 /**
  * The SHAPE of a `rubric-step` stage's parameters — what a part may carry — and nothing about which class is allowed in
  * this build (that is `checkRubricParts`, which also sees the whole job). Pure, never throws.
@@ -58,6 +65,28 @@ export function buildStepSpec(params: {
     step: number;
     parts: any[];
 }, inputShas: Record<string, string>): Record<string, any>;
+/**
+ * The files one named check READS, tree-relative: a `rubric-step` stage's own step file (`output/steps/N.json`). Any other kind reads
+ * none that a try's output can be told by, so `[]`. From the signed declaration, never guessed.
+ * @param {any} closeDecl @param {string|null|undefined} checkName
+ * @returns {string[]}
+ */
+export function judgedFilesOf(closeDecl: any, checkName: string | null | undefined): string[];
+/**
+ * PRD v1.106 Part 5: what each file a try's `check-passes` checks read looked like WHEN it was judged: `{path, bytes, sha256}`. The step
+ * file is overwritten by the next try, so the spine's `output-judged` record is the only trace; the content itself is never written (hard
+ * line). A missing, non-regular or over-size file is skipped — nothing was judged there.
+ * @param {any} closeDecl @param {string} workdir @param {Array<{type?: string, name?: string}>} exits a step's declared exits
+ * @returns {Promise<Array<{path: string, bytes: number, sha256: string}>>}
+ */
+export function outputJudgedRecords(closeDecl: any, workdir: string, exits: Array<{
+    type?: string;
+    name?: string;
+}>): Promise<Array<{
+    path: string;
+    bytes: number;
+    sha256: string;
+}>>;
 /**
  * The step file's bytes as the close reads them: the parsed JSON object, or WHY there is none. A file cut off mid-write
  * parses to nothing (reason `not-json`); text cut off INSIDE an otherwise valid JSON object cannot be told from a short
@@ -101,7 +130,9 @@ export function plainStepGap(step: number, why: string, g: any, params?: any): s
  *   `inputs` maps each cited label to its frozen TEXT; its sha256 is taken here from that text, and bareguard compares it to
  *   the manifest's recorded sha via `inputShas`.
  * @param {Record<string, string>} inputShas the manifest's recorded sha256 per cited label
- * @returns {Promise<{verdict: 'green'|'red'|'stopped', gapLines: string[], fault: string|null, detail: Record<string, any>}>}
+ * @returns {Promise<{verdict: 'green'|'red'|'stopped', gapLines: string[], fault: string|null, detail: Record<string, any>,
+ *   evidence?: any[], evidenceTotal?: number}>} `evidence`/`evidenceTotal` are bareguard's `full.evidence` (what each `cited` check read), carried out
+ *   for the report-only `rubric-evidence` spine record; no verdict, gap or count above is derived from them
  */
 export function gradeStep({ params, bytes, outputBytes, inputs, factQuotes, factMissing }: {
     params: {
@@ -118,6 +149,8 @@ export function gradeStep({ params, bytes, outputBytes, inputs, factQuotes, fact
     gapLines: string[];
     fault: string | null;
     detail: Record<string, any>;
+    evidence?: any[];
+    evidenceTotal?: number;
 }>;
 /**
  * The labels of a job's numbered inputs, or null when it carries none (a caller that has no inputs in hand skips the label rule).
@@ -178,6 +211,17 @@ export function settlePersonsWords(declaration: any, jobLines: any[] | null | un
  * @param {any} declaration @returns {any}
  */
 export function withFactBindings(declaration: any): any;
+/**
+ * NO SILENT DROP (idea A core, spec 4.4): code writes the Not checked rows for what the page rules removed, before the declaration is validated.
+ *   - a dropped FACT that carries a `~` rule no part carries and no `refused` entry names -> `closeDecl.refused` gets {line, rule, reason}
+ *     (shown under that line in the person's own rule words by {@link ruleNotChecked});
+ *   - any other drop (a fact from the job line itself, a rule another fact carries, a word dropped from a fact that is still checked, so a
+ *     narrower check is still said) -> one line in `closeDecl.notes`, shown as Not checked (the AI's own reading).
+ * Never a line-level `refused` entry without `rule` (that would silence every other rule red on the line). A rule the drafter already listed
+ * itself is never listed twice, and running this twice adds nothing. Pure; the input is untouched.
+ * @param {any} declaration @param {import('./pagerules.js').Dropped[]|null|undefined} dropped @param {any[]|null|undefined} jobLines @returns {any}
+ */
+export function withDropNotes(declaration: any, dropped: import("./pagerules.js").Dropped[] | null | undefined, jobLines: any[] | null | undefined): any;
 /**
  * The ~ rules the drafter listed under Not checked (`refused` entries that name a `rule`), each as one line in the person's own
  * words: `line N: "<the rule as written>" — <the drafter's reason>` (PART 1b, RF6 / RF16).
@@ -190,6 +234,11 @@ export function ruleNotChecked(closeDecl: any, jobLines: any[] | null | undefine
  * @param {any} closeDecl @returns {string[]}
  */
 export function proseNotChecked(closeDecl: any): string[];
+/** the same items as {@link proseNotChecked} with the job line each belongs to (the stage's own `step`) @param {any} closeDecl @returns {{line: number, text: string}[]} */
+export function proseNotCheckedItems(closeDecl: any): {
+    line: number;
+    text: string;
+}[];
 /**
  * One countable part as a plain sentence, written by code from the part's signed fields (never from the model's words), so the
  * plan card and the close are one thing seen twice.
@@ -269,6 +318,11 @@ export const STEP_DIR: "output/steps";
 export function stepFileRel(n: number): string;
 /** the largest step file the close reads: a bigger one is a stop, never silently truncated (bareguard's own source cap) */
 export const STEP_MAX_BYTES: number;
+/**
+ * What a rubric job's goal text is: the worker brief `rubricGoal` builds. The Job tab's "AI's summary" is only the one
+ * sentence the person confirmed, never this brief, so the first line and the confirmed-sentence prefix have ONE spelling.
+ */
+export const RUBRIC_GOAL_HEAD: "Do the job below from the input files, then write one JSON file per numbered line.";
 /** the closed set of classes a part is sorted into; `none` = "I could not sort this one" (a red, in plain words, never a guess) */
 export const PART_CLASSES: readonly string[];
 /**
@@ -279,6 +333,8 @@ export const PART_CLASSES: readonly string[];
  */
 export const COUNT_CHECKS: Readonly<Record<string, readonly string[]>>;
 export function sha256Of(b: string | Buffer): string;
+export function boundInWords(b: unknown, said: string): boolean;
+export function wordsSaidOn(jl: any): string;
 export type ShapeRed = {
     code: string;
     path: string;

package/types/runlist.d.ts

@@ -48,7 +48,8 @@ export function appendRun(row: RunRow, opts?: {
     reason?: "duplicate-runid";
 };
 /**
- * @typedef {{ runid: string, type: 'settled'|'released', by: string, at: string, reason?: string, spentUsd?: number, spendComplete?: boolean, leg?: number }} RunEvent
+ * @typedef {{ runid: string, type: 'settled'|'released', by: string, at: string, reason?: string, words?: string, spentUsd?: number, spendComplete?: boolean, leg?: number }} RunEvent
+ * `words` (2026-10-19): on a `settled` with `reason: 'refused before start'`, the plain refusal the panel shows for that run (it has no spine).
  * `leg` (P5-R): which leg of the run the write-back is about; absent = leg 1 (every entry written before P5-R).
  * A resumed run is ONE row, so `settled`/`released` are per leg: a later leg's `released` gives back THAT leg's
  * claim and never removes the run.
@@ -67,6 +68,26 @@ export function appendRun(row: RunRow, opts?: {
 export function appendRunEvent(event: RunEvent, opts?: {
     home?: string;
 }): void;
+/**
+ * RULED 2026-10-15 ("Remove from Needs you"): the person took a stopped run's card out of the Needs-you list. ONE row
+ * `{runid, type:'needs-removed', at}` appended beside the run rows; it is not a run, a claim or an event ({@link readRunList}
+ * ignores it, so the monthly limit, the run counter and the scheduler never see it). Nothing is rewritten.
+ * @param {string} runid
+ * @param {{ home?: string, now?: () => number }} [opts]
+ * @returns {string} the `at` written
+ */
+export function appendNeedsRemoved(runid: string, opts?: {
+    home?: string;
+    now?: () => number;
+}): string;
+/**
+ * The newest `needs-removed` time (ms) per run id. An absent file is an empty map; a row with no readable time is not a removal.
+ * @param {{ home?: string }} [opts]
+ * @returns {Map<string, number>}
+ */
+export function readNeedsRemovals(opts?: {
+    home?: string;
+}): Map<string, number>;
 /**
  * @typedef {{ type: 'leg-start', runid: string, leg: number, pid?: number, capUsd?: number, at: string }} LegStart
  * A resumed run's NEW claim (P5-R, hamr 2026-10-02: one run, one id, one row): appended beside the run's row
@@ -206,6 +227,7 @@ export type RunRow = {
     leg?: number;
 };
 /**
+ * `words` (2026-10-19): on a `settled` with `reason: 'refused before start'`, the plain refusal the panel shows for that run (it has no spine).
  * `leg` (P5-R): which leg of the run the write-back is about; absent = leg 1 (every entry written before P5-R).
  * A resumed run is ONE row, so `settled`/`released` are per leg: a later leg's `released` gives back THAT leg's
  * claim and never removes the run.
@@ -221,6 +243,7 @@ export type RunEvent = {
     by: string;
     at: string;
     reason?: string;
+    words?: string;
     spentUsd?: number;
     spendComplete?: boolean;
     leg?: number;

package/types/schedulewords.d.ts

@@ -0,0 +1,137 @@
+/**
+ * What starts the job, in words. `null` (by hand) has no sentence.
+ * @param {Trigger|null|undefined} t @param {string} [home]
+ * @returns {string|null}
+ */
+export function scheduledWords(t: Trigger | null | undefined, home?: string): string | null;
+/** "Mon 13 Oct, 09:00" — local time, fixed English names (never the machine's locale). @param {number} ms */
+export function slotWords(ms: number): string;
+/**
+ * The Scheduled card's first line: "today 17:00", "tomorrow 09:00", else the date the NEXT line already says
+ * ("Tue 20 Oct, 09:05"). Local time, by calendar day. @param {number} ms the next run @param {number} now
+ */
+export function nextTimeWords(ms: number, now: number): string;
+/** "next in 20m" / "next in 3h" / "next in 3d" (whole units, rounded down, never "0m"). @param {number} ms @param {number} now */
+export function nextInWords(ms: number, now: number): string;
+/**
+ * NEXT of a scheduled job: one sentence, first match wins.
+ *  1. a run of this job is waiting for the person's Accept (the next scheduled run does NOT wait for it, T7);
+ *  2. the latest outcome this month is `monthly-exhausted` (amounts from the row), RED;
+ *  3. a clock kind with a next slot; 4. a file kind that is armed; 5. not armed yet.
+ * A last outcome of `refused` goes in front of 3-5, so a trigger that cannot start is never silent.
+ * `red` is the typed flag for "the person must act": the page paints it and never guesses from the text.
+ * @param {{trigger: Trigger, armed: boolean, nextSlotMs: number|null, lastOutcome: any, waitingRunNo: number|null, now: number, retryInMs?: number|null, gaveUp?: any}} f
+ *   `lastOutcome` = the newest outcome row of the CURRENT signing (`kind`, `at` in ms, `why`, `leftUsd`, `needUsd`, `atLeast`)
+ * @returns {{text: string, red: boolean}}
+ */
+export function scheduledNextFor(f: {
+    trigger: Trigger;
+    armed: boolean;
+    nextSlotMs: number | null;
+    lastOutcome: any;
+    waitingRunNo: number | null;
+    now: number;
+    retryInMs?: number | null;
+    gaveUp?: any;
+}): {
+    text: string;
+    red: boolean;
+};
+/** Is `atMs` in the same local calendar month as `nowMs`? A non-number is never. @param {unknown} atMs @param {number} nowMs */
+export function sameMonthAs(atMs: unknown, nowMs: number): boolean;
+/** RULED 2026-10-15: the red NEXT of a schedule that gave up. @param {unknown} why the refusal's own words */
+export function gaveUpNextWords(why: unknown): string;
+/** The give-up date on the Needs-you card, local `MM/DD HH:MM`. @param {number} ms */
+export function gaveUpDateWords(ms: number): string;
+/** RULED 2026-10-15: after an install-needed refusal, the wait that is left, in whole minutes rounded up; '' when no wait. @param {number|null|undefined} ms */
+export function retryWords(ms: number | null | undefined): string;
+/** The fixed catch-up sentence from a run's `trigger.json`. @param {any} rec */
+export function catchUpWords(rec: any): "This run was a catch-up: it started more than 2 minutes after its set time (the panel was off)." | null;
+/**
+ * A spawn error AFTER the consuming row: `tries` releases so far, `max` the bound. Under the bound it will be tried again;
+ * at the bound it stays consumed and says so. @param {string} why @param {number} tries @param {number} max
+ */
+export function lateRefusalWords(why: string, tries: number, max: number): string;
+/** "Thu 10/16 08:15" — local time, fixed English day names. @param {number} ms */
+export function nextSlotShort(ms: number): string;
+/**
+ * Job tab, "Started": how the run began, then its local start time. `rec` = the run's `trigger.json` (null on a hand run).
+ * @param {any} rec @param {number|null} atMs the run's start
+ */
+export function startedWords(rec: any, atMs: number | null): string;
+/**
+ * Audit, first row of a run a schedule started. @param {any} rec `trigger.json` @param {number|null} originNo the origin run's number
+ */
+export function startedAuditWords(rec: any, originNo: number | null): string;
+/**
+ * A fire that started nothing, in plain words. `short` = the SCHEDULE row's `last` reason; else the Audit group's line.
+ * @param {any} row a ledger row (`busy` | `monthly-exhausted` | `refused` | `gave-up`) @param {boolean} [short]
+ */
+export function skippedWords(row: any, short?: boolean): string;
+/**
+ * Job tab, "Schedule": the job's schedule NOW and what it is bound to. The first part IS the Run tab's line ({@link scheduledWords}),
+ * first letter lowered, so the two can never disagree.
+ * @param {{trigger: Trigger|null, originNo: number|null, model: string|null, destination: string|null, home?: string}} f
+ */
+export function jobScheduleWords(f: {
+    trigger: Trigger | null;
+    originNo: number | null;
+    model: string | null;
+    destination: string | null;
+    home?: string;
+}): string;
+/** RULED 2026-10-15: the SCHEDULE row's `next` while an install-needed refusal is waiting to be tried again. @param {number} ms */
+export function retryNextWords(ms: number): string;
+/**
+ * RULED 2026-10-15: the sign on the head of the Audit's `schedule` section. ONE small rule (hamr may still adjust it): [▶] only while a
+ * run of the job is running (as everywhere in the panel), [✗] when the SCHEDULE row is red, else [·] (on, waiting). RULED 2026-10-18 (v1.106
+ * Part 4): the header reads `[sign] word schedule · ...`, the sign AND the word both from the one status table (src/panel/status.js), never typed here.
+ * @param {{running: boolean, red: boolean}} f @returns {{sign: string, word: string}}
+ */
+export function scheduleSignFor(f: {
+    running: boolean;
+    red: boolean;
+}): {
+    sign: string;
+    word: string;
+};
+/** Audit schedule section, the `this run` words of a run the schedule started (the head already says which schedule and from where). @param {any} rec `trigger.json` */
+export function sectionThisRunWords(rec: any): string;
+/** Audit schedule section, folded tail: `1 try started nothing` / `N tries started nothing`; '' for none. @param {number} n */
+export function triesTailWords(n: number): string;
+/**
+ * Every schedule button/word the page shows lives here, so a reword is ONE edit (hamr will reword on his walk).
+ * The server sends this table with the run detail and the schedule card; the page reads every label from it.
+ */
+export const SCHEDULE_WORDS: Readonly<{
+    byHand: "By hand";
+    cancelSchedule: "Cancel schedule";
+    cancelWords: "Cancel schedule";
+    scheduleRun: "Schedule run";
+    cancelModify: "Cancel / modify schedule";
+    signSchedule: "Sign schedule";
+    nothingChanged: "Nothing changed yet. This card only sets or adjusts the schedule; it never runs the job.";
+    confirmPrefix: "Confirm: ";
+    whenLabel: "When";
+    nowPrefix: "Now: ";
+    scheduledLabel: "SCHEDULE";
+    nextLabel: "NEXT";
+    options: Readonly<{
+        hand: "By hand";
+        daily: "Every day at HH:MM";
+        weekdays: "Weekdays at HH:MM";
+        weekly: "Every <day> at HH:MM";
+        'file-updated': "When <file> is updated";
+        'new-file': "When a new file arrives in <folder>";
+    }>;
+    gaveUpPill: "Check";
+    problemNext: "next: fix it in Cancel / modify schedule";
+    monthNext: "next: raise the limit in Settings, or it starts on the 1st";
+    acceptWaiting: "waiting for your Accept (the next run does not wait)";
+    scheduleGroup: "schedule";
+    notGreen: "This job has not had a good run yet. Run it by hand and get it right first; then you can set when it runs. A rubric job also needs your Accept once. Nothing was changed.";
+    stale: "What you were shown is not what is on the card now. Nothing was signed. Look again, then sign.";
+}>;
+export function dateTimeWords(ms: number): string;
+export function lowerFirst(s: string): string;
+export type Trigger = import("./trigger.js").Trigger;

package/types/source.d.ts

@@ -421,6 +421,17 @@ export function refreezeUrlInputs({ into, fetchUrl }: {
     ok: false;
     error: string;
 }>;
+/**
+ * PRD v1.106 Part 5 Q2: what `source.json` says about web inputs, read synchronously and never throwing: whether the copy has any web input
+ * (`inputs[].url`) and when the run-start refetch last finished (`refrozenAt`, written last by {@link refreezeUrlInputs}). The panel decides
+ * "fetching the page..." from this: it applies while a web input exists and no refetch has finished at or after `sinceIso`.
+ * @param {string} sourceJsonPath @param {string|null|undefined} sinceIso
+ * @returns {{ hasWeb: boolean, fetching: boolean }}
+ */
+export function webFetchState(sourceJsonPath: string, sinceIso: string | null | undefined): {
+    hasWeb: boolean;
+    fetching: boolean;
+};
 /** the per-file ceiling for a rubric input: bareguard's `cited` check searches a quote in a source only up to this size
  * (its `quoteSourceMaxBytes`); a bigger file could never be cited from, so the door refuses it at $0 */
 export const RUBRIC_INPUT_MAX_BYTES: number;

package/types/thinking.d.ts

@@ -84,6 +84,45 @@ export function thinkingRowText({ mode, support, status }: {
     support?: true | false | "unverified";
     status?: string;
 }): string;
+/**
+ * THE one decision for a worker model call (PRD v1.106 Part 1): from the phase label and attempt iteration `mkWorker` already holds,
+ * and the job's tick (`job.thinking === true`). Decided in code, never by the model.
+ *   tick on                                   -> 'on' for every call
+ *   plan (draft, redraft, replan)             -> 'on'   (the planner is the hard part of a run)
+ *   scout                                     -> 'off'
+ *   step:<id> attempt 1                       -> 'off'
+ *   step:<id> attempt >= 2                    -> 'on'
+ *   fix (close-fix)                           -> 'on'
+ * A step or fix iteration that is not a whole number >= 1 throws (operator error), as does an unknown phase — never a guess.
+ * @param {{ phase: unknown, iteration?: unknown, tick?: unknown }} o
+ * @returns {'on'|'off'}
+ */
+export function workerThinkingMode({ phase, iteration, tick }: {
+    phase: unknown;
+    iteration?: unknown;
+    tick?: unknown;
+}): "on" | "off";
+/**
+ * PRD v1.106 Part 3 — the words one worker call carries in the Audit, READ from the run's own spine, never guessed. Finds the LAST
+ * `thinking-decision` of `phase` (and `iteration`, when given) whose seq lies strictly between `lo` and `hi`, pairs it with the first
+ * `thinking-status` of the same phase and iteration after it (before the next decision), and words both through {@link thinkingRowText}
+ * (drafting's own words). `null` when the window holds no decision: a run from before the records existed shows no thinking word.
+ * @param {any[]} spine the run's spine records (each with a numeric `seq`)
+ * @param {{ phase: string, lo?: number, hi?: number, iteration?: number|null }} q
+ * @returns {string|null}
+ */
+export function thinkingWordsFrom(spine: any[], { phase, lo, hi, iteration }: {
+    phase: string;
+    lo?: number;
+    hi?: number;
+    iteration?: number | null;
+}): string | null;
+/**
+ * The Job tab's row words (PRD v1.106 Part 3): the default rule, or the job's "Thinking on" tick, but only for a run whose spine
+ * recorded a `thinking-decision`; a run from before the thinking rule reads `—`, never a guess from the job's tick (fwdloop M4d am28).
+ * @param {boolean} tick @param {boolean} recorded the run's spine holds at least one `thinking-decision` @returns {string}
+ */
+export function thinkingJobText(tick: boolean, recorded: boolean): string;
 /** The words under a greyed "Thinking on" box (the server's `thinking.canChange` decides; the page decides nothing). */
 export const THINKING_FIXED_SAY: "can't change this for this model";
 /** The enumerated operator knob a drafting call is built with: 'on' | 'off' (the tick, spelled as a word). */

package/types/trigger.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The only way a trigger enters the system. Returns the typed trigger, or says what to fix (and which field).
+ * @param {unknown} t
+ * @returns {{ok: true, trigger: Trigger} | {ok: false, say: string, code: 'invalid-value'|'unknown-field', path: string}}
+ */
+export function validateTrigger(t: unknown): {
+    ok: true;
+    trigger: Trigger;
+} | {
+    ok: false;
+    say: string;
+    code: "invalid-value" | "unknown-field";
+    path: string;
+};
+/** @typedef {import('./triggerclock.js').Schedule | {kind:'new-file', folder:string} | {kind:'file-updated', path:string}} Trigger */
+export const TRIGGER_KINDS: readonly string[];
+export const CLOCK_KINDS: readonly string[];
+export const FILE_KINDS: readonly string[];
+export function isClockTrigger(t: unknown): t is {
+    kind: "daily" | "weekdays" | "weekly";
+    hour: number;
+    minute: number;
+};
+export function isFileTrigger(t: unknown): t is {
+    kind: "new-file";
+    folder: string;
+} | {
+    kind: "file-updated";
+    path: string;
+};
+export type Trigger = import("./triggerclock.js").Schedule | {
+    kind: "new-file";
+    folder: string;
+} | {
+    kind: "file-updated";
+    path: string;
+};

package/types/triggerclock.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The only way a clock schedule enters the system. Refuses anything else, naming the field.
+ * @param {unknown} s
+ * @returns {Schedule}
+ */
+export function validateSchedule(s: unknown): Schedule;
+/**
+ * Is a run due at `now`? Slots missed (panel off) collapse to ONE fire, for the latest slot, marked catch-up.
+ * Catch-up = more than one slot was missed, or the latest slot is more than GRACE_MS old.
+ * @param {Schedule} schedule
+ * @param {ClockRow[]} rows
+ * @param {number} now epoch ms
+ * @returns {Due}
+ */
+export function due(schedule: Schedule, rows: ClockRow[], now: number): Due;
+/**
+ * The next slot time strictly after `afterMs` (epoch ms). Words are the caller's (schedulewords.js).
+ * @param {Schedule} schedule
+ * @param {number} afterMs
+ * @returns {number}
+ */
+export function nextSlot(schedule: Schedule, afterMs: number): number;
+/** The trigger was set at `now` under signature `sig`: no slot before this ever fires. @param {string} file @param {number} now @param {string} sig */
+export function armTrigger(file: string, now: number, sig: string): void;
+/**
+ * Record that the run for this due slot is starting (the consuming row). Write-once per slot.
+ * @param {string} file @param {Due} d the result of `due` with fire true @param {number} now @param {string} sig
+ */
+export function recordFire(file: string, d: Due, now: number, sig: string): void;
+/** @typedef {{kind:'daily'|'weekdays', hour:number, minute:number} | {kind:'weekly', day:string, hour:number, minute:number}} Schedule */
+/** @typedef {import('./triggerledger.js').LedgerRow} ClockRow */
+/** @typedef {{fire:boolean, catchUp:boolean, missed:number, slot?:number}} Due */
+/** A slot seen MORE than this after its set time is a catch-up. Exactly this late is on time. */
+export const GRACE_MS: 120000;
+export const DAYS: string[];
+export type Schedule = {
+    kind: "daily" | "weekdays";
+    hour: number;
+    minute: number;
+} | {
+    kind: "weekly";
+    day: string;
+    hour: number;
+    minute: number;
+};
+export type ClockRow = import("./triggerledger.js").LedgerRow;
+export type Due = {
+    fire: boolean;
+    catchUp: boolean;
+    missed: number;
+    slot?: number;
+};

package/types/triggerfiles.d.ts

@@ -0,0 +1,93 @@
+/** The file-kind rows of the job's ledger that still count (a released `ran` does not). @param {string} file @returns {SeenRow[]} */
+export function readSeen(file: string): SeenRow[];
+/** Arrived rows are never overwritten: the 2nd arrival of a sha (after a drop) gets its own id. @param {string} ledger @param {ToRun & {name?:string}} item @param {number} at the scheduler's clock, never the file's mtime @param {string} sig */
+export function recordArrived(ledger: string, item: ToRun & {
+    name?: string;
+}, at: number, sig: string): boolean;
+/** `of` = the arrived row it cancels (item.id when a queue row is passed). @param {string} ledger @param {{sha:string, path:string, size:number, id?:string}} item @param {string} why a plain reason: deleted, changed, schedule-changed, schedule-cancelled @param {number} at @param {string} sig */
+export function recordDropped(ledger: string, item: {
+    sha: string;
+    path: string;
+    size: number;
+    id?: string;
+}, why: string, at: number, sig: string): boolean;
+/**
+ * The queue: arrived and neither ran nor dropped, oldest arrival first. Identical arrival times: by name, then by sha (deterministic).
+ * @param {SeenRow[]} rows @returns {(SeenRow & {path:string})[]}
+ */
+export function queueOf(rows: SeenRow[]): (SeenRow & {
+    path: string;
+})[];
+/**
+ * At a queued file's turn, look at it again, at use time: lstat (no symlink, a regular file), realpath of its folder, re-hash.
+ * @param {{path:string, sha:string}} item
+ * @returns {{state:'ok', path:string, sha:string, size:number} | {state:'deleted', say:string} | {state:'changed', sha:string}}
+ */
+export function recheck(item: {
+    path: string;
+    sha: string;
+}): {
+    state: "ok";
+    path: string;
+    sha: string;
+    size: number;
+} | {
+    state: "deleted";
+    say: string;
+} | {
+    state: "changed";
+    sha: string;
+};
+/**
+ * The target is usable NOW, or an Error naming why: a file that is not a symlink and not something else (a file that does not exist yet
+ * is allowed: it may arrive), a folder that exists, resolved with realpathSync. The one rule `arm` and a door's set-time check share.
+ * @param {'new'|'updated'} mode @param {string} target
+ */
+export function checkTarget(mode: "new" | "updated", target: string): void;
+/**
+ * @param {{mode:'new'|'updated', target:string, ledger:string, sig:string, now?:() => number}} opts target = folder (new) or file (updated)
+ */
+export function createFileTrigger({ mode, target, ledger, sig, now }: {
+    mode: "new" | "updated";
+    target: string;
+    ledger: string;
+    sig: string;
+    now?: () => number;
+}): {
+    arm: () => void;
+    poll: () => {
+        arrived: ToRun[];
+        refused: Refused[];
+    };
+};
+/** @typedef {{id:string, kind:'baseline'|'arrived'|'ran'|'dropped', sha:string, name:string, size:number, at:number, sig?:string, path?:string, why?:string, of?:string}} SeenRow */
+/** @typedef {{path:string, sha:string, size:number}} ToRun */
+/** @typedef {{path:string, why:string}} Refused */
+/** Consecutive polls with the same size and mtime before a file is taken. (Two matches in a row = taken on the third sighting.) */
+export const STABLE_POLLS: 2;
+export function recordRan(ledger: string, item: {
+    sha: string;
+    path: string;
+    size: number;
+}, at: number, sig: string): boolean;
+export type SeenRow = {
+    id: string;
+    kind: "baseline" | "arrived" | "ran" | "dropped";
+    sha: string;
+    name: string;
+    size: number;
+    at: number;
+    sig?: string;
+    path?: string;
+    why?: string;
+    of?: string;
+};
+export type ToRun = {
+    path: string;
+    sha: string;
+    size: number;
+};
+export type Refused = {
+    path: string;
+    why: string;
+};

package/types/triggerledger.d.ts

@@ -0,0 +1,35 @@
+/** @typedef {{id?: string, kind: string, sig?: string, at?: number, [k: string]: unknown}} LedgerRow */
+/**
+ * Every row that parses, oldest first, and how many lines did not. A missing file is no rows.
+ * @param {string} file
+ * @returns {{rows: LedgerRow[], skipped: number}}
+ */
+export function readLedger(file: string): {
+    rows: LedgerRow[];
+    skipped: number;
+};
+/**
+ * Append one row (dir 0700, file 0600). A torn tail gets a newline first. `once` refuses a row whose `id` is
+ * already on disk (write-once ids), by throwing.
+ * @param {string} file
+ * @param {LedgerRow} row
+ * @param {{once?: boolean}} [opts]
+ */
+export function appendRow(file: string, row: LedgerRow, opts?: {
+    once?: boolean;
+}): void;
+/**
+ * Walk the rows in order: a `released` row (`of` = an id) cancels the latest earlier live row with that id, and
+ * is itself dropped. A released `fire` or `ran` is not consumed, so its slot or file is retryable (Part 4) and
+ * the same id may be written again.
+ * @param {LedgerRow[]} rows
+ * @returns {LedgerRow[]}
+ */
+export function withoutReleased(rows: LedgerRow[]): LedgerRow[];
+export type LedgerRow = {
+    id?: string;
+    kind: string;
+    sig?: string;
+    at?: number;
+    [k: string]: unknown;
+};

package/types/userrun.d.ts

@@ -219,6 +219,10 @@ export type RunCtx = {
      * see `RunOpts.into`
      */
     into?: string | undefined;
+    /**
+     * a FRESH `--spec` run: fetch the web inputs again AFTER the run is listed (never on resume/door/decide)
+     */
+    refreeze?: boolean | undefined;
     model: string | null;
     providerKey: string | null;
     readShim: string | null;