@open-tomato/rafa 0.44.0 → 0.46.0

package/dist/core/plan/plan-stamp.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The plan marker the loop stamps onto every prompt it dispatches.
+ *
+ * Effort attribution used to reach a session's plan through its BRANCH
+ * NAME, which works only while a run happens on a branch whose stub
+ * resolves. Measured after one run executed on `main`: all 74 of its
+ * sessions attributed to the `main` branch group instead of the plan,
+ * and the group they landed in mixes every main-branch session ever
+ * recorded, so the plan's figures were not recoverable from the store
+ * without knowing the run's wall-clock window by hand.
+ *
+ * Two of those sessions in three could not have been recovered by any
+ * derivation either. A task session carries the tracker line it was
+ * dispatched with, so its plan is at least derivable from the tracker
+ * text; a compaction and a wrap-up session carried neither the plan
+ * path nor the stub anywhere in their prompts, measured across both
+ * shapes before the wrap-up was handed its plan.
+ * So the signal did not exist to be inferred, and the fix is to WRITE
+ * one rather than to guess better.
+ *
+ * The marker is an HTML comment because every prompt this loop builds
+ * is markdown handed to a model: a comment carries no instruction, and
+ * a model that echoes the prompt back cannot turn it into one.
+ *
+ * It is APPENDED and never prepended, and that is load-bearing rather
+ * than cosmetic. `effort/classify.ts` buckets a session by
+ * `content.startsWith(shape.prefix)` over the WHOLE prompt, so one
+ * line above the body re-buckets every one of the four shapes as
+ * `other` — silently, because that module's drift guard is a
+ * containment check that would stay green. `start/wrap-up.ts` states
+ * the same rule at its wrap-up builder: add lines after line 1, never
+ * before it. {@link planStubFromPrompt} therefore SEARCHES rather than
+ * matching a prefix, which is what lets the marker sit at the end.
+ *
+ * A stub is written verbatim and matched against the same character
+ * class `readPlanStubs` derives from a filename, so a stamp can never
+ * name a stub the store could not also have resolved from a branch.
+ */
+/** True when the text is usable as a stamped stub. */
+export declare function isStampableStub(stub: string): boolean;
+/**
+ * Builds the marker line for one plan stub.
+ *
+ * Throws on a stub the pattern would not match, rather than writing a
+ * marker {@link planStubFromPrompt} could not read back. A stamp that
+ * silently fails to parse is worse than no stamp: it reports as an
+ * unattributed session while looking like it was handled.
+ */
+export declare function planStampLine(stub: string): string;
+/**
+ * Reads the stub back out of a dispatched prompt, or null.
+ *
+ * Null for absent content, for a prompt carrying no marker, and for a
+ * marker whose stub does not match the class — the three cases a
+ * caller treats alike, since each means the session has no stamped
+ * plan and must fall back to its branch.
+ */
+export declare function planStubFromPrompt(content: string | null | undefined): string | null;
+/**
+ * Appends the marker to a prompt the loop is about to dispatch.
+ *
+ * Never prepends: the first line is a classifier key, and the module
+ * note above carries the measurement.
+ */
+export declare function stampPrompt(stub: string, prompt: string): string;
+/**
+ * Derives a plan stub from a plan or tracker path.
+ *
+ * `PLAN-q16a-compose-n8n.md` and `PLAN_TRACKER-q16a-compose-n8n.md`
+ * both answer `q16a-compose-n8n`; a bare `PLAN.md` answers null,
+ * having no stub to name. Null rather than a fallback string: an
+ * unstubbed plan is exactly the case a stamp must not invent a group
+ * for, and the caller reports it instead.
+ */
+export declare function planStubFromPath(planPath: string): string | null;

package/dist/core/runtime/identity.d.ts

