@smthrs/std 0.0.0-stage → 1.0.0-rc.12

package/dist/esm/Checkpoints.d.ts

@@ -0,0 +1,322 @@
+/**
+ * Pinned trees, and the scratch checkouts a call runs against.
+ *
+ * A checkpoint is a **value**: minting one changes nothing about the workspace,
+ * and running a call against one leaves the live tree exactly as it stands.
+ * That is the whole of what it buys. Before it existed, the only way a run
+ * could answer "did this command fail before my change" was to undo the change
+ * — and the journals price that exactly. On `sympy__sympy-13878` the r95repl
+ * lane applied one byte-identical 4,789-character patch **five times**, four of
+ * those applications preceded by `git checkout -- sympy/stats/crv_types.py`,
+ * because a clean fails-before proof required reverting the very work it was
+ * meant to prove.
+ *
+ * This module is the host half of `@smthrs/harness`'s `ctx.checkpoint()` and
+ * `ctx.call(flow, input, { at })`. The harness owns the surface, the identity,
+ * the bound and the refusals; nothing in it knows what a tree is. This owns the
+ * two host operations that need one:
+ *
+ * - {@link Checkpoints.capture} records the working tree under an id, and
+ * - {@link Checkpoints.materialize} gives that tree back as a directory for the
+ *   length of one call.
+ *
+ * ## The git binding, and the container constraint it is shaped by
+ *
+ * {@link layerGit} records a checkpoint with `git stash create`, then names the
+ * commit it prints in this repository's own git config rather than with a ref —
+ * see {@link configSection} for why a ref would hand the agent its own edit back
+ * as history. `stash create` is the one git command
+ * that records the working tree and changes nothing else: it does not move the
+ * worktree and does not touch the stash ref. It runs against a shadow
+ * `GIT_DIR` over a copy of the workspace index (see `internal/GitWorktree.ts`),
+ * so it never writes the repository's index and never runs a program the
+ * workspace's `.git` names. That matters more than it sounds. The agent runs `git` in this same
+ * workspace and its own `git diff` is the run's evidence, so a capture that
+ * staged into the real index would be the harness editing the evidence while
+ * recording it. A tree with nothing to record prints nothing, and the
+ * checkpoint is then `HEAD` — which is exactly what the tree is.
+ *
+ * Untracked files are not in the recorded tree, which matches how the rig
+ * captures a patch: `capture-patch.sh` drops paths that did not exist when the
+ * agent started, so a checkpoint holds what a patch would hold.
+ *
+ * The materialization is a detached checkout at `<root>/.flows-checkpoints/<id>-<lease>`
+ * — **inside** the workspace, which looks wrong and is the only thing that
+ * works. A benchmark check runs through `docker exec` inside `/testbed`, and
+ * `/testbed` is a bind mount of the live workspace. A scratch checkout anywhere
+ * else on the host is simply not visible to the container, so the call would run
+ * against a path that does not exist. Placed under the workspace it is visible
+ * at the same subpath under the mount, needs no second mount, and needs no
+ * change to how the rig starts its container. `TestRun`'s `against: "base"`
+ * reached the same conclusion first and this reuses its shape;
+ * `evals/swebench/run-instance.sh` excludes the directory from patch capture for
+ * the same reason it excludes `.flows-test-base`.
+ *
+ * The checkout is added and removed around **one call**, which is stricter than
+ * the frame lifetime the design asks for and much simpler: there is no cache to
+ * invalidate, no id to leak, and a checkpoint used by three calls pays three
+ * checkouts rather than risking one stale directory. A run that reuses a
+ * checkpoint across frames simply re-materializes it, because the ref is what
+ * persists.
+ *
+ * ## What can be pointed at a checkpoint, and what cannot
+ *
+ * {@link relocate} is the closed answer, and `Relocate.ts` owns it. That half
+ * knows the input shapes of `bash`, `read`, `ls`, `grep` and `glob`; this half
+ * knows git. They change for different reasons, so they are different modules,
+ * and {@link relocate} is re-exported here because the harness reaches the whole
+ * feature through this one.
+ *
+ * @since 1.0.0
+ */
+import { ChildProcessSpawner } from "@smthrs/kernel/ChildProcessSpawner";
+import { Context, Effect, Layer, Schema } from "effect";
+import * as Container from "./Container.ts";
+import * as StdError from "./StdError.ts";
+/**
+ * The id naming the tree a run opened on.
+ *
+ * It is not minted: the host either recorded one before the agent started or it
+ * did not. {@link layerGit} resolves it to {@link TestRunner.captureBase} and
+ * then to `HEAD`, which is the same precedence `TestRun` uses for the same
+ * question — so a workspace that has one answer for a baseline has one answer
+ * for both.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const baseId = "base";
+/**
+ * The directory checkpoints are materialized into, relative to the repository
+ * root and therefore also relative to a container's view of it.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const scratchDirectory = ".flows-checkpoints";
+/**
+ * The git-config section {@link layerGit} records minted checkpoints under.
+ *
+ * Config and **not a ref**, and that is the whole of the decision. A ref is
+ * history: `git log --all` lists it, `git show` prints it, and `git log --all
+ * -S` searches it — so a checkpoint named by a ref would hand an agent a commit
+ * containing its own edit and let it read that back as if it were upstream
+ * work. That exact class cost the measured program real money before the rig
+ * moved jj's store out of the workspace (`evals/swebench/run-instance.sh`:
+ * django-13346 applied two of its own snapshots as a fake fix), and a ref here
+ * would reintroduce it one wave later.
+ *
+ * The commit object itself is unreferenced. It stays alive for the life of the
+ * run — nothing in a run prunes — and a checkout by id works perfectly well,
+ * which is measured in `CheckpointsFixture.test.ts`. So the tree is reachable
+ * by id and no command that walks refs can reach it:
+ * `git log`, `git log --all`, `git log -S` and `git show <ref>` all answer
+ * exactly as they did before the capture.
+ *
+ * One command still sees it, measured rather than argued in
+ * `CheckpointsFixture.test.ts`: `git fsck` reports it as a dangling commit,
+ * because that is what an unreferenced commit is. A checkout is a standalone
+ * repository, not a worktree of this one, so `git log --all` does not list it
+ * even while a call runs in it. It is not reachable by a name that looks like project history, and the cell
+ * contract's environment section says outright that a dangling commit is this
+ * harness holding the agent's own tree — which is the half of the django-13346
+ * lesson that a store cannot enforce.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const configSection = "flows-checkpoint";
+declare const Snapshot_base: Schema.Class<Snapshot, Schema.Struct<{
+    readonly id: Schema.String;
+    readonly ref: Schema.String;
+}>, {}>;
+/**
+ * One tree this run has pinned.
+ *
+ * `ref` is the store's own name for it. Nothing above this module interprets
+ * it; it travels so the journal says which tree a checkpointed call read.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export declare class Snapshot extends Snapshot_base {
+}
+/**
+ * A tree handed back as a directory, for the length of one call.
+ *
+ * `host` is where the process running on this machine finds it. `guest` is
+ * where a container finds the same directory, which is the same path when no
+ * container is in play. They differ exactly as `TestRunner.Runner`'s `cwd` and
+ * `root` differ, and for the same reason: one directory, two names.
+ *
+ * `root` and `guestRoot` are the workspace itself under those same two names.
+ * They travel because a call that named a directory *inside* the workspace has
+ * to keep it: a check that runs in `tests/` and is pointed at a checkpoint must
+ * run in the checkpoint's `tests/`, not at its top. Silently dropping that
+ * subpath is how a baseline comes back failing for a reason nobody chose, which
+ * is the one failure a checkpoint exists to make impossible.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Materialized {
+    readonly id: string;
+    readonly host: string;
+    readonly guest: string;
+    /** The workspace this checkpoint is a tree of, as this machine names it. */
+    readonly root: string;
+    /** The workspace as a container names it; the same as {@link Materialized.root} when none does. */
+    readonly guestRoot: string;
+}
+/**
+ * The two host operations a checkpoint needs.
+ *
+ * @category services
+ * @since 1.0.0
+ */
+export interface Checkpoints {
+    /** Records the working tree as it stands, under `id`. */
+    readonly capture: (id: string) => Effect.Effect<Snapshot, StdError.StdError>;
+    /**
+     * Hands `id` back as a directory for the length of the effect it wraps.
+     *
+     * Scoped rather than returned, because the directory has to be removed
+     * however the call ends — a benchmark run killed at its wall-clock budget
+     * would otherwise leave a second checkout of the whole repository in a tree
+     * whose diff is the run's answer.
+     */
+    readonly materialize: <A, E, R>(id: string, use: (materialized: Materialized) => Effect.Effect<A, E, R>) => Effect.Effect<A, E | StdError.StdError, R>;
+}
+/**
+ * The {@link Checkpoints} service tag.
+ *
+ * @category services
+ * @since 1.0.0
+ */
+export declare const Checkpoints: Context.Service<Checkpoints, Checkpoints>;
+/**
+ * Builds a store from its two operations.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const make: (service: Checkpoints) => Checkpoints;
+/**
+ * The refusal a host with nowhere to pin a tree answers with.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export declare const unavailable: (id: string) => StdError.StdError;
+/**
+ * Builds a store for a host that pins nothing.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const makeNoop: () => Checkpoints;
+/**
+ * Provides {@link makeNoop}.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export declare const layerNoop: Layer.Layer<Checkpoints>;
+/**
+ * What {@link layerGit} needs to know about the repository it pins.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface GitOptions {
+    /**
+     * The host path of the git repository whose trees are pinned.
+     *
+     * It is opened when the store is built. A root that was not a repository
+     * then pins nothing, and one whose `.git` later names another repository is
+     * refused with `permission_denied`.
+     */
+    readonly root: string;
+    /**
+     * Where a container sees {@link GitOptions.root}, when one does.
+     *
+     * Absent means there is no container, and the guest path of a materialized
+     * checkpoint is then its host path.
+     */
+    readonly cwd?: string | undefined;
+    /**
+     * The ref naming the tree the run opened on, for {@link baseId}.
+     *
+     * Absent takes `TestRunner.captureBase` and then `HEAD`, which is the
+     * precedence `TestRun` already uses.
+     */
+    readonly baseRef?: string | undefined;
+}
+/**
+ * Builds the git-backed store.
+ *
+ * Every git command that records or checks out a tree runs against a shadow
+ * `GIT_DIR` the harness owns, never the workspace's `.git`, which the agent
+ * can write; see `internal/GitWorktree.ts`. The capture reads a copy of the
+ * workspace index, so the agent's own index is untouched: its `git diff` is the
+ * run's evidence and must not move because the harness recorded something.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const makeGit: (options: GitOptions) => Effect.Effect<Checkpoints, never, ChildProcessSpawner>;
+/**
+ * Provides {@link makeGit}.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export declare const layerGit: (options: GitOptions) => Layer.Layer<Checkpoints, never, ChildProcessSpawner>;
+/**
+ * What {@link makeContainer} needs to know about the container it pins in.
+ *
+ * @category models
+ * @since 1.0.0-rc.8
+ */
+export interface ContainerOptions {
+    /** The container `bash` runs in. */
+    readonly container: string;
+    /** A directory of the repository inside it; absent is the container's own working directory. */
+    readonly cwd?: string | undefined;
+}
+/**
+ * Builds the store for a host whose `bash` runs in one container.
+ *
+ * The repository is the container's, so every git command runs there, through
+ * the same {@link Container.Container} transport `bash` takes. The host store
+ * looked in the CLI's own directory instead and refused every `at` in 112 of
+ * 123 trials of the 2026-10-14 SWE-bench Pro run. This keeps that store's
+ * shape: a checkpoint is a `stash create` commit named in config, and a tree
+ * is checked out under the repository for one call, so a relocated `bash`
+ * call keeps its subdirectory and still finds what the workspace installs
+ * beside it. That git may run what the repository configures, but only inside
+ * the container the agent already commands.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.8
+ */
+export declare const makeContainer: (options: ContainerOptions) => Effect.Effect<Checkpoints, never, ChildProcessSpawner | Container.Container>;
+/**
+ * Provides {@link makeContainer}.
+ *
+ * @category layers
+ * @since 1.0.0-rc.8
+ */
+export declare const layerContainer: (options: ContainerOptions) => Layer.Layer<Checkpoints, never, ChildProcessSpawner | Container.Container>;
+/**
+ * Rewrites one call's input so the call runs against a materialized checkpoint.
+ *
+ * Re-exported from {@link Relocate}, which owns the table of flows and fields
+ * this rewrite is driven by. It is exported here because the harness reaches the
+ * whole checkpoint feature through this module.
+ *
+ * @category conversions
+ * @since 1.0.0
+ */
+export { relocate, type Relocation } from "./Relocate.ts";
+//# sourceMappingURL=Checkpoints.d.ts.map

