@mohan-cao/jev-trajectory 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,97 @@
+# @mohan-cao/jev-trajectory
+
+The progress signal: **two orthogonal Jev judgments per settled turn** — did it
+advance the work, did it reopen something — composed into four outcomes, plus
+pure arithmetic over a series of them.
+
+```bash
+npm install @mohan-cao/jev-trajectory
+```
+
+```ts
+import { judgeTrajectory, progressOf, summarizeProgress } from "@mohan-cao/jev-trajectory";
+
+const judgment = await judgeTrajectory(turns, apiKey, jevConfig);
+// { advanceConfidence: 0.9, regressConfidence: 0.8 }
+progressOf(judgment); // "mixed"
+
+summarizeProgress(series, 0.7);
+// { counted: 8, advanced: 4, regressed: 3, mixed: 2,
+//   advancedRate: 0.5, regressedRate: 0.375, mixedRate: 0.25,
+//   net: 0.125, oscillation: 2, longestStall: 3 }
+```
+
+A judgment carries **only the two answers**. The composed label is derived by
+`progressOf`, so it cannot drift out of step with the confidences it came from.
+
+## Two questions, not one scale
+
+| `advance?` | `regress?` | outcome |
+| --- | --- | --- |
+| no | no | `held` |
+| yes | no | `advanced` |
+| no | yes | `regressed` |
+| yes | yes | `mixed` |
+
+A turn can genuinely do both — settle the API shape and reopen the storage
+choice — and a single axis cannot say so. **This is the same reason
+classification asks two Nouls rather than one Choice**: a single axis makes the
+residual compete in an argmax. Forcing a two-dimensional turn onto one line is
+the same mistake.
+
+`mixed` is not a failure state. Neither is `regressed`: reopening a detail that
+turned out to rest on a false premise is how a wrong premise gets caught.
+
+## There is no `stuck` value
+
+An earlier version classified turns as `converging | stuck_detail | stuck_framing
+| early`. The objection that killed it is worth keeping: *if something is in
+progress and not converging, is it stuck?* That vocabulary answered yes by
+omission — it had no place for a turn that neither advanced nor revisited, and
+both `stuck` labels were **verdicts rather than observations**.
+
+Divergence is therefore *recorded, not named*. The reader decides whether a
+series is a correction cycle or a spiral; naming it would be the same overreach
+as recommending a model.
+
+## The aggregates
+
+| aggregate | reading |
+| --- | --- |
+| `net` | mean of the −1/0/+1 series, with `mixed` cancelling to zero. Positive means progressing, *even with much still open* |
+| `oscillation` | direction reversals. `held` and `mixed` are pauses, not reversals |
+| `longestStall` | longest run that did not net forward — `mixed` counts as not netting forward |
+| `advancedRate`, `regressedRate` | **marginals**, so they overlap on `mixed`. The gap between `mixedRate` and what independence would predict is the interesting part |
+
+Percentiles and variance are deliberately absent. Over a window this short they
+are noise, and over a three-valued series spread is nearly redundant with the
+proportions.
+
+## Where the pieces live
+
+- **This package** — the questions, the judge, and pure aggregation. No I/O, no
+  state, no rendering.
+- **The host** — the window, the reset point, and the wording. The tally is
+  cumulative from the last **state transition** and resets to `0/0` there, which
+  the host decides because a phase change is not this package's concern.
+
+## Caveats
+
+- **No eval baselines.** The old cases — `detail-spiral`, `framing-loop`,
+  `design-open` — were labelled against the retired categories. Until they are
+  re-baselined against the rates, this signal is **unvalidated**.
+- **A turn counts only when both answers are decisive enough.** The gate is on
+  **decisiveness** — distance from the midpoint — not on the raw probability. A
+  clear advance has `P(regress) ≈ 0.1`, so gating on the probability would exclude
+  every one-sided turn and leave the signal inert. The weaker of the two decides,
+  which keeps one denominator and makes the rates comparable. Below it the turn is
+  excluded, not forced to `held`.
+- **Sensitivity falls as the stretch lengthens.** A three-turn spiral inside a
+  forty-turn stretch barely moves the rates. If that becomes a problem the fix is
+  a second, shorter measure alongside this one.
+- **Never used in a real session.** Like everything here, it is younger than the
+  problem it is meant to observe.
+
+## License
+
+Apache-2.0.

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The progress signal.
+ *
+ * Two orthogonal Noul judgments per settled turn — did it advance the work, did
+ * it reopen something — composed into four outcomes, plus pure arithmetic over a
+ * series of them. It reports rates rather than a verdict: nothing here decides
+ * whether the work is "stuck", because the reader is the one who can tell a
+ * spiral from a correction.
+ *
+ * Read the README before relying on it. The tally's reset point is the host's
+ * business, and there are no eval baselines for this signal yet.
+ */
+import { type HistoryTurn, type JevConfig } from "@mohan-cao/jev-classifier";
+import { ADVANCE_QUESTION, REGRESS_QUESTION } from "./questions.js";
+import { PROGRESS, PROGRESS_VALUE, progressFrom, type Progress, type ProgressSummary, type TrajectoryJudgment } from "./types.js";
+export { ADVANCE_QUESTION, REGRESS_QUESTION };
+export { PROGRESS, PROGRESS_VALUE, progressFrom };
+export type { Progress, ProgressSummary, TrajectoryConfig, TrajectoryJudgment, } from "./types.js";
+/**
+ * The composed outcome of a judgment, at the Noul midpoint.
+ *
+ * The only place the cutoff appears, so nothing else has to know it.
+ */
+export declare function progressOf(judgment: TrajectoryJudgment): Progress;
+/**
+ * Its own call, not shared with verification, classification, or the phase
+ * judgment. They read different state and are conceptually independent — and
+ * questions sharing a call can perturb each other.
+ */
+export declare function judgeTrajectory(turns: HistoryTurn[], apiKey: string, config: JevConfig, parentSignal?: AbortSignal): Promise<TrajectoryJudgment>;
+/**
+ * Pure arithmetic over a series of judgments, in order.
+ *
+ * A turn counts only when **both** answers are decisive enough. Turns below the
+ * gate are excluded rather than forced to `held`: a turn the judge could not read
+ * should not inflate the denominator, and one denominator is what makes the
+ * rates comparable.
+ *
+ * `oscillation` counts direction reversals, not pauses — `held` and `mixed` both
+ * net to zero, so neither changes direction.
+ */
+export declare function summarizeProgress(judgments: TrajectoryJudgment[], minConfidence: number): ProgressSummary;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,SAAS,EACf,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EACL,QAAQ,EACR,cAAc,EACd,YAAY,EACZ,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACxB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,YAAY,EAAE,CAAC;AAClD,YAAY,EACV,QAAQ,EACR,eAAe,EACf,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAYpB;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,kBAAkB,GAAG,QAAQ,CAKjE;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,WAAW,EAAE,EACpB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,SAAS,EACjB,YAAY,CAAC,EAAE,WAAW,GACzB,OAAO,CAAC,kBAAkB,CAAC,CAc7B;AAeD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,kBAAkB,EAAE,EAC/B,aAAa,EAAE,MAAM,GACpB,eAAe,CAsEjB"}

