@turri-dev/cli 0.1.6 → 0.1.7-next.9aec40e

package/dist/regenerate/panel-dock.d.ts

@@ -0,0 +1,23 @@
+/** The columns the panel takes beside the chat: half of what they share, the rule between them in the middle - 0 when that is too narrow to share. */
+export declare function dockedWidth(columns: number): number;
+/**
+ * The chat narrowed by `panelWidth()` columns, read at each frame - 0 gives it the whole width. Returns what gives it the
+ * whole width back for good.
+ */
+export declare function narrowChat(tui: object, panelWidth: () => number): () => void;
+/**
+ * A press of a mouse button, as pi's full screen takes it - `side` told whether it was in the chat, left of `chatWidth()`
+ * columns, or in the panel - before the press goes on as it would have. Motion and the wheel are not presses. pi's
+ * regular screen reads no mouse: nothing is done there. Returns what takes the watch off.
+ */
+export declare function clickToFocus(tui: object, chatWidth: () => number, side: (side: "chat" | "panel") => void): () => void;
+/**
+ * A line drawn faint - the side that does not have the keys, in the shade. Faint (SGR 2) holds through a line's colours;
+ * only a reset - SGR 0, or 22 - ends it, so it is set again after each one. A line holding an image is left as it is.
+ */
+export declare function shade(line: string): string;
+/**
+ * The chat in the shade while `shaded()`: each of its rows drawn faint as the screen lays the overlays over it - the
+ * docked panel the last of them, which covers its own columns. Returns what takes the shade off.
+ */
+export declare function shadeChat(tui: object, shaded: () => boolean): () => void;

package/dist/regenerate/paths.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The ***plain standard library: import modules for generic pieces of software that ship with turri,
+ * imported as `stdlib/backend/python-fastapi` - a reserved name (see plain/stdlib.ts).
+ */
+export declare const STDLIB_DIR: string;
+/**
+ * Where a module's generated code and tests live.
+ *
+ * Everything a module produces sits under `plain_modules/<module>/`, next to the specs it
+ * came from and inside the project's own repository: `code/` holds the implementation and
+ * its unit tests, `tests/` the black-box conformance tests - of every functionality built so
+ * far, the required modules' included, organised however suits them.
+ * The build state is written into `code/`, so what a codebase contains travels with that
+ * codebase instead of living in a scratch directory that can be cleared without anyone
+ * noticing the specs and the code have drifted apart.
+ */
+export declare const MODULES_DIR = "plain_modules";
+export declare function moduleDir(moduleName: string, cwd?: string): string;
+/** Implementation and unit tests: `plain_modules/<module>/code`. */
+export declare function defaultBuildDir(moduleName: string, cwd?: string): string;
+/**
+ * The directory every module's output hangs off, `plain_modules` by default.
+ *
+ * Callers override this to build somewhere else - a sandbox, a test fixture - and the
+ * layout underneath it stays the same.
+ */
+/**
+ * The project a spec belongs to: the nearest folder, from the spec's own up, that holds a
+ * `config.turri.yaml`, a stack's `config.turri.<stack>.yaml`, the `config.yaml` turri read before it had a file of
+ * its own, or a `plain_modules` - where its code is built, its config read, its testing scripts found. Without any, the
+ * spec's own folder. So `plain/hubspot.plain`, beside `plain/config.turri.yaml` and `plain/plain_modules`, is built there,
+ * wherever turri was started;
+ * specs at the root of their project are built where they always were.
+ */
+export declare function projectDirOf(plainFile: string): string;
+export declare function modulesRoot(cwd?: string): string;
+export declare function buildDirUnder(root: string, moduleName: string): string;
+export declare function testsDirUnder(root: string, moduleName: string): string;
+/**
+ * The `plain_modules` a directory sits in: what holds every module's code and tests. A
+ * directory outside one - a sandbox, an explicit `--build-dir` - is its own root, so this
+ * never silently widens to a whole disk.
+ */
+export declare function modulesRootOf(dir: string): string;
+/**
+ * `.turri` inside the modules root: what turri keeps beside the code - the package
+ * caches, the modules' homes and temporary folders, the copies test runs happen in, the
+ * outputs kept for read_output. Ignored by the project's history.
+ */
+export declare function modulesScratchDir(dir: string): string;
+/** Make `path` inside the modules' scratch, which ignores itself. Returns `path`. */
+export declare function ensureInModulesScratch(dir: string, path: string): string;
+/** Where the project keeps what `deploy` puts out: `dist/`, beside `plain_modules`. */
+export declare const DIST_DIR = "dist";
+/**
+ * Where a person tries a module: `<project>/dist/<module>`, the module's code as its last commit has
+ * it. Outside `plain_modules`, so no agent can reach it, and replaced whole by every deploy.
+ */
+export declare function distDirFor(projectDir: string, moduleName: string): string;
+/**
+ * The project a directory belongs to: the one `plain_modules` sits in, when the directory is
+ * inside it; otherwise the directory's parent for a build folder, or the directory itself.
+ */
+export declare function projectRootOf(dir: string): string;
+/**
+ * `.turri` in the project: the harness's own scratch space - copies to try things in,
+ * saved agent sessions. Never part of the project's history, so it ignores itself - but for `skills/`, the
+ * project's own skills.
+ */
+export declare function scratchDir(dir: string): string;
+/**
+ * Where a skill run keeps its state - the manifest an interrupted run resumes from, the evidence
+ * each phase's gate is judged on: `.turri/runs/<skill>` in the project, beside the rest of
+ * turri's scratch, ignored by the project's history like it.
+ */
+export declare function skillRunDir(cwd: string, skillName: string): string;
+/**
+ * What the scratch dir's .gitignore says: everything in it is ignored but `skills/` - the project's own skills
+ * (skills.ts), which are written by hand and kept in its history.
+ */
+export declare const SCRATCH_IGNORE = "*\n!skills/\n!skills/**\n";
+/** Make `path`, inside a scratch dir, and see that the scratch dir ignores itself, its skills apart. Returns `path`. */
+export declare function ensureInScratch(scratch: string, path: string): string;
+/** Where agent sessions are saved, so what an agent did can be read - and resumed - later. */
+export declare function sessionsDir(project: string): string;
+/**
+ * Template search order, matching file_utils.get_template_directories: the plain file's
+ * own directory first, then a sibling `template/` directory if there is one (where a
+ * project keeps its import modules), then anything passed in, then PLAIN_TEMPLATE_DIRS.
+ * A `stdlib/...` import is not looked for in them: it is turri's (see plain/stdlib.ts).
+ */
+export declare function resolveTemplateDirs(plainFile: string, extra?: string[]): string[];

