pi-pier 0.3.0 → 0.4.1

package/src/jev-client.ts

@@ -1,23 +1,17 @@
 /**
- * Jev decision layer — direct HTTP client (RFC docs/rfc-jev-integration.md §5).
+ * Jev decision layer — direct HTTP client (RFC docs/rfc-jev-integration.md §5). Not the official SDK
+ * (@typesafe-ai/sdk): its retry machinery has no total-latency budget (timeouts retried by default,
+ * Retry-After honored up to 60s), which is incompatible with pier's fail-open budgets.
  *
- * Why not the official SDK (@typesafe-ai/sdk v0.6.0): its retry machinery has
- * no total-latency budget (DEFAULT_TIMEOUT_MS is per attempt, apiTimeoutError
- * retries timeouts by default, Retry-After honored up to 60s — worst case
- * >80s), which is incompatible with pier's fail-open budgets. The call surface
- * here is one endpoint and three question types, and pi-pier ships as an npm
- * package where a zero-dependency transport wins. Payload is pinned to the
- * versioned model id; see the RFC for re-evaluation triggers.
- *
- * Every ask() resolves (never throws): errors, timeouts, 429s and low
- * confidence at the call site all mean " unanswered" -> caller fails open.
+ * Every ask() resolves (never throws): errors, timeouts, 429s and low confidence at the call site
+ * all mean unanswered, and the caller fails open.
  */
 import { sha256Hex } from './observation-core.ts';
 import { appendEfficiencyLog, efficiencyLogPath } from './efficiency-store.ts';
 import { parseJevAnswers, type JevAnswer, type JevQuestion, type JevUsage } from './jev-core.ts';
 import type { JevConfig } from './efficiency-config-core.ts';
 
