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

package/dist/cjs/TruncatedOutput.d.ts

@@ -0,0 +1,186 @@
+/**
+ * The truncation ledger: which bytes this run was handed as a fragment.
+ *
+ * A flow that caps a captured stream returns the part that fit and declares the
+ * cut in a sibling flag. What the cell reads is an ordinary string, and by the
+ * time that string reaches a write there is nothing on it that remembers it was
+ * cut — so an agent that restores a file with `git show <rev>:<path>` and writes
+ * the captured stdout back replaces the file with its last 30,000 bytes. That is
+ * not hypothetical: on a graded benchmark instance a 645-line module became its
+ * own tail, the compile check failed with an indentation error, the run repeated
+ * the identical restore without re-reading the flag, and the mangled file was
+ * the answer submitted.
+ *
+ * The call boundary is the only place that sees both halves — the result that
+ * declared the truncation, and the later input carrying those same bytes — so
+ * the ledger lives there. A write of bytes a call already reported as truncated
+ * is refused rather than warned about, because there is no case in which
+ * writing a known fragment over a file is what the caller meant.
+ *
+ * The producing half is `@smthrs/std`: `Bash` declares `stdoutTruncated` beside
+ * `stdout`, and the paged flows declare a bare `truncated` beside the text they
+ * cut. Neither is a shared type — the controller must not depend on the tool
+ * library — so both are read here as documented wire conventions, exactly as
+ * `invalidProbe` is read by `CellTurn`.
+ *
+ * @since 0.1.0
+ */
+import { Schema } from "effect";
+/**
+ * The suffix a flow flags one named payload's truncation with.
+ *
+ * `stdoutTruncated: true` says the sibling `stdout` is a fragment. The prefix
+ * names the field, which is what lets the ledger record what was cut without
+ * knowing the flow.
+ *
+ * @category constants
+ * @since 0.1.0
+ * @slop
+ */
+export declare const flagSuffix = "Truncated";
+/**
+ * The suffix a flow states one named payload's discarded byte count with.
+ *
+ * @category constants
+ * @since 0.1.0
+ * @slop
+ */
+export declare const droppedSuffix = "DroppedBytes";
+/**
+ * The bare flag a single-payload flow declares its truncation with.
+ *
+ * A paged read returns `content` and `truncated`, with no field name to pair
+ * them, so every long string beside the flag is treated as the cut payload.
+ *
+ * @category constants
+ * @since 0.1.0
+ * @slop
+ */
+export declare const flagKey = "truncated";
+/**
+ * Smallest payload, in UTF-8 bytes, the ledger records or refuses.
+ *
+ * The refusal exists because a truncated capture is a file-sized fragment; a
+ * short one is neither destructive to write nor distinctive enough to match
+ * safely. Every real capture clears this by an order of magnitude — a shell
+ * stream is cut at 30,000 bytes and a paged read at 60,000 — so the floor costs
+ * the guard nothing and keeps a one-line notice out of the ledger.
+ *
+ * @category constants
+ * @since 0.1.0
+ * @slop
+ */
+export declare const minimumBytes = 1024;
+/**
+ * How many *distinct* captures one run carries forward.
+ *
+ * The ledger is durable controller state, so it is bounded: the digest of a
+ * capture is what the guard compares, and a run that has produced sixteen newer
+ * fragments is no longer plausibly about to write the seventeenth.
+ *
+ * The bound counts distinct payloads because the run this guard exists for
+ * repeats itself: the graded instance ran the identical `git show` restore
+ * frame after frame. Counting each repetition would let one command evict every
+ * other fragment the run was handed and re-open the hole sixteen calls later.
+ *
+ * @category constants
+ * @since 0.1.0
+ * @slop
+ */
+export declare const retained = 16;
+declare const Capture_base: Schema.Class<Capture, Schema.Struct<{
+    /** The flow whose result declared the cut. */
+    readonly flow: Schema.String;
+    /** The result field that carries the fragment. */
+    readonly field: Schema.String;
+    /** Bytes the flow discarded, as it reported them; zero when it did not say. */
+    readonly droppedBytes: Schema.Int;
+    /** The digest of the exact string the flow returned. */
+    readonly digest: Schema.String;
+}>, {}>;
+/**
+ * One payload a flow returned after cutting it.
+ *
+ * The bytes themselves are not kept. A capture carries their digest, which is
+ * all an exact-match refusal needs and is what keeps the ledger small enough to
+ * live in journaled controller state.
+ *
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export declare class Capture extends Capture_base {
+}
+/**
+ * One input field found to carry the exact bytes of an earlier capture.
+ *
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export interface Reuse {
+    /** Where in the refused input the fragment was found. */
+    readonly path: string;
+    /** The capture those bytes came from. */
+    readonly capture: Capture;
+}
+/**
+ * Reads every truncated payload one settled call result declares.
+ *
+ * @category conversions
+ * @since 0.1.0
+ * @slop
+ */
+export declare const captures: (flow: string, value: Schema.Json) => ReadonlyArray<Capture>;
+/**
+ * Finds the first input field that carries an earlier capture verbatim.
+ *
+ * Only an exact match counts. Content the agent derived from a fragment —
+ * re-indented, spliced, summarized — is its own value and is not this
+ * function's business; the one case being caught is the fragment handed
+ * straight back as if it were whole.
+ *
+ * @category conversions
+ * @since 0.1.0
+ * @slop
+ */
+export declare const reuse: (input: Schema.Json, ledger: ReadonlyArray<Capture>) => Reuse | undefined;
+/**
+ * States why a call carrying a known fragment was refused.
+ *
+ * The message names the alternative, because a refusal an agent cannot act on
+ * costs a frame and changes nothing: a file is restored from git with git
+ * itself, never by piping a revision through captured output.
+ *
+ * @category constructors
+ * @since 0.1.0
+ * @slop
+ */
+export declare const refusal: (flow: string, found: Reuse) => string;
+/**
+ * Bounds the ledger to the {@link retained} most recent distinct captures.
+ *
+ * A repeated call returns the same bytes and so the same digest, and the guard
+ * compares digests, so a second copy adds nothing but costs a slot. Collapsing
+ * them keeps the bound a bound on what the run was handed rather than on how
+ * many times it asked: a cell looping on one truncated `git show` no longer
+ * pushes the fragment it captured before that loop out of the ledger.
+ *
+ * The newest position of a repeated digest is the one kept, so the record
+ * states when the run was last handed those bytes.
+ *
+ * @category conversions
+ * @since 0.1.0
+ * @slop
+ */
+export declare const retain: (ledger: ReadonlyArray<Capture>) => ReadonlyArray<Capture>;
+/**
+ * The ledger schema carried in controller state.
+ *
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export declare const Ledger: Schema.withDecodingDefaultKey<Schema.withConstructorDefault<Schema.$Array<typeof Capture>>, never>;
+export {};
+//# sourceMappingURL=TruncatedOutput.d.ts.map

package/dist/cjs/TruncatedOutput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TruncatedOutput.d.ts","sourceRoot":"","sources":["../../src/TruncatedOutput.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,EAAU,MAAM,EAAE,MAAM,QAAQ,CAAA;AAGvC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,cAAc,CAAA;AAErC;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,iBAAiB,CAAA;AAE3C;;;;;;;;;GASG;AACH,eAAO,MAAM,OAAO,cAAc,CAAA;AAElC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY,OAAO,CAAA;AAEhC;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,QAAQ,KAAK,CAAA;;IAcxB,8CAA8C;;IAE9C,kDAAkD;;IAElD,+EAA+E;;IAE/E,wDAAwD;;;AAlB1D;;;;;;;;;;GAUG;AACH,qBAAa,OAAQ,SAAQ,YAS3B;CAAG;AAEL;;;;;;GAMG;AACH,MAAM,WAAW,KAAK;IACpB,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,yCAAyC;IACzC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;AAsDD;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,GAAI,MAAM,MAAM,EAAE,OAAO,MAAM,CAAC,IAAI,KAAG,aAAa,CAAC,OAAO,CAIhF,CAAA;AA2BD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,KAAK,GAChB,OAAO,MAAM,CAAC,IAAI,EAClB,QAAQ,aAAa,CAAC,OAAO,CAAC,KAC7B,KAAK,GAAG,SAGyE,CAAA;AAEpF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,OAAO,GAAI,MAAM,MAAM,EAAE,OAAO,KAAK,KAAG,MAC6Y,CAAA;AAElc;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,MAAM,GAAI,QAAQ,aAAa,CAAC,OAAO,CAAC,KAAG,aAAa,CAAC,OAAO,CAS5E,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,oGAGlB,CAAA"}

package/dist/cjs/TruncatedOutput.js

@@ -0,0 +1,143 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var TruncatedOutput_exports = {};
+__export(TruncatedOutput_exports, {
+  Capture: () => Capture,
+  Ledger: () => Ledger,
+  captures: () => captures,
+  droppedSuffix: () => droppedSuffix,
+  flagKey: () => flagKey,
+  flagSuffix: () => flagSuffix,
+  minimumBytes: () => minimumBytes,
+  refusal: () => refusal,
+  retain: () => retain,
+  retained: () => retained,
+  reuse: () => reuse
+});
+module.exports = __toCommonJS(TruncatedOutput_exports);
+var Digest = __toESM(require("@smthrs/core/Digest"), 1);
+var import_effect = require("effect");
+var import_nonNegativeSafeInt = require("./internal/nonNegativeSafeInt.js");
+const flagSuffix = "Truncated";
+const droppedSuffix = "DroppedBytes";
+const flagKey = "truncated";
+const minimumBytes = 1024;
+const retained = 16;
+class Capture extends import_effect.Schema.Class("flows/harness/TruncatedOutput/Capture")({
+  /** The flow whose result declared the cut. */
+  flow: import_effect.Schema.String,
+  /** The result field that carries the fragment. */
+  field: import_effect.Schema.String,
+  /** Bytes the flow discarded, as it reported them; zero when it did not say. */
+  droppedBytes: import_nonNegativeSafeInt.NonNegativeSafeInt,
+  /** The digest of the exact string the flow returned. */
+  digest: import_effect.Schema.String
+}) {
+}
+const encoder = new TextEncoder();
+const byteLength = (text) => encoder.encode(text).byteLength;
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const droppedBytes = (node, field) => {
+  const declared = node[`${field}${droppedSuffix}`];
+  return typeof declared === "number" && Number.isSafeInteger(declared) && declared >= 0 ? declared : 0;
+};
+const captureField = (flow, node, field, into) => {
+  const text = node[field];
+  if (typeof text !== "string" || byteLength(text) < minimumBytes) return;
+  into.push(
+    new Capture({
+      flow,
+      field,
+      droppedBytes: droppedBytes(node, field),
+      digest: Digest.digest(text)
+    })
+  );
+};
+const captureNode = (flow, node, into) => {
+  for (const [key, value] of Object.entries(node)) {
+    if (value !== true) continue;
+    if (key === flagKey) {
+      for (const sibling of Object.keys(node)) captureField(flow, node, sibling, into);
+      continue;
+    }
+    if (!key.endsWith(flagSuffix) || key.length === flagSuffix.length) continue;
+    captureField(flow, node, key.slice(0, -flagSuffix.length), into);
+  }
+};
+const collect = (flow, value, into) => {
+  if (Array.isArray(value)) {
+    for (const item of value) collect(flow, item, into);
+    return;
+  }
+  if (!isObject(value)) return;
+  captureNode(flow, value, into);
+  for (const item of Object.values(value)) collect(flow, item, into);
+};
+const captures = (flow, value) => {
+  const found = [];
+  collect(flow, value, found);
+  return found;
+};
+const search = (value, path, known) => {
+  if (typeof value === "string") {
+    if (byteLength(value) < minimumBytes) return void 0;
+    const capture = known.get(Digest.digest(value));
+    return capture === void 0 ? void 0 : { path: path === "" ? "input" : path, capture };
+  }
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index++) {
+      const found = search(value[index], `${path}[${index}]`, known);
+      if (found !== void 0) return found;
+    }
+    return void 0;
+  }
+  if (!isObject(value)) return void 0;
+  for (const [key, member] of Object.entries(value)) {
+    const found = search(member, path === "" ? key : `${path}.${key}`, known);
+    if (found !== void 0) return found;
+  }
+  return void 0;
+};
+const reuse = (input, ledger) => ledger.length === 0 ? void 0 : search(input, "", new Map(ledger.map((capture) => [capture.digest, capture])));
+const refusal = (flow, found) => `Flow ${flow} was refused: its ${found.path} is byte-identical to output this run already returned truncated \u2014 ${found.capture.flow} cut ${found.capture.field} and dropped ${found.capture.droppedBytes} bytes. Those bytes are a fragment of the value, not the value, so writing them replaces the target with a piece of itself. To restore a file from git, run git checkout or git restore on the path; never route file content through captured stdout.`;
+const retain = (ledger) => {
+  const newest = /* @__PURE__ */ new Map();
+  for (const capture of ledger) {
+    newest.delete(capture.digest);
+    newest.set(capture.digest, capture);
+  }
+  if (newest.size === ledger.length && ledger.length <= retained) return ledger;
+  const distinct = [...newest.values()];
+  return distinct.length <= retained ? distinct : distinct.slice(distinct.length - retained);
+};
+const Ledger = import_effect.Schema.Array(Capture).pipe(
+  import_effect.Schema.withConstructorDefault(import_effect.Effect.succeed([])),
+  import_effect.Schema.withDecodingDefaultKey(import_effect.Effect.succeed([]))
+);
+//# sourceMappingURL=TruncatedOutput.js.map