package/dist/esm/Checkpoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Checkpoints.d.ts","sourceRoot":"","sources":["../../src/Checkpoints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAA;AACxE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAa,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAClE,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAA;AAK3C,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAGzC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,MAAM,SAAS,CAAA;AAE5B;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,uBAA0B,CAAA;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,aAAa,qBAAqB,CAAA;;;;;AAE/C;;;;;;;;GAQG;AACH,qBAAa,QAAS,SAAQ,aAG5B;CAAG;AAEL;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,mGAAmG;IACnG,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAA;IAC5E;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAC5B,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,CAAC,YAAY,EAAE,YAAY,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KACxD,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAA;CAChD;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,EAAE,OAAO,CAAC,OAAO,CAAC,WAAW,EAAE,WAAW,CAA8C,CAAA;AAEhH;;;;;GAKG;AACH,eAAO,MAAM,IAAI,GAAI,SAAS,WAAW,KAAG,WAAsC,CAAA;AAElF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,IAAI,MAAM,KAAG,QAAQ,CAAC,QAI9C,CAAA;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,QAAO,WAIxB,CAAA;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,WAAW,CAA0C,CAAA;AAEzF;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACtC;AAYD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,OAAO,GAClB,SAAS,UAAU,KAClB,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,EAAE,mBAAmB,CASpD,CAAA;AAwHJ;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,GAAI,SAAS,UAAU,KAAG,KAAK,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,EAAE,mBAAmB,CACrD,CAAA;AAE7C;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,gGAAgG;IAChG,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAClC;AA4CD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,aAAa,GACxB,SAAS,gBAAgB,KACxB,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,EAAE,mBAAmB,GAAG,SAAS,CAAC,SAAS,CAgD1E,CAAA;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GACzB,SAAS,gBAAgB,KACxB,KAAK,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,EAAE,mBAAmB,GAAG,SAAS,CAAC,SAAS,CACzB,CAAA;AAEnD;;;;;;;;;GASG;AACH,OAAO,EAAE,QAAQ,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAA"}