@jinn-network/client 0.1.8 → 0.1.9-canary.144d87d2

package/dist/learner/revert-decision.js

@@ -13,12 +13,17 @@
  *   - recentAttemptsWindow: how many most-recent attempts per codeDigest the
  *     aggregate is computed over. Overridable via implStateDir/policy.json
  *     (`policy.revert.recentAttemptsWindow`), mirroring policy.maxNotesBytes.
+ *   - gradedMinSamplesPerArm: minimum per-arm graded scores before the graded
+ *     (Tier 2) sensitivity test runs. Below it, Tier 2 is skipped entirely.
+ *   - gradedAlpha: significance threshold for the Mann-Whitney graded test.
  */
-import { twoProportionZTest } from './revert-stats.js';
+import { twoProportionZTest, mannWhitneyU } from './revert-stats.js';
 export const DEFAULT_REVERT_POLICY = {
     minSamplesPerArm: 30,
     alpha: 0.05,
     recentAttemptsWindow: 200,
+    gradedMinSamplesPerArm: 10,
+    gradedAlpha: 0.05,
 };
 export function decideRevert(input, policy = DEFAULT_REVERT_POLICY) {
     const { withCommit, atParent } = input;
@@ -26,25 +31,40 @@ export function decideRevert(input, policy = DEFAULT_REVERT_POLICY) {
         withCommit: { codeDigest: withCommit.codeDigest, n: withCommit.attempts, passRate: withCommit.passRate },
         atParent: { codeDigest: atParent.codeDigest, n: atParent.attempts, passRate: atParent.passRate },
     };
-    // Sample floor first — a zero-attempt codeDigest is "insufficient_samples",
-    // NOT pass-rate zero (a fresh promotion that has not run yet is not a regression).
-    if (withCommit.attempts < policy.minSamplesPerArm || atParent.attempts < policy.minSamplesPerArm) {
-        return { ...base, delta: withCommit.passRate - atParent.passRate, pValue: 1, significant: false, recommendRevert: false, reason: 'insufficient_samples' };
+    const mean = (xs) => (xs.length ? xs.reduce((s, v) => s + v, 0) / xs.length : 0);
+    const gradedReady = withCommit.gradedScores.length >= policy.gradedMinSamplesPerArm &&
+        atParent.gradedScores.length >= policy.gradedMinSamplesPerArm;
+    // gradedDelta is only meaningful when gradedReady; mean([]) === 0 is a sentinel otherwise.
+    const gradedDelta = gradedReady ? mean(withCommit.gradedScores) - mean(atParent.gradedScores) : 0;
+    // Tier 1 — binary objective.
+    const binaryUnderpowered = withCommit.attempts < policy.minSamplesPerArm || atParent.attempts < policy.minSamplesPerArm;
+    if (!binaryUnderpowered) {
+        const stats = twoProportionZTest({
+            passesA: withCommit.passes, totalA: withCommit.attempts,
+            passesB: atParent.passes, totalB: atParent.attempts,
+        });
+        const significant = stats.pValue < policy.alpha;
+        if (stats.delta >= 0) {
+            return { ...base, delta: stats.delta, pValue: stats.pValue, significant, recommendRevert: false, reason: 'no_regression' };
+        }
+        if (!significant) {
+            return { ...base, delta: stats.delta, pValue: stats.pValue, significant, recommendRevert: false, reason: 'not_significant' };
+        }
+        // Binary says significant regression. Confirmation guardrail: if graded
+        // data exists and DISAGREES (graded improved), hold rather than revert.
+        if (gradedReady && gradedDelta > 0) {
+            return { ...base, delta: stats.delta, pValue: stats.pValue, significant: true, recommendRevert: false, reason: 'binary_graded_disagree' };
+        }
+        return { ...base, delta: stats.delta, pValue: stats.pValue, significant: true, recommendRevert: true, reason: 'significant_regression' };
     }
-    const stats = twoProportionZTest({
-        passesA: withCommit.passes,
-        totalA: withCommit.attempts,
-        passesB: atParent.passes,
-        totalB: atParent.attempts,
-    });
-    const significant = stats.pValue < policy.alpha;
-    if (stats.delta >= 0) {
-        return { ...base, delta: stats.delta, pValue: stats.pValue, significant, recommendRevert: false, reason: 'no_regression' };
+    // Tier 2 — graded sensitivity (only when binary is underpowered).
+    if (gradedReady) {
+        const mw = mannWhitneyU(withCommit.gradedScores, atParent.gradedScores);
+        if (mw.pValue < policy.gradedAlpha && gradedDelta < 0) {
+            return { ...base, delta: gradedDelta, pValue: mw.pValue, significant: true, recommendRevert: true, reason: 'graded_regression_provisional' };
+        }
     }
-    if (!significant) {
-        return { ...base, delta: stats.delta, pValue: stats.pValue, significant, recommendRevert: false, reason: 'not_significant' };
-    }
-    return { ...base, delta: stats.delta, pValue: stats.pValue, significant: true, recommendRevert: true, reason: 'significant_regression' };
+    return { ...base, delta: withCommit.passRate - atParent.passRate, pValue: 1, significant: false, recommendRevert: false, reason: 'insufficient_samples' };
 }
 /** Merge a partial policy (e.g. from implStateDir/policy.json) over the defaults. */
 export function resolveRevertPolicy(override) {

package/dist/learner/revert-decision.js.map

@@ -1 +1 @@
-{"version":3,"file":"revert-decision.js","sourceRoot":"","sources":["../../src/learner/revert-decision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAWvD,MAAM,CAAC,MAAM,qBAAqB,GAAiB;IACjD,gBAAgB,EAAE,EAAE;IACpB,KAAK,EAAE,IAAI;IACX,oBAAoB,EAAE,GAAG;CAC1B,CAAC;AAiCF,MAAM,UAAU,YAAY,CAC1B,KAA0B,EAC1B,SAAuB,qBAAqB;IAE5C,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;IACvC,MAAM,IAAI,GAAG;QACX,UAAU,EAAE,EAAE,UAAU,EAAE,UAAU,CAAC,UAAU,EAAE,CAAC,EAAE,UAAU,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,CAAC,QAAQ,EAAE;QACxG,QAAQ,EAAE,EAAE,UAAU,EAAE,QAAQ,CAAC,UAAU,EAAE,CAAC,EAAE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE;KACjG,CAAC;IAEF,4EAA4E;IAC5E,mFAAmF;IACnF,IAAI,UAAU,CAAC,QAAQ,GAAG,MAAM,CAAC,gBAAgB,IAAI,QAAQ,CAAC,QAAQ,GAAG,MAAM,CAAC,gBAAgB,EAAE,CAAC;QACjG,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,UAAU,CAAC,QAAQ,GAAG,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC;IAC5J,CAAC;IAED,MAAM,KAAK,GAAG,kBAAkB,CAAC;QAC/B,OAAO,EAAE,UAAU,CAAC,MAAM;QAC1B,MAAM,EAAE,UAAU,CAAC,QAAQ;QAC3B,OAAO,EAAE,QAAQ,CAAC,MAAM;QACxB,MAAM,EAAE,QAAQ,CAAC,QAAQ;KAC1B,CAAC,CAAC;IACH,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC;IAEhD,IAAI,KAAK,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;QACrB,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,WAAW,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;IAC7H,CAAC;IACD,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,WAAW,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC/H,CAAC;IACD,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC;AAC3I,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,mBAAmB,CAAC,QAAgC;IAClE,OAAO,EAAE,GAAG,qBAAqB,EAAE,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,CAAC;AAC3D,CAAC"}
+{"version":3,"file":"revert-decision.js","sourceRoot":"","sources":["../../src/learner/revert-decision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAerE,MAAM,CAAC,MAAM,qBAAqB,GAAiB;IACjD,gBAAgB,EAAE,EAAE;IACpB,KAAK,EAAE,IAAI;IACX,oBAAoB,EAAE,GAAG;IACzB,sBAAsB,EAAE,EAAE;IAC1B,WAAW,EAAE,IAAI;CAClB,CAAC;AA2CF,MAAM,UAAU,YAAY,CAC1B,KAA0B,EAC1B,SAAuB,qBAAqB;IAE5C,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;IACvC,MAAM,IAAI,GAAG;QACX,UAAU,EAAE,EAAE,UAAU,EAAE,UAAU,CAAC,UAAU,EAAE,CAAC,EAAE,UAAU,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,CAAC,QAAQ,EAAE;QACxG,QAAQ,EAAE,EAAE,UAAU,EAAE,QAAQ,CAAC,UAAU,EAAE,CAAC,EAAE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE;KACjG,CAAC;IAEF,MAAM,IAAI,GAAG,CAAC,EAAY,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3F,MAAM,WAAW,GACf,UAAU,CAAC,YAAY,CAAC,MAAM,IAAI,MAAM,CAAC,sBAAsB;QAC/D,QAAQ,CAAC,YAAY,CAAC,MAAM,IAAI,MAAM,CAAC,sBAAsB,CAAC;IAChE,2FAA2F;IAC3F,MAAM,WAAW,GAAG,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAElG,6BAA6B;IAC7B,MAAM,kBAAkB,GACtB,UAAU,CAAC,QAAQ,GAAG,MAAM,CAAC,gBAAgB,IAAI,QAAQ,CAAC,QAAQ,GAAG,MAAM,CAAC,gBAAgB,CAAC;IAE/F,IAAI,CAAC,kBAAkB,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,kBAAkB,CAAC;YAC/B,OAAO,EAAE,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,QAAQ;YACvD,OAAO,EAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,QAAQ;SACpD,CAAC,CAAC;QACH,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC;QAChD,IAAI,KAAK,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;YACrB,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,WAAW,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;QAC7H,CAAC;QACD,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,WAAW,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;QAC/H,CAAC;QACD,wEAAwE;QACxE,wEAAwE;QACxE,IAAI,WAAW,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;YACnC,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC;QAC5I,CAAC;QACD,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC;IAC3I,CAAC;IAED,kEAAkE;IAClE,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,EAAE,GAAG,YAAY,CAAC,UAAU,CAAC,YAAY,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAC;QACxE,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,WAAW,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;YACtD,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,EAAE,+BAA+B,EAAE,CAAC;QAC/I,CAAC;IACH,CAAC;IAED,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,UAAU,CAAC,QAAQ,GAAG,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC;AAC5J,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,mBAAmB,CAAC,QAAgC;IAClE,OAAO,EAAE,GAAG,qBAAqB,EAAE,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,CAAC;AAC3D,CAAC"}

package/dist/learner/revert-stats.d.ts

@@ -22,3 +22,17 @@ export interface TwoProportionResult {
 }
 /** Two-proportion z-test. Returns no-signal (z=0, p=1) if either total is 0. */
 export declare function twoProportionZTest(input: TwoProportionInput): TwoProportionResult;
+export interface MannWhitneyResult {
+    /** U statistic for arm A. */
+    u: number;
+    /** Normal-approx z (sign matches "A − B": negative => A stochastically lower). */
+    z: number;
+    /** Two-sided p-value in [0, 1]; 1 when there is no signal or an arm is empty. */
+    pValue: number;
+}
+/**
+ * Mann-Whitney U (rank-sum) with tie correction and normal approximation.
+ * Rank-based per the design §3 — robust to the bounded/bimodal/miscalibrated
+ * graded-score distribution. No I/O. (#1019)
+ */
+export declare function mannWhitneyU(a: number[], b: number[]): MannWhitneyResult;

package/dist/learner/revert-stats.js

@@ -41,4 +41,46 @@ function erf(x) {
             Math.exp(-x * x);
     return x >= 0 ? y : -y;
 }
+/**
+ * Mann-Whitney U (rank-sum) with tie correction and normal approximation.
+ * Rank-based per the design §3 — robust to the bounded/bimodal/miscalibrated
+ * graded-score distribution. No I/O. (#1019)
+ */
+export function mannWhitneyU(a, b) {
+    const nA = a.length;
+    const nB = b.length;
+    if (nA === 0 || nB === 0)
+        return { u: 0, z: 0, pValue: 1 };
+    const all = [...a.map((v) => ({ v, g: 0 })), ...b.map((v) => ({ v, g: 1 }))];
+    all.sort((x, y) => x.v - y.v);
+    // Average ranks (1-based), tie-aware.
+    const ranks = new Array(all.length).fill(0);
+    let i = 0;
+    let tieTerm = 0; // Σ (t³ − t) over tie groups, for the variance correction
+    while (i < all.length) {
+        let j = i;
+        while (j + 1 < all.length && all[j + 1].v === all[i].v)
+            j++;
+        const avgRank = (i + 1 + (j + 1)) / 2;
+        for (let k = i; k <= j; k++)
+            ranks[k] = avgRank;
+        const t = j - i + 1;
+        if (t > 1)
+            tieTerm += t * t * t - t;
+        i = j + 1;
+    }
+    let rankSumA = 0;
+    for (let k = 0; k < all.length; k++)
+        if (all[k].g === 0)
+            rankSumA += ranks[k];
+    const uA = rankSumA - (nA * (nA + 1)) / 2;
+    const n = nA + nB;
+    const meanU = (nA * nB) / 2;
+    const varU = (nA * nB / (n * (n - 1))) * ((n * n * n - n) / 12 - tieTerm / 12);
+    if (varU <= 0)
+        return { u: uA, z: 0, pValue: 1 };
+    const z = (uA - meanU) / Math.sqrt(varU);
+    const pValue = 2 * (1 - standardNormalCdf(Math.abs(z)));
+    return { u: uA, z, pValue };
+}
 //# sourceMappingURL=revert-stats.js.map

package/dist/learner/revert-stats.js.map

@@ -1 +1 @@
-{"version":3,"file":"revert-stats.js","sourceRoot":"","sources":["../../src/learner/revert-stats.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAkBH,gFAAgF;AAChF,MAAM,UAAU,kBAAkB,CAAC,KAAyB;IAC1D,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IACnD,IAAI,MAAM,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QAC/B,MAAM,EAAE,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7C,MAAM,EAAE,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7C,OAAO,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;IAC7C,CAAC;IACD,MAAM,EAAE,GAAG,OAAO,GAAG,MAAM,CAAC;IAC5B,MAAM,EAAE,GAAG,OAAO,GAAG,MAAM,CAAC;IAC5B,MAAM,KAAK,GAAG,EAAE,GAAG,EAAE,CAAC;IACtB,MAAM,MAAM,GAAG,CAAC,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IACvD,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;IACxE,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC;QACb,wDAAwD;QACxD,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;IACpC,CAAC;IACD,MAAM,CAAC,GAAG,KAAK,GAAG,EAAE,CAAC;IACrB,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxD,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;AAC9B,CAAC;AAED,gFAAgF;AAChF,SAAS,iBAAiB,CAAC,CAAS;IAClC,OAAO,GAAG,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;AACzC,CAAC;AAED,SAAS,GAAG,CAAC,CAAS;IACpB,qDAAqD;IACrD,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5C,MAAM,CAAC,GACL,CAAC;QACD,CAAC,CAAC,CAAC,CAAC,WAAW,GAAG,CAAC,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,GAAG,CAAC;YAC1E,WAAW,CAAC;YACZ,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACzB,CAAC"}
+{"version":3,"file":"revert-stats.js","sourceRoot":"","sources":["../../src/learner/revert-stats.ts"],"names":[],"mappings":"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"}

package/dist/local-provider-url.d.ts

@@ -0,0 +1,3 @@
+export declare function canonicalLocalHttpBaseUrl(value: string): string | undefined;
+export declare function isLocalHttpBaseUrl(value: string): boolean;
+export declare function urlAtBasePath(baseUrl: string, path: string): string;

package/dist/local-provider-url.js

@@ -0,0 +1,28 @@
+import { isIP } from 'node:net';
+export function canonicalLocalHttpBaseUrl(value) {
+    try {
+        const url = new URL(value);
+        if (url.protocol !== 'http:' && url.protocol !== 'https:')
+            return undefined;
+        if (url.username || url.password)
+            return undefined;
+        if (url.search || url.hash)
+            return undefined;
+        const hostname = url.hostname.toLowerCase();
+        const isLocal = hostname === 'localhost' ||
+            hostname === '[::1]' ||
+            hostname === '::1' ||
+            (isIP(hostname) === 4 && hostname.startsWith('127.'));
+        return isLocal ? url.toString() : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function isLocalHttpBaseUrl(value) {
+    return canonicalLocalHttpBaseUrl(value) !== undefined;
+}
+export function urlAtBasePath(baseUrl, path) {
+    return new URL(path, baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`).toString();
+}
+//# sourceMappingURL=local-provider-url.js.map

package/dist/local-provider-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-provider-url.js","sourceRoot":"","sources":["../src/local-provider-url.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAEhC,MAAM,UAAU,yBAAyB,CAAC,KAAa;IACrD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;QAC3B,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QAC5E,IAAI,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ;YAAE,OAAO,SAAS,CAAC;QACnD,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI;YAAE,OAAO,SAAS,CAAC;QAC7C,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;QAC5C,MAAM,OAAO,GACX,QAAQ,KAAK,WAAW;YACxB,QAAQ,KAAK,OAAO;YACpB,QAAQ,KAAK,KAAK;YAClB,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;QACxD,OAAO,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,OAAO,yBAAyB,CAAC,KAAK,CAAC,KAAK,SAAS,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,IAAY;IACzD,OAAO,IAAI,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC;AACnF,CAAC"}

package/dist/main.js

@@ -43,6 +43,8 @@ import { buildEnvelope, emitEnvelope } from './errors/envelope.js';
 import { clearBootstrapError, persistBootstrapError, } from './errors/persisted-bootstrap-error.js';
 import { emitStructured } from './events/emitter.js';
 import { applyPidfileLivenessGate } from './preflight/pidfile-liveness.js';
+import { applyDeploymentReadinessGate } from './preflight/deployment-readiness.js';
+import { detectAuthContext } from './preflight/claude-auth.js';
 import { FleetBootstrapper, recoverEvictedService as recoverEvictedServiceFn } from './earning/bootstrap.js';
 import { DEFAULT_TESTNET_ARTIFACTS, applyChainGasOverrides, getChainConfig, loadJinnMviConfig } from './earning/contracts.js';
 import { runLegacyAgentIdMigration } from './earning/migrate-agent-id.js';
@@ -60,7 +62,8 @@ import { createJinnPublicClient, createJinnWalletClient, createJinnL1PublicClien
 import { privateKeyToAccount } from 'viem/accounts';
 import { getAddress } from 'viem';
 import { DEFAULT_DISABLED_HARNESSES, DEFAULT_HARNESS, HarnessRegistry, } from './harnesses/engine/registry.js';
-import { joinedSolverNetsViewFromConfig } from './harnesses/engine/engine.js';
+import { createMutableJoinedSolverNetsView } from './harnesses/engine/engine.js';
+import { createJoinApplier } from './daemon/join-applier.js';
 import { buildHarnesses } from './harnesses/impls/index.js';
 import { loadExternalImpl } from './harnesses/external-impls/index.js';
 import { CLAUDE_CODE_HARNESS, CODEX_HARNESS, HERMES_AGENT_HARNESS, harnessStateDirName } from './harnesses/names.js';
@@ -858,6 +861,13 @@ export async function main() {
     // builder-artifacts. Holder ref lets the routes register eagerly and
     // start returning real data the moment main.ts assigns holder.current.
     const discoveryApiHolder = { current: undefined };
+    // #1037: same eager-register / late-populate pattern for the join applier.
+    // The join endpoint registers eagerly inside startApiServer; the applier is
+    // built only after the latest join-consuming subsystem (the engine view,
+    // wired in the Daemon ctor). The endpoint tolerates an empty holder in the
+    // gap between server-start and populate by falling back to
+    // restartRequired:true.
+    const joinApplierHolder = { current: undefined };
     // hjex.6: retry signal for the bootstrap halt-and-resume loop.
     // When a SetupBootstrapHalted is caught (fatal non-funding error or funding
     // timeout), main() waits on this promise instead of returning, so the setup
@@ -964,6 +974,7 @@ export async function main() {
                     rpcUrl: config.rpcUrl,
                     defaultRpcUrl: CHAIN_CONFIG.rpcUrl,
                     joinedSolverNets: config.joinedSolverNets,
+                    onboardingComplete: config.onboardingComplete,
                 }),
             },
             // SolverNet catalog. Stubbed to the bundled `prediction` net for v1.
@@ -1111,6 +1122,17 @@ export async function main() {
                         resolve();
                     });
                 },
+                // #1037: hot-apply a join to the running daemon. Populated after the
+                // join-consuming subsystems are built (see joinApplierHolder). Empty
+                // until then → the endpoint returns restartRequired:true.
+                joinApplier: joinApplierHolder,
+                // #983: mutate the in-memory config so GET /v1/bootstrap reflects the
+                // completion flag live (the endpoint persists to disk; this keeps the
+                // configReader's in-memory read consistent — same pattern as the
+                // join-applier's config write). Cast: JinnConfig has the optional field.
+                markOnboardingComplete: () => {
+                    config.onboardingComplete = true;
+                },
             },
             status: {
                 earningDir: config.earningDir,
@@ -1547,6 +1569,28 @@ export async function main() {
     // the panel's next refetch. Before this, the routes 404'd forever and
     // the /build page rendered "Discovery unavailable" permanently.
     discoveryApiHolder.current = sharedDiscoveryApi;
+    // #1037: the live task-discovery descriptor. Always present with a mutable
+    // `solverNetManifestCids` array (`taskDiscoveryManifestCids` is a fresh
+    // `.map` result, safe to push onto). The join applier holds this same object
+    // reference and pushes a newly-joined cid onto it live.
+    const taskDiscovery = {
+        discoveryApi: sharedDiscoveryApi,
+        solverNetManifestCids: taskDiscoveryManifestCids,
+        // No explicit `onchainFromBlock` by default — let `MechAdapter`'s
+        // `DEFAULT_TASK_DISCOVERY_FROM_BLOCK` per-chain default flow through.
+        // Hardcoding here shadowed the adapter's default and re-introduced the
+        // ghost-task floor every release; removing the shadow makes `adapter.ts`
+        // the single source of truth. See gh #300. An operator MAY opt in to a
+        // recent floor via `taskDiscoveryOnchainFromBlock` to bound the canonical
+        // getLogs scan (which otherwise parses a large history on the main thread
+        // and can stall the loop) and lean on the indexer DiscoveryAPI.
+        ...(config.taskDiscoveryOnchainFromBlock !== undefined
+            ? { onchainFromBlock: config.taskDiscoveryOnchainFromBlock }
+            : {}),
+        ...(config.taskDiscoveryAllowedTaskIds?.length
+            ? { allowedTaskIds: config.taskDiscoveryAllowedTaskIds }
+            : {}),
+    };
     const adapter = new MechAdapter({
         rpcUrl: config.rpcUrls,
         mechMarketplaceAddress: MARKETPLACE_ADDRESS,
@@ -1560,27 +1604,7 @@ export async function main() {
         chainId: config.network === 'testnet' ? 84532 : 8453,
         routerClaimDeliveryVariant: CHAIN_CONFIG.routerClaimDeliveryVersion,
         evictionRecovery,
-        taskDiscovery: taskDiscoveryManifestCids.length > 0
-            ? {
-                discoveryApi: sharedDiscoveryApi,
-                solverNetManifestCids: taskDiscoveryManifestCids,
-                // No explicit `onchainFromBlock` by default — let `MechAdapter`'s
-                // `DEFAULT_TASK_DISCOVERY_FROM_BLOCK` per-chain default flow
-                // through. Hardcoding here shadowed the adapter's default and
-                // re-introduced the ghost-task floor every release; removing the
-                // shadow makes `adapter.ts` the single source of truth. See gh
-                // #300. An operator MAY opt in to a recent floor via
-                // `taskDiscoveryOnchainFromBlock` to bound the canonical getLogs
-                // scan (which otherwise parses a large history on the main thread
-                // and can stall the loop) and lean on the indexer DiscoveryAPI.
-                ...(config.taskDiscoveryOnchainFromBlock !== undefined
-                    ? { onchainFromBlock: config.taskDiscoveryOnchainFromBlock }
-                    : {}),
-                ...(config.taskDiscoveryAllowedTaskIds?.length
-                    ? { allowedTaskIds: config.taskDiscoveryAllowedTaskIds }
-                    : {}),
-            }
-            : undefined,
+        taskDiscovery,
     }, sharedStore);
     // ── TaskEngine wiring ─────────────────────────────────────────────────
     // Build agent viem clients (same creds as MechAdapter uses internally).
@@ -1729,6 +1753,7 @@ export async function main() {
         hermesPath: config.hermesPath,
         hermesModel: config.hermesModel,
         hermesProvider: config.hermesProvider,
+        hermesBaseUrl: config.hermesBaseUrl,
         hermesDoctorTimeoutMs: config.hermesDoctorTimeoutMs,
         codexPath: config.codexPath,
         codexDoctorTimeoutMs: config.codexDoctorTimeoutMs,
@@ -1762,6 +1787,13 @@ export async function main() {
     // is no longer needed and would throw on Hono's locked matcher.
     harnessReadinessRegistryHolder.current = harnessReadinessRegistry;
     console.log('[main] HarnessReadinessRegistry started; /v1/harnesses/readiness routes active.');
+    // #1037: always construct the engine eligibility view (mutable) so a
+    // hot-applied join can inject its cid live. Previously this was wired only
+    // when config.joinedSolverNets was truthy; a zero-join daemon then ran the
+    // legacy solverType gate. With an always-present empty view, a zero-join
+    // daemon rejects cid-bearing tasks (its discovery cid set is empty so it
+    // discovers none) and still passes legacy no-cid tasks. See plan §behaviour-change.
+    const joinedSolverNetsView = createMutableJoinedSolverNetsView(config.joinedSolverNets);
     // ── Engine deps ───────────────────────────────────────────────────────────────
     // Packaging deps: artifacts are always written to served_artifacts
     // (operator-local SQLite). In public-testnet donation mode, scrubbed artifact
@@ -2070,6 +2102,7 @@ export async function main() {
                 agentEoa: agentEoaAddress,
                 safeAddress,
                 agentPrivateKey,
+                ipfsGatewayUrl: config.ipfsGatewayUrl,
                 ...(sharedDiscoveryApi ? { discoveryApi: sharedDiscoveryApi } : {}),
             },
             logger: {
@@ -2226,9 +2259,8 @@ export async function main() {
             // doesn't match a joined entry (plus a role gate). Absent when the
             // operator hasn't joined any nets yet — the engine then falls back to
             // the legacy solverType-keyed gate.
-            ...(config.joinedSolverNets
-                ? { joinedSolverNets: joinedSolverNetsViewFromConfig(config.joinedSolverNets) }
-                : {}),
+            // #1037: always wire the (mutable) view so a hot-applied join is live.
+            joinedSolverNets: joinedSolverNetsView,
             // Spec §14: task validation resolves manifest → contract → schemas.
             // Threaded only when the SolverNet registry client was constructed
             // (testnet branch above). The engine treats absence as "schema
@@ -2262,6 +2294,7 @@ export async function main() {
             CHAIN_CONFIG.distributorAddress
             ? {
                 intervalMs: config.evictionCheckIntervalMs,
+                reStakeThrottleMs: config.checkpointIntervalMs,
                 store: earningStore,
                 chain: NETWORK_CHAIN,
                 readContract: (opts) => publicClient.readContract(opts),
@@ -2309,13 +2342,49 @@ export async function main() {
                 },
             }
             : undefined,
+        // #1043 loop watchdog. Always constructed in production so a stale loop is
+        // detected + surfaced; the process-exit recovery is flag-gated (default
+        // OFF) by config.watchdogAutoRestart.
+        watchdog: { autoRestart: config.watchdogAutoRestart },
+    });
+    // #1037: populate the join applier now that all four join-consuming
+    // subsystems exist — the live task-discovery descriptor (`taskDiscovery`),
+    // the mutable engine view (`joinedSolverNetsView`), the readiness registry,
+    // and the SolverNet registry. The join endpoint registered eagerly at
+    // server-start; before this point it returns restartRequired:true.
+    joinApplierHolder.current = createJoinApplier({
+        taskDiscovery,
+        view: joinedSolverNetsView,
+        readiness: harnessReadinessRegistry,
+        registry: solverNetRegistry,
+        config,
     });
+    if (config.watchdogAutoRestart) {
+        console.log('[watchdog] auto-restart ENABLED (stale loop → non-zero exit)');
+    }
     // Write pidfile so `jinn stop` can find us. First, refuse the run if another
     // daemon already owns this earning directory — see issue #649. The gate
     // handles all three branches (refuse-and-exit, unlink-stale-and-continue,
     // proceed); the writeFileSync below MUST stay outside the helper so the
     // "// DO NOT add store mutations above this line — see #649" invariant is
     // visible right here at the call site.
+    // Deployment-readiness gate (#958). In a deployment context (JINN_STATE_DIR
+    // set or a container/compose auth context) this fails loud and exits when a
+    // hard check fails (writable-volume, state-on-volume, agent-cli-non-root).
+    // Outside a deployment context it only logs advisories — a plain local
+    // `jinn run` is NEVER newly gated here. Runs before the pidfile gate so an
+    // unfit environment refuses before we touch the pidfile.
+    await applyDeploymentReadinessGate({
+        stateDir: config.stateDir,
+        earningDir: config.earningDir,
+        relayerUrl: undefined,
+        runtimeMode: config.runtimeMode,
+    }, {
+        env: process.env,
+        getuid: typeof process.getuid === 'function' ? process.getuid.bind(process) : undefined,
+        detectAuthContext,
+        fetch,
+    });
     const pidPath = join(config.earningDir, 'daemon.pid');
     applyPidfileLivenessGate(pidPath);
     writeFileSyncMain(pidPath, String(process.pid) + '\n', 'utf-8');