-export const JEV_DEFAULT_BASE_URL = 'https://api.typesafe.ai';
+const JEV_DEFAULT_BASE_URL = 'https://api.typesafe.ai';
 
 export interface JevAskMeta {
   /** Stable question-set id for telemetry rows (e.g. 'epr-diagnostic-gate'). */
@@ -28,9 +22,8 @@ export interface JevAskMeta {
   /** Site-specific static fields for telemetry; must never contain request bodies. */
   extra?: Record<string, unknown>;
   /**
-   * Post-answer decision fields for telemetry (choices/scores/final verdicts —
-   * the data later threshold tuning needs; still never request bodies).
-   * Called exactly once per ask, success or failure.
+   * Post-answer decision fields for telemetry (choices/scores/final verdicts — what threshold tuning
+   * needs; still never request bodies). Called exactly once per ask.
    */
   enrich?: (outcome: { ok: boolean; answers: Record<string, JevAnswer> | null }) => Record<string, unknown>;
 }
@@ -44,6 +37,8 @@ export interface JevRuntimeDeps {
   now?: () => number;
   /** Session root for jev.jsonl; telemetry is skipped when absent. */
   getSessionRoot?: () => string | null;
+  /** Session id fallback for telemetry rows; sites that know it pass meta.sessionId instead. */
+  getSessionId?: () => string | null | undefined;
 }
 
 export interface JevRuntime {
@@ -70,8 +65,8 @@ export function createJevRuntime(getConfig: () => JevConfig, deps: JevRuntimeDep
     const record: Record<string, unknown> = {
       schema: 'pier-efficiency/1',
       mechanism: 'jev',
+      sessionId: meta.sessionId ?? deps.getSessionId?.() ?? 'unknown',
       ts: new Date(now()).toISOString(),
-      sessionId: meta.sessionId ?? 'unknown',
       questionId: meta.questionId,
       model: outcome.ok ? outcome.model : config.model,
       latencyMs,
@@ -87,7 +82,7 @@ export function createJevRuntime(getConfig: () => JevConfig, deps: JevRuntimeDep
     try {
       await appendEfficiencyLog(efficiencyLogPath(sessionRoot, 'jev'), record);
     } catch {
-      // Telemetry is best effort; never surface logging failures.
+      /* Never surfaced to the caller. */
     }
   }
 

package/src/jev-core.ts

@@ -1,23 +1,17 @@
 /**
  * Jev decision layer — pure core (RFC docs/rfc-jev-integration.md).
  *
- * Question/answer shapes mirror the closed set of POST /v1/systemone
- * (https://docs.typesafe.ai/api): noul / choice / score. No I/O here; the HTTP
- * client + jev.jsonl telemetry live in jev-client.ts.
+ * Question/answer shapes mirror the closed set of POST /v1/systemone (https://docs.typesafe.ai/api):
+ * noul / choice / score. No I/O here; the HTTP client and jev.jsonl telemetry live in jev-client.ts.
  *
- * Design rules from the RFC:
- *  - arithmetic, counting and thresholds stay in code (jaggedness #2/#3);
- *  - state is minimal — only the fields each question needs (jaggedness #5);
- *  - instructions are English (models page: English is the primary training
- *    language; CJK is handled but weaker, so P0-2 runs a stricter gate);
- *  - any answer below its confidence gate counts as unanswered -> caller
- *    fails open to the existing heuristic.
+ * RFC design rules: arithmetic, counting and thresholds stay in code; state carries only what each
+ * question needs; instructions are English (CJK is weaker, hence the stricter P0-2 gate); and any
+ * answer below its confidence gate counts as unanswered so callers fail open.
  */
-import { FAILURE_SIGNAL } from './reducer-core.ts';
+import { isPlainObject } from './guards.ts';
+import { containsLikelySecret, FAILURE_SIGNAL } from './reducer-core.ts';
 
-// ---------------------------------------------------------------------------
-// Request/response shapes (closed set)
-// ---------------------------------------------------------------------------
+/* ── Request/response shapes (closed set) ── */
 
 export type JevQuestion =
   | { readonly type: 'noul'; readonly instructions: string; readonly criteria?: { readonly true?: string; readonly false?: string } }
@@ -43,9 +37,6 @@ export type JevParsed =
   | { readonly ok: true; readonly answers: Record<string, JevAnswer>; readonly model: string; readonly usage: JevUsage }
   | { readonly ok: false; readonly reason: string };
 
-function isPlainObject(v: unknown): v is Record<string, unknown> {
-  return typeof v === 'object' && v !== null && !Array.isArray(v);
-}
 
 function finiteNumber(v: unknown): number | undefined {
   return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
@@ -56,6 +47,18 @@ function unitNumber(v: unknown): number | undefined {
   return n !== undefined && n >= 0 && n <= 1 ? n : undefined;
 }
 
+type AnswerOf<T extends JevAnswer['type']> = Extract<JevAnswer, { type: T }>;
+
+/** A missing or wrongly-shaped answer counts as unanswered, never as a verdict (RFC fail-open). */
+function answerOf<T extends JevAnswer['type']>(
+  answers: Record<string, JevAnswer>,
+  id: string,
+  type: T,
+): AnswerOf<T> | undefined {
+  const answer = answers[id];
+  return answer?.type === type ? answer as AnswerOf<T> : undefined;
+}
+
 function parseProbabilities(v: unknown): Record<string, number> | undefined {
   if (!isPlainObject(v)) return undefined;
   const out: Record<string, number> = {};
@@ -67,11 +70,8 @@ function parseProbabilities(v: unknown): Record<string, number> | undefined {
   return out;
 }
 
-/**
- * Strict validation of one response against the question ids we sent.
- * Extra answer ids are ignored; every expected id must be present and
- * well-formed or the whole call counts as unanswered (fail-open).
- */
+/** Strict validation of one response against the question ids we sent: extra ids are ignored, and
+ *  every expected id must be present and well-formed or the call counts as unanswered (fail-open). */
 export function parseJevAnswers(raw: unknown, expectedIds: readonly string[]): JevParsed {
   if (!isPlainObject(raw)) return { ok: false, reason: 'response-not-object' };
   const model = typeof raw.model === 'string' && raw.model.trim() ? raw.model : undefined;
@@ -120,9 +120,7 @@ export function parseJevAnswers(raw: unknown, expectedIds: readonly string[]): J
   return { ok: true, answers, model, usage: { inputTokens, outputTokens } };
 }
 
-// ---------------------------------------------------------------------------
-// P0-1: EPR diagnostic-command gate
-// ---------------------------------------------------------------------------
+/* ── P0-1: EPR diagnostic-command gate ── */
 
 export const DIAGNOSTIC_OUTPUT_MIN_NOUL = 0.6;
 
@@ -152,18 +150,16 @@ export interface DiagnosticGateVerdict {
   readonly hit: boolean;
   readonly reason: string;
   readonly confidence: number | null;
-  /** Selected cmd_kind option (telemetry); null when the answer was malformed. */
   readonly choice: string | null;
-  /** diagnostic_output noul value (telemetry); null when the answer was malformed. */
   readonly noul: number | null;
 }
 export function evaluateDiagnosticGate(
   answers: Record<string, JevAnswer>,
   minConfidence: number,
 ): DiagnosticGateVerdict {
-  const kind = answers.cmd_kind;
-  const output = answers.diagnostic_output;
-  if (kind === undefined || output === undefined || kind.type !== 'choice' || output.type !== 'noul') {
+  const kind = answerOf(answers, 'cmd_kind', 'choice');
+  const output = answerOf(answers, 'diagnostic_output', 'noul');
+  if (kind === undefined || output === undefined) {
     return { hit: false, reason: 'missing-answer', confidence: null, choice: null, noul: null };
   }
   if (kind.choice !== 'build_test_run') {
@@ -178,17 +174,18 @@ export function evaluateDiagnosticGate(
   return { hit: true, reason: 'hit', confidence: kind.confidence, choice: kind.choice, noul: output.noul };
 }
 
-// ---------------------------------------------------------------------------
-// P0-2: settlement-notice relevance ranking
-// ---------------------------------------------------------------------------
+/** Flip semantics: jev judges first, the regex list decides only when jev produced no usable answer
+ * (failure, malformed, below gate). A confident rejection outranks a regex match. */
+export function isDiagnosticGateUnanswered(verdict: DiagnosticGateVerdict): boolean {
+  return verdict.reason === 'missing-answer' || verdict.reason === 'low-confidence';
+}
 
-/**
- * Stricter than the global minConfidence default: settlement text is mostly
- * Chinese while English is jev's primary training language (models page), so
- * the initial gate starts at 0.7 and calibrates from jev.jsonl.
- */
+/* ── P0-2: settlement-notice relevance ranking ── */
+
+/** Stricter than the global default: settlement text is mostly Chinese while English is jev's primary
+ * training language, so the initial gate starts at 0.7 and calibrates from jev.jsonl. */
 export const NOTICE_RANK_MIN_CONFIDENCE = 0.7;
-export const RANK_SCORE_WEIGHT = 0.6;
+const RANK_SCORE_WEIGHT = 0.6;
 
 const RANK_LEVELS = [
   'Routine completion; the master agent can check it later',
@@ -202,9 +199,7 @@ export function noticeRankRequest(input: {
 }): JevRequest {
   const questions: Record<string, JevQuestion> = {};
   for (let i = 0; i < input.notices.length; i++) {
-    // Question keys are NOT sent to the model, so identical instructions would
-    // collapse every notice into the same question (observed live: 5x "1.98:0.97").
-    // Each instruction must name its settlement by state index (cookbook pattern).
+    // Question keys are NOT sent to the model: identical instructions would collapse every notice into one.
     questions[`notice_${i}_rank`] = {
       type: 'score',
       instructions: `How urgently does the master agent need to see settlements[${i}] right now, given in_progress_todos?`,
@@ -224,23 +219,15 @@ export function noticeRankRequest(input: {
   };
 }
 
-/**
- * Failure-pin threshold: a settlement whose fail-noul clears this is forced to
- * the front regardless of its relevance score. Live calibration (2026-09-18):
- * two runs over the same Chinese batch reordered a failure notice from #2 to
- * #4 — beyond the 3-shown cap. Score noise on CJK must not be able to bury a
- * failure; the invariant lives in code, not in the model.
- */
-export const NOTICE_FAIL_PIN_THRESHOLD = 0.7;
+/** A settlement whose fail-noul clears this is pinned to the front regardless of relevance score:
+ * score noise on CJK reordered the same failure notice beyond the cap of shown notices. */
+const NOTICE_FAIL_PIN_THRESHOLD = 0.7;
 
 /**
- * Compose the display order: pinned failures first, then descending composed
- * relevance (stable on ties -> arrival order). Per-item confidence gate: an
- * item whose score answer is below the gate sinks to the routine bucket
- * instead of voiding the batch (one unsure routine notice must not reorder
- * everything back to arrival). All items gated -> null (nothing was answered).
- * The fail pin itself ignores the score gate: noul answers carry no confidence
- * field, and failure visibility is the safety property.
+ * Display order: pinned failures first, then descending composed relevance (stable on ties -> arrival
+ * order); the per-item confidence gate sinks an item to the routine bucket instead of voiding the
+ * batch, and all items gated -> null. The fail pin ignores the score gate: noul answers carry no
+ * confidence field and failure visibility is the safety property.
  */
 export function composeNoticeRanking(
   noticeCount: number,
@@ -250,11 +237,9 @@ export function composeNoticeRanking(
   const entries: Array<{ pin: number; value: number; index: number }> = [];
   let answered = 0;
   for (let i = 0; i < noticeCount; i++) {
-    const rank = answers[`notice_${i}_rank`];
-    const fail = answers[`notice_${i}_fail`];
-    if (rank === undefined || fail === undefined || rank.type !== 'score' || fail.type !== 'noul') {
-      return null;
-    }
+    const rank = answerOf(answers, `notice_${i}_rank`, 'score');
+    const fail = answerOf(answers, `notice_${i}_fail`, 'noul');
+    if (rank === undefined || fail === undefined) return null;
     const gated = rank.confidence < minConfidence;
     if (!gated) answered++;
     const normalizedScore = rank.score / Math.max(1, RANK_LEVELS.length - 1);
@@ -269,11 +254,9 @@ export function composeNoticeRanking(
   return entries.map((entry) => entry.index);
 }
 
-// ---------------------------------------------------------------------------
-// P0-3: OBS excerpt window candidates (head/tail halves miss the middle)
-// ---------------------------------------------------------------------------
+/* ── P0-3: OBS excerpt window candidates (head/tail halves miss the middle) ── */
 
-export type ExcerptWindowId = 'first_signal' | 'densest';
+export type ExcerptWindowId = 'first_signal' | 'densest' | 'mid';
 
 export interface ExcerptWindow {
   readonly id: ExcerptWindowId;
@@ -306,11 +289,9 @@ function buildLineWindow(lines: readonly string[], start: number, budgetBytes: n
   return { text: selected.join('\n'), bytes, signalCount };
 }
 
-/**
- * Generate code-owned middle-window candidates for a packed observation:
- * the region around the first failure-signal line, and the densest cluster
- * of failure-signal lines within one half-budget. Deterministic, no model.
- */
+/** Code-owned middle-window candidates for a packed observation: failure-signal windows (first hit,
+ * densest cluster) when present, plus a plain mid-output window ALWAYS offered, so jev judges every
+ * packed output — including logs whose failure lines the English FAILURE_SIGNAL regex cannot see. */
 export function buildExcerptWindows(text: string, halfBudgetBytes: number): ExcerptWindow[] {
   if (halfBudgetBytes <= 0) return [];
   const lines = text.split('\n');
@@ -318,28 +299,34 @@ export function buildExcerptWindows(text: string, halfBudgetBytes: number): Exce
   for (let i = 0; i < lines.length; i++) {
     if (FAILURE_SIGNAL.test(lines[i]!)) signalLines.add(i);
   }
-  if (signalLines.size === 0) return [];
 
   const out: ExcerptWindow[] = [];
   const seen = new Set<string>();
 
-  const first = Math.min(...signalLines);
-  const firstWindow = buildLineWindow(lines, Math.max(0, first - 2), halfBudgetBytes, signalLines);
-  if (firstWindow !== null && !seen.has(firstWindow.text)) {
-    seen.add(firstWindow.text);
-    out.push({ id: 'first_signal', label: 'first failure-signal region', text: firstWindow.text });
-  }
+  if (signalLines.size > 0) {
+    const first = Math.min(...signalLines);
+    const firstWindow = buildLineWindow(lines, Math.max(0, first - 2), halfBudgetBytes, signalLines);
+    if (firstWindow !== null && !seen.has(firstWindow.text)) {
+      seen.add(firstWindow.text);
+      out.push({ id: 'first_signal', label: 'first failure-signal region', text: firstWindow.text });
+    }
 
-  // Densest cluster: anchor at every signal line, extend greedily while in budget.
-  let best: LineWindow | null = null;
-  for (const anchor of signalLines) {
-    const window = buildLineWindow(lines, anchor, halfBudgetBytes, signalLines);
-    if (window === null) continue;
-    if (best === null || window.signalCount > best.signalCount) best = window;
+    let best: LineWindow | null = null;
+    for (const anchor of signalLines) {
+      const window = buildLineWindow(lines, anchor, halfBudgetBytes, signalLines);
+      if (window === null) continue;
+      if (best === null || window.signalCount > best.signalCount) best = window;
+    }
+    if (best !== null && !seen.has(best.text)) {
+      seen.add(best.text);
+      out.push({ id: 'densest', label: 'densest failure-signal region', text: best.text });
+    }
   }
-  if (best !== null && !seen.has(best.text)) {
-    seen.add(best.text);
-    out.push({ id: 'densest', label: 'densest failure-signal region', text: best.text });
+
+  const midAnchor = Math.min(Math.floor(lines.length / 2), Math.max(0, lines.length - 1));
+  const midWindow = buildLineWindow(lines, midAnchor, halfBudgetBytes, signalLines);
+  if (midWindow !== null && !seen.has(midWindow.text)) {
+    out.push({ id: 'mid', label: 'middle region of the output', text: midWindow.text });
   }
   return out;
 }
@@ -374,8 +361,69 @@ export function evaluateExcerptPick(
   answers: Record<string, JevAnswer>,
   minConfidence: number,
 ): ExcerptWindowId | null {
-  const picked = answers.window;
-  if (picked === undefined || picked.type !== 'choice') return null;
+  const picked = answerOf(answers, 'window', 'choice');
+  if (picked === undefined) return null;
   if (picked.confidence < minConfidence) return null;
-  return picked.choice === 'first_signal' || picked.choice === 'densest' ? picked.choice : null;
+  return picked.choice === 'first_signal' || picked.choice === 'densest' || picked.choice === 'mid'
+    ? picked.choice
+    : null;
+}
+
+/** Local privacy gate for the excerpt-pick request: its state is sent for EVERY packed output — a path
+ *  the EPR secret gate never covers — so any credential-shaped text keeps the whole request local. */
+export function excerptAskIsSafe(
+  middleWindows: readonly ExcerptWindow[],
+  headExcerpt: string,
+  tailExcerpt: string,
+): boolean {
+  const parts = [headExcerpt, tailExcerpt, ...middleWindows.map((w) => w.text)];
+  return !parts.some((part) => containsLikelySecret(part));
+}
+
+/* ── P0-4: settlement attribution check ─────────────────────────── */
+
+/** Noul answers carry no confidence field (unlike choice/score), so this use case gates on the noul
+ *  probabilities themselves via dedicated constants, like DIAGNOSTIC_OUTPUT_MIN_NOUL. */
+const SETTLE_MATCH_MIN_NOUL = 0.6;
+const SETTLE_FINAL_MIN_NOUL = 0.6;
+
+export type SettleNullVerdict = 'silent' | 'attribution-suspect' | 'extraction-failed';
+
+export function settleVerdictRequest(input: { description: string; tail: string }): JevRequest {
+  return {
+    state: { task: input.description, transcriptTail: input.tail },
+    questions: {
+      tail_matches_task: {
+        type: 'noul',
+        instructions: 'Is this transcript tail from a session working on the described task? Answer false only when the tail is clearly about a different task or conversation.',
+        criteria: {
+          true: 'The tail discusses, works on, or reports on the described task',
+          false: 'The tail is about an unrelated task or a different conversation',
+        },
+      },
+      tail_has_final_answer: {
+        type: 'noul',
+        instructions: 'Does the transcript tail end with (or contain) a complete final answer or report for the task, rather than only intermediate tool exchanges?',
+        criteria: {
+          true: 'A complete final answer/report is present',
+          false: 'Only intermediate steps, questions, or tool exchanges — no final answer',
+        },
+      },
+    },
+  };
+}
+/** Compose the null-closing verdict. null = unanswered (jev off / failed / wrong shapes): callers
+ *  fall back to deterministic signals and the legacy wording, so jev-off stays byte-identical. */
+export function evaluateSettleVerdict(answers: Record<string, JevAnswer>): SettleNullVerdict | null {
+  const match = answerOf(answers, 'tail_matches_task', 'noul');
+  const fin = answerOf(answers, 'tail_has_final_answer', 'noul');
+  if (match === undefined || fin === undefined) return null;
+  if (match.noul < SETTLE_MATCH_MIN_NOUL) return 'attribution-suspect';
+  if (fin.noul >= SETTLE_FINAL_MIN_NOUL) return 'extraction-failed';
+  return 'silent';
+}
+
+/** Privacy gate shared with EPR: never ship credential-shaped tails off-host. */
+export function settleAskIsSafe(tail: string): boolean {
+  return !containsLikelySecret(tail);
 }

package/src/ledger.ts

@@ -1,24 +1,20 @@
 /**
  * Disposal ledger shared by HMR and session shutdown (D80⑤ + D79).
  *
- * HMR partial reload can skip old fiber effect disposers, so process-level resources
- * such as intervals, pipe servers, and watchers would leak without compensation.
- * Core modules register those resources by module key; reload disposes matching keys,
- * while session_shutdown disposes everything.
- *
- * D79 reuses this mechanism for pi-surface registration cleanup; logical keys need not
- * be file paths. The ledger stays dependency-free and connects through bootstrap/index.
+ * HMR partial reload can skip old fiber effect disposers, so process-level resources (intervals, pipe
+ * servers, watchers) would leak without compensation. Modules register those resources by module key;
+ * reload disposes matching keys, session_shutdown disposes everything. D79 reuses the same mechanism
+ * for pi-surface registration cleanup, where keys need not be file paths.
  */
 
 import { fileURLToPath } from 'node:url';
 
-/** Normalize file URLs and paths to comparable absolute keys for HMR matching. */
-export function normalizeModuleKey(spec: string): string {
+function normalizeModuleKey(spec: string): string {
   let s = String(spec);
   try {
     if (s.startsWith('file://')) s = fileURLToPath(s);
   } catch {
-    /* Keep malformed URLs unchanged so disposal can still use the caller's key. */
+    // Malformed URL: keep the caller's key so disposal still matches.
   }
   return s.replace(/\\/g, '/');
 }
@@ -27,7 +23,7 @@ export class DisposeLedger {
   /** LIFO order matches Cordis effect disposal semantics. */
   private order: Array<{ key: string; dispose: () => void }> = [];
 
-  /** Register a resource and return cancellation so self-disposal cannot run twice. */
+  /** Register a resource; the returned cancellation makes self-disposal a no-op. */
   add(spec: string, dispose: () => void): () => void {
     const entry = { key: normalizeModuleKey(spec), dispose };
     this.order.push(entry);
@@ -37,27 +33,23 @@ export class DisposeLedger {
     };
   }
 
-  /** HMR compensation disposes only matching keys in LIFO order. */
   disposeKey(spec: string | string[]): number {
-    const keys = new Set((Array.isArray(spec) ? spec : [spec]).map(normalizeModuleKey));
+    const keys = (Array.isArray(spec) ? spec : [spec]).map(normalizeModuleKey);
     let n = 0;
     for (let i = this.order.length - 1; i >= 0; i--) {
-      if (keys.has(this.order[i].key)) {
-        const { dispose } = this.order[i];
-        this.order.splice(i, 1);
-        try { dispose(); } catch { /* Compensation failures are non-fatal. */ }
-        n++;
-      }
+      if (!keys.includes(this.order[i]!.key)) continue;
+      const { dispose } = this.order.splice(i, 1)[0]!;
+      try { dispose(); } catch { /* Compensation must never abort the reload. */ }
+      n++;
     }
     return n;
   }
 
-  /** Dispose every entry in LIFO order during session_shutdown. */
   disposeAll(): number {
     let n = 0;
     while (this.order.length > 0) {
       const { dispose } = this.order.pop()!;
-      try { dispose(); } catch { /* Compensation failures are non-fatal. */ }
+      try { dispose(); } catch { /* Reload/shutdown must survive a broken disposer. */ }
       n++;
     }
     return n;