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

package/dist/cjs/Probe.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Telling an invalid probe from a failing check.
+ *
+ * A non-zero exit is a runner's verdict about the code it ran. It is not the
+ * runner's verdict about the command it was handed. When an invocation names a
+ * test, a file, a module, an environment, or a program that does not exist, the
+ * runner never reaches any code and still exits non-zero — and at the tool
+ * boundary that is indistinguishable from the bug reproducing. A SWE-bench run
+ * lost thirty-nine frames to exactly that: the reproduction named a test method
+ * the class does not define, so it read `exitCode: 1` before the edit and
+ * `exitCode: 1` after it, and the agent could not tell it had already won.
+ *
+ * This module names that class. The taxonomy is one idea — *the invocation
+ * named something that does not exist* — and {@link Reason} enumerates the five
+ * things that something can be. An enumerated answer over prose is a judgment,
+ * so Jev makes it: {@link classify} asks the `probe/attribution` classifier
+ * whether this exit describes the tree or one of the five, and whether a runner
+ * ran anything at all. Nothing here reads the output itself. The judgment used
+ * to be nine regexes over runner wording, vetoed by two more over runner
+ * tallies, and every phrase they matched is also printed by genuine failures —
+ * a bug that *is* an import error, a test that asserts on a shell message — so
+ * precision cost recall and both cost maintenance.
+ *
+ * A zero exit needs no judgment: it belongs to the tree, whatever it printed.
+ * A non-zero exit, including 126 or 127, needs attribution. A runner can
+ * execute its tests and return either status, so neither proves that the shell
+ * refused to launch the check.
+ *
+ * There is no third path. When the judge does not answer, {@link unjudged}
+ * turns its failure into the caller's typed failure: a guess about whether a
+ * reproduction reproduced is worth less than nothing, and the caller can say
+ * that a result was not judged where it cannot say that a guess was wrong.
+ *
+ * A flow that can tell the difference reports it under the reserved output key
+ * {@link key}. The harness reads that key off an otherwise opaque call result
+ * and refuses to count such a result as evidence that anything about the tree
+ * changed, which is what stops a broken probe from being cited as a
+ * reproduction.
+ *
+ * @since 1.0.0
+ */
+import * as Classifier from "@smthrs/model/Classifier";
+import type * as Evaluator from "@smthrs/model/Evaluator";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as StdError from "./StdError.ts";
+/**
+ * The reserved output key a flow reports an invalid probe under.
+ *
+ * Stated as a constant because it is a wire contract with the harness rather
+ * than a shared type: `@smthrs/harness` reads this key off a `Schema.Json`
+ * result and must not depend on the tool library to do it.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export declare const key = "invalidProbe";
+/**
+ * What the invocation named that does not exist.
+ *
+ * Five members, and the classifier offers exactly these five beside `tree`.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Reason: Schema.Literals<readonly ["unknown-command", "unknown-test", "unknown-path", "unknown-module", "unknown-environment"]>;
+/**
+ * What the invocation named that does not exist.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Reason = typeof Reason.Type;
+/**
+ * One command's failure, attributed to the command rather than to the tree.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const InvalidProbe: Schema.Struct<{
+    readonly reason: Schema.Literals<readonly ["unknown-command", "unknown-test", "unknown-path", "unknown-module", "unknown-environment"]>;
+    readonly evidence: Schema.String;
+    readonly message: Schema.String;
+}>;
+/**
+ * One command's failure, attributed to the command rather than to the tree.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type InvalidProbe = typeof InvalidProbe.Type;
+/**
+ * What one command's exit code was attributed to.
+ *
+ * `to` is the tree, or the kind of name the command could not resolve, and
+ * `invalidProbe` is present in exactly the second case, ready to report under
+ * {@link key}. `executed` is the judge's separate reading of whether a runner
+ * ran any test, absent when nothing was asked.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Attribution {
+    readonly to: "tree" | Reason;
+    readonly executed?: boolean;
+    readonly invalidProbe?: InvalidProbe;
+}
+/**
+ * The confidence an attribution needs before it outranks the tree.
+ *
+ * Below it the failure is the tree's, which is the reading that leaves the
+ * caller the output it would have had anyway. A missed invalid probe costs a
+ * reader nothing it had; a false one tells it its reproduction proved nothing.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const CONFIDENCE_FLOOR = 0.7;
+/**
+ * The most output bytes one judgment carries, newest kept.
+ *
+ * A runner prints its refusal last, and the classifier's whole state is held
+ * to 32 KiB.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const MAX_OUTPUT_BYTES: number;
+/**
+ * The standard-flow failure a judge that did not answer is.
+ *
+ * A handler that cannot say whether a failing command failed about itself has
+ * no result to return: reporting the exit code alone is the reading that lost
+ * the thirty-nine frames. So the call fails, the code names which way the
+ * gateway went wrong, and the message says what is missing and how a host
+ * supplies it.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export declare const unjudged: (error: Classifier.ClassifierError) => StdError.StdError;
+/**
+ * What one failed command's exit code describes: the tree, or a name the
+ * command could not resolve.
+ *
+ * No cell calls this classifier. {@link classify} asks it on behalf of the
+ * `test` flow, which has the command and its output and has no task to judge
+ * them against, so the state is the three facts of the run and the questions
+ * carry every criterion themselves. It is declared here rather than in a
+ * catalog a host binds: a door for the model to ask this would be a door onto
+ * a judgment the flow has already made.
+ *
+ * @category classifiers
+ * @since 1.0.0
+ */
+export declare const probeAttribution: Classifier.Classifier<"probe/attribution", Schema.Struct<{
+    readonly command: Schema.String;
+    readonly exitCode: Schema.Int;
+    readonly output: Schema.String;
+}>, {
+    readonly attribution: Omit<Evaluator.ChoiceQuestion, "criteria"> & {
+        readonly criteria: {
+            readonly tree: "the command ran the intended tests and the failure is the code's";
+            readonly "unknown-command": "the shell could not find the program it was asked to run";
+            readonly "unknown-test": "the test runner could not find the test that was named";
+            readonly "unknown-path": "the file or directory that was named does not exist";
+            readonly "unknown-module": "the module that was imported does not exist here";
+            readonly "unknown-environment": "the runner has no environment by that name";
+        };
+    };
+    readonly executed: Evaluator.BooleanQuestion;
+}>;
+/**
+ * Attributes one command result to the tree, or to a name the command could
+ * not resolve.
+ *
+ * A zero exit needs no judgment. Every non-zero exit, including 126 and 127,
+ * goes through the attribution classifier: a runner may choose either code
+ * after executing tests. An answer under {@link CONFIDENCE_FLOOR} is the tree's
+ * failure, reported with the `executed` reading beside it.
+ *
+ * Pass the text the caller will actually return, so the judgment is made on
+ * the output the reader can see.
+ *
+ * @category classification
+ * @since 1.0.0
+ */
+export declare const classify: (result: {
+    readonly command: string;
+    readonly exitCode: number;
+    readonly output: string;
+}) => Effect.Effect<Attribution, Classifier.ClassifierError, Evaluator.Evaluator>;
+//# sourceMappingURL=Probe.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Probe.d.ts","sourceRoot":"","sources":["../../src/Probe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,UAAU,MAAM,0BAA0B,CAAA;AACtD,OAAO,KAAK,KAAK,SAAS,MAAM,yBAAyB,CAAA;AACzD,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC;;;;;;;;;GASG;AACH,eAAO,MAAM,GAAG,iBAAiB,CAAA;AAEjC;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,wHAMjB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAA;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,YAAY;;;;EAMvB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAA;AAEnD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAA;CACrC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,MAAM,CAAA;AAEnC;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,QAAY,CAAA;AAuCzC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,UAAU,CAAC,eAAe,KAAG,QAAQ,CAAC,QAKlE,CAAA;AAEJ;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;EA4B3B,CAAA;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,QAAQ;sBACD,MAAM;uBACL,MAAM;qBACR,MAAM;iFAiBvB,CAAA"}

