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

package/dist/esm/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/esm/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/esm/Probe.js

@@ -0,0 +1,225 @@
+/**
+ * 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 * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { truncateBytes } from "./internal/Text.js";
+import * as StdError from "./StdError.js";
+/**
+ * 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 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 const Reason = Schema.Literals([
+    "unknown-command",
+    "unknown-test",
+    "unknown-path",
+    "unknown-module",
+    "unknown-environment"
+]);
+/**
+ * One command's failure, attributed to the command rather than to the tree.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export 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" })
+});
+/**
+ * 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 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 const MAX_OUTPUT_BYTES = 32 * 1024;
+/** What each reason means, in the second half of one sentence. */
+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)
+});
+/** How the judge's own reading is quoted back to the caller. */
+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" : ""}`;
+/** Which typed failure each way the judge can fail to answer is. */
+const unjudgedCode = {
+    unconfigured: "provider_unavailable",
+    unreachable: "provider_unavailable",
+    refused: "provider_unavailable",
+    empty: "provider_unavailable",
+    timeout: "timeout",
+    invalid_answer: "request_failed",
+    invalid_question: "request_failed"
+};
+/**
+ * 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 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.`
+});
+/**
+ * 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 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"
+            }
+        })
+    }
+});
+/**
+ * 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 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: 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 === undefined || decided === "tree"
+        ? { to: "tree", executed }
+        : {
+            to: decided,
+            executed,
+            invalidProbe: invalid(decided, judged(decided, answers.attribution.confidence, executed))
+        };
+});
+//# sourceMappingURL=Probe.js.map

package/dist/esm/Probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Probe.js","sourceRoot":"","sources":["../../src/Probe.ts"],"names":[],"mappings":"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","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 — 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 — *the invocation\n * named something that does not exist* — 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 —\n * a bug that *is* an import error, a test that asserts on a shell message — 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"]}

package/dist/esm/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/esm/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"}