@@ -0,0 +1,21 @@
+/** An installed runtime: a runtime copy, or the package installed from npm. */
+export interface InstalledIdentity {
+    readonly kind: 'installed';
+    /** The entry file, through its real path when it exists. */
+    readonly entry: string;
+}
+/** A development build: rafa run from a checkout. */
+export interface DevelopmentIdentity {
+    readonly kind: 'development';
+    /** The entry file, through its real path when it exists. */
+    readonly entry: string;
+    /** The checkout's root, the directory holding its `package.json` and `src/rafa.ts`. */
+    readonly checkout: string;
+}
+/** Which build is running; see the module note. */
+export type RuntimeIdentity = InstalledIdentity | DevelopmentIdentity;
+/**
+ * Which build runs from `entry`, `Bun.main` by default. See the module
+ * note for the walk.
+ */
+export declare function readRuntimeIdentity(entry?: string): RuntimeIdentity;

package/dist/core/runtime/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The barrel over the runtime identity: every name `identity.ts`
+ * exports, and nothing else.
+ *
+ * A file outside `packages/rafa/src/core/` imports this file and never the one behind
+ * it (`scripts/survey/core-barrels.ts` measures that, and
+ * `src/tests/core-barrels.sweep.test.ts` holds it against the tree). A
+ * file inside `packages/rafa/src/core/` imports `identity.ts` directly and never this
+ * file. The effort store under `packages/rafa/src/effort/store/` is core by
+ * assignment and not by folder, so it is outside `packages/rafa/src/core/` for the
+ * rule and imports this file.
+ *
+ * ## What sits behind it
+ *
+ * `identity.ts` alone: {@link readRuntimeIdentity}, which reads whether
+ * the running build is an installed runtime or a development build run
+ * from a checkout, and the three types it answers with. It moved here
+ * from `src/runtime/identity.ts` (#1088), so the effort store, which
+ * asks it before it migrates a live store, imports nothing above core
+ * for it.
+ *
+ * ## Why one barrel can hold it
+ *
+ * A barrel that groups a file with a file outside `packages/rafa/src/core/` that
+ * imports the barrel back by value is a runtime cycle. `identity.ts`
+ * imports `node:fs`, `node:path` and the root `package.json`, and no
+ * file under `src/`, so no file behind this barrel reaches a file that
+ * imports it back.
+ *
+ * ## The old path
+ *
+ * `src/runtime/identity.ts` re-exported this file's names under the same
+ * names until core moved into its package (#1090), which deleted it and
+ * pointed its importers at `@open-tomato/rafa/core/runtime`.
+ *
+ * ## What it exports
+ *
+ * Each name is spelled, types apart from values, as the other core
+ * barrels spell theirs. No name here is part of the published surface:
+ * `src/index.ts` re-exports nothing from this file.
+ *
+ * `index.test.ts` holds the list to the file: every name `identity.ts`
+ * exports is here once, as the same binding, and no other name is here.
+ */
+export type { DevelopmentIdentity, InstalledIdentity, RuntimeIdentity } from './identity.js';
+export { readRuntimeIdentity } from './identity.js';

package/dist/effort/store/bring-forward.d.ts

@@ -0,0 +1,131 @@
+/**
+ * The log-aware open: bring a SQLite store to this build's migrations,
+ * recording each one in the store's migration log, or refuse it.
+ *
+ * ## The migration log
+ *
+ * `schema_migrations` holds one row per migration the store holds: its
+ * id, the sha256 of its SQL, what it `breaks` as a JSON array of words,
+ * when it was applied and by which rafa. {@link bringForward} creates the
+ * table in the same transaction as the rows it first records, so a store
+ * never holds an empty log it was not given in that transaction.
+ *
+ * ## What an open does
+ *
+ * {@link bringForward} reads the log and `user_version`, and hands them
+ * to `planSchema` (`schema-plan.ts`), which decides. A refusal is thrown
+ * as a {@link SchemaRefusedError} carrying the plan's reason, message and
+ * next step, and nothing is written. A plan with nothing to adopt or
+ * apply returns at once, taking no lock and writing nothing, so a read
+ * open of a current store never writes.
+ *
+ * Otherwise the open takes the write lock with `BEGIN IMMEDIATE`, reads
+ * the store again and plans again, since another process may have
+ * brought the store forward, or recorded a migration this build does
+ * not know, while this one waited. Under that second plan, and in one
+ * transaction, it:
+ *
+ *   - creates `schema_migrations` when the store has none;
+ *   - adopts a store with no log: the legacy entries its `user_version`
+ *     counts are logged with this build's checksums and not run, since
+ *     a shipped entry is frozen and so is what ran;
+ *   - runs each pending migration's SQL and logs it, in catalogue order;
+ *   - sets `user_version` to the gate the plan answers.
+ *
+ * A throw anywhere rolls all of it back, `user_version` included, and
+ * leaves the store as it was found. The second plan can find nothing
+ * left to do, which is the answer when another process applied the same
+ * migrations first; the transaction then writes nothing.
+ *
+ * A store with a log and nothing pending keeps the `user_version` it
+ * holds, even when its log would give another gate: only a transaction
+ * that records a migration moves the gate.
+ *
+ * ## A development build never migrates the live store
+ *
+ * Between the first plan and the lock, an open with something to write
+ * asks `refuseUnownedDevelopmentWrite` (`development-build.ts`), which
+ * throws a `DevelopmentBuildRefusedError` when this rafa is a
+ * development build and the store lies outside the temporary directory
+ * and `RAFA_EFFORT_DIR`. The refusal comes before the lock and before
+ * any write, adoption included, so the store keeps its bytes. With
+ * nothing to write the open returns before that question is asked, so
+ * a development build uses a current store as any rafa does. That
+ * module's note says which stores it owns and what the text names.
+ *
+ * An open with {@link BringForwardOptions.builtAside} set skips that
+ * question: its file is one the caller built beside a store, which
+ * reaches the store only through the build-aside swap
+ * (`rebuild-aside.ts`), so the caller asks the question of the swap.
+ * `fix-schema.ts` builds its rebuild this way, since the parallel file
+ * sits in the project's store directory where the question would
+ * otherwise refuse even a dry run.
+ *
+ * ## What this module does not decide
+ *
+ * `planSchema` owns every refusal and its text. Which rafa counts as the
+ * one applying a migration is the caller's to say through
+ * {@link BringForwardOptions.appliedBy}; with none given it is this
+ * build's package version.
+ */
+import type { DevelopmentProbe } from './development-build.js';
+import type { SqliteMigration } from './migrations.js';
+import type { RefusalReason, SchemaCaller, SchemaRefusal, SchemaUse, StoreAccess, StoreSchema } from './schema-plan.js';
+import type { Database } from 'bun:sqlite';
+/** The migration log's table. */
+export declare const MIGRATION_LOG_TABLE = "schema_migrations";
+/** A store refused by `planSchema`, carrying the plan's answer. */
+export declare class SchemaRefusedError extends Error {
+    /** Which of the seven refusals this is. */
+    readonly reason: RefusalReason;
+    /** The one command to run next, which the message also ends with. */
+    readonly nextStep: string;
+    constructor(refusal: SchemaRefusal);
+}
+/**
+ * What an open may vary; each field has the running build's default.
+ * The {@link DevelopmentProbe} fields say which build runs and which
+ * stores it owns (`development-build.ts`).
+ */
+export interface BringForwardOptions extends DevelopmentProbe {
+    /** The catalogue to bring the store to; a test passes a synthetic tail here. */
+    readonly migrations?: readonly SqliteMigration[];
+    /** The `applied_by` of every row this open logs; this build's version by default. */
+    readonly appliedBy?: string;
+    /** The clock `applied_at` is read from. */
+    readonly now?: () => Date;
+    /**
+     * True when `db` is a file the caller built beside a store and swaps
+     * in only through the build-aside steps; the development-build
+     * question is then the caller's, and this open does not ask it.
+     */
+    readonly builtAside?: boolean;
+}
+/** What an open wrote. Both lists are empty when it wrote nothing. */
+export interface BroughtForward {
+    /** Legacy ids logged without running, in catalogue order. */
+    readonly adopted: readonly string[];
+    /** Ids whose SQL ran and was logged, in the order it ran. */
+    readonly applied: readonly string[];
+    /** The store's `user_version` once the open is done. */
+    readonly userVersion: number;
+}
+/**
+ * Bring the store open on `db` to this build's migrations for an open
+ * with `access` from `caller`, or throw {@link SchemaRefusedError}.
+ * `path` is what a refusal names the store as. The module note says
+ * what is written, and when.
+ */
+export declare function bringForward(db: Database, path: string, access: StoreAccess, caller: SchemaCaller, options?: BringForwardOptions): BroughtForward;
+/**
+ * The store's `user_version` and its migration log, or a null log when
+ * it has no `schema_migrations` table. Reads only.
+ */
+export declare function readStoreSchema(db: Database, path: string): StoreSchema;
+/**
+ * What a plan's write would record: the log first when it adopts, then
+ * each pending id. Empty when the plan writes nothing. `rafa effort
+ * schema` names the same list when it asks the development-build
+ * question an open would ask (`schema-report.ts`).
+ */
+export declare function writeNames(plan: SchemaUse): readonly string[];

package/dist/effort/store/check-rows.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The check rows of a pull request and the verdict over them, which the
+ * store's plan CI writer (`./plan-ci.ts`) reads and `src/pr/checks.ts`
+ * re-exports for the poll and the provider that parse and wait on them.
+ *
+ * They sit in core so the store reads a verdict without importing the
+ * `pr` module above it.
+ */
+/** Whether a single check has passed, failed, or is still in flight. */
+export type CheckOutcome = 'pass' | 'fail' | 'pending';
+/** One row of `gh pr checks --json name,state,link`. */
+export interface CheckRow {
+    name: string;
+    /** GitHub's raw state, kept verbatim so an unknown one stays reportable. */
+    state: string;
+    link: string;
+    outcome: CheckOutcome;
+}
+/**
+ * The verdict over every row: `none` when the PR has no checks at all,
+ * which is the shape a conflicting PR produces, and the shape of a head
+ * pushed seconds ago whose first check has not registered yet.
+ */
+export type ChecksVerdict = 'green' | 'red' | 'pending' | 'none';
+/**
+ * Reduces rows to one verdict. Pending outranks failure so a run that is
+ * still going is never reported as red on a partial reading.
+ */
+export declare function verdictOf(rows: readonly CheckRow[]): ChecksVerdict;
+/** Rows the caller should act on: the failing ones, for a repair prompt. */
+export declare function failingRows(rows: readonly CheckRow[]): CheckRow[];

package/dist/effort/store/commit-stats.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The commit row of the effort store and the gap arithmetic its rows
+ * carry.
+ *
+ * Moved down from `src/effort/commits.ts`, which parses `git log` into
+ * these rows and re-exports both names under the same names: the
+ * store's row types (`types.ts`), the merge's gap recompute
+ * (`merge-commit-gaps.ts`) and its scenario fixtures
+ * (`testdata/merge-scenarios.ts`) need the row and the arithmetic but
+ * not the parser, so they import them here and the store imports
+ * nothing above core for them. The parser's module note in
+ * `commits.ts` still describes how each field is read from the log.
+ */
+/** One row per commit. */
+export interface CommitStats {
+    /** Full 40-character sha, and the store's key projection. */
+    sha: string;
+    /** Author date, ISO 8601 with offset, as `%aI` emits it. */
+    timestamp: string;
+    /** Subject line only. No commit message body reaches the row. */
+    subject: string;
+    /** Author name, as `%an` emits it. */
+    author: string;
+    /** Ref the walk reached this commit from, or null for `HEAD`. */
+    branch: string | null;
+    /** Numstat lines attributed to the commit, binary files included. */
+    filesChanged: number;
+    /** Summed added lines; a binary file contributes zero. */
+    insertions: number;
+    /** Summed removed lines; a binary file contributes zero. */
+    deletions: number;
+    /** Parents. Two or more is a merge, which prints no diff. */
+    parentCount: number;
+    /** Minutes since the preceding commit in time order, or null. */
+    minutesSincePrevious: number | null;
+}
+/**
+ * Minutes between two ISO timestamps, or null when either fails to
+ * parse. Rounded to {@link ELAPSED_DECIMALS}; never negative, because
+ * the caller orders the pair before asking.
+ */
+export declare function minutesBetween(earlier: string, later: string): number | null;

package/dist/effort/store/copy.d.ts

@@ -0,0 +1,35 @@
+/** The store files a directory can hold, the SQLite file first. */
+export declare const EFFORT_COPY_FILE_NAMES: readonly string[];
+/** A copy that was never started; nothing was made. */
+export declare class EffortCopyRefusal extends Error {
+    readonly name = "EffortCopyRefusal";
+}
+/** A read or a write that failed once the copy started; what it made is removed. */
+export declare class EffortCopyFailure extends Error {
+    readonly name = "EffortCopyFailure";
+}
+/** What one copy is handed. */
+export interface EffortCopyRequest {
+    /** The store directory copied from. */
+    readonly source: string;
+    /** The directory copied into: absent, or an empty directory. */
+    readonly target: string;
+}
+/** What one copy did. */
+export interface EffortCopyResult {
+    /** The store directory copied from, resolved. */
+    readonly source: string;
+    /** The directory copied into, resolved. */
+    readonly directory: string;
+    /** The store files copied, by name, in {@link EFFORT_COPY_FILE_NAMES} order. */
+    readonly files: readonly string[];
+}
+/** Writes `source`'s SQLite store to `target` as one snapshot, reading only. */
+export declare function vacuumInto(source: string, target: string): void;
+/**
+ * Copies the store in `request.source` into `request.target`, answering
+ * what it copied. Throws {@link EffortCopyRefusal} with nothing made, and
+ * {@link EffortCopyFailure} with what it made removed; see the module
+ * note.
+ */
+export declare function copyEffortStore(request: EffortCopyRequest): EffortCopyResult;

package/dist/effort/store/development-build.d.ts

@@ -0,0 +1,105 @@
+/**
+ * A development build never migrates the live store: the refusal
+ * `bringForward` (`bring-forward.ts`) raises before it writes a store
+ * this build does not own.
+ *
+ * ## When it refuses
+ *
+ * `bringForward` asks {@link refuseUnownedDevelopmentWrite} once its
+ * first plan leaves something to write: a store to adopt, or a pending
+ * migration. It refuses when both hold:
+ *
+ *   - the running rafa is a development build, as `readRuntimeIdentity`
+ *     (`packages/rafa/src/core/runtime/identity.ts`) reads it: `bun src/rafa.ts`, a
+ *     checkout's `dist/cli.js` or a `bun test` process;
+ *   - the store is not one it owns ({@link isOwnedStore}).
+ *
+ * A plan with nothing to write never gets here, so a development build
+ * reads and writes the live store as it always did while the store is
+ * current. An installed runtime is never refused here. Adoption counts
+ * as a write, so a development build never adopts the live store
+ * either, and the refusal names `schema_migrations` for it, ahead of
+ * the pending ids.
+ *
+ * ## The stores a development build owns
+ *
+ * A store under the temporary directory (`tmpdir()`, read at each call,
+ * or its real path), which is where every test's store is, and a store
+ * under the directory `RAFA_EFFORT_DIR` names, which is where a copy
+ * made by `rafa effort copy` is. A store that sits in a project's own
+ * `<root>/.rafa/effort/` directory is owned under the temporary
+ * directory only, never through the variable: a variable naming a
+ * directory above a project would otherwise let branch code migrate
+ * that project's live store. `location.ts` already refuses a variable
+ * naming the project's own store where it resolves the directory, and
+ * a relative value, which counts for nothing here.
+ *
+ * ## The text
+ *
+ * The spec's, verbatim, naming the ids and the checkout:
+ *
+ *     effort store: <path> needs migration <ids> and this rafa is a
+ *     development build (<checkout>); a development build migrates only
+ *     a store under the temp directory or RAFA_EFFORT_DIR. Copy it with
+ *     'rafa effort copy' and run this command with
+ *     RAFA_EFFORT_DIR=<the copy>.
+ *
+ * When the store is a project's own (`<root>/.rafa/effort/`), each loop
+ * record under `<root>/.rafa/runs/` that reads `running` or `paused`
+ * with its pid alive (`readSessions`, `packages/rafa/src/core/loop/sessions.ts`) adds
+ * ` Loop <sessionId> (pid <pid>, plan <stub>) is running on this
+ * store.`, oldest first; a record with no stub names its plan's path.
+ * When the records cannot be read, the text says so and names the
+ * error, rather than dropping the sentence in silence. The refusal is
+ * thrown before any write, so the store's bytes are left as they were.
+ */
+import type { StoreEnvironment } from './location.js';
+import type { PidProbe } from '../../core/loop/index.js';
+import type { RuntimeIdentity } from '../../core/runtime/index.js';
+/** The command a refused development build is sent to. */
+export declare const DEVELOPMENT_NEXT_STEP = "rafa effort copy";
+/** What the refusal names in place of an id when the write would adopt the store. */
+export declare const ADOPTION_NAME = "schema_migrations";
+/** What the refusal reads about the process it runs in; each field has a default. */
+export interface DevelopmentProbe {
+    /** Which build is running; `readRuntimeIdentity()` by default. */
+    readonly identity?: RuntimeIdentity;
+    /** The environment `RAFA_EFFORT_DIR` is read from; `process.env` by default. */
+    readonly env?: StoreEnvironment;
+    /** The temporary directory; `tmpdir()` by default. */
+    readonly tempDir?: string;
+    /** Whether a loop record's pid is alive; `isPidAlive` by default. */
+    readonly isAlive?: PidProbe;
+}
+/** What follows the version in the `applied_by` of a row a development build logged, ahead of its checkout. */
+export declare const DEVELOPMENT_MARK = "+dev:";
+/**
+ * The running rafa as a migration log's `applied_by` names it: its
+ * version for an installed runtime, and `<version>+dev:<checkout>` for a
+ * development build, so a row a checkout logged says which one.
+ */
+export declare function appliedByName(identity: RuntimeIdentity): string;
+/** A development build refused a write to a store it does not own. */
+export declare class DevelopmentBuildRefusedError extends Error {
+    /** The store refused. */
+    readonly path: string;
+    /** The one command to run next. */
+    readonly nextStep: string;
+    constructor(path: string, message: string);
+}
+/**
+ * The project root a store file sits in, when its directory is that
+ * project's `<root>/.rafa/effort/`, and null for a store anywhere else.
+ */
+export declare function storeProjectRoot(path: string): string | null;
+/** True when the store at `path` is one a development build may write; see the module note. */
+export declare function isOwnedStore(path: string, env: StoreEnvironment, tempDir: string): boolean;
+/** The refusal's text; see the module note. */
+export declare function developmentRefusalText(path: string, needs: readonly string[], checkout: string, loops: string): string;
+/**
+ * Throws {@link DevelopmentBuildRefusedError} when a development build
+ * would write the store at `path`, which it does not own, and does
+ * nothing otherwise. `needs` names what the write would record, in the
+ * order it would record it. Reads, and writes nothing.
+ */
+export declare function refuseUnownedDevelopmentWrite(path: string, needs: readonly string[], probe?: DevelopmentProbe): void;

package/dist/effort/store/effort-levels.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The effort levels a task's declaration may name, held in core so the
+ * store's dispatch writer (`dispatches.ts`) can type a declared effort
+ * without importing the declaration parser above core.
+ *
+ * The declaration parser, `core/plan/declaration.ts`, imports
+ * `EffortLevel` from here, and is where a task line's `effort=` value is
+ * read and checked.
+ */
+/** Levels `--effort` accepts, taken from the CLI's own help text. */
+export declare const EFFORT_LEVELS: readonly ["low", "medium", "high", "xhigh", "max"];
+/** One of the five levels `--effort` accepts. */
+export type EffortLevel = (typeof EFFORT_LEVELS)[number];