bareloop 0.8.0 → 0.9.0

package/types/authoring.d.ts

@@ -0,0 +1,447 @@
+/**
+ * THE CEILING (hamr, 2026-08-08, *"yes to both, go"*): the picked class is a
+ * PROMISE, and this is what the composition actually demands.
+ *
+ * Every kind carries the class of verdict it can honestly render, so a
+ * declaration's ceiling is the HIGHEST class any of its stages needs. A pick
+ * below that ceiling is a silent UPGRADE — a judgment ruler running under a
+ * green promise, which is exactly the fake-hard verdict `CLASS_BY_CLOSE` and
+ * `CLASS_BY_VERDICT` exist to stop, defeated from ABOVE by never letting the
+ * illegal pair be formed.
+ *
+ * INERT IN v1 BY CONSTRUCTION, which is why it is cheap now: every LIVE kind is
+ * mechanical, so no declaration a v1 catalogue can express reaches above green.
+ * It is written before the second class exists so the first soft-green kind is
+ * not the thing that discovers the question.
+ *
+ * A kind the catalogue does not know contributes NOTHING — it already carries an
+ * `unknown-kind` red, and guessing a class for it would be deriving the promise
+ * from a typo. A catalogue entry with no class at all THROWS: the catalogue is
+ * OURS, and failing loudly beats weighing a kind whose honesty nobody stated.
+ * @param {any} declaration
+ * @param {Record<string, KindSpec>} [catalogue]
+ * @returns {{class: string, kind: string, stage: string|null, locked: boolean}|null}
+ */
+export function closeCeiling(declaration: any, catalogue?: Record<string, KindSpec>): {
+    class: string;
+    kind: string;
+    stage: string | null;
+    locked: boolean;
+} | null;
+/**
+ * Which kinds can carry an environment at all, read off the CATALOGUE rather
+ * than a hand-kept list. ONE spelling, because two consumers must agree
+ * EXACTLY: `applyGenreEnv` injects the genre's variable into these stages and
+ * nowhere else, and the validator's completeness rule demands it on these
+ * stages and nowhere else. A second copy that drifted either way is a hole —
+ * stages injected but unchecked, or stages checked for what nothing injects.
+ * @param {string} kind @param {Record<string, KindSpec>} [catalogue]
+ */
+export function envCapableKind(kind: string, catalogue?: Record<string, KindSpec>): boolean;
+/**
+ * The floor's decision for one declared `cmd`, as a reason or null.
+ *
+ * NORMALISATION FIRST, because that is where the dodge lives: `/usr/bin/rm`
+ * carries the same program as `rm` and only a basename read taken AFTER
+ * splitting the path can see it. Case is folded for the same reason.
+ *
+ * A cmd naming a program OUTSIDE the repository — an absolute path, or one that
+ * climbs out with `..` — is refused whatever its basename says. Two reasons, and
+ * both are the fail-safe direction: the validator has no repository in hand at
+ * every call site (the job validator judges a signed spec with no tree), so
+ * "outside" cannot be decided per-machine; and a machine-absolute path inside a
+ * SIGNED artefact grades a different machine than the one it was signed on.
+ * @param {string} cmd @returns {string|null}
+ */
+export function deniedCommandReason(cmd: string): string | null;
+/**
+ * The picked class's mandatory guards, FULLY ENUMERATED (D13 forward-compat
+ * point 3: an omittable-with-a-default field is the omitted-`tools` shape, where
+ * widening changes what runs without changing what was signed — so the guards
+ * are stored spelled out, and the hash is taken over the resolved form).
+ *
+ * `fill` names the ONLY slot the model supplies. `changed-from-seed`'s
+ * allowPrefixes is the job's own target scope and cannot be ours; everything
+ * else — including `no-suppressions`' absent scope — is.
+ *
+ * AN EMPTY BATTERY IS IMPOSSIBLE for a known class and a known language, and
+ * that is enforced rather than asserted: an unknown class, a locked class, an
+ * unknown language, a battery that resolved to nothing, and a composed param
+ * that resolved to nothing all THROW. F59's shape at the load-bearing decision
+ * of the design — a suppression scan with no patterns reads clean exactly like
+ * one that scanned correctly, and it lands in a SIGNED artefact.
+ *
+ * Returns a fresh deep copy each call: a frozen constant handed to a caller that
+ * edits it is one shared battery away from a silently weakened guard.
+ * @param {{verdictType: string, lang: string}} o
+ * @returns {{name: string, kind: string, params: Record<string, any>, compose: string[], fill: string[]}[]}
+ */
+export function classGuards({ verdictType, lang }: {
+    verdictType: string;
+    lang: string;
+}): {
+    name: string;
+    kind: string;
+    params: Record<string, any>;
+    compose: string[];
+    fill: string[];
+}[];
+/**
+ * The genre's environment for this patient — ours to inject at execution (M3),
+ * never model-authored. An entry with no value produces NO VARIABLE: an empty
+ * `MYPYPATH` is not the same instruction as an unset one, and shipping `''`
+ * would silently change how mypy resolves.
+ * @param {string} lang
+ * @param {{sourcePrefixes?: string[]}} [o]
+ * @returns {Record<string, string>}
+ */
+export function genreEnv(lang: string, { sourcePrefixes }?: {
+    sourcePrefixes?: string[];
+}): Record<string, string>;
+/** The names the genre OWNS — the validator refuses a declaration that authors
+ * one of them, because ownership is only real if it is mechanical.
+ * @param {string} lang @returns {string[]} */
+export function genreOwnedEnvNames(lang: string): string[];
+/**
+ * GROUNDING for a RECORDED genre environment — the provenance half of the
+ * owned-env rule, and the reason the by-value comparison is worth anything.
+ *
+ * The value check proves the envelope's `genreEnv` and the stage's `params.env`
+ * AGREE. Both copies live in the same hand-editable spec, so agreement is
+ * something a forger gets for free: a spec carrying
+ * `MYPYPATH=/tmp/attacker-stubs` in both places is perfectly self-consistent and
+ * would point the checker at a tree nobody signed. Agreement is not provenance.
+ *
+ * What a forger does NOT own is the repository at the seed. Every value the
+ * arbiter can build is `genreEnv`'s join of `sourcePrefixes`, and those prefixes
+ * were already filtered against the seed listing before the join — so each
+ * ELEMENT of a genuine value is a path the listing SELECTS, exactly like hamr's
+ * listing rule for a declared path. Grounding therefore accepts precisely what
+ * `applyGenreEnv` produces and refuses everything else, without needing a second
+ * spelling of what "ours" means.
+ *
+ * Element-wise, never whole-value: a joined list is as strong as its weakest
+ * element, and one real prefix must not launder the rest. A root spelling is
+ * ungrounded here rather than waved through the way `checkPaths` waves it —
+ * `genreEnv` filters those out before joining, so the arbiter can never produce
+ * one, and a validator that admits what its own producer cannot emit is a gap.
+ *
+ * Callers that hold a listing only; the deferred job-spec gate cannot run this
+ * and does not pretend to (see `validateCloseDecl`).
+ * @param {string} lang
+ * @param {Record<string, string>} recorded what the envelope claims the arbiter injected
+ * @param {string[]} listing repo-relative paths at the seed
+ * @returns {{name: string, value: string, element: string, resolved: string}[]} one row per ungrounded element
+ */
+export function ungroundedGenreEnv(lang: string, recorded: Record<string, string>, listing: string[]): {
+    name: string;
+    value: string;
+    element: string;
+    resolved: string;
+}[];
+/**
+ * Validate an authored close DECLARATION. Never throws on model output — every
+ * failure is a named red, in the shipped `{ok, reds, <parsed>}` shape, and the
+ * parsed value is the RESOLVED declaration (every short-form parser expanded),
+ * because that is the form the executor runs and the signature covers.
+ *
+ * `listing`, `guards` and `envOwned` are REQUIRED, and their absence is a red
+ * rather than a skipped check — all three guard the SAME failure: a validator
+ * that silently stops checking when handed nothing to check against reports a
+ * clean declaration it never examined. v1 only admits a job with a runnable
+ * patient and a git seed (D13), so the listing always exists, and D5's guards
+ * exist by construction. `envOwned` is separated into absent-vs-empty for
+ * F59's reason exactly: `[]` is a genre that owns no variables (JS), and
+ * `undefined` is a caller that never asked — the two must not read alike.
+ *
+ * The CATALOGUE is ours, not model input: a malformed one is a bareloop bug and
+ * is allowed to throw, because failing loudly beats a validator that quietly
+ * stops enforcing a rule it was configured out of.
+ *
+ * `deferListing: true` is the ONE way to run without a listing, and it must be
+ * spelled literally. It exists for exactly one caller — the job-spec validator,
+ * which judges a signed `closeDecl` with no repository in hand — and it does NOT
+ * make the listing optional: it moves that half of the gate to the runner, which
+ * re-validates GROUNDED against the real seed before any stage runs. Two checks
+ * ride on the listing and both are named here rather than discovered later: the
+ * path rule (a path SELECTS or it does not exist), and the SCOPED-job derivation
+ * that arms the F84 one-population law. With the listing deferred, neither
+ * fires, and `grounded: false` on the result is how a caller knows.
+ *
+ * `verdictType` is REQUIRED for the same reason: it is the PROMISE the ceiling
+ * rule checks the composition against, and a validator with no pick in hand
+ * cannot check it. Absent or unknown is `class-absent`, naming the closed set.
+ *
+ * @param {any} declaration the parsed model output
+ * @param {{catalogue?: Record<string, KindSpec>, listing?: string[]|null,
+ *   guards?: {name: string, kind: string, params: Record<string, any>, fill: string[]}[]|null,
+ *   envOwned?: string[]|null, envInjected?: Record<string, string>|null, deferListing?: boolean,
+ *   verdictType?: string|null}} [opts]
+ *   `listing` — repo-relative paths at the seed (`git ls-tree -r --name-only`).
+ *   `guards` — the picked class's injected guards (`classGuards`).
+ *   `verdictType` — the class the USER picked (`VERDICT_CLASSES`).
+ *   `envOwned` — env names the genre injects (`genreOwnedEnvNames`), `[]` when it owns none.
+ *   `envInjected` — the env the ARBITER itself injected (`genreEnv`'s output), for a
+ *     POST-injection re-validation. Omitted is the PRE-injection form: every owned name
+ *     is the model's and reds. Supplied, an owned name is accepted only when its value is
+ *     EXACTLY the injected one — a wrong value is the model's guess or corruption.
+ *   `deferListing` — literally `true` to run the tree-independent half only.
+ * @returns {{ok: boolean, reds: Red[], declaration: any, grounded: boolean,
+ *   scoped: {scoped: boolean, via: string|null},
+ *   ceiling: {class: string, kind: string, stage: string|null, locked: boolean}|null}}
+ */
+export function validateDeclaration(declaration: any, opts?: {
+    catalogue?: Record<string, KindSpec>;
+    listing?: string[] | null;
+    guards?: {
+        name: string;
+        kind: string;
+        params: Record<string, any>;
+        fill: string[];
+    }[] | null;
+    envOwned?: string[] | null;
+    envInjected?: Record<string, string> | null;
+    deferListing?: boolean;
+    verdictType?: string | null;
+}): {
+    ok: boolean;
+    reds: Red[];
+    declaration: any;
+    grounded: boolean;
+    scoped: {
+        scoped: boolean;
+        via: string | null;
+    };
+    ceiling: {
+        class: string;
+        kind: string;
+        stage: string | null;
+        locked: boolean;
+    } | null;
+};
+/**
+ * The declaration the EXECUTOR sees and the SIGNATURE covers: every
+ * `count-not-worse` parser resolved to `{terms: [...]}`, so the short form stops
+ * existing at this boundary and there is exactly one shape downstream (D13
+ * forward-compat point 3 — the hash is taken over the RESOLVED form, or an
+ * omittable-with-a-default field changes what runs without changing what was
+ * signed).
+ *
+ * A parser that would not normalise is left VERBATIM: it already carries a red,
+ * and rewriting it would hide what the model actually wrote.
+ * @param {any} declaration
+ */
+export function normalizeDeclaration(declaration: any): any;
+/** @typedef {{code: string, path: string, detail: string, [k: string]: any}} Red */
+/** @typedef {{required: readonly string[], optional: readonly string[], pathParams: readonly string[], locked?: true, verdictClass: string, shape: string, asserts: string}} KindSpec */
+/** the whole menu, in ascending order of what it takes to render the verdict */
+export const VERDICT_CLASSES: readonly string[];
+/** declared-but-locked: selecting one is COUNTED demand, never an admission */
+export const LOCKED_CLASSES: readonly string[];
+/** the classes v1 actually builds — exactly one */
+export const LIVE_CLASSES: readonly string[];
+/**
+ * The whole vocabulary, as DATA. `shape` and `asserts` are the strings the
+ * authoring prompt renders (M3) — the prompt and this validator must judge the
+ * same facts, so they read one catalogue rather than two (the drift class
+ * SECRET_PATTERNS exists to prevent, one layer up).
+ *
+ * `pathParams` names every param that carries a repository path, in dotted
+ * form. It is data rather than a switch so hamr's listing rule reaches a new
+ * path-bearing param the day one is added, instead of the day someone
+ * remembers to widen a condition.
+ *
+ * `verdictClass` is the class of verdict this kind can HONESTLY render, and it
+ * is what makes the user's pick a promise the composer must keep (PRD v1.57 §1).
+ * Every live kind is `green` — a command's measurement is the truth — so the
+ * ceiling rule is inert in v1 by construction; the two locked kinds carry the
+ * classes they belong to so the rule is already correct the day one goes live.
+ *
+ * Optionality is read off the prereg §5 table, with ONE deliberate divergence
+ * from the gate-2 POC validator, named because it reverses a POC behaviour:
+ * `pattern-absent-in-diff.scope` is OPTIONAL here and the guard ships without
+ * it. Under addendum 6 the guard's scope is GENRE property and the answer is
+ * "every changed file of these extensions" — an absent scope is exactly that
+ * (M1's `inScope` admits everything when no scope object is present). The POC
+ * required it, and required it filled, which is how round 3's arm A came to
+ * narrow the scan and call it stricter.
+ * @type {Record<string, KindSpec>}
+ */
+export const KIND_CATALOGUE: Record<string, KindSpec>;
+export const CATALOGUE_KINDS: readonly string[];
+export const LOCKED_KINDS: readonly string[];
+/** the catalogue's live half — asserted EQUAL to the executor's own LIVE_KINDS
+ * by the suite, both directions: a kind the catalogue offers and the executor
+ * cannot run is a close that stops at runtime, and a kind the executor runs
+ * that the catalogue never names is a capability nothing can reach. */
+export const CATALOGUE_LIVE_KINDS: readonly string[];
+export const DIRECTIONS: readonly string[];
+/** D12: the close stores the COUNTING RULE, never the number. "seed" is measured
+ * at this run's own seed every run; 0 is literally zero. A frozen constant (the
+ * hand-written closes' `SEED_ERRORS 63`) is exactly what this menu retires. */
+export const BASELINES: readonly (string | number)[];
+/** a runaway stage list is a red, not a bill — the sibling of M1's MAX_TERMS */
+export const MAX_STAGES: 12;
+/**
+ * THE DENY FLOOR under a declared command (hamr's ruling, PRD v1.57 §3: *"there
+ * should be a floor of all dangerous things… straight out block… no one wants
+ * `rm -rf` allowed either ways"*).
+ *
+ * Four families, and each one is here for a different reason:
+ *   - SHELL INTERPRETERS. A shell runs anything, so admitting one makes every
+ *     other entry decoration — the D3 line ("the danger is in the ACTIONS, not
+ *     the SYNTAX") reappearing at the close's own spawn.
+ *   - DESTRUCTIVE / SYSTEM commands. The `rm -rf` class the ruling names, plus
+ *     the machine-level siblings (`dd`, the `mkfs` FAMILY, shutdown/reboot) and
+ *     privilege escalation.
+ *   - FETCH-AND-RUN vectors (`curl`, `wget`). A close that downloads its own
+ *     instrument is a close nobody signed.
+ *   - INDIRECTION (`env`, `eval`, `exec`, `xargs`). They run a program the
+ *     declaration never names, which defeats every entry above by construction.
+ *
+ * It is a FLOOR, and MONOTONIC: names are only ever ADDED, never removed or
+ * narrowed (the F49 precedent — closing a false negative is the allowed
+ * direction; chasing a false positive is not). A legitimate runner refused here
+ * is fixed by declaring the runner, never by shrinking the floor.
+ *
+ * It is NOT A SANDBOX, and nothing here claims to be one. The local-trust model
+ * of v1.41 stands intact and its limitations are written out in PRD v1.57 §3:
+ * close children keep the operator's OS user, network egress and file access;
+ * `args` are not inspected (`node -e <anything>` is reachable and always was);
+ * resource use is bounded by liveness checks, not quotas. The floor narrows
+ * blast radius; it does not promise containment.
+ */
+export const DENIED_COMMANDS: readonly string[];
+/**
+ * THE FROZEN TYPES GENRE TEMPLATE — prereg addendum 3's six policy points,
+ * VERBATIM. The suite reads the prereg and compares BYTES, so a paraphrase here
+ * fails the build rather than quietly changing what every future close is
+ * authored against. It deliberately carries no repo-specific command, path, env
+ * value or regex: round 2 measured that stating the LAW still leaves the model
+ * to find the VALUE, and that is the axis the build must keep live.
+ */
+export const TYPES_GENRE_TEMPLATE: "1. The graded instrument is the STRICT form of the language's type checker, regardless of what\n   the repo's own scripts run. If the repo's script omits strictness, the close adds it.\n2. Tools are invoked so their binaries actually resolve \u2014 through the project's own package\n   runner or language module runner, never a bare binary name.\n3. The stage skeleton, in first-red-wins order: changed-from-seed (guard) \u2192 typecheck (error\n   count IN the target scope, baseline 0, lower-is-better) \u2192 typecheck-outside (error count\n   OUTSIDE the target scope, baseline measured at seed, a ceiling \u2014 required whenever the job\n   scopes to a subset of the tree; omitted only for whole-tree jobs) \u2192 tests-kept (a floor on\n   tests that actually EXECUTED, baseline at seed, higher-is-better; a skipped or deselected\n   test did not run and must not count) \u2192 suite-green (the suite exits clean AND reports zero\n   failing tests \u2014 two assertions) \u2192 no-suppressions (guard).\n4. One population per stage \u2014 two structurally different counts never share a stage.\n5. The checker must judge the PATIENT's own tree: if imports could resolve to an installed or\n   editable copy elsewhere, the environment is set so they resolve inside the patient.\n6. A number the tool did not report is unknown, never zero.";
+export const GENRE_LANGUAGES: readonly string[];
+/**
+ * THE GENRE, as data. The suppression batteries are the hand-written closes'
+ * own `SUPPRESSIONS` tables (`scripts/u-pulselog-close.mjs:35`,
+ * `scripts/u-spawner-close.mjs:34`) — operator-owned genre knowledge, minted by
+ * paying for live runs. `unknown` is deliberately NOT a JS suppression and not
+ * a Python one: it forces narrowing at the use site, which is real typing work.
+ *
+ * `env` is the addendum-6 residue expressed as data. Python's `MYPYPATH` is
+ * load-bearing and was found by probe, never by reading: the aurora patient sets
+ * `explicit_package_bases`, so without it a sibling import falls through to an
+ * editable install pointing at a DIFFERENT checkout and a cross-module fix is
+ * graded against unedited source. It moves no seed number, which is why no
+ * seed-verdict read can ever catch its absence — the only place it can live is
+ * here, in genre data, injected by the flow.
+ */
+export const TYPES_GENRE: Readonly<{
+    name: "TYPES";
+    template: "1. The graded instrument is the STRICT form of the language's type checker, regardless of what\n   the repo's own scripts run. If the repo's script omits strictness, the close adds it.\n2. Tools are invoked so their binaries actually resolve — through the project's own package\n   runner or language module runner, never a bare binary name.\n3. The stage skeleton, in first-red-wins order: changed-from-seed (guard) → typecheck (error\n   count IN the target scope, baseline 0, lower-is-better) → typecheck-outside (error count\n   OUTSIDE the target scope, baseline measured at seed, a ceiling — required whenever the job\n   scopes to a subset of the tree; omitted only for whole-tree jobs) → tests-kept (a floor on\n   tests that actually EXECUTED, baseline at seed, higher-is-better; a skipped or deselected\n   test did not run and must not count) → suite-green (the suite exits clean AND reports zero\n   failing tests — two assertions) → no-suppressions (guard).\n4. One population per stage — two structurally different counts never share a stage.\n5. The checker must judge the PATIENT's own tree: if imports could resolve to an installed or\n   editable copy elsewhere, the environment is set so they resolve inside the patient.\n6. A number the tool did not report is unknown, never zero.";
+    languages: Readonly<{
+        js: Readonly<{
+            suppressions: readonly (Readonly<{
+                id: "ts-ignore";
+                regex: "@ts-ignore";
+            }> | Readonly<{
+                id: "ts-expect-error";
+                regex: "@ts-expect-error";
+            }> | Readonly<{
+                id: "ts-nocheck";
+                regex: "@ts-nocheck";
+            }> | Readonly<{
+                id: "eslint-disable";
+                regex: "eslint-disable";
+            }> | Readonly<{
+                id: "any";
+                regex: "(?:[{<|(\\[:,]|\\bas)\\s*any\\b|\\bany\\[\\]";
+            }> | Readonly<{
+                id: "any-star";
+                regex: "@\\w+\\s*\\{\\s*[*?]\\s*\\}";
+            }> | Readonly<{
+                id: "cast";
+                regex: "@type\\s*\\{.*\\}\\s*\\*\\/\\s*\\(";
+            }>)[];
+            extensions: readonly string[];
+            /** no import-resolution hazard on this runner — an EMPTY list, declared,
+             * never an absent field that would read as "not looked into" (F59) */
+            env: readonly never[];
+        }>;
+        python: Readonly<{
+            suppressions: readonly (Readonly<{
+                id: "ignore";
+                regex: "#\\s*type:\\s*ignore";
+            }> | Readonly<{
+                id: "any";
+                regex: "\\bAny\\b";
+            }> | Readonly<{
+                id: "cast";
+                regex: "\\bcast\\s*\\(";
+            }> | Readonly<{
+                id: "noqa";
+                regex: "#\\s*noqa";
+            }> | Readonly<{
+                id: "mypy-disable";
+                regex: "#\\s*mypy:\\s*disable";
+            }>)[];
+            extensions: readonly string[];
+            env: readonly Readonly<{
+                name: "MYPYPATH";
+                from: "sourcePrefixes";
+                join: ":";
+                why: string;
+            }>[];
+        }>;
+    }>;
+}>;
+/**
+ * THE GUARD BATTERY, KEYED BY VERDICT CLASS (hamr's ruling, PRD v1.57 §2).
+ *
+ * D5's battery was genre-keyed data. Under class-keyed interviews it has no
+ * genre to hang from, and the ruling gives it the same home the interview took:
+ * **the battery attaches to the verdict class the user picked** — not to a
+ * problem-genre label, and not per catalogue KIND.
+ *
+ * WHY THE CLASS. What a battery is FOR is the class of dishonesty the class of
+ * VERDICT admits. A green job is a job whose *done* is claimed to be
+ * machine-checkable, so it carries the green battery whatever problem it came
+ * from — that is the anti-suppression obligation the F87 genre earned, and it
+ * must not travel with a label the interview no longer asks for.
+ *
+ * ATTACHMENT POINT vs CONTENTS, and the split is the whole implementation:
+ *   - the battery's STRUCTURE and its un-removability key off the CLASS. That
+ *     is this table: which guards exist, what they assert, which slot is the
+ *     model's (`fill`), and which params are ours.
+ *   - the battery's CONTENTS fill in at COMPOSITION (`compose`), because a
+ *     suppression pattern, a file extension and a checker's escape hatch belong
+ *     to the TOOL the declaration names, and nothing before composition knows
+ *     that tool. `classGuards` resolves them from the language data below.
+ *
+ * A LOCKED class carries `guards: null`, not `[]`. Absent is never empty (F59):
+ * `[]` would read as "this class needs no guards", which is exactly the sentence
+ * D5 exists to make unsayable. Nothing ever reaches it — admission refuses a
+ * locked class before its battery is asked for — and `classGuards` throws rather
+ * than hand back nothing if anything ever does.
+ * @type {Record<string, {locked: boolean, guards: readonly any[]|null}>}
+ */
+export const CLASS_BATTERIES: Record<string, {
+    locked: boolean;
+    guards: readonly any[] | null;
+}>;
+export type Red = {
+    code: string;
+    path: string;
+    detail: string;
+    [k: string]: any;
+};
+export type KindSpec = {
+    required: readonly string[];
+    optional: readonly string[];
+    pathParams: readonly string[];
+    locked?: true;
+    verdictClass: string;
+    shape: string;
+    asserts: string;
+};