package/dist/cjs/TruncatedOutput.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/TruncatedOutput.ts"],
+  "sourcesContent": ["/**\n * The truncation ledger: which bytes this run was handed as a fragment.\n *\n * A flow that caps a captured stream returns the part that fit and declares the\n * cut in a sibling flag. What the cell reads is an ordinary string, and by the\n * time that string reaches a write there is nothing on it that remembers it was\n * cut \u2014 so an agent that restores a file with `git show <rev>:<path>` and writes\n * the captured stdout back replaces the file with its last 30,000 bytes. That is\n * not hypothetical: on a graded benchmark instance a 645-line module became its\n * own tail, the compile check failed with an indentation error, the run repeated\n * the identical restore without re-reading the flag, and the mangled file was\n * the answer submitted.\n *\n * The call boundary is the only place that sees both halves \u2014 the result that\n * declared the truncation, and the later input carrying those same bytes \u2014 so\n * the ledger lives there. A write of bytes a call already reported as truncated\n * is refused rather than warned about, because there is no case in which\n * writing a known fragment over a file is what the caller meant.\n *\n * The producing half is `@smthrs/std`: `Bash` declares `stdoutTruncated` beside\n * `stdout`, and the paged flows declare a bare `truncated` beside the text they\n * cut. Neither is a shared type \u2014 the controller must not depend on the tool\n * library \u2014 so both are read here as documented wire conventions, exactly as\n * `invalidProbe` is read by `CellTurn`.\n *\n * @since 0.1.0\n */\n\nimport * as Digest from \"@smthrs/core/Digest\"\nimport { Effect, Schema } from \"effect\"\nimport { NonNegativeSafeInt } from \"./internal/nonNegativeSafeInt.ts\"\n\n/**\n * The suffix a flow flags one named payload's truncation with.\n *\n * `stdoutTruncated: true` says the sibling `stdout` is a fragment. The prefix\n * names the field, which is what lets the ledger record what was cut without\n * knowing the flow.\n *\n * @category constants\n * @since 0.1.0\n * @slop\n */\nexport const flagSuffix = \"Truncated\"\n\n/**\n * The suffix a flow states one named payload's discarded byte count with.\n *\n * @category constants\n * @since 0.1.0\n * @slop\n */\nexport const droppedSuffix = \"DroppedBytes\"\n\n/**\n * The bare flag a single-payload flow declares its truncation with.\n *\n * A paged read returns `content` and `truncated`, with no field name to pair\n * them, so every long string beside the flag is treated as the cut payload.\n *\n * @category constants\n * @since 0.1.0\n * @slop\n */\nexport const flagKey = \"truncated\"\n\n/**\n * Smallest payload, in UTF-8 bytes, the ledger records or refuses.\n *\n * The refusal exists because a truncated capture is a file-sized fragment; a\n * short one is neither destructive to write nor distinctive enough to match\n * safely. Every real capture clears this by an order of magnitude \u2014 a shell\n * stream is cut at 30,000 bytes and a paged read at 60,000 \u2014 so the floor costs\n * the guard nothing and keeps a one-line notice out of the ledger.\n *\n * @category constants\n * @since 0.1.0\n * @slop\n */\nexport const minimumBytes = 1024\n\n/**\n * How many *distinct* captures one run carries forward.\n *\n * The ledger is durable controller state, so it is bounded: the digest of a\n * capture is what the guard compares, and a run that has produced sixteen newer\n * fragments is no longer plausibly about to write the seventeenth.\n *\n * The bound counts distinct payloads because the run this guard exists for\n * repeats itself: the graded instance ran the identical `git show` restore\n * frame after frame. Counting each repetition would let one command evict every\n * other fragment the run was handed and re-open the hole sixteen calls later.\n *\n * @category constants\n * @since 0.1.0\n * @slop\n */\nexport const retained = 16\n\n/**\n * One payload a flow returned after cutting it.\n *\n * The bytes themselves are not kept. A capture carries their digest, which is\n * all an exact-match refusal needs and is what keeps the ledger small enough to\n * live in journaled controller state.\n *\n * @category models\n * @since 0.1.0\n * @slop\n */\nexport class Capture extends Schema.Class<Capture>(\"flows/harness/TruncatedOutput/Capture\")({\n  /** The flow whose result declared the cut. */\n  flow: Schema.String,\n  /** The result field that carries the fragment. */\n  field: Schema.String,\n  /** Bytes the flow discarded, as it reported them; zero when it did not say. */\n  droppedBytes: NonNegativeSafeInt,\n  /** The digest of the exact string the flow returned. */\n  digest: Schema.String\n}) {}\n\n/**\n * One input field found to carry the exact bytes of an earlier capture.\n *\n * @category models\n * @since 0.1.0\n * @slop\n */\nexport interface Reuse {\n  /** Where in the refused input the fragment was found. */\n  readonly path: string\n  /** The capture those bytes came from. */\n  readonly capture: Capture\n}\n\nconst encoder = new TextEncoder()\n\nconst byteLength = (text: string): number => encoder.encode(text).byteLength\n\nconst isObject = (value: Schema.Json): value is Schema.JsonObject =>\n  value !== null && typeof value === \"object\" && !Array.isArray(value)\n\nconst droppedBytes = (node: Schema.JsonObject, field: string): number => {\n  const declared = node[`${field}${droppedSuffix}`]\n  return typeof declared === \"number\" && Number.isSafeInteger(declared) && declared >= 0 ? declared : 0\n}\n\nconst captureField = (\n  flow: string,\n  node: Schema.JsonObject,\n  field: string,\n  into: Array<Capture>\n): void => {\n  const text = node[field]\n  if (typeof text !== \"string\" || byteLength(text) < minimumBytes) return\n  into.push(\n    new Capture({\n      flow,\n      field,\n      droppedBytes: droppedBytes(node, field),\n      digest: Digest.digest(text)\n    })\n  )\n}\n\nconst captureNode = (flow: string, node: Schema.JsonObject, into: Array<Capture>): void => {\n  for (const [key, value] of Object.entries(node)) {\n    if (value !== true) continue\n    if (key === flagKey) {\n      for (const sibling of Object.keys(node)) captureField(flow, node, sibling, into)\n      continue\n    }\n    if (!key.endsWith(flagSuffix) || key.length === flagSuffix.length) continue\n    captureField(flow, node, key.slice(0, -flagSuffix.length), into)\n  }\n}\n\nconst collect = (flow: string, value: Schema.Json, into: Array<Capture>): void => {\n  if (Array.isArray(value)) {\n    for (const item of value) collect(flow, item, into)\n    return\n  }\n  if (!isObject(value)) return\n  captureNode(flow, value, into)\n  for (const item of Object.values(value)) collect(flow, item, into)\n}\n\n/**\n * Reads every truncated payload one settled call result declares.\n *\n * @category conversions\n * @since 0.1.0\n * @slop\n */\nexport const captures = (flow: string, value: Schema.Json): ReadonlyArray<Capture> => {\n  const found: Array<Capture> = []\n  collect(flow, value, found)\n  return found\n}\n\nconst search = (\n  value: Schema.Json,\n  path: string,\n  known: ReadonlyMap<string, Capture>\n): Reuse | undefined => {\n  if (typeof value === \"string\") {\n    if (byteLength(value) < minimumBytes) return undefined\n    const capture = known.get(Digest.digest(value))\n    return capture === undefined ? undefined : { path: path === \"\" ? \"input\" : path, capture }\n  }\n  if (Array.isArray(value)) {\n    for (let index = 0; index < value.length; index++) {\n      const found = search(value[index], `${path}[${index}]`, known)\n      if (found !== undefined) return found\n    }\n    return undefined\n  }\n  if (!isObject(value)) return undefined\n  for (const [key, member] of Object.entries(value)) {\n    const found = search(member, path === \"\" ? key : `${path}.${key}`, known)\n    if (found !== undefined) return found\n  }\n  return undefined\n}\n\n/**\n * Finds the first input field that carries an earlier capture verbatim.\n *\n * Only an exact match counts. Content the agent derived from a fragment \u2014\n * re-indented, spliced, summarized \u2014 is its own value and is not this\n * function's business; the one case being caught is the fragment handed\n * straight back as if it were whole.\n *\n * @category conversions\n * @since 0.1.0\n * @slop\n */\nexport const reuse = (\n  input: Schema.Json,\n  ledger: ReadonlyArray<Capture>\n): Reuse | undefined =>\n  ledger.length === 0\n    ? undefined\n    : search(input, \"\", new Map(ledger.map((capture) => [capture.digest, capture])))\n\n/**\n * States why a call carrying a known fragment was refused.\n *\n * The message names the alternative, because a refusal an agent cannot act on\n * costs a frame and changes nothing: a file is restored from git with git\n * itself, never by piping a revision through captured output.\n *\n * @category constructors\n * @since 0.1.0\n * @slop\n */\nexport const refusal = (flow: string, found: Reuse): string =>\n  `Flow ${flow} was refused: its ${found.path} is byte-identical to output this run already returned truncated \u2014 ${found.capture.flow} cut ${found.capture.field} and dropped ${found.capture.droppedBytes} bytes. Those bytes are a fragment of the value, not the value, so writing them replaces the target with a piece of itself. To restore a file from git, run git checkout or git restore on the path; never route file content through captured stdout.`\n\n/**\n * Bounds the ledger to the {@link retained} most recent distinct captures.\n *\n * A repeated call returns the same bytes and so the same digest, and the guard\n * compares digests, so a second copy adds nothing but costs a slot. Collapsing\n * them keeps the bound a bound on what the run was handed rather than on how\n * many times it asked: a cell looping on one truncated `git show` no longer\n * pushes the fragment it captured before that loop out of the ledger.\n *\n * The newest position of a repeated digest is the one kept, so the record\n * states when the run was last handed those bytes.\n *\n * @category conversions\n * @since 0.1.0\n * @slop\n */\nexport const retain = (ledger: ReadonlyArray<Capture>): ReadonlyArray<Capture> => {\n  const newest = new Map<string, Capture>()\n  for (const capture of ledger) {\n    newest.delete(capture.digest)\n    newest.set(capture.digest, capture)\n  }\n  if (newest.size === ledger.length && ledger.length <= retained) return ledger\n  const distinct = [...newest.values()]\n  return distinct.length <= retained ? distinct : distinct.slice(distinct.length - retained)\n}\n\n/**\n * The ledger schema carried in controller state.\n *\n * @category schemas\n * @since 0.1.0\n * @slop\n */\nexport const Ledger = Schema.Array(Capture).pipe(\n  Schema.withConstructorDefault(Effect.succeed<ReadonlyArray<Capture>>([])),\n  Schema.withDecodingDefaultKey(Effect.succeed<ReadonlyArray<Capture>>([]))\n)\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/UnmovedTree.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The completion with nothing behind it.
+ *
+ * A run finishes by claiming its work is done. Every other control in this
+ * package asks whether the *evidence* for that claim holds up. This one asks a
+ * question that comes before evidence: is there anything for the evidence to be
+ * about. A run that has not changed the workspace at any point in its life has
+ * produced nothing, and a sentence describing a change it did not make is not a
+ * result — it is a description of one.
+ *
+ * It is not hypothetical. On a graded benchmark one instance ran seven frames,
+ * issued eleven flow calls — three `read`, seven `grep`, one `bash` — made no
+ * editing call of any kind, and closed all seven frames on the identical
+ * workspace digest the run had opened on. It then completed with "Updated
+ * `AdminSite.catch_all_view()` to preserve query strings when `APPEND_SLASH`
+ * redirects add a trailing slash." The captured patch was zero bytes. The same
+ * instance had resolved in five frames one wave earlier.
+ *
+ * Every armed control let that through, and each for a reason that was correct
+ * about its own subject: the read-only cap is a stall detector and the run
+ * finished below it, the narrowing demand judges the shape of a check and there
+ * was no check to narrow, and the phantom-write veto vetoes a write that was
+ * declared and did not happen — this run declared none. The harness held the
+ * fact that decides it the whole time, in seven `mutation-observed` events on
+ * one digest, and never consulted it at the `complete` transition.
+ *
+ * The comparison is between two measurements the harness already took: the
+ * digest of the tree the run opened on, and the digest the completing frame
+ * closed on. Equal digests mean the tree the completion describes is the tree
+ * the run was handed. Nothing here reads the completion's text, and nothing
+ * here decides whether the run was right: "no change is needed" is a legitimate
+ * answer to a task, and the demand names it as one of the two ways out.
+ *
+ * @since 0.1.0
+ */
+/**
+ * A completion taken over the tree the run was handed.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Unmoved {
+    /** Content address of the workspace the run opened on. */
+    readonly opened: string;
+    /** Content address of the workspace the completing frame closed on. */
+    readonly closed: string;
+}
+/**
+ * Whether a completing frame is finishing on the tree the run started with.
+ *
+ * Both conditions are read off measurements the controller already took, and
+ * both are required:
+ *
+ * 1. the run has an opening measurement that covered the whole tree, and the
+ *    completing frame closed on one — an incomplete walk cannot say a tree held
+ *    still, and an empty digest is recorded for exactly that case;
+ * 2. the two digests are equal.
+ *
+ * Digest equality, rather than a count of frames that reported a mutation, is
+ * what the demand's own sentence claims: that nothing in this workspace differs
+ * from the tree the run opened on. That is true of a run that never wrote and
+ * equally true of a run that wrote and undid it, and the sentence holds in both
+ * cases. A run whose tree moved and stayed moved is not this failure, whatever
+ * else may be wrong with it.
+ *
+ * @category conversions
+ * @since 0.1.0
+ */
+export declare const find: (options: {
+    /** The digest the run opened on; empty when the run never measured one. */
+    readonly opened: string;
+    /** The digest the completing frame closed on; empty when unmeasured. */
+    readonly digest: string;
+    /**
+     * Writes this run recorded on trees the two digests do not cover.
+     *
+     * A `bash` call routed into a container measures that container's working
+     * directory itself and reports a move under the reserved `mutated` key; the
+     * host walk behind `opened` and `digest` never saw that tree. One such write
+     * is the tree moving, and the two digests agreeing says nothing against it.
+     * Absent or zero leaves the comparison exactly as it was.
+     */
+    readonly elsewhere?: number | undefined;
+}) => Unmoved | undefined;
+/**
+ * States that the tree never moved, and names the two answers that end it.
+ *
+ * The two ways out are stated as equals because they are equals. A task whose
+ * right answer is "nothing needs changing" exists, and a run that reaches that
+ * conclusion honestly must be able to say so and finish; a demand that only
+ * accepted an edit would be pushing such a run into making one. What the demand
+ * refuses is the third thing, which is what the recorded run did: a sentence
+ * describing an edit, with no edit behind it.
+ *
+ * The second answer asks for its own working, and the wave that armed this is
+ * why. The run this module was built from was bounced off a fabricated
+ * completion and answered with "No change is needed", from a run that had made
+ * *one* call in its whole life. Nothing is gated on the answer — the harness
+ * cannot know whether the claim is true, and grading it would be the harness
+ * deciding the task — but the sentence no longer hands the exit over for free:
+ * a run that concluded the repository is already correct concluded it from
+ * something, and saying what that was costs a truthful run nothing and costs a
+ * run that checked nothing the whole answer.
+ *
+ * It also says plainly that nothing makes the change for the run, and that the
+ * next answer stands. Anything softer invites a re-submission of the same
+ * frame; anything harder would be the harness grading the run's conclusion.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const demand: (found: Unmoved) => string;
+//# sourceMappingURL=UnmovedTree.d.ts.map

package/dist/cjs/UnmovedTree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UnmovedTree.d.ts","sourceRoot":"","sources":["../../src/UnmovedTree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAIH;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,IAAI,GAAI,SAAS;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACxC,KAAG,OAAO,GAAG,SAI0C,CAAA;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,OAAO,KAAG,MAAwD,CAAA"}

package/dist/cjs/UnmovedTree.js

@@ -0,0 +1,38 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var UnmovedTree_exports = {};
+__export(UnmovedTree_exports, {
+  demand: () => demand,
+  find: () => find
+});
+module.exports = __toCommonJS(UnmovedTree_exports);
+var DemandText = __toESM(require("./internal/demandText.js"), 1);
+const find = (options) => options.opened === "" || options.digest === "" || options.opened !== options.digest || (options.elsewhere ?? 0) > 0 ? void 0 : { opened: options.opened, closed: options.digest };
+const demand = (found) => DemandText.unmoved(found.opened, found.closed);
+//# sourceMappingURL=UnmovedTree.js.map

package/dist/cjs/UnmovedTree.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/UnmovedTree.ts"],
+  "sourcesContent": ["/**\n * The completion with nothing behind it.\n *\n * A run finishes by claiming its work is done. Every other control in this\n * package asks whether the *evidence* for that claim holds up. This one asks a\n * question that comes before evidence: is there anything for the evidence to be\n * about. A run that has not changed the workspace at any point in its life has\n * produced nothing, and a sentence describing a change it did not make is not a\n * result \u2014 it is a description of one.\n *\n * It is not hypothetical. On a graded benchmark one instance ran seven frames,\n * issued eleven flow calls \u2014 three `read`, seven `grep`, one `bash` \u2014 made no\n * editing call of any kind, and closed all seven frames on the identical\n * workspace digest the run had opened on. It then completed with \"Updated\n * `AdminSite.catch_all_view()` to preserve query strings when `APPEND_SLASH`\n * redirects add a trailing slash.\" The captured patch was zero bytes. The same\n * instance had resolved in five frames one wave earlier.\n *\n * Every armed control let that through, and each for a reason that was correct\n * about its own subject: the read-only cap is a stall detector and the run\n * finished below it, the narrowing demand judges the shape of a check and there\n * was no check to narrow, and the phantom-write veto vetoes a write that was\n * declared and did not happen \u2014 this run declared none. The harness held the\n * fact that decides it the whole time, in seven `mutation-observed` events on\n * one digest, and never consulted it at the `complete` transition.\n *\n * The comparison is between two measurements the harness already took: the\n * digest of the tree the run opened on, and the digest the completing frame\n * closed on. Equal digests mean the tree the completion describes is the tree\n * the run was handed. Nothing here reads the completion's text, and nothing\n * here decides whether the run was right: \"no change is needed\" is a legitimate\n * answer to a task, and the demand names it as one of the two ways out.\n *\n * @since 0.1.0\n */\n\nimport * as DemandText from \"./internal/demandText.ts\"\n\n/**\n * A completion taken over the tree the run was handed.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Unmoved {\n  /** Content address of the workspace the run opened on. */\n  readonly opened: string\n  /** Content address of the workspace the completing frame closed on. */\n  readonly closed: string\n}\n\n/**\n * Whether a completing frame is finishing on the tree the run started with.\n *\n * Both conditions are read off measurements the controller already took, and\n * both are required:\n *\n * 1. the run has an opening measurement that covered the whole tree, and the\n *    completing frame closed on one \u2014 an incomplete walk cannot say a tree held\n *    still, and an empty digest is recorded for exactly that case;\n * 2. the two digests are equal.\n *\n * Digest equality, rather than a count of frames that reported a mutation, is\n * what the demand's own sentence claims: that nothing in this workspace differs\n * from the tree the run opened on. That is true of a run that never wrote and\n * equally true of a run that wrote and undid it, and the sentence holds in both\n * cases. A run whose tree moved and stayed moved is not this failure, whatever\n * else may be wrong with it.\n *\n * @category conversions\n * @since 0.1.0\n */\nexport const find = (options: {\n  /** The digest the run opened on; empty when the run never measured one. */\n  readonly opened: string\n  /** The digest the completing frame closed on; empty when unmeasured. */\n  readonly digest: string\n  /**\n   * Writes this run recorded on trees the two digests do not cover.\n   *\n   * A `bash` call routed into a container measures that container's working\n   * directory itself and reports a move under the reserved `mutated` key; the\n   * host walk behind `opened` and `digest` never saw that tree. One such write\n   * is the tree moving, and the two digests agreeing says nothing against it.\n   * Absent or zero leaves the comparison exactly as it was.\n   */\n  readonly elsewhere?: number | undefined\n}): Unmoved | undefined =>\n  options.opened === \"\" || options.digest === \"\" || options.opened !== options.digest ||\n    (options.elsewhere ?? 0) > 0\n    ? undefined\n    : { opened: options.opened, closed: options.digest }\n\n/**\n * States that the tree never moved, and names the two answers that end it.\n *\n * The two ways out are stated as equals because they are equals. A task whose\n * right answer is \"nothing needs changing\" exists, and a run that reaches that\n * conclusion honestly must be able to say so and finish; a demand that only\n * accepted an edit would be pushing such a run into making one. What the demand\n * refuses is the third thing, which is what the recorded run did: a sentence\n * describing an edit, with no edit behind it.\n *\n * The second answer asks for its own working, and the wave that armed this is\n * why. The run this module was built from was bounced off a fabricated\n * completion and answered with \"No change is needed\", from a run that had made\n * *one* call in its whole life. Nothing is gated on the answer \u2014 the harness\n * cannot know whether the claim is true, and grading it would be the harness\n * deciding the task \u2014 but the sentence no longer hands the exit over for free:\n * a run that concluded the repository is already correct concluded it from\n * something, and saying what that was costs a truthful run nothing and costs a\n * run that checked nothing the whole answer.\n *\n * It also says plainly that nothing makes the change for the run, and that the\n * next answer stands. Anything softer invites a re-submission of the same\n * frame; anything harder would be the harness grading the run's conclusion.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const demand = (found: Unmoved): string => DemandText.unmoved(found.opened, found.closed)\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAoCA,iBAA4B;AAoCrB,MAAM,OAAO,CAAC,YAgBnB,QAAQ,WAAW,MAAM,QAAQ,WAAW,MAAM,QAAQ,WAAW,QAAQ,WAC1E,QAAQ,aAAa,KAAK,IACzB,SACA,EAAE,QAAQ,QAAQ,QAAQ,QAAQ,QAAQ,OAAO;AA6BhD,MAAM,SAAS,CAAC,UAA2B,WAAW,QAAQ,MAAM,QAAQ,MAAM,MAAM;",
+  "names": []
+}