bareloop 0.41.0 → 0.42.0

package/types/labelscan.d.ts

@@ -0,0 +1,38 @@
+/** @typedef {{id: string, label: string, count: number, example: string}} LabelEntry */
+/** @typedef {Record<'money'|'number'|'date'|'time'|'text', LabelEntry[]>} LabelScan */
+/** @param {string} t @returns {string} white space made one space, quote marks at the edges dropped, trimmed - how a label is compared */
+export function normLabel(t: string): string;
+/**
+ * Scan one source text for the labels that sit before values, per shape.
+ * @param {string} text
+ * @returns {LabelScan}
+ */
+export function scanLabels(text: string): LabelScan;
+/**
+ * Is this label on the list for this shape? Compared the way a label is read: white space of any kind is one space, quote marks at the
+ * edges are dropped. `idOrText` may be a list id (`t1`) or the exact words.
+ * @param {LabelScan} scan @param {string} shape @param {unknown} idOrText
+ * @returns {LabelEntry|null}
+ */
+export function labelOnList(scan: LabelScan, shape: string, idOrText: unknown): LabelEntry | null;
+/**
+ * The list as the look and the drafter are shown it, one block per shape that has any label.
+ * @param {string} inputLabel the input the list belongs to @param {LabelScan} scan
+ * @returns {string}
+ */
+export function renderLabelList(inputLabel: string, scan: LabelScan): string;
+/** the shapes a list is made for */
+export const LABEL_SHAPES: readonly string[];
+/** a label must occur at least this often to be listed (1: a one-page document with one total still has its label; the list is cut to the highest counts) */
+export const MIN_COUNT: 1;
+/** how many labels one shape's list holds at most (the highest counts first) */
+export const MAX_PER_SHAPE: 40;
+/** only this much of a source is scanned (a source over it is scanned up to a line end) */
+export const SCAN_MAX_CHARS: 2000000;
+export type LabelEntry = {
+    id: string;
+    label: string;
+    count: number;
+    example: string;
+};
+export type LabelScan = Record<"money" | "number" | "date" | "time" | "text", LabelEntry[]>;

package/types/pagefetch.d.ts

@@ -0,0 +1,71 @@
+/** @param {unknown} v @returns {boolean} an http(s) address (the one spelling of "this Inputs value is a web address") */
+export function isWebUrl(v: unknown): boolean;
+/**
+ * How much of a fetched page is the page's own content: the snapshot's header lines (url, size note, hint) and every part of the tree
+ * under a banner / navigation / contentinfo landmark are taken out, the page reader's bracketed tags are removed, and what is left is
+ * counted. Generic - no site names, only the ARIA landmark roles. Text that is not a snapshot tree (a plain file) has no landmark, so it
+ * counts whole.
+ * @param {string} text @returns {number}
+ */
+export function pageContentChars(text: string): number;
+/**
+ * @typedef {{goto: (url: string, timeout?: number) => Promise<void>, waitForNetworkIdle: (o?: {idle?: number, timeout?: number}) => Promise<void>,
+ *   snapshot: (o?: {mode?: string}) => Promise<string>, close: () => Promise<void>}} FetchPage the part of barebrowse's page handle the fetch uses
+ */
+/**
+ * Fetch one page's text. `connect` is injected (a test never reaches the network); the default is barebrowse's own `connect`.
+ * @param {string} url
+ * @param {{connect?: (opts: Record<string, any>) => Promise<FetchPage>, timeoutMs?: number, idleMs?: number, idleTimeoutMs?: number, closeWaitMs?: number}} [o]
+ * @returns {Promise<{ok: true, text: string, url: string}|{ok: false, error: string}>} `error` is plain words, without a spend line
+ */
+export function fetchPageText(url: string, { connect, timeoutMs, idleMs, idleTimeoutMs, closeWaitMs }?: {
+    connect?: (opts: Record<string, any>) => Promise<FetchPage>;
+    timeoutMs?: number;
+    idleMs?: number;
+    idleTimeoutMs?: number;
+    closeWaitMs?: number;
+}): Promise<{
+    ok: true;
+    text: string;
+    url: string;
+} | {
+    ok: false;
+    error: string;
+}>;
+/** the session options (incognito: no auth ever enters; blockPrivateNetwork: SSRF guard); ONE frozen object so a test can pin them */
+export const CONNECT_OPTIONS: Readonly<{
+    incognito: true;
+    blockPrivateNetwork: true;
+}>;
+/** the snapshot options step 0 proved */
+export const SNAPSHOT_OPTIONS: Readonly<{
+    mode: "act";
+}>;
+/** the page's network must be quiet this long (ms) before we read it: long enough to span the gap between a page's first load and the
+ *  script requests that fill the results, short enough not to stretch a plain page */
+export const NETWORK_IDLE_MS: 1500;
+/** the most we wait for the network to go quiet (ms); a page that never settles (polling, streaming) is read as it stands after this */
+export const NETWORK_IDLE_TIMEOUT_MS: 20000;
+/** the most we wait for the page to load at all (ms) */
+export const GOTO_TIMEOUT_MS: 30000;
+/** a page that comes back with fewer characters than this (after trimming) is treated as "nothing came back" */
+export const MIN_PAGE_CHARS: 200;
+/** the page text left after the site's own header, menus and footer are taken out must hold at least this many characters, or the page is
+ *  "only site chrome" (L2: a 719-character fetch of Google's header and sign-in passed the 200-character floor) */
+export const MIN_CONTENT_CHARS: 100;
+/** our own deadline around one whole fetch (a hung browser leaves no trace; this is the only thing that fires on the absence of an answer) */
+export const PAGE_FETCH_TIMEOUT_MS: 90000;
+/**
+ * the part of barebrowse's page handle the fetch uses
+ */
+export type FetchPage = {
+    goto: (url: string, timeout?: number) => Promise<void>;
+    waitForNetworkIdle: (o?: {
+        idle?: number;
+        timeout?: number;
+    }) => Promise<void>;
+    snapshot: (o?: {
+        mode?: string;
+    }) => Promise<string>;
+    close: () => Promise<void>;
+};