package/dist/index.js

@@ -0,0 +1,134 @@
+/**
+ * The progress signal.
+ *
+ * Two orthogonal Noul judgments per settled turn — did it advance the work, did
+ * it reopen something — composed into four outcomes, plus pure arithmetic over a
+ * series of them. It reports rates rather than a verdict: nothing here decides
+ * whether the work is "stuck", because the reader is the one who can tell a
+ * spiral from a correction.
+ *
+ * Read the README before relying on it. The tally's reset point is the host's
+ * business, and there are no eval baselines for this signal yet.
+ */
+import { callSystemOne, parseNoulAnswer, } from "@mohan-cao/jev-classifier";
+import { ADVANCE_QUESTION, REGRESS_QUESTION } from "./questions.js";
+import { PROGRESS, PROGRESS_VALUE, progressFrom, } from "./types.js";
+export { ADVANCE_QUESTION, REGRESS_QUESTION };
+export { PROGRESS, PROGRESS_VALUE, progressFrom };
+const ADVANCE_ID = "advanced";
+const REGRESS_ID = "regressed";
+/**
+ * A Noul is a probability, so composing it into a boolean needs a midpoint.
+ * The reliability gate is separate and lives in `TrajectoryConfig`: 0.51 is
+ * enough to *call* it advancing, but not enough to count it.
+ */
+const NOUL_CUTOFF = 0.5;
+/**
+ * The composed outcome of a judgment, at the Noul midpoint.
+ *
+ * The only place the cutoff appears, so nothing else has to know it.
+ */
+export function progressOf(judgment) {
+    return progressFrom(judgment.advanceConfidence >= NOUL_CUTOFF, judgment.regressConfidence >= NOUL_CUTOFF);
+}
+/**
+ * Its own call, not shared with verification, classification, or the phase
+ * judgment. They read different state and are conceptually independent — and
+ * questions sharing a call can perturb each other.
+ */
+export async function judgeTrajectory(turns, apiKey, config, parentSignal) {
+    const payload = await callSystemOne({ recent_conversation: turns.map((turn) => `${turn.role}: ${turn.text}`) }, { [ADVANCE_ID]: ADVANCE_QUESTION, [REGRESS_ID]: REGRESS_QUESTION }, apiKey, config, parentSignal);
+    const advanceConfidence = parseNoulAnswer(payload, ADVANCE_ID);
+    const regressConfidence = parseNoulAnswer(payload, REGRESS_ID);
+    const judgment = { advanceConfidence, regressConfidence };
+    return payload.model ? { ...judgment, model: payload.model } : judgment;
+}
+/**
+ * How decisive a Noul answer is: its distance from the midpoint, as 0.5–1.
+ *
+ * A Noul carries P(true), so a *confidently false* answer has a **low**
+ * probability. Gating on the raw probability would therefore exclude every
+ * one-sided turn — a clear advance has `P(regress) ≈ 0.1`, and the minimum of the
+ * two would sit below any sensible threshold. What the gate wants is how far
+ * each answer is from a coin flip.
+ */
+function decisiveness(probability) {
+    return Math.max(probability, 1 - probability);
+}
+/**
+ * Pure arithmetic over a series of judgments, in order.
+ *
+ * A turn counts only when **both** answers are decisive enough. Turns below the
+ * gate are excluded rather than forced to `held`: a turn the judge could not read
+ * should not inflate the denominator, and one denominator is what makes the
+ * rates comparable.
+ *
+ * `oscillation` counts direction reversals, not pauses — `held` and `mixed` both
+ * net to zero, so neither changes direction.
+ */
+export function summarizeProgress(judgments, minConfidence) {
+    const counted = judgments.filter((judgment) => Math.min(decisiveness(judgment.advanceConfidence), decisiveness(judgment.regressConfidence)) >=
+        minConfidence);
+    if (counted.length === 0) {
+        return {
+            counted: 0,
+            advanced: 0,
+            regressed: 0,
+            mixed: 0,
+            advancedRate: 0,
+            regressedRate: 0,
+            mixedRate: 0,
+            net: 0,
+            oscillation: 0,
+            longestStall: 0,
+        };
+    }
+    let advanced = 0;
+    let regressed = 0;
+    let mixed = 0;
+    let oscillation = 0;
+    let longestStall = 0;
+    let stall = 0;
+    let lastSign = 0;
+    let sum = 0;
+    for (const judgment of counted) {
+        const progress = progressOf(judgment);
+        // Marginals of the two questions, so `mixed` counts toward both.
+        if (progress === "advanced" || progress === "mixed")
+            advanced += 1;
+        if (progress === "regressed" || progress === "mixed")
+            regressed += 1;
+        if (progress === "mixed")
+            mixed += 1;
+        const value = PROGRESS_VALUE[progress];
+        sum += value;
+        // A stall is any turn that did not net forward — `regressed` is no more
+        // progress than `held` is, and `mixed` cancels itself out.
+        if (value > 0) {
+            stall = 0;
+        }
+        else {
+            stall += 1;
+        }
+        longestStall = Math.max(longestStall, stall);
+        const sign = Math.sign(value);
+        if (sign !== 0) {
+            if (lastSign !== 0 && sign !== lastSign)
+                oscillation += 1;
+            lastSign = sign;
+        }
+    }
+    return {
+        counted: counted.length,
+        advanced,
+        regressed,
+        mixed,
+        advancedRate: advanced / counted.length,
+        regressedRate: regressed / counted.length,
+        mixedRate: mixed / counted.length,
+        net: sum / counted.length,
+        oscillation,
+        longestStall,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/questions.d.ts

@@ -0,0 +1,15 @@
+import type { NoulQuestionSpec } from "@mohan-cao/jev-classifier";
+/**
+ * The progress questions — two orthogonal Nouls, asked in one call.
+ *
+ * Deliberately **not** one ordinal scale. A turn can advance one thing and
+ * reopen another, and a single axis cannot say so; two independent answers
+ * compose into four outcomes in code, the same way classification keeps
+ * `normal` as a residual instead of a competing argmax candidate.
+ *
+ * Phase-agnostic on purpose: the same answers read correctly in build as in
+ * design, and converging on agreement counts as advancing.
+ */
+export declare const ADVANCE_QUESTION: NoulQuestionSpec;
+export declare const REGRESS_QUESTION: NoulQuestionSpec;
+//# sourceMappingURL=questions.d.ts.map

package/dist/questions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"questions.d.ts","sourceRoot":"","sources":["../src/questions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,gBAAgB,EAAE,gBAQ9B,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,gBAQ9B,CAAC"}

package/dist/questions.js

@@ -0,0 +1,28 @@
+/**
+ * The progress questions — two orthogonal Nouls, asked in one call.
+ *
+ * Deliberately **not** one ordinal scale. A turn can advance one thing and
+ * reopen another, and a single axis cannot say so; two independent answers
+ * compose into four outcomes in code, the same way classification keeps
+ * `normal` as a residual instead of a competing argmax candidate.
+ *
+ * Phase-agnostic on purpose: the same answers read correctly in build as in
+ * design, and converging on agreement counts as advancing.
+ */
+export const ADVANCE_QUESTION = {
+    type: "noul",
+    instructions: "Did this turn move the work forward? Judge the effect on the work itself, not how smoothly the conversation went, and judge it for any kind of work: a decision settled by agreement advances the work as much as a newly resolved detail does.",
+    criteria: {
+        true: "The turn settled something, moved the work forward, or converged on agreement.",
+        false: "The turn neither settled anything nor moved the work forward.",
+    },
+};
+export const REGRESS_QUESTION = {
+    type: "noul",
+    instructions: "Did this turn reopen or undo something previously settled? A detail that turned out to rest on a false premise counts — catching a wrong premise is the point, but it is still a reopening. Answer this independently of whether the turn also advanced something; both can be true of the same turn.",
+    criteria: {
+        true: "Something previously settled was reopened, revised, or undone.",
+        false: "Nothing previously settled was reopened or undone.",
+    },
+};
+//# sourceMappingURL=questions.js.map

package/dist/questions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"questions.js","sourceRoot":"","sources":["../src/questions.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAqB;IAChD,IAAI,EAAE,MAAM;IACZ,YAAY,EACV,iPAAiP;IACnP,QAAQ,EAAE;QACR,IAAI,EAAE,gFAAgF;QACtF,KAAK,EAAE,+DAA+D;KACvE;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAqB;IAChD,IAAI,EAAE,MAAM;IACZ,YAAY,EACV,uSAAuS;IACzS,QAAQ,EAAE;QACR,IAAI,EAAE,gEAAgE;QACtE,KAAK,EAAE,oDAAoD;KAC5D;CACF,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,94 @@
+import type { JevConfig } from "@mohan-cao/jev-classifier";
+/**
+ * What a single turn did to the work.
+ *
+ * Four outcomes composed from two orthogonal questions, not one ordinal scale.
+ * A turn can genuinely do both — settle the API shape and reopen the storage
+ * choice — and forcing that onto a single axis loses exactly the information
+ * that matters. This is the same reason classification asks two Nouls rather
+ * than one Choice: a single axis makes the residual compete in an argmax.
+ */
+export declare const PROGRESS: readonly ["held", "advanced", "regressed", "mixed"];
+export type Progress = (typeof PROGRESS)[number];
+/** Composed from the two answers. `mixed` is not a failure state: it is both. */
+export declare function progressFrom(advance: boolean, regress: boolean): Progress;
+/**
+ * −1, 0, +1 — the series the trend aggregates operate on.
+ *
+ * `mixed` nets to zero, because one thing moved each way. That is deliberate: a
+ * run of mixed turns keeps changing things without netting forward, which is a
+ * stall in the only sense this signal claims.
+ */
+export declare const PROGRESS_VALUE: {
+    regressed: number;
+    held: number;
+    mixed: number;
+    advanced: number;
+};
+/**
+ * What the progress judge observed on one settled turn.
+ *
+ * Deliberately carries **only the two answers**, not a composed label. A label
+ * here would be derived state that the type cannot keep consistent with its
+ * inputs, and anything reading it would have to trust that they agree. Compose
+ * with `progressOf` instead.
+ */
+export interface TrajectoryJudgment {
+    /** P(the turn advanced the work). */
+    advanceConfidence: number;
+    /** P(the turn reopened or undid something). */
+    regressConfidence: number;
+    model?: string;
+}
+/** Transport settings plus this component's settings. */
+export interface TrajectoryConfig extends JevConfig {
+    /** Conversation turns supplied to the progress judge. */
+    historyTurns: number;
+    /**
+     * Minimum **decisiveness** for both answers before a turn counts at all.
+     *
+     * A Noul carries P(true), so decisiveness is its distance from the midpoint —
+     * 0.7 means each answer is at least 70% sure of itself. Gating on the raw
+     * probability instead would exclude every one-sided turn, since a clear advance
+     * has `P(regress) ≈ 0.1`.
+     *
+     * Gating on the weaker of the two keeps a single denominator, which is what
+     * makes the rates comparable with one another. Below it the turn is excluded
+     * rather than forced to `held`, which would inflate the denominator with turns
+     * the judge could not read.
+     */
+    progressConfidenceThreshold: number;
+}
+/**
+ * The aggregates, all pure arithmetic over the counted turns.
+ *
+ * Nothing here decides whether the work is "stuck". That judgement belongs to
+ * the reader, and the point of reporting rates rather than a verdict is to give
+ * them what they need to make it.
+ */
+export interface ProgressSummary {
+    /** Turns where both answers cleared the confidence gate. */
+    counted: number;
+    /**
+     * Turns where *something* advanced — `mixed` included.
+     *
+     * The rates are marginals of the two questions, so `advancedRate` and
+     * `regressedRate` overlap on `mixed` turns. The gap between `mixedRate` and
+     * what independence would predict is the interesting part.
+     */
+    advanced: number;
+    /** Turns where something was reopened — `mixed` included. */
+    regressed: number;
+    /** Turns that did both. */
+    mixed: number;
+    advancedRate: number;
+    regressedRate: number;
+    mixedRate: number;
+    /** Mean of the −1/0/+1 series. Positive means the work is progressing, even with much still open. */
+    net: number;
+    /** Sign changes in the series — thrashing, whatever it is about. */
+    oscillation: number;
+    /** Longest run that did not net forward. `held` and `mixed` both count as not netting forward. */
+    longestStall: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAE3D;;;;;;;;GAQG;AACH,eAAO,MAAM,QAAQ,qDAAsD,CAAC;AAC5E,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjD,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,QAAQ,CAKzE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc;;;;;CAKS,CAAC;AAErC;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,+CAA+C;IAC/C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,yDAAyD;AACzD,MAAM,WAAW,gBAAiB,SAAQ,SAAS;IACjD,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;OAYG;IACH,2BAA2B,EAAE,MAAM,CAAC;CACrC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,qGAAqG;IACrG,GAAG,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAC;IACpB,kGAAkG;IAClG,YAAY,EAAE,MAAM,CAAC;CACtB"}

package/dist/types.js

@@ -0,0 +1,34 @@
+/**
+ * What a single turn did to the work.
+ *
+ * Four outcomes composed from two orthogonal questions, not one ordinal scale.
+ * A turn can genuinely do both — settle the API shape and reopen the storage
+ * choice — and forcing that onto a single axis loses exactly the information
+ * that matters. This is the same reason classification asks two Nouls rather
+ * than one Choice: a single axis makes the residual compete in an argmax.
+ */
+export const PROGRESS = ["held", "advanced", "regressed", "mixed"];
+/** Composed from the two answers. `mixed` is not a failure state: it is both. */
+export function progressFrom(advance, regress) {
+    if (advance && regress)
+        return "mixed";
+    if (advance)
+        return "advanced";
+    if (regress)
+        return "regressed";
+    return "held";
+}
+/**
+ * −1, 0, +1 — the series the trend aggregates operate on.
+ *
+ * `mixed` nets to zero, because one thing moved each way. That is deliberate: a
+ * run of mixed turns keeps changing things without netting forward, which is a
+ * stall in the only sense this signal claims.
+ */
+export const PROGRESS_VALUE = {
+    regressed: -1,
+    held: 0,
+    mixed: 0,
+    advanced: 1,
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,OAAO,CAAU,CAAC;AAG5E,iFAAiF;AACjF,MAAM,UAAU,YAAY,CAAC,OAAgB,EAAE,OAAgB;IAC7D,IAAI,OAAO,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IACvC,IAAI,OAAO;QAAE,OAAO,UAAU,CAAC;IAC/B,IAAI,OAAO;QAAE,OAAO,WAAW,CAAC;IAChC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,SAAS,EAAE,CAAC,CAAC;IACb,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;IACR,QAAQ,EAAE,CAAC;CACuB,CAAC"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@mohan-cao/jev-trajectory",
+  "version": "0.1.0",
+  "description": "Jev progress signal: one signed per-turn judgment of whether the work advanced, held, or was reopened.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mohan-cao/pi-extensions.git",
+    "directory": "packages/jev-trajectory"
+  },
+  "keywords": [
+    "jev",
+    "typesafe-ai",
+    "system-one",
+    "classifier",
+    "llm"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@mohan-cao/jev-classifier": "^0.2.0"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.json",
+    "build:unchecked": "tsc -p tsconfig.json --noCheck",
+    "test": "node --test test/*.test.mjs"
+  }
+}