package/dist/regenerate/plain-palette.d.ts

@@ -0,0 +1,34 @@
+import type { DiffPaint } from "./diff-view.ts";
+/** A colour's SGR parameters: 24-bit, or the nearest of the 256 where the terminal has no more. */
+export declare function sgr(hex: string, background: boolean, truecolor: boolean): string;
+/**
+ * Neon, for what is shown to do what its spec says - regen's ◆: the design system's colour for what can be followed,
+ * 12.2:1 on abyss. On a light surface, where neon is illegible (1.6:1 on white), blue whale, 12.9:1 on white.
+ */
+export declare const BRAND_NEON: {
+    light: string;
+    dark: string;
+};
+/**
+ * Pink, the one pink thing in a view - the banner's wordmark: 6.54:1 on abyss. On a light surface, where pink is
+ * too pale (2.9:1 on white), eggplant, 9.9:1 on white.
+ */
+export declare const BRAND_PINK: {
+    light: string;
+    dark: string;
+};
+/** Text in neon on a theme - blue whale on a light one - in as many colours as the terminal has. */
+export declare const brandNeon: (theme: {
+    appearance?: "dark" | "light";
+    getColorMode?(): string;
+}) => ((text: string) => string);
+/** Text in pink on a theme - eggplant on a light one - in as many colours as the terminal has. */
+export declare const brandPink: (theme: {
+    appearance?: "dark" | "light";
+    getColorMode?(): string;
+}) => ((text: string) => string);
+/** How a spec diff is painted on a theme: its palette by whether the theme is dark or light, in as many colours as the terminal has. */
+export declare function plainPaint(theme: {
+    appearance?: "dark" | "light";
+    getColorMode?(): string;
+}): DiffPaint;

package/dist/regenerate/prompt.d.ts