package/types/panel/authorsession.d.ts

@@ -7,8 +7,9 @@ export function latestStep(steps: StepLine[], id: string): StepLine | undefined;
  * earlier line keeps its status and detail). Existing lines are never moved. Re-starting the step that is still the
  * LAST line just resumes that line.
  * @param {StepLine[]} steps @param {string} id @param {string} [detail] (absent = keep what the line has)
+ * @param {Readonly<Record<string, string>>} [labels] the label table (a file job passes its own)
  */
-export function advanceSteps(steps: StepLine[], id: string, detail?: string): void;
+export function advanceSteps(steps: StepLine[], id: string, detail?: string, labels?: Readonly<Record<string, string>>): void;
 /**
  * The confirm turn's plan as a chat message (P7): a STRUCTURED `{role:'bot', kind:'plan', plan}` the page draws with the
  * same renderer the Job tab uses — each numbered job line, its `~` rule, its drafted checks folded; the AI's own "not
@@ -139,7 +140,7 @@ export function validateJobCard(card: any, opts?: {
  * @param {any} card the validated job card (see {@link validateJobCard})
  * @param {{env?: Record<string,string|undefined>, sessionsRoot?: string, home?: string, timeoutMs?: number,
  *   scout?: any, generate?: Function, confirmGenerate?: Function, authorFn?: Function,
- *   prepareSigningFn?: Function, npmCiFn?: Function, draftThinking?: "on"|"off", reuse?: {spec: any, workflowKey: string}}} [deps] `scout`..`prepareSigningFn` are
+ *   prepareSigningFn?: Function, npmCiFn?: Function, lookFn?: Function|null, fetchUrl?: (url: string) => Promise<{ok: true, text: string, url: string}|{ok: false, error: string}>, draftThinking?: "on"|"off", reuse?: {spec: any, workflowKey: string}}} [deps] `scout`..`prepareSigningFn` are
  *   TEST SEAMS ONLY — see the note just above where each is read, below. `reuse` (Reuse workflow) is NOT a seam: the
  *   caller (`/api/author/start`) sets it only when the server's own same-job rule held.
  * @returns {any} the session object
@@ -155,6 +156,15 @@ export function createSession(card: any, deps?: {
     authorFn?: Function;
     prepareSigningFn?: Function;
     npmCiFn?: Function;
+    lookFn?: Function | null;
+    fetchUrl?: (url: string) => Promise<{
+        ok: true;
+        text: string;
+        url: string;
+    } | {
+        ok: false;
+        error: string;
+    }>;
     draftThinking?: "on" | "off";
     reuse?: {
         spec: any;
@@ -168,6 +178,12 @@ export function createSession(card: any, deps?: {
  * @type {Readonly<Record<string, string>>}
  */
 export const STEP_LABELS: Readonly<Record<string, string>>;
