@dzhechkov/harness-core 0.8.2 → 0.8.6

package/src/loop-trace.ts

@@ -89,7 +89,19 @@ export interface TraceRunClosed {
   counts: { dispatched: number; settled: number };
 }
 
-export type TraceEvent = TraceDispatchEvent | TraceSettleEvent | TraceRunOpened | TraceRunClosed;
+/** A deliberate work-dropping receipt. Its presence is required for overflow:'truncate' to grade. */
+export interface TraceFanoutTruncatedEvent {
+  v: 1;
+  runId: string;
+  seq: number;
+  event: 'fanout-truncated';
+  stage: string;
+  registrySize: number;
+  dispatched: number;
+  reason: string;
+}
+
+export type TraceEvent = TraceDispatchEvent | TraceSettleEvent | TraceRunOpened | TraceRunClosed | TraceFanoutTruncatedEvent;
 
 export interface TraceState {
   runId: string;
@@ -148,6 +160,20 @@ export function traceValidateEvent(e: unknown): string | null {
   return 'unknown event kind';
 }
 
+/** Reader extension kept outside the generated emitter slice: the two locked feature-adr workflow
+ * copies embed the v1 emitter byte-for-byte and cannot be rewritten during this parallel Step 7. */
+function traceValidateReaderEvent(e: unknown): string | null {
+  const base = traceValidateEvent(e);
+  if (base !== 'unknown event kind') return base;
+  const ev = e as Record<string, unknown>;
+  if (ev['event'] !== 'fanout-truncated') return base;
+  if (typeof ev['stage'] !== 'string' || !TRACE_KEY_RE.test(ev['stage'])) return 'fanout-truncated stage fails its VO regex';
+  if (typeof ev['registrySize'] !== 'number' || !Number.isInteger(ev['registrySize']) || ev['registrySize'] < 0) return 'fanout-truncated registrySize must be a non-negative integer';
+  if (typeof ev['dispatched'] !== 'number' || !Number.isInteger(ev['dispatched']) || ev['dispatched'] < 0 || ev['dispatched'] > ev['registrySize']) return 'fanout-truncated dispatched must be an integer within registrySize';
+  if (typeof ev['reason'] !== 'string' || ev['reason'].trim() === '') return 'fanout-truncated reason required';
+  return null;
+}
+
 /**
  * Open a trace state and buffer the run.opened frame. Throws on an invalid runId (fail-closed).
  *
@@ -204,6 +230,20 @@ export function traceOnSettle(state: TraceState, e: { invocationId: string; outc
   return seq;
 }
 
+/** Emit the trace half of the loud truncation receipt. This is not a dispatch and does not alter
+ * run.closed invocation counts. */
+export function traceOnFanoutTruncated(
+  state: TraceState,
+  e: { stage: string; registrySize: number; dispatched: number; reason: string },
+): number {
+  const seq = ++state.seq;
+  const event: TraceFanoutTruncatedEvent = { v: 1, runId: state.runId, seq, event: 'fanout-truncated', ...e };
+  const err = traceValidateReaderEvent(event);
+  if (err !== null) throw new Error('loop-trace: refusing non-conforming event (' + err + ') — the authoritative ordering source is never repaired later');
+  state.buffer.push(JSON.stringify(event));
+  return seq;
+}
+
 /** Buffer the run.closed frame (a trace without it parses as incomplete). */
 export function traceClose(state: TraceState): void {
   const closed: TraceRunClosed = {
@@ -378,7 +418,7 @@ export function parseTrace(text: string): TraceRun {
       run.parseErrors.push('unparseable line: ' + t.slice(0, 120));
       continue;
     }
-    const err = traceValidateEvent(e);
+    const err = traceValidateReaderEvent(e);
     if (err !== null) {
       run.parseErrors.push('invalid event (' + err + '): ' + t.slice(0, 120));
       continue;
@@ -646,6 +686,53 @@ export function runInvariants(projection: TraceProjection, run: TraceRun): Invar
       if (peak > bound) out.push({ id: idC, status: 'fail', message: `observed scheduling concurrency ${peak} exceeds maxFanout ${bound}` });
       else out.push({ id: idC, status: 'pass', message: `peak scheduled concurrency ${peak} <= maxFanout ${bound}` });
     }
+
+    // ADR-001: coverage is matched to registry POSITIONS, never inferred from equal totals. A
+    // duplicate-valued registry therefore owns two independent expected slots. Retries do not
+    // manufacture coverage: only attempt 1 of the first member stage witnesses branch admission.
+    const idD = 'region-dispatch-completeness:' + region.fanout;
+    if ((projection as { kind: string }).kind === 'trace-projection/1' || !Array.isArray(region.registry) || typeof region.registrySize !== 'number' || region.overflow === undefined) {
+      out.push({ id: idD, status: 'inconclusive', message: 'trace-projection/1 region has no positional registry evidence — dispatch completeness cannot be proved' });
+    } else {
+      const registry = region.dedup === true
+        ? region.registry.filter((key, index, all) => all.indexOf(key) === index)
+        : region.registry;
+      const expected = region.overflow === 'truncate' ? registry.slice(0, Math.max(0, region.maxFanout)) : registry;
+      const witness = region.members[0];
+      const observed = witness === undefined
+        ? []
+        : run.events.filter((e): e is TraceDispatchEvent => e.event === 'dispatched' && e.stepId === witness && e.attempt === 1).map((e) => e.itemKey);
+      const unmatched = new Set(expected.map((_key, index) => index));
+      const extras: (string | null)[] = [];
+      for (const key of observed) {
+        const position = [...unmatched].find((index) => expected[index] === key);
+        if (position === undefined) extras.push(key);
+        else unmatched.delete(position);
+      }
+      const missing = [...unmatched].map((index) => `#${index + 1}:${expected[index]}`);
+      const receipt = run.events.find((e): e is TraceFanoutTruncatedEvent =>
+        e.event === 'fanout-truncated' && e.stage === region.fanout,
+      );
+      const badReceipt = region.overflow === 'truncate' && (
+        receipt === undefined ||
+        receipt.registrySize !== region.registrySize ||
+        receipt.dispatched !== expected.length ||
+        receipt.reason.trim() === ''
+      );
+      if (missing.length > 0 || extras.length > 0 || badReceipt) {
+        const parts: string[] = [];
+        if (missing.length > 0) parts.push('missing registry position(s) ' + missing.join(', '));
+        if (extras.length > 0) parts.push('unexpected dispatch key(s) ' + extras.map((x) => String(x)).join(', '));
+        if (badReceipt) parts.push('missing or mismatched fanout-truncated trace receipt');
+        out.push({
+          id: idD,
+          status: run.incomplete && region.overflow === 'window' && missing.length > 0 && extras.length === 0 ? 'inconclusive' : 'fail',
+          message: parts.join('; ') + (run.incomplete ? ' (trace incomplete)' : ''),
+        });
+      } else {
+        out.push({ id: idD, status: 'pass', message: `every one of ${expected.length} expected registry position(s) has exactly one first-attempt dispatch${region.overflow === 'truncate' ? ' and a matching truncation receipt' : ''}` });
+      }
+    }
     // Join coverage: the join itself is a structural pseudo-step (no trace event of its own), so
     // its trace-visible witnesses are (a) every dispatched member settles (a dispatched branch is
     // never skippable) and (b) every post-region dispatching step (`after`) dispatches AFTER every
@@ -833,6 +920,8 @@ export function assembleTimeline(input: {
       rows.push({ seq: e.seq, kind: 'trace', label: `settle ${e.invocationId}`, detail: `outcome=${e.outcome}`, wallTime: e.wallTime ?? null });
     } else if (e.event === 'run.opened') {
       rows.push({ seq: e.seq, kind: 'trace', label: 'run.opened', detail: `plan=${e.planDigest.slice(0, 12)} exec-fp=${e.execFp.slice(0, 12)}`, wallTime: null });
+    } else if (e.event === 'fanout-truncated') {
+      rows.push({ seq: e.seq, kind: 'trace', label: `fanout-truncated ${e.stage}`, detail: `${e.dispatched} of ${e.registrySize} — ${e.reason}`, wallTime: null });
     } else {
       rows.push({ seq: e.seq, kind: 'trace', label: 'run.closed', detail: JSON.stringify(e.counts), wallTime: null });
     }

package/src/model-recommender.ts

@@ -92,7 +92,9 @@ export function harvestStageOutcomes(records: readonly unknown[]): Harvest {
     if (!isRecord(modelsUsed)) { skipped.noModels += 1; continue; }
     const grade = extractGrade(result);
     if (grade === null) { skipped.noGrade += 1; continue; }
-    const runId = typeof source['runId'] === 'string' ? source['runId'] : JSON.stringify(modelsUsed).slice(0, 40);
+    // Full canonical JSON is intentional: the former 40-character prefix merged distinct records
+    // whose stage names shared a long prefix, manufacturing idempotency across different runs.
+    const runId = typeof source['runId'] === 'string' ? source['runId'] : `models:${JSON.stringify(modelsUsed)}`;
     const ts = typeof source['timestamp'] === 'string' ? source['timestamp'] : null;
     const tier = typeof result['tier'] === 'string' && result['tier'] !== '' ? result['tier'] : 'unknown';
     let contributed = false;
@@ -138,6 +140,8 @@ export interface Recommendation {
     readonly rule: string;
     readonly skipped: Harvest['skipped'];
     readonly crossFamilyNote: string;
+    readonly unfed: { readonly count: number; readonly runIds: string[] };
+    readonly freshness: 'current' | 'stale' | 'unfed';
   };
 }
 
@@ -154,7 +158,7 @@ const CROSS_NOTE =
   'the qe pick is computed with the family FORCED to the cross of the code pick — a same-family qe recommendation is unrepresentable (ADR-001 D3)';
 
 /** Recommend per stage over the harvested samples (optionally one tier's slice). */
-export function recommendModels(harvest: Harvest, opts: { tier?: string; qualityBar?: number; minSamples?: number } = {}): Recommendation {
+export function recommendModels(harvest: Harvest, opts: { tier?: string; qualityBar?: number; minSamples?: number; alreadyFed?: readonly string[] } = {}): Recommendation {
   const slice = opts.tier === undefined ? harvest.samples : harvest.samples.filter((s) => s.tier === opts.tier);
   const tierLabel = opts.tier ?? 'all';
   const byStage = new Map<string, HarvestSample[]>();
@@ -197,9 +201,21 @@ export function recommendModels(harvest: Harvest, opts: { tier?: string; quality
     }
   }
   if (!stages.includes('code')) perStage.unshift(code);
+  const pending = unfedRuns(harvest.samples, opts.alreadyFed ?? []);
+  const harvestRunIds = [...new Set(harvest.samples.map((s) => s.runId))];
+  const fed = new Set(opts.alreadyFed ?? []);
+  const fedInHarvest = harvestRunIds.filter((runId) => fed.has(runId)).length;
   return {
     perStage,
-    basis: { runsUsed: harvest.runsUsed, window: harvest.window, rule: harvest.rule, skipped: harvest.skipped, crossFamilyNote: CROSS_NOTE },
+    basis: {
+      runsUsed: harvest.runsUsed,
+      window: harvest.window,
+      rule: harvest.rule,
+      skipped: harvest.skipped,
+      crossFamilyNote: CROSS_NOTE,
+      unfed: { count: pending.length, runIds: pending },
+      freshness: pending.length === 0 ? 'current' : fedInHarvest === 0 ? 'unfed' : 'stale',
+    },
   };
 }
 
@@ -213,15 +229,30 @@ export interface FeedPlan {
   readonly fedAfter: string[];
 }
 
+/** One shared definition of the telemetry/store gap, used by recommendation, apply and guard. */
+export function unfedRuns(samples: readonly HarvestSample[], alreadyFed: readonly string[]): string[] {
+  const fed = new Set(alreadyFed);
+  return [...new Set(samples.map((s) => s.runId))].filter((runId) => !fed.has(runId)).sort();
+}
+
 /** A run feeds ONCE. Double-feeding the same telemetry manufactures confidence the data does not
  * contain — the second `--apply` must feed 0 and say which runs it skipped. */
 export function planFeed(samples: readonly HarvestSample[], alreadyFed: readonly string[]): FeedPlan {
   const fed = new Set(alreadyFed);
   const toFeed: HarvestSample[] = [];
   const skippedRuns = new Set<string>();
+  const seenSamples = new Set<string>();
   for (const s of samples) {
     if (fed.has(s.runId)) skippedRuns.add(s.runId);
-    else toFeed.push(s);
+    else {
+      // A multi-stage run legitimately feeds one sample per stage. Only a repeated sample from a
+      // duplicated record is suppressed within this harvest.
+      const sampleKey = JSON.stringify([s.runId, s.stage]);
+      if (!seenSamples.has(sampleKey)) {
+        seenSamples.add(sampleKey);
+        toFeed.push(s);
+      }
+    }
   }
   const fedAfter = [...new Set([...alreadyFed, ...toFeed.map((s) => s.runId)])].sort();
   return { toFeed, skippedRuns: [...skippedRuns].sort(), fedAfter };

package/src/qe-bridge.ts

@@ -392,6 +392,15 @@ export function buildBridgePrompt(
     '4. Judge only what the extracts below actually show; if the evidence is insufficient to judge',
     '   something, say so explicitly rather than assuming it is fine.',
     '',
+    'You have been given NO tools and NO filesystem access — this is deliberate isolation, not an',
+    'accident, and there is nothing else to inspect. Do not attempt to run a shell command, read a',
+    'file, or explore a directory: no such action can succeed here, and any text that looks like a',
+    'tool invocation will simply sit in your own output unexecuted. The extracts below are the',
+    'COMPLETE evidence you will ever receive for this review. If they are insufficient to judge a',
+    'specific point, write that as a finding (e.g. "cannot verify X from the given extracts") and',
+    'continue to a grade regardless — never stop your review to attempt verification that cannot',
+    'happen in this environment.',
+    '',
     'Output format — ALL THREE parts are required, in this order, at the END of your answer:',
     '  (a) your review prose, containing exactly ONE line that reads:  GRADE: <A-F>',
     '  (b) a fenced code block labelled ' + BRIDGE_FENCE_LABEL + ' whose body is JSON:',