@@ -0,0 +1,192 @@
+import { type MarshalledPlainSource, type Specifications } from "../plain/spec.ts";
+import { type LoadedResource } from "./resources.ts";
+import type { JobCases } from "./drift.ts";
+import type { RequiredSpec } from "./state.ts";
+import { type SpecChange } from "./spec-steps.ts";
+/**
+ * Functional specs grouped by the module they belong to - in the order the modules are built on
+ * one another, the current module marked - and each tagged with its module and its id there. A codebase holds the
+ * functionalities of every module it is built on, and each module numbers its own from 1, so
+ * "functionality 1" alone is ambiguous: the first listed may be base's 1 and the next top's 3.
+ * (the reference implementation's implemented functional requirements prompt section, as tags.)
+ */
+export declare function functionalitiesByModule(entries: Array<{
+    module: string;
+    frid: string;
+    spec: string;
+}>, currentModule: string, status?: string): string;
+/** "functionality 3 of module `app`": a functionality, named so that no other module's can be meant. */
+export declare function functionalityOf(frid: string, moduleName: string): string;
+/**
+ * How to read a ***plain specification: what each section is, and what the predefined concepts
+ * mean. At the head of every prompt for an agent that builds, tests or judges from a spec - the
+ * spec-writing agents have it from the authoring rules. Without it an agent reads
+ * "- :Implementation: uses FastAPI." as a term it should have found in the definitions.
+ *
+ * `testReqs`: whether this agent is given the test reqs - the agents that write and judge the
+ * conformance tests are, the ones that write code are not.
+ */
+export declare function specPrimer(options: {
+    testReqs: boolean;
+}): string;
+/**
+ * How a failure is fixed without being hidden - for every agent that fixes code or tests. The
+ * point of a failing test is the failure: a fix that makes it go away without making the software
+ * right leaves the defect in, and the test unable to catch it again.
+ */
+export declare const INTEGRITY_RULES: string[];
+/**
+ * How a failure is fixed - for every agent sent back with one: understand it, reproduce it, fix the
+ * cause, check the fix the way the harness will. A fix made from the last line of the output alone
+ * fixes the symptom, if anything, and comes back next round.
+ */
+export declare function fixMethod(options: {
+    what: "unit tests" | "conformance tests";
+    fixes: "code" | "tests";
+    runTool: string;
+}): string[];
+/**
+ * Why something failed is never lost - for every agent that writes or fixes code. A failure answered
+ * with a bare "failed" and logged nowhere leaves whoever has to fix it guessing, round after round.
+ */
+export declare const ERROR_CAUSE_RULES: string[];
+/** A section's tag - its name in every prompt: `<implementation reqs>`, `<acceptance tests>`. */
+export declare function sectionTag(key: string): string;
+export declare function section(key: string, items: string[]): string | null;
+/**
+ * The module each item of a spec's sections belongs to, in order, by section. A codebase is built from the spec of its
+ * whole requires chain: an item of a module below carries that module's name (records.ts `chainTree`); the module's
+ * own - and what it imports, which is its own - carry none, and are `moduleName`'s.
+ */
+export type SectionModules = Partial<Record<string, string[]>>;
+export declare function sectionModules(tree: MarshalledPlainSource, moduleName: string): SectionModules;
+/**
+ * A section of the spec, its items grouped under the module each belongs to - the modules in the order they are built on
+ * one another, the current one marked - as the functional specs are (`functionalitiesByModule`). Without `modules`, or
+ * when they do not match the items one for one, every item is the current module's.
+ */
+export declare function moduleSection(key: string, items: string[], moduleName: string, modules?: SectionModules): string | null;
+export interface SpecDiffPromptInput {
+    moduleName: string;
+    /** The spec change, as a diff of the .plain files. */
+    diff: string;
+    /** The change item by item, from what the code is built from to the spec it ends on: shown section by section in place of the diff. */
+    changes?: SpecChange[];
+    /** The module's sections and its functional specs, as they stand after the change. */
+    specifications: Specifications;
+    /** Functional specs of the modules this one requires, as they stand after the change. */
+    required: RequiredSpec[];
+    linkedResources: LoadedResource[];
+    codebase?: string | null;
+    /** Nothing is built yet: the change is the whole spec. */
+    empty: boolean;
+    /** What the job does to each functional spec (work.ts): the agent is told case by case. Not given: in general. */
+    cases?: JobCases;
+    /** The module each definition and req belongs to: see `sectionModules`. */
+    modules?: SectionModules;
+}
+/**
+ * The specification a review of some work is given: laid out exactly as the coding agent had it - how to read a
+ * ***plain spec, the definitions, the implementation reqs, what was already implemented - and then what is new, in
+ * a block of its own: the change the work made, section by section. The reviewer reads what the coding agent read,
+ * and knows exactly what this work was.
+ */
+export declare function reviewedSpec(input: {
+    moduleName: string;
+    specifications: Specifications;
+    /** Functional specs of the modules this one requires: already in the code. */
+    required?: RequiredSpec[];
+    /** The change, section by section. */
+    change?: string;
+    /** The module each definition and req belongs to: see `sectionModules`. */
+    modules?: SectionModules;
+}): string;
+/** A change in its tag: told section by section, or - when it could not be - the raw diff, with which tag each heading is. */
+export declare function specChangeBlock(change: string): string;
+/**
+ * A spec change as an agent reads it: section by section, what was added, what changed - before and now - and what
+ * was removed. A definition taken out and put back reworded, or moved, is one change to it, not two. Every item is
+ * named so no other module's can be meant: a functional spec by its module and number, and a definition or req of a
+ * module below by its module; `moduleName` is the module whose codebase it is - whose own items carry no module.
+ */
+export declare function describeSpecChange(changes: SpecChange[], moduleName?: string): string;
+/**
+ * Build the prompt for rendering a change to the specs.
+ *
+ * The change is given as the person made it - a diff of the .plain files - and the specs as
+ * they stand after it come with it, so the agent has both what moved and what it must add up
+ * to. Additions, changes and removals, in any section, are one task: make the code match.
+ */
+export declare function buildSpecDiffPrompt(input: SpecDiffPromptInput): string;
+export interface ConformancePromptInput {
+    /** What the job does to each functional spec (work.ts): the agent is told case by case. Not given: in general. */
+    cases?: JobCases;
+    moduleName: string;
+    /** The functionality under test; for a spec change, the last there is - none before the first is written. */
+    frid?: string;
+    specifications: Specifications;
+    linkedResources: LoadedResource[];
+    /** File names in the build directory. */
+    manifest: string[];
+    /** Where the code is, for fixing it when it is what is wrong. */
+    codeDir?: string;
+    /**
+     * How to invoke the built software from outside, as an agent that explored the code wrote it.
+     * Given, the author works from this and fixes only tests - when a run fails, another agent decides
+     * whether the test or the code is wrong.
+     */
+    invocation?: string;
+    /** The code, which the author may read but never change. */
+    readCode?: string;
+    /** The code's build files, read by the harness: the exact name, coordinates and version a test project points at. */
+    manifests?: Array<{
+        path: string;
+        content: string;
+    }>;
+    /** For a spec change: the functionalities it touches, with their acceptance tests - each implemented and labelled. */
+    touched?: Array<{
+        frid: string;
+        acceptanceTests: string[];
+    }>;
+    /** Tests already in the conformance directory, from an earlier version of the spec. */
+    existingTests?: string[];
+    /** Functional specs of the modules this one requires, transitively. */
+    required?: RequiredSpec[];
+    /**
+     * A change to the specs, as a diff, instead of one functionality: the tests are brought in
+     * line with the specs as they stand after it.
+     */
+    diff?: string;
+    /** The module each definition and req belongs to: see `sectionModules`. */
+    modules?: SectionModules;
+}
+/**
+ * Build the prompt for conformance tests.
+ *
+ * These are black-box in shape: they invoke the built functionality from outside and check
+ * it does what the specification says. The agent can read the implementation - it needs to
+ * know how to call the thing - but the prompt leads with the specification, because a test
+ * written from the code can only ever agree with it.
+ */
+export declare function buildConformancePrompt(input: ConformancePromptInput): string;
+/** What a conformance test covering no functional spec yet - a definition, a req - is labelled. */
+export declare const CHANGE_LABEL = "conformance tests of the spec";
+export interface RegressionFixPromptInput {
+    moduleName: string;
+    /** Functionalities built so far, in order. */
+    frids: string[];
+    specifications: Specifications;
+    failure: string;
+    /** Functional specs of the modules this one requires, transitively. */
+    required?: RequiredSpec[];
+    /** The module each definition and req belongs to: see `sectionModules`. */
+    modules?: SectionModules;
+}
+/**
+ * Build the prompt for repairing a regression.
+ *
+ * A regression means the newest functionality broke an older one, so the whole module's
+ * conformance suite is the subject. The tests are not editable from here - they state
+ * what the specification requires of every functionality built so far.
+ */
+export declare function buildRegressionFixPrompt(input: RegressionFixPromptInput): string;