+/**
+ * The same steps, worded for a job on the person's own local FILES (Part 1a): there is no worktree and no repo to read.
+ * Code-owned, one table beside STEP_LABELS; a step with no entry keeps its STEP_LABELS word.
+ * @type {Readonly<Record<string, string>>}
+ */
+export const FILE_JOB_STEP_LABELS: Readonly<Record<string, string>>;
 /**
  * The library's own `onPhase(name, ...)` calls (`src/authorjob.js`/`src/authorflow.js`) -> the step each one advances.
  * A phase with no entry leaves the current step as it was.

package/types/panel/jobplan.d.ts

@@ -1,5 +1,5 @@
 /** @typedef {{name: string, cls: 'machine check'|'judge'|null}} PlanCheck */
-/** @typedef {{n: number, text: string, rule: string, checks: PlanCheck[], refused: string[]}} PlanLine */
+/** @typedef {{n: number, text: string, rule: string, rules: string[], checks: PlanCheck[], refused: string[]}} PlanLine */
 /** @typedef {{lines: PlanLine[], loose: PlanCheck[], notChecked: string[], alwaysOn: string[], older: boolean, goal?: string}} JobPlan */
 /**
  * `machine check` for a kind a command decides, `judge` for one that needs judgement; `null` for a stage whose kind is
@@ -8,9 +8,15 @@
  * @returns {'machine check'|'judge'|null}
  */
 export function checkClassOfKind(kind: unknown): "machine check" | "judge" | null;
+/**
+ * The `~` rules of one job line, each on its own (the page draws one `~` row per rule): the line's own `rules` array when it
+ * has one (a rule may itself contain "; "), else the joined `rule` split on "; " (an older line that saved only the join).
+ * @param {any} l @returns {string[]}
+ */
+export function rulesOfLine(l: any): string[];
 /**
  * The plan of a SIGNED spec. With `jobLines`, each stage lands under EACH line its `fromLine` array names (a stage with none is
- * a mandatory guard: "Always on"), `closeDecl.refused` reasons land under their line, and `closeDecl.notes` are the
+ * a mandatory guard: "Always checked"), `closeDecl.refused` reasons land under their line, and `closeDecl.notes` are the
  * drafter's own "not checked" words. Without `jobLines` (a spec that predates the job block) the signed goal sentence is
  * line 1 and every stage name is a check under it — `older: true`.
  * @param {any} spec
@@ -19,8 +25,8 @@ export function checkClassOfKind(kind: unknown): "machine check" | "judge" | nul
 export function planFromSpec(spec: any): JobPlan;
 /**
  * The plan of the confirm turn, before anything is drafted: the person's own job lines, the model's checks under the
- * line each names, its own "not checked" words, and the real protections (code-owned) as "Always on".
- * @param {{n: number, text: string, rule: string}[]|null|undefined} jobLines
+ * line each names, its own "not checked" words, and the real protections (code-owned) as "Always checked".
+ * @param {{n: number, text: string, rule: string, rules?: string[]}[]|null|undefined} jobLines
  * @param {{checkItems?: {text: string, fromLine: number[]|null}[], checks?: string[], notChecked?: string[], protections?: string[]}} plan
  * @returns {JobPlan}
  */