package/dist/cjs/Probe.js

@@ -0,0 +1,134 @@
+"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 key2 of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key2) && key2 !== except)
+        __defProp(to, key2, { get: () => from[key2], enumerable: !(desc = __getOwnPropDesc(from, key2)) || 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 Probe_exports = {};
+__export(Probe_exports, {
+  CONFIDENCE_FLOOR: () => CONFIDENCE_FLOOR,
+  InvalidProbe: () => InvalidProbe,
+  MAX_OUTPUT_BYTES: () => MAX_OUTPUT_BYTES,
+  Reason: () => Reason,
+  classify: () => classify,
+  key: () => key,
+  probeAttribution: () => probeAttribution,
+  unjudged: () => unjudged
+});
+module.exports = __toCommonJS(Probe_exports);
+var Classifier = __toESM(require("@smthrs/model/Classifier"), 1);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Option = __toESM(require("effect/Option"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+var import_Text = require("./internal/Text.js");
+var StdError = __toESM(require("./StdError.js"), 1);
+const key = "invalidProbe";
+const Reason = Schema.Literals([
+  "unknown-command",
+  "unknown-test",
+  "unknown-path",
+  "unknown-module",
+  "unknown-environment"
+]);
+const InvalidProbe = Schema.Struct({
+  reason: Reason.annotate({ description: "Which kind of name the command could not resolve" }),
+  evidence: Schema.String.annotate({
+    description: "What this attribution rests on: the shell's own exit code, or the judge's reading and how sure it is"
+  }),
+  message: Schema.String.annotate({ description: "What the failure does and does not prove, stated for the caller" })
+});
+const CONFIDENCE_FLOOR = 0.7;
+const MAX_OUTPUT_BYTES = 32 * 1024;
+const named = {
+  "unknown-command": "the shell could not find the program it was asked to run",
+  "unknown-test": "the test runner could not find the test that was named",
+  "unknown-path": "the file or directory that was named does not exist",
+  "unknown-module": "the module that was imported does not exist here",
+  "unknown-environment": "the runner has no environment by that name"
+};
+const explain = (reason) => `This command never ran a check: ${named[reason]}. The non-zero exit describes the command, not the code under test, so it is not a reproduction and reads the same before and after a correct fix. Find the real names, repair the command, and run it again before drawing any conclusion from it.`;
+const invalid = (reason, evidence) => ({
+  reason,
+  evidence,
+  message: explain(reason)
+});
+const judged = (reason, confidence, executed) => `the judge read this output as ${reason} at confidence ${confidence.toFixed(2)}${executed ? ", although the runner also reported that it ran tests" : ""}`;
+const unjudgedCode = {
+  unconfigured: "provider_unavailable",
+  unreachable: "provider_unavailable",
+  refused: "provider_unavailable",
+  empty: "provider_unavailable",
+  timeout: "timeout",
+  invalid_answer: "request_failed",
+  invalid_question: "request_failed"
+};
+const unjudged = (error) => new StdError.StdError({
+  code: unjudgedCode[error.code],
+  message: `This result was not judged: the attribution judge answered ${error.code}. ${error.message} Nothing here says whether the non-zero exit is the code's failure or the command's, and a guess at that is worth less than no answer. Connect a subscription seat for the evaluator, then run the command again.`
+});
+const probeAttribution = Classifier.make("probe/attribution", {
+  description: "Judge one failed command: whether it ran the tests it named and failed about the code, or never resolved a name it was given.",
+  state: Schema.Struct({
+    command: Schema.String.annotate({ description: "The command that ran" }),
+    exitCode: Schema.Int.annotate({ description: "Its exit code, which is not zero" }),
+    output: Schema.String.annotate({ description: "Its captured stdout and stderr, newest bytes when clipped" })
+  }),
+  questions: {
+    attribution: Classifier.choice({
+      instructions: "What does this non-zero exit describe?",
+      criteria: {
+        tree: "the command ran the intended tests and the failure is the code's",
+        "unknown-command": "the shell could not find the program it was asked to run",
+        "unknown-test": "the test runner could not find the test that was named",
+        "unknown-path": "the file or directory that was named does not exist",
+        "unknown-module": "the module that was imported does not exist here",
+        "unknown-environment": "the runner has no environment by that name"
+      }
+    }),
+    executed: Classifier.boolean({
+      instructions: "Did a test runner actually run tests?",
+      criteria: {
+        true: "the runner reported its own tally of tests that ran, such as a count of passes or failures",
+        false: "nothing in the output reports that any test was executed"
+      }
+    })
+  }
+});
+const classify = Effect.fn("Probe.classify")(function* (result) {
+  if (result.exitCode === 0) return { to: "tree" };
+  const answers = yield* probeAttribution.evaluate({
+    command: result.command,
+    exitCode: result.exitCode,
+    output: (0, import_Text.truncateBytes)(result.output, MAX_OUTPUT_BYTES, { keep: "tail" }).text
+  });
+  const executed = answers.executed.value;
+  const decided = Option.getOrUndefined(Classifier.confident(answers.attribution, CONFIDENCE_FLOOR));
+  return decided === void 0 || decided === "tree" ? { to: "tree", executed } : {
+    to: decided,
+    executed,
+    invalidProbe: invalid(decided, judged(decided, answers.attribution.confidence, executed))
+  };
+});
+//# sourceMappingURL=Probe.js.map

package/dist/cjs/Probe.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/Probe.ts"],
+  "sourcesContent": ["/**\n * Telling an invalid probe from a failing check.\n *\n * A non-zero exit is a runner's verdict about the code it ran. It is not the\n * runner's verdict about the command it was handed. When an invocation names a\n * test, a file, a module, an environment, or a program that does not exist, the\n * runner never reaches any code and still exits non-zero \u2014 and at the tool\n * boundary that is indistinguishable from the bug reproducing. A SWE-bench run\n * lost thirty-nine frames to exactly that: the reproduction named a test method\n * the class does not define, so it read `exitCode: 1` before the edit and\n * `exitCode: 1` after it, and the agent could not tell it had already won.\n *\n * This module names that class. The taxonomy is one idea \u2014 *the invocation\n * named something that does not exist* \u2014 and {@link Reason} enumerates the five\n * things that something can be. An enumerated answer over prose is a judgment,\n * so Jev makes it: {@link classify} asks the `probe/attribution` classifier\n * whether this exit describes the tree or one of the five, and whether a runner\n * ran anything at all. Nothing here reads the output itself. The judgment used\n * to be nine regexes over runner wording, vetoed by two more over runner\n * tallies, and every phrase they matched is also printed by genuine failures \u2014\n * a bug that *is* an import error, a test that asserts on a shell message \u2014 so\n * precision cost recall and both cost maintenance.\n *\n * A zero exit needs no judgment: it belongs to the tree, whatever it printed.\n * A non-zero exit, including 126 or 127, needs attribution. A runner can\n * execute its tests and return either status, so neither proves that the shell\n * refused to launch the check.\n *\n * There is no third path. When the judge does not answer, {@link unjudged}\n * turns its failure into the caller's typed failure: a guess about whether a\n * reproduction reproduced is worth less than nothing, and the caller can say\n * that a result was not judged where it cannot say that a guess was wrong.\n *\n * A flow that can tell the difference reports it under the reserved output key\n * {@link key}. The harness reads that key off an otherwise opaque call result\n * and refuses to count such a result as evidence that anything about the tree\n * changed, which is what stops a broken probe from being cited as a\n * reproduction.\n *\n * @since 1.0.0\n */\n\nimport * as Classifier from \"@smthrs/model/Classifier\"\nimport type * as Evaluator from \"@smthrs/model/Evaluator\"\nimport * as Effect from \"effect/Effect\"\nimport * as Option from \"effect/Option\"\nimport * as Schema from \"effect/Schema\"\nimport { truncateBytes } from \"./internal/Text.ts\"\nimport * as StdError from \"./StdError.ts\"\n\n/**\n * The reserved output key a flow reports an invalid probe under.\n *\n * Stated as a constant because it is a wire contract with the harness rather\n * than a shared type: `@smthrs/harness` reads this key off a `Schema.Json`\n * result and must not depend on the tool library to do it.\n *\n * @category identifiers\n * @since 1.0.0\n */\nexport const key = \"invalidProbe\"\n\n/**\n * What the invocation named that does not exist.\n *\n * Five members, and the classifier offers exactly these five beside `tree`.\n *\n * @category schemas\n * @since 1.0.0\n */\nexport const Reason = Schema.Literals([\n  \"unknown-command\",\n  \"unknown-test\",\n  \"unknown-path\",\n  \"unknown-module\",\n  \"unknown-environment\"\n])\n\n/**\n * What the invocation named that does not exist.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Reason = typeof Reason.Type\n\n/**\n * One command's failure, attributed to the command rather than to the tree.\n *\n * @category schemas\n * @since 1.0.0\n */\nexport const InvalidProbe = Schema.Struct({\n  reason: Reason.annotate({ description: \"Which kind of name the command could not resolve\" }),\n  evidence: Schema.String.annotate({\n    description: \"What this attribution rests on: the shell's own exit code, or the judge's reading and how sure it is\"\n  }),\n  message: Schema.String.annotate({ description: \"What the failure does and does not prove, stated for the caller\" })\n})\n\n/**\n * One command's failure, attributed to the command rather than to the tree.\n *\n * @category models\n * @since 1.0.0\n */\nexport type InvalidProbe = typeof InvalidProbe.Type\n\n/**\n * What one command's exit code was attributed to.\n *\n * `to` is the tree, or the kind of name the command could not resolve, and\n * `invalidProbe` is present in exactly the second case, ready to report under\n * {@link key}. `executed` is the judge's separate reading of whether a runner\n * ran any test, absent when nothing was asked.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Attribution {\n  readonly to: \"tree\" | Reason\n  readonly executed?: boolean\n  readonly invalidProbe?: InvalidProbe\n}\n\n/**\n * The confidence an attribution needs before it outranks the tree.\n *\n * Below it the failure is the tree's, which is the reading that leaves the\n * caller the output it would have had anyway. A missed invalid probe costs a\n * reader nothing it had; a false one tells it its reproduction proved nothing.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const CONFIDENCE_FLOOR = 0.7\n\n/**\n * The most output bytes one judgment carries, newest kept.\n *\n * A runner prints its refusal last, and the classifier's whole state is held\n * to 32 KiB.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const MAX_OUTPUT_BYTES = 32 * 1024\n\n/** What each reason means, in the second half of one sentence. */\nconst named: Record<Reason, string> = {\n  \"unknown-command\": \"the shell could not find the program it was asked to run\",\n  \"unknown-test\": \"the test runner could not find the test that was named\",\n  \"unknown-path\": \"the file or directory that was named does not exist\",\n  \"unknown-module\": \"the module that was imported does not exist here\",\n  \"unknown-environment\": \"the runner has no environment by that name\"\n}\n\nconst explain = (reason: Reason): string =>\n  `This command never ran a check: ${\n    named[reason]\n  }. The non-zero exit describes the command, not the code under test, so it is not a reproduction and reads the same before and after a correct fix. Find the real names, repair the command, and run it again before drawing any conclusion from it.`\n\nconst invalid = (reason: Reason, evidence: string): InvalidProbe => ({\n  reason,\n  evidence,\n  message: explain(reason)\n})\n\n/** How the judge's own reading is quoted back to the caller. */\nconst judged = (reason: Reason, confidence: number, executed: boolean): string =>\n  `the judge read this output as ${reason} at confidence ${confidence.toFixed(2)}${\n    executed ? \", although the runner also reported that it ran tests\" : \"\"\n  }`\n\n/** Which typed failure each way the judge can fail to answer is. */\nconst unjudgedCode: Record<Evaluator.EvaluatorErrorCode, StdError.Code> = {\n  unconfigured: \"provider_unavailable\",\n  unreachable: \"provider_unavailable\",\n  refused: \"provider_unavailable\",\n  empty: \"provider_unavailable\",\n  timeout: \"timeout\",\n  invalid_answer: \"request_failed\",\n  invalid_question: \"request_failed\"\n}\n\n/**\n * The standard-flow failure a judge that did not answer is.\n *\n * A handler that cannot say whether a failing command failed about itself has\n * no result to return: reporting the exit code alone is the reading that lost\n * the thirty-nine frames. So the call fails, the code names which way the\n * gateway went wrong, and the message says what is missing and how a host\n * supplies it.\n *\n * @category errors\n * @since 1.0.0\n */\nexport const unjudged = (error: Classifier.ClassifierError): StdError.StdError =>\n  new StdError.StdError({\n    code: unjudgedCode[error.code],\n    message:\n      `This result was not judged: the attribution judge answered ${error.code}. ${error.message} Nothing here says whether the non-zero exit is the code's failure or the command's, and a guess at that is worth less than no answer. Connect a subscription seat for the evaluator, then run the command again.`\n  })\n\n/**\n * What one failed command's exit code describes: the tree, or a name the\n * command could not resolve.\n *\n * No cell calls this classifier. {@link classify} asks it on behalf of the\n * `test` flow, which has the command and its output and has no task to judge\n * them against, so the state is the three facts of the run and the questions\n * carry every criterion themselves. It is declared here rather than in a\n * catalog a host binds: a door for the model to ask this would be a door onto\n * a judgment the flow has already made.\n *\n * @category classifiers\n * @since 1.0.0\n */\nexport const probeAttribution = Classifier.make(\"probe/attribution\", {\n  description:\n    \"Judge one failed command: whether it ran the tests it named and failed about the code, or never resolved a name it was given.\",\n  state: Schema.Struct({\n    command: Schema.String.annotate({ description: \"The command that ran\" }),\n    exitCode: Schema.Int.annotate({ description: \"Its exit code, which is not zero\" }),\n    output: Schema.String.annotate({ description: \"Its captured stdout and stderr, newest bytes when clipped\" })\n  }),\n  questions: {\n    attribution: Classifier.choice({\n      instructions: \"What does this non-zero exit describe?\",\n      criteria: {\n        tree: \"the command ran the intended tests and the failure is the code's\",\n        \"unknown-command\": \"the shell could not find the program it was asked to run\",\n        \"unknown-test\": \"the test runner could not find the test that was named\",\n        \"unknown-path\": \"the file or directory that was named does not exist\",\n        \"unknown-module\": \"the module that was imported does not exist here\",\n        \"unknown-environment\": \"the runner has no environment by that name\"\n      }\n    }),\n    executed: Classifier.boolean({\n      instructions: \"Did a test runner actually run tests?\",\n      criteria: {\n        true: \"the runner reported its own tally of tests that ran, such as a count of passes or failures\",\n        false: \"nothing in the output reports that any test was executed\"\n      }\n    })\n  }\n})\n\n/**\n * Attributes one command result to the tree, or to a name the command could\n * not resolve.\n *\n * A zero exit needs no judgment. Every non-zero exit, including 126 and 127,\n * goes through the attribution classifier: a runner may choose either code\n * after executing tests. An answer under {@link CONFIDENCE_FLOOR} is the tree's\n * failure, reported with the `executed` reading beside it.\n *\n * Pass the text the caller will actually return, so the judgment is made on\n * the output the reader can see.\n *\n * @category classification\n * @since 1.0.0\n */\nexport const classify = Effect.fn(\"Probe.classify\")(function*(result: {\n  readonly command: string\n  readonly exitCode: number\n  readonly output: string\n}): Effect.fn.Return<Attribution, Classifier.ClassifierError, Evaluator.Evaluator> {\n  if (result.exitCode === 0) return { to: \"tree\" }\n  const answers = yield* probeAttribution.evaluate({\n    command: result.command,\n    exitCode: result.exitCode,\n    output: truncateBytes(result.output, MAX_OUTPUT_BYTES, { keep: \"tail\" }).text\n  })\n  const executed = answers.executed.value\n  const decided = Option.getOrUndefined(Classifier.confident(answers.attribution, CONFIDENCE_FLOOR))\n  return decided === undefined || decided === \"tree\"\n    ? { to: \"tree\", executed }\n    : {\n      to: decided,\n      executed,\n      invalidProbe: invalid(decided, judged(decided, answers.attribution.confidence, executed))\n    }\n})\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/Read.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Read flow declaration and portable handler.
+ *
+ * `content` is raw file text. It used to be rendered as `NNN\t<line>`, and that
+ * rendering was the single most expensive tool defect measured on the 45-instance
+ * SWE-bench trace program: an anchor copied out of a read carried the gutter, so
+ * every `edit` built from a read missed, and every cell that wanted a literal
+ * line had to strip the prefix in JavaScript first. Two instances (django-13346,
+ * django-14351) spent whole frames writing string surgery against text the file
+ * does not contain. Line numbers are facts about the page, so they are page
+ * fields — `startLine` and `endLine` — and never bytes inside the text.
+ *
+ * Every line in `content` is a whole line: a page cut short by the byte budget
+ * drops its trailing partial line rather than handing back a fragment that looks
+ * like an anchor and is not one. CRLF lines retain their trailing CR; only
+ * the page's final LF is omitted.
+ *
+ * @since 1.0.0
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Schema from "effect/Schema";
+import * as StdError from "./StdError.ts";
+export { Preconditions, ReadSession, type VersionedFileSystem } from "./internal/FileMutation.ts";
+/**
+ * Registry name for the read flow.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export declare const name = "read";
+/**
+ * Model-facing description of the read flow.
+ *
+ * @category descriptions
+ * @since 1.0.0
+ */
+export declare const description = "Read a text file by 1-based offset and limit. content is RAW file text with no line-number prefixes, so any line of it is an edit anchor as it stands; the numbers are startLine/endLine.";
+/**
+ * Input schema for the read flow.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Input: Schema.Struct<{
+    readonly path: Schema.String;
+    readonly offset: Schema.optional<Schema.Int>;
+    readonly limit: Schema.optional<Schema.Int>;
+}>;
+/**
+ * Decoded input accepted by the `read` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Input = typeof Input.Type;
+/**
+ * Output schema for the read flow.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Output: Schema.Struct<{
+    readonly content: Schema.String;
+    readonly startLine: Schema.Number;
+    readonly endLine: Schema.Number;
+    readonly totalLines: Schema.Number;
+    readonly truncated: Schema.Boolean;
+    readonly notice: Schema.optional<Schema.String>;
+}>;
+/**
+ * Decoded output returned by the `read` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Output = typeof Output.Type;
+/**
+ * Static conservative effect envelope for the read flow.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export declare const effects: import("@smthrs/plan/Effects").Declaration;
+/**
+ * Narrows the read effect envelope to one input path.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export declare const effectsFor: (input: typeof Input.Type) => import("@smthrs/plan/Effects").Declaration;
+/**
+ * Capabilities required by the read flow.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export declare const capabilities: string[];
+/**
+ * Declaration-only read flow.
+ *
+ * @category flows
+ * @since 1.0.0
+ */
+export declare const flow: {
+    readonly name: "read";
+    readonly description: "Read a text file by 1-based offset and limit. content is RAW file text with no line-number prefixes, so any line of it is an edit anchor as it stands; the numbers are startLine/endLine.";
+    readonly input: Schema.Struct<{
+        readonly path: Schema.String;
+        readonly offset: Schema.optional<Schema.Int>;
+        readonly limit: Schema.optional<Schema.Int>;
+    }>;
+    readonly output: Schema.Struct<{
+        readonly content: Schema.String;
+        readonly startLine: Schema.Number;
+        readonly endLine: Schema.Number;
+        readonly totalLines: Schema.Number;
+        readonly truncated: Schema.Boolean;
+        readonly notice: Schema.optional<Schema.String>;
+    }>;
+    readonly capabilities: string[];
+    readonly effects: import("@smthrs/plan/Effects").Declaration;
+};
+/**
+ * What a call to this flow does, for a reader of a run.
+ *
+ * Display metadata only. `@smthrs/registry` `Descriptor.FlowActivity` is the
+ * governing vocabulary and `StandardFlows` binds this value onto the flow's
+ * descriptor, where the binding site checks it. `declarationDigest` excludes
+ * it, so declaring it cannot invalidate a call identity or a cached prompt.
+ *
+ * @category presentation
+ * @since 1.0.0-rc.0
+ */
+export declare const activity: "reads";
+/**
+ * How one recorded call to this flow reads: the verb for each settlement, the
+ * input field that is its subject, and the measured output fields a one-line
+ * summary may count.
+ *
+ * Display metadata only, governed by `@smthrs/registry`
+ * `Descriptor.CallPresentation` and checked where `StandardFlows` binds it.
+ *
+ * @category presentation
+ * @since 1.0.0-rc.0
+ */
+export declare const presentation: {
+    readonly verb: {
+        readonly pending: "reading";
+        readonly success: "read";
+        readonly failure: "failed to read";
+    };
+    readonly subject: "path";
+    readonly result: "read";
+};
+/**
+ * The largest file `read` loads.
+ *
+ * `read` decodes the whole file to count its lines, so the file is held in
+ * memory twice over: its bytes and a UTF-16 string. Past this bound a page
+ * read would cost the host gigabytes for a window of a few thousand lines,
+ * and past 2 GiB Node cannot load the file at all.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const MAX_READ_FILE_BYTES: number;
+/**
+ * Reads, validates, and renders one page of a UTF-8 text file.
+ *
+ * The kernel filesystem exposes bytes rather than a guaranteed UTF-8 string,
+ * so decoding is deliberately fatal to keep binary input in the typed channel.
+ *
+ * @category handlers
+ * @since 1.0.0
+ */
+export declare const run: (input: {
+    readonly path: string;
+    readonly limit?: number | undefined;
+    readonly offset?: number | undefined;
+}) => Effect.Effect<{
+    readonly content: string;
+    readonly endLine: number;
+    readonly startLine: number;
+    readonly truncated: boolean;
+    readonly totalLines: number;
+    readonly notice?: string | undefined;
+}, StdError.StdError, FileSystem.FileSystem>;
+//# sourceMappingURL=Read.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Read.d.ts","sourceRoot":"","sources":["../../src/Read.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,UAAU,MAAM,mBAAmB,CAAA;AAE/C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAKvC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,KAAK,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAEjG;;;;;GAKG;AACH,eAAO,MAAM,IAAI,SAAS,CAAA;AAE1B;;;;;GAKG;AACH,eAAO,MAAM,WAAW,8LACqK,CAAA;AAE7L;;;;;GAKG;AACH,eAAO,MAAM,KAAK;;;;EAQhB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAA;AAErC;;;;;GAKG;AACH,eAAO,MAAM,MAAM;;;;;;;EAWjB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAA;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,OAAO,4CAKlB,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,OAAO,KAAK,CAAC,IAAI,+CAM/C,CAAA;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,YAAY,UAAiC,CAAA;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;CAAsF,CAAA;AAEvG;;;;;;;;;;GAUG;AACH,eAAO,MAAM,QAAQ,EAAG,OAAgB,CAAA;AAExC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY;;;;;;;;CAIf,CAAA;AAaV;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,QAAmB,CAAA;AAuDnD;;;;;;;;GAQG;AACH,eAAO,MAAM,GAAG;;;;;;;;;;;4CAmGd,CAAA"}