package/dist/regenerate/records.d.ts

@@ -0,0 +1,88 @@
+import { type MarshalledPlainSource } from "../plain/spec.ts";
+/**
+ * What a module is built from, in two records - see docs/regenerating.md.
+ *
+ * - The code record, `code/.turri.json`: the spec the code is built from, without what is only
+ *   for conformance - the test reqs, and the acceptance tests under each functional spec.
+ * - The tests record, `tests/.turri.json`: the functional specs the conformance tests are
+ *   written for - a subset of the code record's, each with its number and its acceptance tests - the
+ *   definitions and implementation reqs they were written against, and the test reqs they follow.
+ *
+ * The tests record is always a substate of the code record: a conformance test exercises
+ * functionality, and only functionality in the code can be tested. Each record is committed with
+ * what it describes, in the module's `.plaingit`, so rolling a unit of work back puts it back too.
+ */
+export declare const RECORD_FILE = ".turri.json";
+/**
+ * A functional spec in the code record marked to regenerate again: its code is built, and is to be regenerated again
+ * all the same - `regenerate` with functionalities named. The mark makes the record differ from the spec at that item,
+ * so the work loop plans it as it plans any change, and the job that regenerates it writes the item back without it.
+ */
+export declare const REGENERATE_AGAIN = "regenerate_again";
+/** Whether a record's item is marked to regenerate again. */
+export declare function marksRegenerateAgain(item: unknown): boolean;
+/** The spec as the code is built from it: no test reqs, and no acceptance tests under the functional specs. */
+export declare function codeTree(tree: MarshalledPlainSource): MarshalledPlainSource;
+/**
+ * A module's tree with the hash of each linked resource's content beside its link: the file is part of the spec,
+ * so a change to what it holds is a change to the item that links it - and, a definition linking it, to every
+ * functional spec using the concept. Found as the parser finds it: the spec's own folder first, then the other
+ * template folders, then the current directory.
+ */
+export declare function withResourceDigests(tree: MarshalledPlainSource, dirs: string[]): MarshalledPlainSource;
+/**
+ * A record written before linked resources were hashed, with the hashes of `spec` where its links are the same:
+ * what it was built from is taken to be the resource as it is now, rather than every item linking one built again.
+ */
+export declare function adoptDigests(record: MarshalledPlainSource | null, spec: MarshalledPlainSource): MarshalledPlainSource | null;
+/**
+ * The spec a codebase is built from: the spec of its whole requires chain, as its code holds it. A
+ * codebase is built on the code of the modules below it, so its code implements their definitions and
+ * implementation reqs too: those come tagged with their module, bottom of the chain first, and the
+ * module's own untagged after them. An item a lower module already has - the same text, from an import
+ * they share - is not the module's own again: its code implements it already. The functional specs of the
+ * modules below are the ones it inherits, as the parser gives them; its test reqs are its own.
+ *
+ * `trees`: every module of the chain, bottom first - the module itself last.
+ */
+export declare function chainTree(trees: Array<{
+    module: string;
+    tree: MarshalledPlainSource;
+}>): MarshalledPlainSource;
+/**
+ * What a new module's codebase starts from, copied from the code of the module it requires: that module's
+ * record, as a lower module's - its own definitions and implementation reqs tagged with it, its functional
+ * specs among the ones inherited. The new module has built nothing of its own yet.
+ */
+export declare function inheritedRecord(source: MarshalledPlainSource, sourceModule: string): MarshalledPlainSource;
+/** Which functional specs are to have conformance tests, by number. Default: every one. */
+export type Chosen = (frid: string) => boolean;
+/**
+ * What the conformance tests are to be written for, now: of the functional specs the code is built
+ * from, those chosen, each as the spec has it now with its acceptance tests - and the code's
+ * definitions and implementation reqs, with the test reqs as the spec has them now.
+ *
+ * Conformance follows the code, never goes ahead of it: a functional spec whose code is not caught up
+ * with the spec - its text in the code record is not the spec's, or the code record does not have it at
+ * all, as while it is regenerated again - stays as the tests record has it, until the code lands. Its tests are
+ * taken out only once the spec and the code have both dropped it.
+ */
+export declare function conformanceTarget(code: MarshalledPlainSource | null, tests: MarshalledPlainSource | null, spec: MarshalledPlainSource, chosen?: Chosen): MarshalledPlainSource;
+/**
+ * Of the functional specs given, by number, those the code record does not have as `tree` has them - not built,
+ * or built from other text: no conformance test can be written for them yet. `tree` is a spec, its functional
+ * specs numbered by place, or what conformance tests are written for, each with its number.
+ */
+export declare function notBuilt(code: MarshalledPlainSource | null, tree: MarshalledPlainSource, frids: string[]): string[];
+/**
+ * A record in `dir`: as the module's last commit has it, by default - what the harness itself wrote
+ * when the last unit of work landed, never what an agent's shell changed since - or, with `onDisk`,
+ * the file as it is. Null when there is none.
+ */
+export declare function readRecord(dir: string, options?: {
+    onDisk?: boolean;
+}): MarshalledPlainSource | null;
+/** Write the code record: the tree, as the code sees it. */
+export declare function writeCodeRecord(codeDir: string, tree: MarshalledPlainSource): void;
+/** Write the tests record: a conformance target, as it now is built. */
+export declare function writeTestsRecord(testsDir: string, tree: MarshalledPlainSource): void;

