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

package/dist/esm/UnmovedTree.js

@@ -0,0 +1,90 @@
+/**
+ * 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
+ */
+import * as DemandText from "./internal/demandText.js";
+/**
+ * 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 const find = (options) => options.opened === "" || options.digest === "" || options.opened !== options.digest ||
+    (options.elsewhere ?? 0) > 0
+    ? undefined
+    : { opened: options.opened, closed: options.digest };
+/**
+ * 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 const demand = (found) => DemandText.unmoved(found.opened, found.closed);
+//# sourceMappingURL=UnmovedTree.js.map

package/dist/esm/UnmovedTree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"UnmovedTree.js","sourceRoot":"","sources":["../../src/UnmovedTree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,UAAU,MAAM,0BAA0B,CAAA;AAetD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,OAepB,EAAuB,EAAE,CACxB,OAAO,CAAC,MAAM,KAAK,EAAE,IAAI,OAAO,CAAC,MAAM,KAAK,EAAE,IAAI,OAAO,CAAC,MAAM,KAAK,OAAO,CAAC,MAAM;IACjF,CAAC,OAAO,CAAC,SAAS,IAAI,CAAC,CAAC,GAAG,CAAC;IAC5B,CAAC,CAAC,SAAS;IACX,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAA;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,KAAc,EAAU,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA","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 — 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 — three `read`, seven `grep`, one `bash` — 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 — 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 — 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 — the harness\n * cannot know whether the claim is true, and grading it would be the harness\n * deciding the task — 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"]}

package/dist/esm/UnresolvedFailure.d.ts

@@ -0,0 +1,196 @@
+/**
+ * The failing check a completion stepped around.
+ *
+ * `NarrowedCheck` names a completion whose last check is a *narrower* version
+ * of one the run already ran, taken after the workspace moved. This module
+ * names the case one step further along: the run's reading of some subject
+ * reported a failure, over the very tree the run is now completing on, and the
+ * run neither re-ran it nor left it alone — it took a *different* reading of the
+ * same subject and completed on that one instead.
+ *
+ * It is not hypothetical. On a graded benchmark, one run edited a source file at
+ * frame 11, ran `pytest -rA testing/python/collect.py` at frame 12 — the whole
+ * file, unfiltered, over the tree it would go on to finish with — and was told
+ * "2 failed, 72 passed". At frame 13 it ran a command naming four cases out of
+ * that same file, was told "4 passed", and at frame 14 it completed. The broad
+ * result was never re-run, never retracted, and never mentioned. Its graded
+ * patch passed both target tests and 144 of 145 neighbours.
+ *
+ * ## Why a failing check alone is not the trigger
+ *
+ * "Some check failed and the run finished anyway" is not a defect, and reading
+ * it as one would be the harness deciding whose failures matter. The same wave
+ * contains the counter-example: an instance that **resolved** ran
+ * `pytest -rA astropy/io/fits/tests/test_header.py` after its edit, was told "2
+ * failed, 148 passed", and completed — correctly, because those two failures
+ * were nothing to do with its change. Nothing in the record distinguishes those
+ * two failure counts, and nothing may: counting failures means parsing a
+ * runner's output, which makes this a rule about pytest instead of a rule about
+ * evidence.
+ *
+ * What separates the two runs is what happened *after* the failing check. The
+ * resolved run walked away from that subject entirely: no later call it made
+ * names `astropy/io/fits/tests/test_header.py` at all. The unresolved run went
+ * back to exactly the subject that had failed, asked a smaller question about
+ * it, and reported the smaller answer. That is the shape this module names, and
+ * it is one the run's own record establishes: the run itself demonstrated the
+ * subject was still live by returning to it.
+ *
+ * So the demand is not "you have a failing test". It is: *the reading you
+ * replaced reported a failure, and you replaced it rather than answering it.*
+ * The run may answer either way — fix what the check reported, or complete again
+ * saying why those failures are expected. The loop asks once and accepts what
+ * comes back, because a harness that decided which failures counted would be
+ * grading the agent's work with its own.
+ *
+ * @since 0.1.0
+ */
+import type { Schema } from "effect";
+import type * as NarrowedCheck from "./NarrowedCheck.ts";
+/**
+ * The reserved key a flow reports its subject's exit status under.
+ *
+ * The second of the two conventions the loop reads off an otherwise opaque call
+ * result, alongside `invalidProbe`. It is not a shared type — the controller
+ * must not depend on the tool library — so it is a documented wire key.
+ * `@smthrs/std` `Bash` and `ShellCommand` are the producing half and own what
+ * the number means; the controller only has to know that a result carrying a
+ * non-zero number under this key is a result whose subject reported failure.
+ *
+ * @category identifiers
+ * @since 0.1.0
+ */
+export declare const exitStatusKey = "exitCode";
+/**
+ * Whether a settled call's result reports a failing exit status.
+ *
+ * A result that declares no exit status is not a failure and not a success: it
+ * is a call whose flow does not report one, and reading its absence either way
+ * would be an assumption. `false` is the answer that costs a demand rather than
+ * inventing one.
+ *
+ * @category predicates
+ * @since 0.1.0
+ */
+export declare const failed: (value: Schema.Json) => boolean;
+/**
+ * The exit status a settled call's result reports about its subject, or
+ * nothing where it reports none.
+ *
+ * The one reader of {@link exitStatusKey}, so the two predicates below and
+ * every caller that wants the number itself agree by construction rather than
+ * by three copies of the same shape test.
+ *
+ * @category getters
+ * @since 1.0.0-rc.0
+ */
+export declare const exitStatus: (value: Schema.Json) => number | undefined;
+/**
+ * Whether a settled call's result reports a passing exit status.
+ *
+ * The mirror of {@link failed}, and not its negation. A result that declares no
+ * exit status is neither: `false` from both predicates is a call whose flow
+ * does not report one, which is what a read and a search are. `Sufficiency`
+ * builds a completion signal out of this answer, so silence has to read as
+ * silence — a file read that "did not fail" is not a check that passed.
+ *
+ * @category predicates
+ * @since 0.1.0
+ */
+export declare const passed: (value: Schema.Json) => boolean;
+/**
+ * A failing check, paired with the reading the run took in its place.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Displaced {
+    /** The check that reported a failure and was never re-run. */
+    readonly failed: NarrowedCheck.Check;
+    /** A later check over the same tree that revisits its subject. */
+    readonly instead: NarrowedCheck.Check;
+}
+/**
+ * Whether a later check asks about the same subject as an earlier one.
+ *
+ * The relation is: same flow, a different call, and every *target* the earlier
+ * check named is named again. Targets — the terms carrying a separator, as
+ * `NarrowedCheck` `targeting` reads them — are the paths, files, modules and
+ * node ids a call is about; everything else is a condition on them. So "same
+ * subject" means the later call went back to all of the places the earlier one
+ * looked, whether it asked a narrower question there, a broader one, or looked
+ * somewhere else as well.
+ *
+ * It is deliberately weaker than `NarrowedCheck` `narrows`, which additionally
+ * requires every *condition* to be carried and forbids adding a target. That
+ * relation misses a compound command — a `git diff` of two source files joined
+ * onto a test run — because the diff's own paths read as added targets. This one
+ * does not, because the question it answers is not "is this the same question
+ * again" but "did you come back to this".
+ *
+ * An earlier check that names no target at all is never revisited. Such a call
+ * has no subject to return to, and treating it as revisited by any later call of
+ * the same flow would make the relation vacuous.
+ *
+ * @category predicates
+ * @since 0.1.0
+ */
+export declare const revisits: (later: NarrowedCheck.Check, earlier: NarrowedCheck.Check) => boolean;
+/**
+ * Finds the failing check a completion replaced rather than answered.
+ *
+ * Every condition is read off something the harness already records:
+ *
+ * 1. the frame closed on a complete measurement, so a digest means something;
+ * 2. some check in the ledger reported a failing exit status;
+ * 3. that check was recorded over the tree this frame is completing on, so its
+ *    result is a statement about the tree the completion stands on;
+ * 4. it was recorded by a frame that changed nothing, so the digest stamped on
+ *    it is the tree it actually ran over rather than a conservative guess;
+ * 5. some *later* check {@link revisits} it.
+ *
+ * Condition 4 is the one that cannot be dropped. A frame's calls are not ordered
+ * against its edits in anything the harness records, so a check taken in a frame
+ * that also edited is stamped with that frame's closing digest — which reads a
+ * check taken *before* the edit as though it ran after. `NarrowedCheck` accepts
+ * that in the direction that suppresses demands; here the same stamp would
+ * attribute a pre-edit failure to a tree the check never ran over, and invent
+ * one. The same wave carries an instance where it would have: a reproduction run
+ * in the same frame as the edit that fixed it, still reporting the bug.
+ *
+ * The ledger holds one entry per call signature, carrying that call's most
+ * recent run, so "never re-ran it" needs no separate test: a check re-run and
+ * passed is no longer failing, and a check re-run and failed again is still
+ * unanswered. Ledger order is recency of last run, which is what makes
+ * condition 5 a statement about time.
+ *
+ * The most recent such failing check wins, because it is the reading the
+ * completion is standing closest to.
+ *
+ * @category conversions
+ * @since 0.1.0
+ */
+export declare const find: (options: {
+    /** Every check this run has run, oldest first, this frame's included. */
+    readonly ledger: ReadonlyArray<NarrowedCheck.Check>;
+    /** The workspace digest the completing frame closed on; empty when unmeasured. */
+    readonly digest: string;
+}) => Displaced | undefined;
+/**
+ * States which reading failed, which one replaced it, and what ends it.
+ *
+ * The text quotes both calls as the run wrote them and asserts only what the
+ * record says: the first reported a failing exit status over this exact tree,
+ * the second asked about the same subject, and the first was never run again.
+ * It does not say the failures are the run's fault, because it does not know —
+ * a pre-existing failure is a real answer and the demand names it as one of the
+ * two ways out.
+ *
+ * It also says plainly that nothing re-runs anything for the run, and that the
+ * next answer stands.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const demand: (found: Displaced) => string;
+//# sourceMappingURL=UnresolvedFailure.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"UnresolvedFailure.d.ts","sourceRoot":"","sources":["../../src/UnresolvedFailure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAEpC,OAAO,KAAK,KAAK,aAAa,MAAM,oBAAoB,CAAA;AAGxD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,aAAa,CAAA;AAEvC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,MAAM,CAAC,IAAI,KAAG,OAG3C,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,CAAC,IAAI,KAAG,MAAM,GAAG,SAIxD,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,MAAM,CAAC,IAAI,KAAG,OAAkC,CAAA;AAE9E;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,KAAK,CAAA;IACpC,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,KAAK,CAAA;CACtC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,QAAQ,GACnB,OAAO,aAAa,CAAC,KAAK,EAC1B,SAAS,aAAa,CAAC,KAAK,KAC3B,OAWF,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,IAAI,GAAI,SAAS;IAC5B,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,aAAa,CAAC,KAAK,CAAC,CAAA;IACnD,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB,KAAG,SAAS,GAAG,SAYf,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,SAAS,KAAG,MACyC,CAAA"}

package/dist/esm/UnresolvedFailure.js

@@ -0,0 +1,218 @@
+/**
+ * The failing check a completion stepped around.
+ *
+ * `NarrowedCheck` names a completion whose last check is a *narrower* version
+ * of one the run already ran, taken after the workspace moved. This module
+ * names the case one step further along: the run's reading of some subject
+ * reported a failure, over the very tree the run is now completing on, and the
+ * run neither re-ran it nor left it alone — it took a *different* reading of the
+ * same subject and completed on that one instead.
+ *
+ * It is not hypothetical. On a graded benchmark, one run edited a source file at
+ * frame 11, ran `pytest -rA testing/python/collect.py` at frame 12 — the whole
+ * file, unfiltered, over the tree it would go on to finish with — and was told
+ * "2 failed, 72 passed". At frame 13 it ran a command naming four cases out of
+ * that same file, was told "4 passed", and at frame 14 it completed. The broad
+ * result was never re-run, never retracted, and never mentioned. Its graded
+ * patch passed both target tests and 144 of 145 neighbours.
+ *
+ * ## Why a failing check alone is not the trigger
+ *
+ * "Some check failed and the run finished anyway" is not a defect, and reading
+ * it as one would be the harness deciding whose failures matter. The same wave
+ * contains the counter-example: an instance that **resolved** ran
+ * `pytest -rA astropy/io/fits/tests/test_header.py` after its edit, was told "2
+ * failed, 148 passed", and completed — correctly, because those two failures
+ * were nothing to do with its change. Nothing in the record distinguishes those
+ * two failure counts, and nothing may: counting failures means parsing a
+ * runner's output, which makes this a rule about pytest instead of a rule about
+ * evidence.
+ *
+ * What separates the two runs is what happened *after* the failing check. The
+ * resolved run walked away from that subject entirely: no later call it made
+ * names `astropy/io/fits/tests/test_header.py` at all. The unresolved run went
+ * back to exactly the subject that had failed, asked a smaller question about
+ * it, and reported the smaller answer. That is the shape this module names, and
+ * it is one the run's own record establishes: the run itself demonstrated the
+ * subject was still live by returning to it.
+ *
+ * So the demand is not "you have a failing test". It is: *the reading you
+ * replaced reported a failure, and you replaced it rather than answering it.*
+ * The run may answer either way — fix what the check reported, or complete again
+ * saying why those failures are expected. The loop asks once and accepts what
+ * comes back, because a harness that decided which failures counted would be
+ * grading the agent's work with its own.
+ *
+ * @since 0.1.0
+ */
+import * as DemandText from "./internal/demandText.js";
+import { targeting } from "./NarrowedCheck.js";
+/**
+ * The reserved key a flow reports its subject's exit status under.
+ *
+ * The second of the two conventions the loop reads off an otherwise opaque call
+ * result, alongside `invalidProbe`. It is not a shared type — the controller
+ * must not depend on the tool library — so it is a documented wire key.
+ * `@smthrs/std` `Bash` and `ShellCommand` are the producing half and own what
+ * the number means; the controller only has to know that a result carrying a
+ * non-zero number under this key is a result whose subject reported failure.
+ *
+ * @category identifiers
+ * @since 0.1.0
+ */
+export const exitStatusKey = "exitCode";
+/**
+ * Whether a settled call's result reports a failing exit status.
+ *
+ * A result that declares no exit status is not a failure and not a success: it
+ * is a call whose flow does not report one, and reading its absence either way
+ * would be an assumption. `false` is the answer that costs a demand rather than
+ * inventing one.
+ *
+ * @category predicates
+ * @since 0.1.0
+ */
+export const failed = (value) => {
+    const status = exitStatus(value);
+    return status !== undefined && status !== 0;
+};
+/**
+ * The exit status a settled call's result reports about its subject, or
+ * nothing where it reports none.
+ *
+ * The one reader of {@link exitStatusKey}, so the two predicates below and
+ * every caller that wants the number itself agree by construction rather than
+ * by three copies of the same shape test.
+ *
+ * @category getters
+ * @since 1.0.0-rc.0
+ */
+export const exitStatus = (value) => {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const status = value[exitStatusKey];
+    return typeof status === "number" ? status : undefined;
+};
+/**
+ * Whether a settled call's result reports a passing exit status.
+ *
+ * The mirror of {@link failed}, and not its negation. A result that declares no
+ * exit status is neither: `false` from both predicates is a call whose flow
+ * does not report one, which is what a read and a search are. `Sufficiency`
+ * builds a completion signal out of this answer, so silence has to read as
+ * silence — a file read that "did not fail" is not a check that passed.
+ *
+ * @category predicates
+ * @since 0.1.0
+ */
+export const passed = (value) => exitStatus(value) === 0;
+/**
+ * Whether a later check asks about the same subject as an earlier one.
+ *
+ * The relation is: same flow, a different call, and every *target* the earlier
+ * check named is named again. Targets — the terms carrying a separator, as
+ * `NarrowedCheck` `targeting` reads them — are the paths, files, modules and
+ * node ids a call is about; everything else is a condition on them. So "same
+ * subject" means the later call went back to all of the places the earlier one
+ * looked, whether it asked a narrower question there, a broader one, or looked
+ * somewhere else as well.
+ *
+ * It is deliberately weaker than `NarrowedCheck` `narrows`, which additionally
+ * requires every *condition* to be carried and forbids adding a target. That
+ * relation misses a compound command — a `git diff` of two source files joined
+ * onto a test run — because the diff's own paths read as added targets. This one
+ * does not, because the question it answers is not "is this the same question
+ * again" but "did you come back to this".
+ *
+ * An earlier check that names no target at all is never revisited. Such a call
+ * has no subject to return to, and treating it as revisited by any later call of
+ * the same flow would make the relation vacuous.
+ *
+ * @category predicates
+ * @since 0.1.0
+ */
+export const revisits = (later, earlier) => {
+    if (later.flow !== earlier.flow)
+        return false;
+    if (later.signature === earlier.signature)
+        return false;
+    const carried = new Set(later.terms);
+    let named = false;
+    for (const term of earlier.terms) {
+        if (!targeting(term))
+            continue;
+        named = true;
+        if (!carried.has(term))
+            return false;
+    }
+    return named;
+};
+/**
+ * Finds the failing check a completion replaced rather than answered.
+ *
+ * Every condition is read off something the harness already records:
+ *
+ * 1. the frame closed on a complete measurement, so a digest means something;
+ * 2. some check in the ledger reported a failing exit status;
+ * 3. that check was recorded over the tree this frame is completing on, so its
+ *    result is a statement about the tree the completion stands on;
+ * 4. it was recorded by a frame that changed nothing, so the digest stamped on
+ *    it is the tree it actually ran over rather than a conservative guess;
+ * 5. some *later* check {@link revisits} it.
+ *
+ * Condition 4 is the one that cannot be dropped. A frame's calls are not ordered
+ * against its edits in anything the harness records, so a check taken in a frame
+ * that also edited is stamped with that frame's closing digest — which reads a
+ * check taken *before* the edit as though it ran after. `NarrowedCheck` accepts
+ * that in the direction that suppresses demands; here the same stamp would
+ * attribute a pre-edit failure to a tree the check never ran over, and invent
+ * one. The same wave carries an instance where it would have: a reproduction run
+ * in the same frame as the edit that fixed it, still reporting the bug.
+ *
+ * The ledger holds one entry per call signature, carrying that call's most
+ * recent run, so "never re-ran it" needs no separate test: a check re-run and
+ * passed is no longer failing, and a check re-run and failed again is still
+ * unanswered. Ledger order is recency of last run, which is what makes
+ * condition 5 a statement about time.
+ *
+ * The most recent such failing check wins, because it is the reading the
+ * completion is standing closest to.
+ *
+ * @category conversions
+ * @since 0.1.0
+ */
+export const find = (options) => {
+    if (options.digest === "")
+        return undefined;
+    let found = undefined;
+    for (const [index, earlier] of options.ledger.entries()) {
+        if (!earlier.failing || !earlier.stable)
+            continue;
+        if (earlier.digest !== options.digest)
+            continue;
+        const instead = options.ledger.slice(index + 1).find((candidate) => revisits(candidate, earlier));
+        // Oldest first, keeping the last match: the ledger is ordered by when each
+        // check last ran, so the surviving pair names the most recent failure.
+        if (instead !== undefined)
+            found = { failed: earlier, instead };
+    }
+    return found;
+};
+/**
+ * States which reading failed, which one replaced it, and what ends it.
+ *
+ * The text quotes both calls as the run wrote them and asserts only what the
+ * record says: the first reported a failing exit status over this exact tree,
+ * the second asked about the same subject, and the first was never run again.
+ * It does not say the failures are the run's fault, because it does not know —
+ * a pre-existing failure is a real answer and the demand names it as one of the
+ * two ways out.
+ *
+ * It also says plainly that nothing re-runs anything for the run, and that the
+ * next answer stands.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const demand = (found) => DemandText.unresolved(found.failed.flow, found.failed.label, found.instead.label);
+//# sourceMappingURL=UnresolvedFailure.js.map

package/dist/esm/UnresolvedFailure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"UnresolvedFailure.js","sourceRoot":"","sources":["../../src/UnresolvedFailure.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The failing check a completion stepped around.\n *\n * `NarrowedCheck` names a completion whose last check is a *narrower* version\n * of one the run already ran, taken after the workspace moved. This module\n * names the case one step further along: the run's reading of some subject\n * reported a failure, over the very tree the run is now completing on, and the\n * run neither re-ran it nor left it alone — it took a *different* reading of the\n * same subject and completed on that one instead.\n *\n * It is not hypothetical. On a graded benchmark, one run edited a source file at\n * frame 11, ran `pytest -rA testing/python/collect.py` at frame 12 — the whole\n * file, unfiltered, over the tree it would go on to finish with — and was told\n * \"2 failed, 72 passed\". At frame 13 it ran a command naming four cases out of\n * that same file, was told \"4 passed\", and at frame 14 it completed. The broad\n * result was never re-run, never retracted, and never mentioned. Its graded\n * patch passed both target tests and 144 of 145 neighbours.\n *\n * ## Why a failing check alone is not the trigger\n *\n * \"Some check failed and the run finished anyway\" is not a defect, and reading\n * it as one would be the harness deciding whose failures matter. The same wave\n * contains the counter-example: an instance that **resolved** ran\n * `pytest -rA astropy/io/fits/tests/test_header.py` after its edit, was told \"2\n * failed, 148 passed\", and completed — correctly, because those two failures\n * were nothing to do with its change. Nothing in the record distinguishes those\n * two failure counts, and nothing may: counting failures means parsing a\n * runner's output, which makes this a rule about pytest instead of a rule about\n * evidence.\n *\n * What separates the two runs is what happened *after* the failing check. The\n * resolved run walked away from that subject entirely: no later call it made\n * names `astropy/io/fits/tests/test_header.py` at all. The unresolved run went\n * back to exactly the subject that had failed, asked a smaller question about\n * it, and reported the smaller answer. That is the shape this module names, and\n * it is one the run's own record establishes: the run itself demonstrated the\n * subject was still live by returning to it.\n *\n * So the demand is not \"you have a failing test\". It is: *the reading you\n * replaced reported a failure, and you replaced it rather than answering it.*\n * The run may answer either way — fix what the check reported, or complete again\n * saying why those failures are expected. The loop asks once and accepts what\n * comes back, because a harness that decided which failures counted would be\n * grading the agent's work with its own.\n *\n * @since 0.1.0\n */\n\nimport type { Schema } from \"effect\"\nimport * as DemandText from \"./internal/demandText.ts\"\nimport type * as NarrowedCheck from \"./NarrowedCheck.ts\"\nimport { targeting } from \"./NarrowedCheck.ts\"\n\n/**\n * The reserved key a flow reports its subject's exit status under.\n *\n * The second of the two conventions the loop reads off an otherwise opaque call\n * result, alongside `invalidProbe`. It is not a shared type — the controller\n * must not depend on the tool library — so it is a documented wire key.\n * `@smthrs/std` `Bash` and `ShellCommand` are the producing half and own what\n * the number means; the controller only has to know that a result carrying a\n * non-zero number under this key is a result whose subject reported failure.\n *\n * @category identifiers\n * @since 0.1.0\n */\nexport const exitStatusKey = \"exitCode\"\n\n/**\n * Whether a settled call's result reports a failing exit status.\n *\n * A result that declares no exit status is not a failure and not a success: it\n * is a call whose flow does not report one, and reading its absence either way\n * would be an assumption. `false` is the answer that costs a demand rather than\n * inventing one.\n *\n * @category predicates\n * @since 0.1.0\n */\nexport const failed = (value: Schema.Json): boolean => {\n  const status = exitStatus(value)\n  return status !== undefined && status !== 0\n}\n\n/**\n * The exit status a settled call's result reports about its subject, or\n * nothing where it reports none.\n *\n * The one reader of {@link exitStatusKey}, so the two predicates below and\n * every caller that wants the number itself agree by construction rather than\n * by three copies of the same shape test.\n *\n * @category getters\n * @since 1.0.0-rc.0\n */\nexport const exitStatus = (value: Schema.Json): number | undefined => {\n  if (value === null || typeof value !== \"object\" || Array.isArray(value)) return undefined\n  const status = (value as Record<string, unknown>)[exitStatusKey]\n  return typeof status === \"number\" ? status : undefined\n}\n\n/**\n * Whether a settled call's result reports a passing exit status.\n *\n * The mirror of {@link failed}, and not its negation. A result that declares no\n * exit status is neither: `false` from both predicates is a call whose flow\n * does not report one, which is what a read and a search are. `Sufficiency`\n * builds a completion signal out of this answer, so silence has to read as\n * silence — a file read that \"did not fail\" is not a check that passed.\n *\n * @category predicates\n * @since 0.1.0\n */\nexport const passed = (value: Schema.Json): boolean => exitStatus(value) === 0\n\n/**\n * A failing check, paired with the reading the run took in its place.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Displaced {\n  /** The check that reported a failure and was never re-run. */\n  readonly failed: NarrowedCheck.Check\n  /** A later check over the same tree that revisits its subject. */\n  readonly instead: NarrowedCheck.Check\n}\n\n/**\n * Whether a later check asks about the same subject as an earlier one.\n *\n * The relation is: same flow, a different call, and every *target* the earlier\n * check named is named again. Targets — the terms carrying a separator, as\n * `NarrowedCheck` `targeting` reads them — are the paths, files, modules and\n * node ids a call is about; everything else is a condition on them. So \"same\n * subject\" means the later call went back to all of the places the earlier one\n * looked, whether it asked a narrower question there, a broader one, or looked\n * somewhere else as well.\n *\n * It is deliberately weaker than `NarrowedCheck` `narrows`, which additionally\n * requires every *condition* to be carried and forbids adding a target. That\n * relation misses a compound command — a `git diff` of two source files joined\n * onto a test run — because the diff's own paths read as added targets. This one\n * does not, because the question it answers is not \"is this the same question\n * again\" but \"did you come back to this\".\n *\n * An earlier check that names no target at all is never revisited. Such a call\n * has no subject to return to, and treating it as revisited by any later call of\n * the same flow would make the relation vacuous.\n *\n * @category predicates\n * @since 0.1.0\n */\nexport const revisits = (\n  later: NarrowedCheck.Check,\n  earlier: NarrowedCheck.Check\n): boolean => {\n  if (later.flow !== earlier.flow) return false\n  if (later.signature === earlier.signature) return false\n  const carried = new Set(later.terms)\n  let named = false\n  for (const term of earlier.terms) {\n    if (!targeting(term)) continue\n    named = true\n    if (!carried.has(term)) return false\n  }\n  return named\n}\n\n/**\n * Finds the failing check a completion replaced rather than answered.\n *\n * Every condition is read off something the harness already records:\n *\n * 1. the frame closed on a complete measurement, so a digest means something;\n * 2. some check in the ledger reported a failing exit status;\n * 3. that check was recorded over the tree this frame is completing on, so its\n *    result is a statement about the tree the completion stands on;\n * 4. it was recorded by a frame that changed nothing, so the digest stamped on\n *    it is the tree it actually ran over rather than a conservative guess;\n * 5. some *later* check {@link revisits} it.\n *\n * Condition 4 is the one that cannot be dropped. A frame's calls are not ordered\n * against its edits in anything the harness records, so a check taken in a frame\n * that also edited is stamped with that frame's closing digest — which reads a\n * check taken *before* the edit as though it ran after. `NarrowedCheck` accepts\n * that in the direction that suppresses demands; here the same stamp would\n * attribute a pre-edit failure to a tree the check never ran over, and invent\n * one. The same wave carries an instance where it would have: a reproduction run\n * in the same frame as the edit that fixed it, still reporting the bug.\n *\n * The ledger holds one entry per call signature, carrying that call's most\n * recent run, so \"never re-ran it\" needs no separate test: a check re-run and\n * passed is no longer failing, and a check re-run and failed again is still\n * unanswered. Ledger order is recency of last run, which is what makes\n * condition 5 a statement about time.\n *\n * The most recent such failing check wins, because it is the reading the\n * completion is standing closest to.\n *\n * @category conversions\n * @since 0.1.0\n */\nexport const find = (options: {\n  /** Every check this run has run, oldest first, this frame's included. */\n  readonly ledger: ReadonlyArray<NarrowedCheck.Check>\n  /** The workspace digest the completing frame closed on; empty when unmeasured. */\n  readonly digest: string\n}): Displaced | undefined => {\n  if (options.digest === \"\") return undefined\n  let found: Displaced | undefined = undefined\n  for (const [index, earlier] of options.ledger.entries()) {\n    if (!earlier.failing || !earlier.stable) continue\n    if (earlier.digest !== options.digest) continue\n    const instead = options.ledger.slice(index + 1).find((candidate) => revisits(candidate, earlier))\n    // Oldest first, keeping the last match: the ledger is ordered by when each\n    // check last ran, so the surviving pair names the most recent failure.\n    if (instead !== undefined) found = { failed: earlier, instead }\n  }\n  return found\n}\n\n/**\n * States which reading failed, which one replaced it, and what ends it.\n *\n * The text quotes both calls as the run wrote them and asserts only what the\n * record says: the first reported a failing exit status over this exact tree,\n * the second asked about the same subject, and the first was never run again.\n * It does not say the failures are the run's fault, because it does not know —\n * a pre-existing failure is a real answer and the demand names it as one of the\n * two ways out.\n *\n * It also says plainly that nothing re-runs anything for the run, and that the\n * next answer stands.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const demand = (found: Displaced): string =>\n  DemandText.unresolved(found.failed.flow, found.failed.label, found.instead.label)\n"]}