@@ -28,6 +34,7 @@ export function planFromConfirm(jobLines: {
     n: number;
     text: string;
     rule: string;
+    rules?: string[];
 }[] | null | undefined, plan: {
     checkItems?: {
         text: string;
@@ -45,6 +52,7 @@ export type PlanLine = {
     n: number;
     text: string;
     rule: string;
+    rules: string[];
     checks: PlanCheck[];
     refused: string[];
 };

package/types/panel/server.d.ts

@@ -514,10 +514,11 @@ export function getStartFromImport(id: string, opts?: {
  * only `createPanelServer` below always supplies one.
  * @param {import('node:http').IncomingMessage} req
  * @param {import('node:http').ServerResponse} res
- * @param {{ home?: string, port: number, token?: string, authorRoutes?: ReturnType<typeof createAuthorRoutes>, settingsRoutes?: ReturnType<typeof createSettingsRoutes>, runRoutes?: ReturnType<typeof createRunRoutes>, importRoutes?: ReturnType<typeof createImportRoutes> }} opts
+ * @param {{ home?: string, packageJsonPath?: string, port: number, token?: string, authorRoutes?: ReturnType<typeof createAuthorRoutes>, settingsRoutes?: ReturnType<typeof createSettingsRoutes>, runRoutes?: ReturnType<typeof createRunRoutes>, importRoutes?: ReturnType<typeof createImportRoutes> }} opts
  */
 export function handleRequest(req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse, opts: {
     home?: string;
+    packageJsonPath?: string;
     port: number;
     token?: string;
     authorRoutes?: ReturnType<typeof createAuthorRoutes>;
@@ -544,7 +545,7 @@ export function handleRequest(req: import("node:http").IncomingMessage, res: imp
  * @param {{ port?: number, home?: string, env?: Record<string,string|undefined>,
  *   sessionsRoot?: string, spawnFn?: (...a: any[]) => any, bareloopBin?: string,
  *   fetchImpl?: typeof fetch, settleMs?: number, userHome?: string,
- *   openFolderSpawn?: (cmd: string, args: string[], o: object) => any, platform?: string }} [opts]
+ *   openFolderSpawn?: (cmd: string, args: string[], o: object) => any, platform?: string, packageJsonPath?: string }} [opts]
  * @returns {Promise<{ server: import('node:http').Server, port: number, token: string, close: () => Promise<void> }>}
  */
 export function createPanelServer(opts?: {
@@ -559,6 +560,7 @@ export function createPanelServer(opts?: {
     userHome?: string;
     openFolderSpawn?: (cmd: string, args: string[], o: object) => any;
     platform?: string;
+    packageJsonPath?: string;
 }): Promise<{
     server: import("node:http").Server;
     port: number;

package/types/rubricstep.d.ts

@@ -0,0 +1,286 @@
+/**
+ * The one statement of the step-file shape, in plain words. The worker's goal and the composer's prompt both carry it.
+ * @returns {string}
+ */
+export function stepFileContract(): string;
+/**
+ * What the worker is told about each line, from the close that will grade it (PART 1b item 7): a FACTS line gets its
+ * facts and its count; a TEXT line that follows a facts line is told its numbers come from that line's quotes. Written by code from
+ * the signed parts, never by a model. A line with no rubric-step stage gets nothing here.
+ * @param {any} closeDecl @returns {{line: number, text: string}[]}
+ */
+export function lineBriefs(closeDecl: any): {
+    line: number;
+    text: string;
+}[];
+/**
+ * The worker's goal for a rubric job on local files — written by code from the person's own numbered lines, never by a
+ * model. It states everything the close will judge about the FORM of the answer (the file, the keys, the quotes); what
+ * each line asks for stays in the person's own words, with its `~` rules beneath it.
+ * @param {{jobLines: {n: number, text: string, rule: string}[], files: {label: string, rel: string}[], confirmedGoal?: string|null, closeDecl?: any}} o
+ *   `confirmedGoal` — the one goal sentence the person confirmed in the confirm turn, kept as the plan line
+ *   `closeDecl` — the drafted close: with it, each line is briefed by what its stage checks (a facts line or a text line, `lineBriefs`)
+ * @returns {string}
+ */
+export function rubricGoal({ jobLines, files, confirmedGoal, closeDecl }: {
+    jobLines: {
+        n: number;
+        text: string;
+        rule: string;
+    }[];
+    files: {
+        label: string;
+        rel: string;
+    }[];
+    confirmedGoal?: string | null;
+    closeDecl?: any;
+}): string;
+/**
+ * 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.
+ * @param {unknown} p the stage's `params`
+ * @param {string} at the path prefix for reds, e.g. `stages[1].params`
+ * @returns {ShapeRed[]}
+ */
+export function rubricStepShapeReds(p: unknown, at: string): ShapeRed[];
+/** the labels of the inputs a step's `cited` parts name (each once, in order) @param {any} params @returns {string[]} */
+export function citedLabels(params: any): string[];
+/**
+ * The rubric spec for ONE step, built from its parameters and the sha256 of each input it cites (taken from the source
+ * manifest at run start — a rubric is rebuilt per run because the inputs belong to the run, not to the signed job).
+ * `happened` is bareguard's own foundational check; the `text` floor below it stops a step file whose only key is junk
+ * from passing a rubric that has no countable part.
+ * @param {{step: number, parts: any[]}} params
+ * @param {Record<string, string>} inputShas label -> sha256 hex, for every label the step cites
+ * @returns {Record<string, any>} a spec for bareguard's `createRubric`
+ */
+export function buildStepSpec(params: {
+    step: number;
+    parts: any[];
+}, inputShas: Record<string, string>): Record<string, any>;
+/**
+ * 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
+ * answer — that limit is documented, not hidden.
+ * @param {string|null} bytes the file's text, or null when it does not exist
+ * @returns {{obj: Record<string, any>, why: null}|{obj: null, why: 'missing'|'not-json'|'not-object'}}
+ */
+export function parseStepFile(bytes: string | null): {
+    obj: Record<string, any>;
+    why: null;
+} | {
+    obj: null;
+    why: "missing" | "not-json" | "not-object";
+};
+/**
+ * The step file as bareguard's rubric reads it: a flat object. `text` stays `text`; each label in `cites` becomes the field
+ * `cites:<label>` (the name a `cited` check reads its claims from). Nothing else in the file is read.
+ * @param {Record<string, any>} obj
+ * @param {string[]} [countLabels] labels whose claim COUNT a minClaims/maxClaims part reads
+ * @param {any} [factPart] the step's `fact` part: its `results` become claims (text built by code) under `cites:<source>`
+ * @returns {Record<string, any>}
+ */
+export function flattenStep(obj: Record<string, any>, countLabels?: string[], factPart?: any): Record<string, any>;
+/**
+ * One bareguard gap as a sentence the worker can act on. The numbers and names are bareguard's own measurements and the
+ * person's signed limits, never anything this module infers; a gap this table does not know falls back to bareguard's own
+ * rendering, so nothing is ever dropped.
+ * @param {number} step @param {string} why why there was no object, when there was none
+ * @param {any} g a bareguard gap
+ * @param {any} [params] the stage's parameters (a fact step words its gaps by fact)
+ * @returns {string}
+ */
+export function plainStepGap(step: number, why: string, g: any, params?: any): string;
+/**
+ * Grade ONE step: build the rubric, run it over the step file's fields, and say what happened in the close's own terms.
+ * Pure of the filesystem (the runner in src/kinds.js reads the files). `stopped` = the instrument failed (never a red).
+ * @param {{params: {step: number, parts: any[]}, bytes: string|null, outputBytes: string|null, inputs: Record<string, string>,
+ *   factQuotes?: Record<number, string[]>, factMissing?: number[]}} o
+ *   `factQuotes` maps an earlier fact line's number to the quotes its (already checked) step file holds — what a prose step's numbers are tied to
+ *   `factMissing` lists the earlier fact lines whose step file is not there (yet): a normal red, never an instrument fault
+ *   `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>}>}
+ */
+export function gradeStep({ params, bytes, outputBytes, inputs, factQuotes, factMissing }: {
+    params: {
+        step: number;
+        parts: any[];
+    };
+    bytes: string | null;
+    outputBytes: string | null;
+    inputs: Record<string, string>;
+    factQuotes?: Record<number, string[]>;
+    factMissing?: number[];
+}, inputShas: Record<string, string>): Promise<{
+    verdict: "green" | "red" | "stopped";
+    gapLines: string[];
+    fault: string | null;
+    detail: Record<string, any>;
+}>;
+/**
+ * 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).
+ * @param {unknown} inputs @returns {string[]|null}
+ */
+export function inputLabelsOf(inputs: unknown): string[] | null;
+/**
+ * R11 — the drafting-time rules for the `rubric-step` stages of a declaration, each a red in the person's plain words that
+ * names the job line and ends "Nothing spent." where nothing was. Pure; never throws. Judged parts are RED in this build
+ * (the judge arrives in the next one): the sorting is still asked for, so a part that needs the judge is named as such
+ * instead of being approximated by a count.
+ *   - a stage serves exactly the one job line it names (`step` = its only `fromLine`), and no line has two stages;
+ *   - a part with no class (`none`) cannot be counted or checked against a quote;
+ *   - a `judged` part needs the judge; a `guard` part is about web sources and the job has no web input;
+ *   - two countable parts of ONE line that no text can satisfy together (a minimum above a maximum) are a contradiction,
+ *     naming both parts and both numbers;
+ *   - a `cited` part names a label the person's inputs do not have.
+ * @param {any[]} stages the declaration's stages
+ * @param {{inputLabels?: string[]|null, red: (code: string, path: string, detail: string, extra?: object) => void}} o
+ *   `inputLabels` absent = the label rule is not run (a caller with no inputs in hand)
+ */
+export function checkRubricParts(stages: any[], { inputLabels, red }: {
+    inputLabels?: string[] | null;
+    red: (code: string, path: string, detail: string, extra?: object) => void;
+}): void;
+/** the ~ rules of one job line, one string each (`rules` when the line has the array, else the joined `rule` split on "; ") @param {any} l @returns {string[]} */
+export function lineRules(l: any): string[];
+/**
+ * PART 1b, RF16 + RF17 — the rules that need the person's own job lines. Only a close built for REQUIRED FACTS is held to them (a
+ * close with a fact part, or any part that says which `~` rules it carries out): an older Part 1a close is left as it was signed.
+ *   - every `~` rule of every job line is carried out by a part (its number in the part's `rules`), or is listed in `refused` with
+ *     its `rule` number, or its whole line is refused: a rule that is none of those was silently dropped, and that is a red;
+ *   - a number the AI made out of the person's words (a bound the person did not write) must be marked `aiProposal`, and a time
+ *     limit the AI proposes must be a range (`between`), never one-sided — "not a red-eye" must not let a 10 PM flight through.
+ * @param {any[]} stages @param {{jobLines?: any[]|null, refused?: any, red: (code: string, path: string, detail: string, extra?: object) => void}} o
+ */
+export function checkRubricRules(stages: any[], { jobLines, refused, red }: {
+    jobLines?: any[] | null;
+    refused?: any;
+    red: (code: string, path: string, detail: string, extra?: object) => void;
+}): void;
+/**
+ * PART 1c L3 - the person's own words win over the AI's reading of them, settled by CODE before anything is validated or signed:
+ *   - a limit on a fact whose bounds are all in the words the person wrote (the line, its `~` rules, an answer they gave) is the
+ *     person's, so it is NOT marked "AI's proposal" (smv710w8c3wdh: the plan called the person's own range the AI's);
+ *   - a time range the AI proposed while the person wrote ONE explicit positive time range ("between 07:00 and 23:00") on that line
+ *     is replaced by exactly that range (smv710w8c3wdh: the plan said 5:00 AM). Only when it is unambiguous: one such range in the
+ *     line's rules and one AI-proposed `between` time fact on the line; a rule with a negation ("not between ...") is never read as a range;
+ *   - a `~` rule is a check or under Not checked, never both: a `refused` entry for a rule that a part of its own line carries is dropped.
+ * Pure; returns a new declaration, the input untouched. The model is told the same in the brief; this makes it true either way.
+ * @param {any} declaration @param {any[]|null|undefined} jobLines @returns {any}
+ */
+export function settlePersonsWords(declaration: any, jobLines: any[] | null | undefined): any;
+/**
+ * PART 1b — put the number tie on every prose step. A rubric-step stage with no fact part that comes AFTER one or more fact
+ * stages gets exactly one `numbersFromFacts` part naming those lines; one the model wrote is replaced. Pure; returns a new
+ * declaration (the input is untouched). The model never writes this part: it is code's, so a draft cannot omit it.
+ * @param {any} declaration @returns {any}
+ */
+export function withFactBindings(declaration: any): 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).
+ * @param {any} closeDecl @param {any[]|null|undefined} jobLines @returns {string[]}
+ */
+export function ruleNotChecked(closeDecl: any, jobLines: any[] | null | undefined): string[];
+/**
+ * The Not-checked lines code owns for the rubric-step stages of a close: a prose step's CONTENT is judged by the person at
+ * Accept, and the card says so (PART 1b, RF5). One line per prose step (a stage with no fact part).
+ * @param {any} closeDecl @returns {string[]}
+ */
+export function proseNotChecked(closeDecl: any): 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.
+ * @param {any} part @returns {string}
+ */
+export function partSentence(part: any): string;
+/**
+ * The checks a signed close actually runs, per job line, in plain code-written sentences: one per countable part of every
+ * rubric-step stage. This is the ONE reader both the plan card and the sign-time invariant use.
+ * @param {any} closeDecl
+ * @returns {{line: number, text: string, covers: number[]}[]}
+ */
+export function checksOfClose(closeDecl: any): {
+    line: number;
+    text: string;
+    covers: number[];
+}[];
+/**
+ * Reconcile the CONFIRMED plan with the close the composer actually wrote. The plan card after drafting shows exactly
+ * the close's own checks (`checksOfClose`); every confirmed check that no part carries out (no part lists its number in
+ * `covers`) is moved to Not checked, in the person's words, with the reason. A check can therefore never be shown and then
+ * silently dropped (run mv5bk400: "lists 3 releases" was confirmed, then left out of the signed close without a word).
+ * @param {{confirmed: {text: string, fromLine: number[]|null}[], notChecked: string[], closeDecl: any, jobLines?: any[]|null}} o
+ *   `jobLines` — the person's numbered lines, so a ~ rule the drafter listed as Not checked reads in the person's own words
+ * @returns {{checkItems: {text: string, fromLine: number[]}[], notChecked: string[], moved: {text: string, fromLine: number[]|null}[]}}
+ */
+export function reconcileRubricPlan({ confirmed, notChecked, closeDecl, jobLines }: {
+    confirmed: {
+        text: string;
+        fromLine: number[] | null;
+    }[];
+    notChecked: string[];
+    closeDecl: any;
+    jobLines?: any[] | null;
+}): {
+    checkItems: {
+        text: string;
+        fromLine: number[];
+    }[];
+    notChecked: string[];
+    moved: {
+        text: string;
+        fromLine: number[] | null;
+    }[];
+};
+/**
+ * The sign-time invariant: the checks the person was shown (`shown`, from the plan card) are exactly the checks the signed
+ * close runs (`checksOfClose`), per line. Pure.
+ * @param {{text: string, fromLine: number[]|null}[]} shown @param {any} closeDecl
+ * @returns {{ok: true}|{ok: false, error: string}}
+ */
+export function planMatchesClose(shown: {
+    text: string;
+    fromLine: number[] | null;
+}[], closeDecl: any): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The frozen TEXT of the named inputs, read the way the runner reads them: the source door's record (`source.json`, one level
+ * above the tree) names each input's file and sha256, and a file whose bytes no longer match is not returned. Used at DRAFTING
+ * (the drafter reads the input, the early tests run on it) and at run start (the backstop). Never throws.
+ * @param {string} workdir the frozen tree @param {string[]} labels
+ * @returns {Promise<{ok: true, texts: Record<string, string>}|{ok: false, why: string}>}
+ */
+export function readFrozenInputs(workdir: string, labels: string[]): Promise<{
+    ok: true;
+    texts: Record<string, string>;
+} | {
+    ok: false;
+    why: string;
+}>;
+/** where the per-line step files live, inside the job's tree; `copyOut` delivers them with the rest of `output/` */
+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;
+/** 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[];
+/**
+ * The counted/quoted checks a `countable` part may name, with the fields each needs — read off bareguard's own rule table
+ * (`rubricVocabulary`): the names are bareguard's, so a check this build cannot run is inexpressible, not rejected late.
+ * (`max`/`min` need a numeric field the step file does not have, so they are not offered.)
+ * @type {Readonly<Record<string, readonly string[]>>}
+ */
+export const COUNT_CHECKS: Readonly<Record<string, readonly string[]>>;
+export function sha256Of(b: string | Buffer): string;
+export type ShapeRed = {
+    code: string;
+    path: string;
+    detail: string;
+};

package/types/source.d.ts

@@ -330,6 +330,100 @@ export function proveInputFiles(inputs: {
     ok: false;
     error: string;
 }>;
+/**
+ * Does this source manifest belong to a rubric job on local files (`proveRubricInputs` wrote it)? One spelling for both
+ * doors (the panel session and the CLI author run): a non-repo source that froze numbered, labelled input files.
+ * @param {Record<string, any>|null|undefined} manifest
+ * @returns {boolean}
+ */
+export function isRubricFilesManifest(manifest: Record<string, any> | null | undefined): boolean;
+/**
+ * PART 1a (docs/product/ITEM33-BUILD.md, "Addendum 2026-10-12"): the front door for a RUBRIC job whose inputs are the
+ * person's own LOCAL FILES, not a repo. Each numbered `label: /absolute/file` line is proven at $0 and frozen into the
+ * same hidden-git tree a plain folder gets (`prepareSource`, which also refuses a secret shape, an environment file
+ * and a symlink), under `input/`; the manifest then also records `inputs: [{label, rel, sha256}]` — the bytes the
+ * rubric's `cited` check will search a quote in, hashed once, here. A line that is a web address is fetched ONCE with
+ * barebrowse (PART 1c, read only) and its text frozen under `input/` like a file (the manifest row also records its `url`,
+ * so run start can fetch it again); a `search:` line is a named refusal (a later build); so is a relative path, a missing file, a folder, a file over
+ * {@link RUBRIC_INPUT_MAX_BYTES}, and text that is not valid UTF-8. Every refusal is plain words naming the line and
+ * ends "Nothing spent." — nothing here touches a model.
+ * @param {{inputs: {n: number, label: string, value: string}[], into: string, destination?: string, fetchUrl?: (url: string) => Promise<{ok: true, text: string, url: string}|{ok: false, error: string}>}} o `fetchUrl` - how a web address is read (default barebrowse via `fetchPageText`; a test injects a stub, never the network)
+ * @returns {Promise<{ok: true, prep: {stop: null, into: string, tree: string, manifestPath: string, manifest: Record<string, any>}}|{ok: false, error: string, code: string}>}
+ */
+export function proveRubricInputs({ inputs, into, destination, fetchUrl }: {
+    inputs: {
+        n: number;
+        label: string;
+        value: string;
+    }[];
+    into: string;
+    destination?: string;
+    fetchUrl?: (url: string) => Promise<{
+        ok: true;
+        text: string;
+        url: string;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+}): Promise<{
+    ok: true;
+    prep: {
+        stop: null;
+        into: string;
+        tree: string;
+        manifestPath: string;
+        manifest: Record<string, any>;
+    };
+} | {
+    ok: false;
+    error: string;
+    code: string;
+}>;
+/**
+ * Is this Inputs value a path to an existing regular FILE on this machine (not a repo folder, not a web address, not a
+ * missing path)? The $0 peek that tells a rubric job on local files from a rubric job on a repo before a session exists;
+ * `proveRubricInputs` makes the authoritative, line-by-line proof.
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function looksLikeLocalFile(value: string): boolean;
+/**
+ * Is this Inputs value one a rubric job can work on without a repo: a regular FILE on this machine, or a web address (PART 1c)?
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function looksLikeRubricInput(value: string): boolean;
+/**
+ * RUN START for a rubric job with web inputs (PART 1c, RF22): fetch every web input AGAIN and make that text the run's frozen input
+ * BEFORE the worker starts. The drafting copy was only for the look (prices change); the close grades, and the worker reads, THIS
+ * copy. It is written into the prepared tree, committed as the new seed (so the page is never read as a worker write), and
+ * `source.json` is rewritten (new sha256 per input, new seed, `draftSha256` keeps what the look saw). Nothing but the text of a
+ * recorded web address is ever refetched; a job with only file inputs returns at once and changes nothing.
+ * @param {{into: string, fetchUrl?: (url: string) => Promise<{ok: true, text: string, url: string}|{ok: false, error: string}>}} o `into` - the prepared copy (source.json + tree/)
+ * @returns {Promise<{ok: true, refreshed: string[], seed: string|null}|{ok: false, error: string}>}
+ */
+export function refreezeUrlInputs({ into, fetchUrl }: {
+    into: string;
+    fetchUrl?: (url: string) => Promise<{
+        ok: true;
+        text: string;
+        url: string;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+}): Promise<{
+    ok: true;
+    refreshed: string[];
+    seed: string | null;
+} | {
+    ok: false;
+    error: string;
+}>;
+/** 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;
 /**
  * a named, non-throwing stop
  */

package/types/userrun.d.ts

@@ -61,6 +61,17 @@ export type Deps = {
      */
     provider?: any;
     providerFor?: ((tier: string) => any) | undefined;
+    /**
+     * PART 1c - a test seam: how a web input is read at run start (production: barebrowse)
+     */
+    fetchUrl?: ((url: string) => Promise<{
+        ok: true;
+        text: string;
+        url: string;
+    } | {
+        ok: false;
+        error: string;
+    }>) | undefined;
     judgeProvider?: any;
     /**
      * F196 — a test seam for `appendRun`'s