package/dist/regenerate/regenerate.d.ts

@@ -0,0 +1,108 @@
+import { type MarshalledPlainSource } from "../plain/spec.ts";
+import type { JobCases } from "./drift.ts";
+import { type SpecGap } from "./notes.ts";
+import { type ChainEntry } from "./requires.ts";
+import { type JobSteering } from "./steering.ts";
+import { type TestRemoval, type TestRun, type MissingToolchain } from "./testing.ts";
+/**
+ * Bring the .plain files to the state the diff describes, with git. A diff that is already
+ * applied is fine - the person may have made the edit themselves and sent its diff - but
+ * one that fits neither way is refused: rendering it would mean guessing.
+ */
+export declare function applySpecDiff(diff: string, cwd: string): "applied" | "already applied";
+/** Undo a spec diff this process applied, when what it produced cannot be used. */
+export declare function revertSpecDiff(diff: string, cwd: string): void;
+/** The .plain files a diff writes to, relative to where it applies. */
+export declare function plainFilesOf(diff: string): string[];
+/** A module's .plain file and every one it imports, transitively - the files its spec is read from. */
+export declare function specFilesOf(plainFile: string, templateDirs?: string[]): string[];
+/** A git diff cut into what it does to each file, in order: the file's path (the new side's), and its part of the diff. */
+export declare function diffByFile(diff: string): Array<{
+    file: string;
+    diff: string;
+}>;
+/**
+ * The spec as it stands with a change in: the codebase the change is rendered in, and that
+ * module parsed - its sections, the functional specs it inherits and its own.
+ */
+export interface SpecSnapshot {
+    moduleName: string;
+    plainFile: string;
+    tree: MarshalledPlainSource;
+    /** The codebase's requires chain, bottom first; the last entry is the codebase itself. */
+    chain: ChainEntry[];
+}
+/** Parse the spec as it stands now, for a change to `plainFile`'s module. */
+export declare function snapshotSpec(plainFile: string, options?: {
+    cwd?: string;
+    templateDirs?: string[];
+    inModule?: string;
+}): SpecSnapshot;
+export interface RenderSpecDiffOptions {
+    /** A .plain file of the module the change is rendered for. */
+    plainFile: string;
+    /** The change, as a git diff of the .plain files. */
+    diff: string;
+    /** Where the diff's paths are relative to. Default: the working directory. */
+    cwd?: string;
+    templateDirs?: string[];
+    /** The codebase to render in, when modules built on this one branch. */
+    inModule?: string;
+    /**
+     * The diff was already put in when it was written - how that went - and is not to be applied
+     * again. A render queued behind the interview runs after later changes have gone on top of
+     * it, so its diff no longer fits the file either way - but it is in, and that is what matters.
+     */
+    applied?: "applied" | "already applied";
+    /** The spec as parsed with the diff in. Taken now, after applying it, when not given. */
+    spec?: SpecSnapshot;
+    model?: string;
+    /** Review the code and unit tests once they pass - that they do what the change says. Default: the config's `review:`, else false. */
+    unitReview?: boolean;
+    /** What the job does to each functional spec (work.ts): its agents are told case by case. Not given: in general. */
+    cases?: JobCases;
+    /** Build the coding agent's task and stop there: nothing is started, and what the render did is rolled back. */
+    dryRun?: boolean;
+    /** The unit test review's model. Default: the project's judge-model, else `model`. */
+    judgeModel?: string;
+    onDelta?: (delta: string) => void;
+    /** The loop's: steers the coding agent when the spec changes inside what it regenerates, and holds the record it lands. */
+    steering?: JobSteering;
+}
+export interface RenderSpecDiffResult {
+    /** The codebase the change was rendered in. */
+    moduleName: string;
+    buildDir: string;
+    diff: "applied" | "already applied";
+    response: string;
+    runs: TestRun[];
+    /** How many times the harness ran the unit testing script on it: the attempts it judged. */
+    attempts: number;
+    testRemovals: TestRemoval[];
+    files: {
+        added: string[];
+        changed: string[];
+        removed: string[];
+    };
+    passed: boolean;
+    stoppedAt: "unit tests" | null;
+    /** Stopped because the unit testing script cannot run: what it needs is not installed where it runs. */
+    missingToolchain?: MissingToolchain;
+    /** Stopped with the unit tests passing and the unit testing script's static checks not. */
+    staticChecks?: boolean;
+    /** What the spec changed while it regenerated that its agent was told - a line each. */
+    steered?: string[];
+    /** The specs were only restructured: nothing was rendered, the spec as now laid out was recorded. */
+    restructured?: boolean;
+    /** A dry run: the task the coding agent would be given. */
+    task?: string;
+    /** Spec gaps its agents reported: what the spec should say and does not, for the person to decide. */
+    specGaps?: SpecGap[];
+    /** What the debugger found, each time it was asked - its root cause. */
+    diagnosed?: string[];
+}
+export declare function renderSpecDiff(options: RenderSpecDiffOptions): Promise<RenderSpecDiffResult>;
+/** Spec gaps a pulse's agents met, as its report says them: for the conversation to put to the person. */
+export declare function specGapsText(gaps: SpecGap[] | undefined): string[];
+/** What a rendered spec change did, for the agent and the person. */
+export declare function describeSpecDiff(result: RenderSpecDiffResult): string;

