@dzhechkov/harness-core 0.3.146 → 0.3.148

package/src/cost-scoring.ts

@@ -78,6 +78,23 @@ const FALLBACK_PRICING = priced(3 / 1e6, 15 / 1e6);
  * Resolve a model id to its pricing by longest-prefix match.
  * `bedrock/anthropic.claude-3-opus...` → strips a leading `provider/` segment.
  */
+/**
+ * Whether {@link pricingFor} will find a REAL entry for this model id, or silently fall back to
+ * {@link FALLBACK_PRICING} (sonnet-class).
+ *
+ * Exists so a cost surface can REPORT the fallback instead of hiding it: `claude-fable-*` has no
+ * entry in {@link MODEL_PRICES} and is the default model of every recorded feature-adr run, so its
+ * dollar figures are priced at a fallback rate (feature `cost-ledger`, ADR-003).
+ */
+export function hasKnownPricing(modelId: string): boolean {
+  if (typeof modelId !== 'string' || modelId.length === 0) return false;
+  const id = modelId.toLowerCase().replace(/^[a-z0-9-]+\//, '');
+  for (const key of Object.keys(MODEL_PRICES)) {
+    if (id.startsWith(key)) return true;
+  }
+  return false;
+}
+
 export function pricingFor(modelId: string): ModelPricing {
   // Strip a leading `provider/` segment (e.g. `bedrock/`, `us-east-1/`).
   const id = modelId.toLowerCase().replace(/^[a-z0-9-]+\//, '');

package/src/feature-adr-checkpoints.ts

@@ -0,0 +1,221 @@
+/**
+ * feature-adr durable checkpoints — the PURE half (backlog 49e4a95b).
+ *
+ * Problem: .claude/workflows/feature-adr.js restarts an L/XL run from scratch when its session dies
+ * (the exact failure that forced usage-adaptive routing — one run cost 623k subagent tokens), and the
+ * STANDARD L/XL two-phase flow (stop-after-plan → re-invoke) re-runs router+design+plan wholesale.
+ * The Workflow harness's own resumeFromRunId is same-session only, so it cannot cover either case.
+ *
+ * Design: the heavyweight state is ALREADY durable — the 00–09 artifacts in features/<slug>/. The
+ * checkpoint layer is deliberately THIN: after each expensive stage the workflow appends one JSONL
+ * line { stage, inputHash, result } to features/<slug>/.fa-state/checkpoints.jsonl (via a cheap
+ * effort-low agent — the workflow sandbox has no fs). On the next run with the same slug, a stage is
+ * SKIPPED only when its recorded inputHash matches the freshly computed one AND its expected artifact
+ * is still on disk. Granularity is per-STAGE, not per-agent-call: a death mid-Step-7 re-runs Step 7,
+ * never Steps 0–6.
+ *
+ * Provenance: concept (checkpoint keyed by input hash + call cache) from ADR-157
+ * darwin-checkpoints-durable-execution (status PROPOSED) in agent-harness-generator. Its "~39% resume
+ * saving" figure is from a SYNTHETIC deterministic simulation — deliberately NOT quoted as expected
+ * field saving anywhere in this feature.
+ *
+ * Everything here is pure and deterministic (no Date/random — the workflow sandbox forbids them);
+ * the workflow script mirrors these functions inline (it is self-contained and cannot import), and
+ * the wiring test asserts the mirror stays present.
+ */
+
+/** Stages the workflow checkpoints, in pipeline order. Cheap side-channel agents (usage probes,
+ * fa-record, auto-cost selects) are never checkpointed; the opt-in Delivery gate re-runs by design
+ * (advisory verdicts should reflect the CURRENT tree). */
+export const CHECKPOINT_STAGES = ['router', 'design', 'plan', 'code', 'qe', 'fleet'] as const;
+export type CheckpointStage = (typeof CHECKPOINT_STAGES)[number];
+
+/** The artifact(s) (relative to features/<slug>/) whose PRESENCE a resume additionally requires in
+ * 'auto' mode — EVERY listed path must exist. null = result-only stage (hash match suffices).
+ * Tier-dependent stages (design) take extra artifacts at the call site via `extraArtifacts` —
+ * an M+ design must probe its ADR/ideation/architecture files too, not just requirements
+ * (Codex QE #2: a one-file probe accepted a materially incomplete design). */
+export const STAGE_ARTIFACTS: Record<CheckpointStage, string | null> = {
+  router: null,
+  design: '01_requirements.md',
+  plan: '06_implementation_plan.md',
+  code: '07_code_changes/change_manifest.md',
+  qe: '08_qe_report.md',
+  fleet: '09_fleet_qe_assessment.md',
+};
+
+/** A checkpoint line as persisted (one JSON object per line). */
+export interface CheckpointEntry {
+  stage: string;
+  inputHash: string;
+  result: unknown;
+}
+
+/** Oversize guard: a result JSON above this is NOT checkpointed (the stage simply re-runs on resume).
+ * Keeps the read-back prompt bounded; artifacts on disk carry the heavy state anyway. */
+export const CHECKPOINT_MAX_RESULT_CHARS = 12_000;
+
+/** Checkpoint format/logic version — SALTED into every input hash. Bump it whenever the workflow's
+ * stage semantics, prompts, or composite result shapes change: every pre-existing checkpoint then
+ * hashes stale and re-runs, instead of an old-format entry resuming into new logic (Codex QE #5). */
+export const CKPT_SCHEMA_VERSION = 'fa-ckpt-2';
+
+/** FNV-1a 32-bit over UTF-16 code units, hex-encoded (one pass; building block for the 64-bit form). */
+export function fnv1a(str: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+  }
+  return h.toString(16).padStart(8, '0');
+}
+
+/** 64 bits from two independent FNV-1a passes (plain + salted). A single 32-bit hash admits
+ * findable collisions (Codex QE #9 produced a real pair at `11a08b58`); two passes make the
+ * single-pair collision odds ~2^-64 — adequate for one slug's checkpoint file. */
+export function fnv1a64(str: string): string {
+  return fnv1a(str) + fnv1a('
fa-ckpt-salt
' + str);
+}
+
+/** The stage's input fingerprint: a JSON-tuple (delimiter-ambiguity class — never a separator join)
+ * of the schema version + stage name + every input that would change the stage's output, hashed.
+ * Upstream stage RESULTS are included as their serialized form, so a stale upstream auto-invalidates
+ * downstream. HONEST SCOPE: the hash proves the run INPUTS are unchanged — it does NOT fingerprint
+ * the working tree (a crash-resume legitimately sees the dead run's uncommitted writes, so a tree
+ * hash would invalidate every real resume). Tree-level staleness is out of the checkpoint contract:
+ * use resume:'never' (or delete .fa-state/) after manual edits, and re-QE independently — the ADR
+ * names this as the accepted limitation (Codex QE #1). */
+export function checkpointInputHash(stage: string, parts: readonly unknown[]): string {
+  return fnv1a64(JSON.stringify([CKPT_SCHEMA_VERSION, stage, ...parts.map((p) => (p === undefined ? null : p))]));
+}
+
+export type ResumeMode = 'auto' | 'never' | 'force';
+
+/** Normalize args.resume: anything but the two explicit strings means the default 'auto'. */
+export function resumeMode(raw: unknown): ResumeMode {
+  return raw === 'never' ? 'never' : raw === 'force' ? 'force' : 'auto';
+}
+
+export interface ResumeDecision {
+  resume: boolean;
+  reason:
+    | 'resumed'
+    | 'resumed-force'
+    | 'mode-never'
+    | 'no-checkpoint'
+    | 'stale-input'
+    | 'artifact-missing';
+}
+
+/** The pure resume decision. 'auto' resumes only on (hash match AND every required artifact
+ * present); 'force' trusts the hash alone; 'never' always runs live. A STALE-INPUT hash NEVER
+ * resumes in any mode — force skips only the artifact probe, never the input check (a checkpoint
+ * for different inputs is a different feature). A malformed/null recorded result is treated as
+ * no-checkpoint (Codex QE #8 — a null result must not resume as a real one). */
+export function decideCheckpointResume(opts: {
+  mode: ResumeMode;
+  entry: CheckpointEntry | undefined;
+  inputHash: string;
+  artifactRel: string | readonly string[] | null;
+  listing: ReadonlySet<string>;
+}): ResumeDecision {
+  if (opts.mode === 'never') return { resume: false, reason: 'mode-never' };
+  if (!opts.entry || opts.entry.result === null || opts.entry.result === undefined) {
+    return { resume: false, reason: 'no-checkpoint' };
+  }
+  if (opts.entry.inputHash !== opts.inputHash) return { resume: false, reason: 'stale-input' };
+  if (opts.mode === 'force') return { resume: true, reason: 'resumed-force' };
+  const required = opts.artifactRel === null ? [] : (typeof opts.artifactRel === 'string' ? [opts.artifactRel] : opts.artifactRel);
+  for (const rel of required) {
+    if (!opts.listing.has(rel)) return { resume: false, reason: 'artifact-missing' };
+  }
+  return { resume: true, reason: 'resumed' };
+}
+
+/** Serialize one checkpoint line, or null when the result is null/oversize/unserializable —
+ * the caller logs the skip loudly; a missing checkpoint only costs a re-run, never corrupts.
+ * A null result is never persisted (Codex QE #8: it would later parse as a resumable entry). */
+export function serializeCheckpoint(stage: string, inputHash: string, result: unknown): string | null {
+  if (result === null || result === undefined) return null;
+  let line: string;
+  try {
+    line = JSON.stringify({ stage, inputHash, result });
+  } catch {
+    return null;
+  }
+  if (typeof line !== 'string' || line.length > CHECKPOINT_MAX_RESULT_CHARS) return null;
+  return line;
+}
+
+export interface ParsedCheckpointRead {
+  entries: Record<string, CheckpointEntry>;
+  listing: Set<string>;
+  malformedLines: number;
+}
+
+/** Sentinel separating the checkpoint file body from the artifact listing in the single read-back
+ * command's stdout. */
+export const CHECKPOINT_LS_SENTINEL = '---FA-CKPT-LS---';
+
+/** Parse the read-back agent's stdout: JSONL entries (LAST occurrence of a stage wins — a re-run
+ * overwrites by append), then the sentinel ON ITS OWN LINE, then one artifact path per line
+ * (relative to the feature dir). The sentinel match is LINE-ANCHORED: JSON.stringify never emits
+ * literal newlines, so a sentinel string INSIDE a recorded result shares its line with JSON syntax
+ * and can never split the stream (Codex QE #10). Malformed JSONL lines are COUNTED, never silently
+ * ignored (corruption is named); entries with a null result are malformed, not resumable. */
+export function parseCheckpointRead(text: string): ParsedCheckpointRead {
+  const out: ParsedCheckpointRead = { entries: {}, listing: new Set(), malformedLines: 0 };
+  const raw = String(text ?? '');
+  const lines = raw.split('\n');
+  const sentinelAt = lines.findIndex((l) => l.trim() === CHECKPOINT_LS_SENTINEL);
+  const body = sentinelAt === -1 ? lines : lines.slice(0, sentinelAt);
+  const ls = sentinelAt === -1 ? [] : lines.slice(sentinelAt + 1);
+  for (const line of body) {
+    const t = line.trim();
+    if (t === '') continue;
+    try {
+      const e = JSON.parse(t) as CheckpointEntry;
+      if (e && typeof e === 'object' && typeof e.stage === 'string' && typeof e.inputHash === 'string' && 'result' in e && e.result !== null && e.result !== undefined) {
+        out.entries[e.stage] = e;
+      } else {
+        // last-wins holds for BAD records too: a stage-identifiable null/invalid record ERASES the
+        // older entry for that stage instead of silently reactivating it (Codex QE r2 #6).
+        if (e && typeof e === 'object' && typeof (e as CheckpointEntry).stage === 'string') delete out.entries[(e as CheckpointEntry).stage];
+        out.malformedLines++;
+      }
+    } catch {
+      out.malformedLines++;
+    }
+  }
+  for (const line of ls) {
+    const t = line.trim();
+    if (t !== '') out.listing.add(t);
+  }
+  return out;
+}
+
+/** Single-quote shell escaping (the workflow's shq twin). */
+export function shellQuote(s: string): string {
+  return "'" + String(s).replace(/'/g, "'\\''") + "'";
+}
+
+/** The one Bash command the read-back agent runs: checkpoint file body (absent file = empty),
+ * the sentinel, then the artifact listing as feature-dir-relative paths (find prints them with a
+ * leading ./ that sed strips). Never fails: every leg is || true. */
+export function checkpointReadCmd(fdirAbs: string): string {
+  const q = shellQuote(fdirAbs);
+  return (
+    'cat ' + q + '/.fa-state/checkpoints.jsonl 2>/dev/null || true; ' +
+    "echo '" + CHECKPOINT_LS_SENTINEL + "'; " +
+    'cd ' + q + ' 2>/dev/null && find . -maxdepth 2 -type f 2>/dev/null | sed "s|^\\./||" || true'
+  );
+}
+
+/** The one Bash command the write agent runs: mkdir the state dir, then append ONE line. The line
+ * is single-quote-escaped as a whole — JSON.stringify output never contains literal newlines, so
+ * printf '%s\n' emits exactly one record. */
+export function checkpointAppendCmd(fdirAbs: string, line: string): string {
+  const dir = shellQuote(fdirAbs + '/.fa-state');
+  const file = shellQuote(fdirAbs + '/.fa-state/checkpoints.jsonl');
+  return 'mkdir -p ' + dir + " && printf '%s\\n' " + shellQuote(line) + ' >> ' + file;
+}

package/src/index.ts

@@ -138,6 +138,23 @@ export { hookDecision, isFenced, isNewLine, ESCAPE_TEACHING } from './claim-chec
 export type { HookDecision, HookDecisionOpts } from './claim-check-hook-policy.js';
 export { step8ClaimGate } from './feature-adr-claim-gate.js';
 export type { Step8ClaimCounts, Step8ClaimGate } from './feature-adr-claim-gate.js';
+export {
+  CHECKPOINT_STAGES,
+  STAGE_ARTIFACTS,
+  CHECKPOINT_MAX_RESULT_CHARS,
+  CHECKPOINT_LS_SENTINEL,
+  CKPT_SCHEMA_VERSION,
+  fnv1a,
+  fnv1a64,
+  checkpointInputHash,
+  resumeMode,
+  decideCheckpointResume,
+  serializeCheckpoint,
+  parseCheckpointRead,
+  checkpointReadCmd,
+  checkpointAppendCmd,
+} from './feature-adr-checkpoints.js';
+export type { CheckpointStage, CheckpointEntry, ResumeMode, ResumeDecision, ParsedCheckpointRead } from './feature-adr-checkpoints.js';
 export {
   detectQueryLang,
   relevanceFloorFor,
@@ -263,6 +280,7 @@ export type { RiskScore, RiskThresholds } from './risk-scoring.js';
 export {
   MODEL_PRICES,
   pricingFor,
+  hasKnownPricing,
   normalizeUsage,
   usageCost,
   invocationCost,
@@ -342,6 +360,43 @@ export {
   readUsageLimits,
   weeklyWindowFor,
 } from './usage.js';
+export { claudeProjectsRoot, rawTokenMixOf, weightedTokensOf } from './usage.js';
+export type { RawTokenMix } from './usage.js';
+// Per-stage cost ledger + reconciliation invariant (feature cost-ledger, ADR-001/002/003).
+export {
+  COST_LEDGER_SCOPE,
+  COST_LEDGER_DEFECT_KINDS,
+  COST_LEDGER_VERDICTS,
+  DEFAULT_COST_LEDGER_EPSILON,
+  extractCostSamples,
+  parseWorkflowRunRecord,
+  buildCostLedger,
+  verifyCostLedgerReport,
+  stageCostAggregates,
+  renderCostLedger,
+  costLedgerJsonl,
+  listCostLedgerRuns,
+  deriveCostLedger,
+  deriveStageCostAggregates,
+  writeCostLedgerJsonl,
+} from './cost-ledger.js';
+export type {
+  CostLedgerDefect,
+  CostLedgerDefectKind,
+  CostLedgerIoOptions,
+  CostLedgerReconciliation,
+  CostLedgerReport,
+  CostLedgerRow,
+  CostLedgerRunRef,
+  CostLedgerSample,
+  CostLedgerVerdict,
+  BuildCostLedgerInput,
+  DeriveCostLedgerOptions,
+  StageCostAggregate,
+  StageSampleSet,
+  WorkflowRunRecord,
+  WorkflowStageEntry,
+} from './cost-ledger.js';
 export type {
   ClaudeUsageModel,
   UsageCalibrationChange,

package/src/usage.ts

@@ -45,6 +45,77 @@ const MTIME_SLACK_MS = HOUR_MS;
  */
 export const TOKEN_WEIGHTS = { input: 1, cacheWrite: 1.25, cacheWrite1h: 2, cacheRead: 0.1, output: 5 } as const;
 
+/** The four raw token buckets of one `message.usage` record, after clamping. */
+export interface RawTokenMix {
+  readonly input: number;
+  /** Cache-CREATION tokens, already priced at their TTL rate inside {@link weightedTokensOf}. */
+  readonly cacheWrite: number;
+  readonly cacheRead: number;
+  readonly output: number;
+}
+
+function positiveFinite(v: unknown): number {
+  return typeof v === 'number' && isFinite(v) && v > 0 ? v : 0;
+}
+
+/**
+ * The raw token buckets of an Anthropic `message.usage` object, clamped to finite non-negatives.
+ * `cacheWrite` prefers the TTL breakdown (`cache_creation.ephemeral_*`) and falls back to the flat
+ * `cache_creation_input_tokens` — reading only the flat field scored a nested-only record as ZERO.
+ */
+export function rawTokenMixOf(usage: unknown): RawTokenMix {
+  if (typeof usage !== 'object' || usage === null) {
+    return { input: 0, cacheWrite: 0, cacheRead: 0, output: 0 };
+  }
+  const u = usage as Record<string, unknown>;
+  const cc = (typeof u['cache_creation'] === 'object' && u['cache_creation'] !== null
+    ? (u['cache_creation'] as Record<string, unknown>)
+    : {}) as Record<string, unknown>;
+  const c5 = positiveFinite(cc['ephemeral_5m_input_tokens']);
+  const c1h = positiveFinite(cc['ephemeral_1h_input_tokens']);
+  const cacheWrite = c5 + c1h > 0 ? c5 + c1h : positiveFinite(u['cache_creation_input_tokens']);
+  return {
+    input: positiveFinite(u['input_tokens']),
+    cacheWrite,
+    cacheRead: positiveFinite(u['cache_read_input_tokens']),
+    output: positiveFinite(u['output_tokens']),
+  };
+}
+
+/**
+ * THE estimator — cost-weighted "input-equivalent" tokens for one `message.usage` object.
+ *
+ * A flat token sum is 89-99.7% `cache_read` on this machine, which tracks CONVERSATION LENGTH
+ * rather than work done. {@link TOKEN_WEIGHTS} are the published per-token price ratios relative to
+ * base input, so the result tracks consumption instead of context size.
+ *
+ * Extracted verbatim from `computeUsage`'s per-sample arithmetic so that `dz usage` and the
+ * per-stage cost ledger measure the same quantity (feature `cost-ledger`, ADR-002 — the invariant
+ * only means something if both sides use ONE estimator). The return value is UNROUNDED; callers
+ * that need exact integer identities round once at their own extraction point.
+ */
+export function weightedTokensOf(usage: unknown): number {
+  if (typeof usage !== 'object' || usage === null) return 0;
+  const mix = rawTokenMixOf(usage);
+  const u = usage as Record<string, unknown>;
+  const cc =
+    typeof u['cache_creation'] === 'object' && u['cache_creation'] !== null
+      ? (u['cache_creation'] as Record<string, unknown>)
+      : {};
+  const c5 = positiveFinite(cc['ephemeral_5m_input_tokens']);
+  const c1h = positiveFinite(cc['ephemeral_1h_input_tokens']);
+  const cacheWriteCost =
+    c5 + c1h > 0
+      ? c5 * TOKEN_WEIGHTS.cacheWrite + c1h * TOKEN_WEIGHTS.cacheWrite1h
+      : mix.cacheWrite * TOKEN_WEIGHTS.cacheWrite;
+  return (
+    mix.input * TOKEN_WEIGHTS.input +
+    cacheWriteCost +
+    mix.cacheRead * TOKEN_WEIGHTS.cacheRead +
+    mix.output * TOKEN_WEIGHTS.output
+  );
+}
+
 export const CLAUDE_USAGE_MODELS = ['fable', 'opus', 'sonnet', 'haiku'] as const;
 export type ClaudeUsageModel = (typeof CLAUDE_USAGE_MODELS)[number];
 
@@ -230,7 +301,7 @@ export function normalizeClaudeUsageModelKey(raw: unknown): ClaudeUsageModel | n
  * The `~/.claude/projects` root (the account-wide transcript store). Overridable via
  * `DZ_CLAUDE_PROJECTS_ROOT` — used by tests to point at a temp tree. Never throws.
  */
-function claudeProjectsRoot(): string {
+export function claudeProjectsRoot(): string {
   const override = process.env['DZ_CLAUDE_PROJECTS_ROOT'];
   if (typeof override === 'string' && override.length > 0) return override;
   return join(homedir(), '.claude', 'projects');
@@ -414,17 +485,8 @@ function extractSamples(path: string, scanCutoff: number, into: Sample[], seen:
     // tokens": a quantity that tracks consumption instead of context size.
     // Prefer the TTL breakdown when present (5m 1.25x / 1h 2x); fall back to the flat field at the
     // 5m rate. Reading only the flat field scored a nested-only record as ZERO.
-    const c5 = n(usage.cache_creation?.ephemeral_5m_input_tokens);
-    const c1h = n(usage.cache_creation?.ephemeral_1h_input_tokens);
-    const cacheWriteCost =
-      c5 + c1h > 0
-        ? c5 * TOKEN_WEIGHTS.cacheWrite + c1h * TOKEN_WEIGHTS.cacheWrite1h
-        : n(usage.cache_creation_input_tokens) * TOKEN_WEIGHTS.cacheWrite;
-    const tokens =
-      n(usage.input_tokens) * TOKEN_WEIGHTS.input +
-      cacheWriteCost +
-      n(usage.cache_read_input_tokens) * TOKEN_WEIGHTS.cacheRead +
-      n(usage.output_tokens) * TOKEN_WEIGHTS.output;
+    // ONE estimator, shared with the per-stage cost ledger (feature `cost-ledger`, ADR-002).
+    const tokens = weightedTokensOf(usage);
     if (tokens <= 0) continue;
     // Dedup: streamed assistant messages repeat their usage object across chunks.
     const id = typeof rec.message?.id === 'string' ? rec.message.id : '';