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

package/dist/esm/Checkpoints.d.ts

@@ -0,0 +1,279 @@
+/**
+ * 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 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. */
+    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>;
+/**
+ * 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":"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"}

package/dist/esm/Checkpoints.js

@@ -0,0 +1,298 @@
+/**
+ * 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 { GitWorktree } from "./internal/GitWorktree.js";
+import { withoutTrailingSlash } from "./internal/Paths.js";
+import * as Prune from "./internal/Prune.js";
+import * as StdError from "./StdError.js";
+import * as TestRunner from "./TestRunner.js";
+/**
+ * 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 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 const scratchDirectory = Prune.checkpointScratch;
+/**
+ * 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 const configSection = "flows-checkpoint";
+/**
+ * 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 class Snapshot extends Schema.Class("@smthrs/std/Checkpoints/Snapshot")({
+    id: Schema.String,
+    ref: Schema.String
+}) {
+}
+/**
+ * The {@link Checkpoints} service tag.
+ *
+ * @category services
+ * @since 1.0.0
+ */
+export const Checkpoints = Context.Service("@smthrs/std/Checkpoints");
+/**
+ * Builds a store from its two operations.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const make = (service) => Checkpoints.of(service);
+/**
+ * The refusal a host with nowhere to pin a tree answers with.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export const unavailable = (id) => new StdError.StdError({
+    code: "provider_unavailable",
+    message: `This host pins no trees, so it holds no checkpoint "${id}". Take the reading on the live tree instead.`
+});
+/**
+ * Builds a store for a host that pins nothing.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const makeNoop = () => make({
+    capture: (id) => Effect.fail(unavailable(id)),
+    materialize: (id) => Effect.fail(unavailable(id))
+});
+/**
+ * Provides {@link makeNoop}.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export const layerNoop = Layer.succeed(Checkpoints, makeNoop());
+const failed = (message, code = "command_failed") => new StdError.StdError({ code, message });
+/**
+ * A checkpoint id, restricted to what can safely become a git-config key and a
+ * directory name. No dots: a dot would split the config key into another
+ * subsection.
+ */
+const namable = /^[A-Za-z0-9][A-Za-z0-9-]*$/;
+/**
+ * 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 const makeGit = (options) => Effect.gen(function* () {
+    const spawner = yield* ChildProcessSpawner;
+    return gitStore(options, spawner);
+});
+/**
+ * The store itself, with the spawner it runs git through already resolved.
+ *
+ * Resolving it here rather than threading it through {@link Checkpoints} keeps
+ * the service's own requirement empty, which is what lets a browser host bind
+ * {@link layerNoop} against the identical interface — the same shape
+ * `TestRunner` and `Container` take.
+ */
+const gitStore = (options, spawner) => {
+    const spawn = (effect) => Effect.provideService(effect, ChildProcessSpawner, spawner);
+    const root = withoutTrailingSlash(options.root);
+    const guestRoot = options.cwd === undefined ? root : withoutTrailingSlash(options.cwd);
+    const keyOf = (id) => `${configSection}.${id}`;
+    const baseRefs = options.baseRef === undefined ? [TestRunner.captureBase, "HEAD"] : [options.baseRef];
+    /**
+     * The commit one id names.
+     *
+     * `base` is the one id nobody mints, so it is resolved from refs — the same
+     * precedence `TestRun` uses. Every other id was recorded by {@link capture}
+     * into this repository's config file, which is where a checkpoint is named
+     * *without* becoming history. See {@link configSection}.
+     */
+    const commitOf = (id) => Effect.gen(function* () {
+        if (id === baseId)
+            return (yield* GitWorktree.resolveCommit(root, baseRefs)).commit;
+        const repository = yield* GitWorktree.open(root);
+        const found = yield* GitWorktree.config(repository, ["--get", keyOf(id)]);
+        const commit = found.stdout.trim();
+        if (found.exitCode !== 0 || commit === "") {
+            return yield* Effect.fail(failed(`No checkpoint is stored under ${id} in ${root}. Take the reading on the live tree instead.`, "not_found"));
+        }
+        return commit;
+    });
+    const capture = (id) => spawn(Effect.gen(function* () {
+        if (!namable.test(id)) {
+            return yield* Effect.fail(failed(`A checkpoint id must match ${namable.source}; ${id} does not.`, "invalid_input"));
+        }
+        const repository = yield* GitWorktree.open(root);
+        const commit = yield* GitWorktree.withShadow(repository, (shadow) => Effect.gen(function* () {
+            const head = (yield* GitWorktree.resolveCommit(root, ["HEAD"])).commit;
+            yield* shadow.adoptIndex;
+            const pinned = yield* shadow.git(["update-ref", "--no-deref", "HEAD", head]);
+            if (pinned.exitCode !== 0) {
+                return yield* Effect.fail(failed(`Could not record the working tree: ${pinned.stderr.trim()}`));
+            }
+            const recorded = yield* shadow.git(["stash", "create", `flows checkpoint ${id}`], root);
+            if (recorded.exitCode !== 0) {
+                return yield* Effect.fail(failed(`Could not record the working tree: ${recorded.stderr.trim()}`));
+            }
+            // Nothing to record means the working tree IS the commit it is on, so
+            // that commit is the checkpoint. `stash create` says so by printing
+            // nothing, which is not an error and must not be read as one.
+            return recorded.stdout.trim() === "" ? head : recorded.stdout.trim();
+        }));
+        const named = yield* GitWorktree.config(repository, [keyOf(id), commit]);
+        if (named.exitCode !== 0) {
+            return yield* Effect.fail(failed(`Could not name the checkpoint: ${named.stderr.trim()}`));
+        }
+        return new Snapshot({ id, ref: commit });
+    }));
+    const materialize = (id, use) => Effect.gen(function* () {
+        if (!namable.test(id)) {
+            return yield* Effect.fail(failed(`A checkpoint id must match ${namable.source}; ${id} does not.`, "invalid_input"));
+        }
+        const commit = yield* spawn(commitOf(id));
+        const context = yield* Effect.context();
+        return yield* GitWorktree.withDetachedWorktree(root, `${scratchDirectory}/${id}`, commit, (host) => use({ id, host, guest: `${guestRoot}${host.slice(root.length)}`, root, guestRoot }).pipe(Effect.provideContext(context))).pipe(Effect.provideService(ChildProcessSpawner, spawner));
+    });
+    return make({ capture, materialize });
+};
+/**
+ * Provides {@link makeGit}.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export const layerGit = (options) => Layer.effect(Checkpoints)(makeGit(options));
+/**
+ * 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 } from "./Relocate.js";
+//# sourceMappingURL=Checkpoints.js.map

package/dist/esm/Checkpoints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Checkpoints.js","sourceRoot":"","sources":["../../src/Checkpoints.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Pinned trees, and the scratch checkouts a call runs against.\n *\n * A checkpoint is a **value**: minting one changes nothing about the workspace,\n * and running a call against one leaves the live tree exactly as it stands.\n * That is the whole of what it buys. Before it existed, the only way a run\n * could answer \"did this command fail before my change\" was to undo the change\n * — and the journals price that exactly. On `sympy__sympy-13878` the r95repl\n * lane applied one byte-identical 4,789-character patch **five times**, four of\n * those applications preceded by `git checkout -- sympy/stats/crv_types.py`,\n * because a clean fails-before proof required reverting the very work it was\n * meant to prove.\n *\n * This module is the host half of `@smthrs/harness`'s `ctx.checkpoint()` and\n * `ctx.call(flow, input, { at })`. The harness owns the surface, the identity,\n * the bound and the refusals; nothing in it knows what a tree is. This owns the\n * two host operations that need one:\n *\n * - {@link Checkpoints.capture} records the working tree under an id, and\n * - {@link Checkpoints.materialize} gives that tree back as a directory for the\n *   length of one call.\n *\n * ## The git binding, and the container constraint it is shaped by\n *\n * {@link layerGit} records a checkpoint with `git stash create`, then names the\n * commit it prints in this repository's own git config rather than with a ref —\n * see {@link configSection} for why a ref would hand the agent its own edit back\n * as history. `stash create` is the one git command\n * that records the working tree and changes nothing else: it does not move the\n * worktree and does not touch the stash ref. It runs against a shadow\n * `GIT_DIR` over a copy of the workspace index (see `internal/GitWorktree.ts`),\n * so it never writes the repository's index and never runs a program the\n * workspace's `.git` names. That matters more than it sounds. The agent runs `git` in this same\n * workspace and its own `git diff` is the run's evidence, so a capture that\n * staged into the real index would be the harness editing the evidence while\n * recording it. A tree with nothing to record prints nothing, and the\n * checkpoint is then `HEAD` — which is exactly what the tree is.\n *\n * Untracked files are not in the recorded tree, which matches how the rig\n * captures a patch: `capture-patch.sh` drops paths that did not exist when the\n * agent started, so a checkpoint holds what a patch would hold.\n *\n * The materialization is a detached checkout at `<root>/.flows-checkpoints/<id>-<lease>`\n * — **inside** the workspace, which looks wrong and is the only thing that\n * works. A benchmark check runs through `docker exec` inside `/testbed`, and\n * `/testbed` is a bind mount of the live workspace. A scratch checkout anywhere\n * else on the host is simply not visible to the container, so the call would run\n * against a path that does not exist. Placed under the workspace it is visible\n * at the same subpath under the mount, needs no second mount, and needs no\n * change to how the rig starts its container. `TestRun`'s `against: \"base\"`\n * reached the same conclusion first and this reuses its shape;\n * `evals/swebench/run-instance.sh` excludes the directory from patch capture for\n * the same reason it excludes `.flows-test-base`.\n *\n * The checkout is added and removed around **one call**, which is stricter than\n * the frame lifetime the design asks for and much simpler: there is no cache to\n * invalidate, no id to leak, and a checkpoint used by three calls pays three\n * checkouts rather than risking one stale directory. A run that reuses a\n * checkpoint across frames simply re-materializes it, because the ref is what\n * persists.\n *\n * ## What can be pointed at a checkpoint, and what cannot\n *\n * {@link relocate} is the closed answer, and `Relocate.ts` owns it. That half\n * knows the input shapes of `bash`, `read`, `ls`, `grep` and `glob`; this half\n * knows git. They change for different reasons, so they are different modules,\n * and {@link relocate} is re-exported here because the harness reaches the whole\n * feature through this one.\n *\n * @since 1.0.0\n */\n\nimport { ChildProcessSpawner } from \"@smthrs/kernel/ChildProcessSpawner\"\nimport { Context, Effect, Layer, Schema } from \"effect\"\nimport { GitWorktree } from \"./internal/GitWorktree.ts\"\nimport { withoutTrailingSlash } from \"./internal/Paths.ts\"\nimport * as Prune from \"./internal/Prune.ts\"\nimport * as StdError from \"./StdError.ts\"\nimport * as TestRunner from \"./TestRunner.ts\"\n\n/**\n * The id naming the tree a run opened on.\n *\n * It is not minted: the host either recorded one before the agent started or it\n * did not. {@link layerGit} resolves it to {@link TestRunner.captureBase} and\n * then to `HEAD`, which is the same precedence `TestRun` uses for the same\n * question — so a workspace that has one answer for a baseline has one answer\n * for both.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const baseId = \"base\"\n\n/**\n * The directory checkpoints are materialized into, relative to the repository\n * root and therefore also relative to a container's view of it.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const scratchDirectory = Prune.checkpointScratch\n\n/**\n * The git-config section {@link layerGit} records minted checkpoints under.\n *\n * Config and **not a ref**, and that is the whole of the decision. A ref is\n * history: `git log --all` lists it, `git show` prints it, and `git log --all\n * -S` searches it — so a checkpoint named by a ref would hand an agent a commit\n * containing its own edit and let it read that back as if it were upstream\n * work. That exact class cost the measured program real money before the rig\n * moved jj's store out of the workspace (`evals/swebench/run-instance.sh`:\n * django-13346 applied two of its own snapshots as a fake fix), and a ref here\n * would reintroduce it one wave later.\n *\n * The commit object itself is unreferenced. It stays alive for the life of the\n * run — nothing in a run prunes — and a checkout by id works perfectly well,\n * which is measured in `CheckpointsFixture.test.ts`. So the tree is reachable\n * by id and no command that walks refs can reach it:\n * `git log`, `git log --all`, `git log -S` and `git show <ref>` all answer\n * exactly as they did before the capture.\n *\n * One command still sees it, measured rather than argued in\n * `CheckpointsFixture.test.ts`: `git fsck` reports it as a dangling commit,\n * because that is what an unreferenced commit is. A checkout is a standalone\n * repository, not a worktree of this one, so `git log --all` does not list it\n * even while a call runs in it. It is not reachable by a name that looks like project history, and the cell\n * contract's environment section says outright that a dangling commit is this\n * harness holding the agent's own tree — which is the half of the django-13346\n * lesson that a store cannot enforce.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const configSection = \"flows-checkpoint\"\n\n/**\n * One tree this run has pinned.\n *\n * `ref` is the store's own name for it. Nothing above this module interprets\n * it; it travels so the journal says which tree a checkpointed call read.\n *\n * @category models\n * @since 1.0.0\n */\nexport class Snapshot extends Schema.Class<Snapshot>(\"@smthrs/std/Checkpoints/Snapshot\")({\n  id: Schema.String,\n  ref: Schema.String\n}) {}\n\n/**\n * A tree handed back as a directory, for the length of one call.\n *\n * `host` is where the process running on this machine finds it. `guest` is\n * where a container finds the same directory, which is the same path when no\n * container is in play. They differ exactly as `TestRunner.Runner`'s `cwd` and\n * `root` differ, and for the same reason: one directory, two names.\n *\n * `root` and `guestRoot` are the workspace itself under those same two names.\n * They travel because a call that named a directory *inside* the workspace has\n * to keep it: a check that runs in `tests/` and is pointed at a checkpoint must\n * run in the checkpoint's `tests/`, not at its top. Silently dropping that\n * subpath is how a baseline comes back failing for a reason nobody chose, which\n * is the one failure a checkpoint exists to make impossible.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Materialized {\n  readonly id: string\n  readonly host: string\n  readonly guest: string\n  /** The workspace this checkpoint is a tree of, as this machine names it. */\n  readonly root: string\n  /** The workspace as a container names it; the same as {@link Materialized.root} when none does. */\n  readonly guestRoot: string\n}\n\n/**\n * The two host operations a checkpoint needs.\n *\n * @category services\n * @since 1.0.0\n */\nexport interface Checkpoints {\n  /** Records the working tree as it stands, under `id`. */\n  readonly capture: (id: string) => Effect.Effect<Snapshot, StdError.StdError>\n  /**\n   * Hands `id` back as a directory for the length of the effect it wraps.\n   *\n   * Scoped rather than returned, because the directory has to be removed\n   * however the call ends — a benchmark run killed at its wall-clock budget\n   * would otherwise leave a second checkout of the whole repository in a tree\n   * whose diff is the run's answer.\n   */\n  readonly materialize: <A, E, R>(\n    id: string,\n    use: (materialized: Materialized) => Effect.Effect<A, E, R>\n  ) => Effect.Effect<A, E | StdError.StdError, R>\n}\n\n/**\n * The {@link Checkpoints} service tag.\n *\n * @category services\n * @since 1.0.0\n */\nexport const Checkpoints: Context.Service<Checkpoints, Checkpoints> = Context.Service(\"@smthrs/std/Checkpoints\")\n\n/**\n * Builds a store from its two operations.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const make = (service: Checkpoints): Checkpoints => Checkpoints.of(service)\n\n/**\n * The refusal a host with nowhere to pin a tree answers with.\n *\n * @category errors\n * @since 1.0.0\n */\nexport const unavailable = (id: string): StdError.StdError =>\n  new StdError.StdError({\n    code: \"provider_unavailable\",\n    message: `This host pins no trees, so it holds no checkpoint \"${id}\". Take the reading on the live tree instead.`\n  })\n\n/**\n * Builds a store for a host that pins nothing.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const makeNoop = (): Checkpoints =>\n  make({\n    capture: (id) => Effect.fail(unavailable(id)),\n    materialize: (id) => Effect.fail(unavailable(id))\n  })\n\n/**\n * Provides {@link makeNoop}.\n *\n * @category layers\n * @since 1.0.0\n */\nexport const layerNoop: Layer.Layer<Checkpoints> = Layer.succeed(Checkpoints, makeNoop())\n\n/**\n * What {@link layerGit} needs to know about the repository it pins.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface GitOptions {\n  /** The host path of the git repository whose trees are pinned. */\n  readonly root: string\n  /**\n   * Where a container sees {@link GitOptions.root}, when one does.\n   *\n   * Absent means there is no container, and the guest path of a materialized\n   * checkpoint is then its host path.\n   */\n  readonly cwd?: string | undefined\n  /**\n   * The ref naming the tree the run opened on, for {@link baseId}.\n   *\n   * Absent takes `TestRunner.captureBase` and then `HEAD`, which is the\n   * precedence `TestRun` already uses.\n   */\n  readonly baseRef?: string | undefined\n}\n\nconst failed = (message: string, code: StdError.Code = \"command_failed\"): StdError.StdError =>\n  new StdError.StdError({ code, message })\n\n/**\n * A checkpoint id, restricted to what can safely become a git-config key and a\n * directory name. No dots: a dot would split the config key into another\n * subsection.\n */\nconst namable = /^[A-Za-z0-9][A-Za-z0-9-]*$/\n\n/**\n * Builds the git-backed store.\n *\n * Every git command that records or checks out a tree runs against a shadow\n * `GIT_DIR` the harness owns, never the workspace's `.git`, which the agent\n * can write; see `internal/GitWorktree.ts`. The capture reads a copy of the\n * workspace index, so the agent's own index is untouched: its `git diff` is the\n * run's evidence and must not move because the harness recorded something.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const makeGit = (\n  options: GitOptions\n): Effect.Effect<Checkpoints, never, ChildProcessSpawner> =>\n  Effect.gen(function*() {\n    const spawner = yield* ChildProcessSpawner\n    return gitStore(options, spawner)\n  })\n\n/**\n * The store itself, with the spawner it runs git through already resolved.\n *\n * Resolving it here rather than threading it through {@link Checkpoints} keeps\n * the service's own requirement empty, which is what lets a browser host bind\n * {@link layerNoop} against the identical interface — the same shape\n * `TestRunner` and `Container` take.\n */\nconst gitStore = (options: GitOptions, spawner: ChildProcessSpawner[\"Service\"]): Checkpoints => {\n  const spawn = <A, E>(effect: Effect.Effect<A, E, ChildProcessSpawner>): Effect.Effect<A, E> =>\n    Effect.provideService(effect, ChildProcessSpawner, spawner)\n  const root = withoutTrailingSlash(options.root)\n  const guestRoot = options.cwd === undefined ? root : withoutTrailingSlash(options.cwd)\n  const keyOf = (id: string) => `${configSection}.${id}`\n  const baseRefs = options.baseRef === undefined ? [TestRunner.captureBase, \"HEAD\"] : [options.baseRef]\n\n  /**\n   * The commit one id names.\n   *\n   * `base` is the one id nobody mints, so it is resolved from refs — the same\n   * precedence `TestRun` uses. Every other id was recorded by {@link capture}\n   * into this repository's config file, which is where a checkpoint is named\n   * *without* becoming history. See {@link configSection}.\n   */\n  const commitOf = (id: string) =>\n    Effect.gen(function*() {\n      if (id === baseId) return (yield* GitWorktree.resolveCommit(root, baseRefs)).commit\n      const repository = yield* GitWorktree.open(root)\n      const found = yield* GitWorktree.config(repository, [\"--get\", keyOf(id)])\n      const commit = found.stdout.trim()\n      if (found.exitCode !== 0 || commit === \"\") {\n        return yield* Effect.fail(\n          failed(\n            `No checkpoint is stored under ${id} in ${root}. Take the reading on the live tree instead.`,\n            \"not_found\"\n          )\n        )\n      }\n      return commit\n    })\n\n  const capture = (id: string) =>\n    spawn(Effect.gen(function*() {\n      if (!namable.test(id)) {\n        return yield* Effect.fail(\n          failed(`A checkpoint id must match ${namable.source}; ${id} does not.`, \"invalid_input\")\n        )\n      }\n      const repository = yield* GitWorktree.open(root)\n      const commit = yield* GitWorktree.withShadow(repository, (shadow) =>\n        Effect.gen(function*() {\n          const head = (yield* GitWorktree.resolveCommit(root, [\"HEAD\"])).commit\n          yield* shadow.adoptIndex\n          const pinned = yield* shadow.git([\"update-ref\", \"--no-deref\", \"HEAD\", head])\n          if (pinned.exitCode !== 0) {\n            return yield* Effect.fail(failed(`Could not record the working tree: ${pinned.stderr.trim()}`))\n          }\n          const recorded = yield* shadow.git([\"stash\", \"create\", `flows checkpoint ${id}`], root)\n          if (recorded.exitCode !== 0) {\n            return yield* Effect.fail(failed(`Could not record the working tree: ${recorded.stderr.trim()}`))\n          }\n          // Nothing to record means the working tree IS the commit it is on, so\n          // that commit is the checkpoint. `stash create` says so by printing\n          // nothing, which is not an error and must not be read as one.\n          return recorded.stdout.trim() === \"\" ? head : recorded.stdout.trim()\n        }))\n      const named = yield* GitWorktree.config(repository, [keyOf(id), commit])\n      if (named.exitCode !== 0) {\n        return yield* Effect.fail(failed(`Could not name the checkpoint: ${named.stderr.trim()}`))\n      }\n      return new Snapshot({ id, ref: commit })\n    }))\n\n  const materialize = <A, E, R>(\n    id: string,\n    use: (materialized: Materialized) => Effect.Effect<A, E, R>\n  ): Effect.Effect<A, E | StdError.StdError, R> =>\n    Effect.gen(function*() {\n      if (!namable.test(id)) {\n        return yield* Effect.fail(\n          failed(`A checkpoint id must match ${namable.source}; ${id} does not.`, \"invalid_input\")\n        )\n      }\n      const commit = yield* spawn(commitOf(id))\n      const context = yield* Effect.context<R>()\n      return yield* GitWorktree.withDetachedWorktree(\n        root,\n        `${scratchDirectory}/${id}`,\n        commit,\n        (host) =>\n          use({ id, host, guest: `${guestRoot}${host.slice(root.length)}`, root, guestRoot }).pipe(\n            Effect.provideContext(context)\n          )\n      ).pipe(Effect.provideService(ChildProcessSpawner, spawner))\n    })\n\n  return make({ capture, materialize })\n}\n\n/**\n * Provides {@link makeGit}.\n *\n * @category layers\n * @since 1.0.0\n */\nexport const layerGit = (options: GitOptions): Layer.Layer<Checkpoints, never, ChildProcessSpawner> =>\n  Layer.effect(Checkpoints)(makeGit(options))\n/**\n * Rewrites one call's input so the call runs against a materialized checkpoint.\n *\n * Re-exported from {@link Relocate}, which owns the table of flows and fields\n * this rewrite is driven by. It is exported here because the harness reaches the\n * whole checkpoint feature through this module.\n *\n * @category conversions\n * @since 1.0.0\n */\nexport { relocate, type Relocation } from \"./Relocate.ts\"\n"]}