package/dist/regenerate/regression.d.ts

@@ -0,0 +1,58 @@
+import { type MarshalledPlainSource } from "../plain/spec.ts";
+import { type WorkStart } from "./lineage.ts";
+import { type TestScripts } from "./test-scripts.ts";
+import type { RequiredSpec } from "./state.ts";
+import { type TestRun } from "./testing.ts";
+/** What a regression run reports as it goes: a run of the suite, a repair. */
+export type RegressionEvent = {
+    type: "run";
+    command: string;
+    exitCode: number;
+    frids?: string[];
+} | {
+    type: "repair";
+    frids: string[];
+};
+export interface RegressionRun extends TestRun {
+    /** Functionalities whose tests took part in this run. */
+    frids: string[];
+}
+export interface RegressionResult {
+    passed: boolean;
+    runs: RegressionRun[];
+    /** Each time the implementation was changed to repair a regression. */
+    repairs: string[];
+    /** The conformance testing script that ran the suite; null when there were no tests to run. */
+    command: string | null;
+    /** Conformance was turned off, so the conformance tests already here were not run. */
+    conformanceOff?: boolean;
+}
+/**
+ * Run every conformance test built so far, and repair the code until they all pass.
+ *
+ * This is the gate between one functionality and the next. A functionality that passed on
+ * its own is not finished until the ones before it still pass alongside it, and each
+ * repair changes the code - so the suite is run again after every one.
+ */
+export declare function ensureRegressionPasses(input: {
+    buildDir: string;
+    conformanceRoot: string;
+    moduleName: string;
+    frids: string[];
+    tree: MarshalledPlainSource;
+    /** The required modules' functional specs, for the repair agent. */
+    required: RequiredSpec[];
+    /**
+     * The unit of work the run belongs to, undone whole when the suite still fails. Without one,
+     * only what the repairs did is undone.
+     */
+    start?: WorkStart;
+    /** The step the regression run is for, as a repair's notes say; the last functionality by default. */
+    step?: string;
+    /** The codebase's testing scripts: its conformance testing script runs the suite. */
+    scripts: TestScripts;
+    model?: string;
+    maxRounds?: number;
+    onDelta?: (delta: string) => void;
+    onEvent?: (event: RegressionEvent) => void;
+}): Promise<RegressionResult>;