@dzhechkov/harness-core 0.7.2 → 0.7.4

package/src/provenance.ts

@@ -0,0 +1,217 @@
+/**
+ * The provenance gate — nothing leaves this machine citing a source that may not.
+ *
+ * It checks PROVENANCE, not words. A denylist of forbidden phrases is an enumeration, and it loses
+ * to the first confidential note it has never heard of; the `.gitignore` in this repository carries
+ * a comment warning about exactly that mistake. An allowlist of SOURCES wins by construction: an
+ * unknown source is refused because it is unknown.
+ *
+ * Two things this module deliberately does NOT do, both named in ADR-001 rather than implied:
+ *  - it does not read CONTENT, so confidential text pasted by hand into an allowed file inherits
+ *    that file's permission;
+ *  - it cannot see a paraphrase with no citation. It proves what was CITED, never what was known.
+ * The last line against both is a person reading the draft, and that is the design, not a gap.
+ *
+ * PURE: no filesystem, no git, no clock. The oracle runs in the CLI and arrives as a fact — a
+ * verdict that needs a real repository to reproduce is a verdict no test can pin.
+ *
+ * See features/provenance-gate/03_adr/ for the decisions and the measurements behind them.
+ */
+
+/** Why one claim was refused. A CLOSED set, so a reason is machine-readable and never prose. */
+export type SourceVerdict =
+  | 'allowed'
+  /** The claim names no source at all. A claim with no source is the thing we must not publish. */
+  | 'no-source'
+  /** The manifest did not declare what kind of source this is — never inferred from its shape. */
+  | 'unknown-kind'
+  /** A store record that the TRACKED public list does not name. Default-deny. */
+  | 'not-marked-public'
+  /** The path does not resolve. You cannot cite what does not exist. */
+  | 'unresolvable'
+  /** Resolved outside the repository — a symlink out of the tree lands here too. */
+  | 'outside-repo'
+  /** Git says this path is ignored: the owner's own boundary refuses it. */
+  | 'ignored-path'
+  /** Not tracked by git — nobody has reviewed it, so "not ignored" proves nothing about it. */
+  | 'untracked'
+  /** Tracked, but carrying uncommitted changes: its CURRENT contents went through no review. */
+  | 'uncommitted';
+
+export type SourceProvenanceOutcome = 'allowed' | 'blocked' | 'not-established';
+
+/** One claim in a draft, and where it came from. */
+export interface SourceClaim {
+  readonly id: string;
+  /** `path` — a file in the repository. `record` — an addressed row in a `.dz` store. */
+  readonly kind?: string;
+  readonly source?: string;
+}
+
+export interface SourceManifest {
+  readonly version: number;
+  readonly draft: string;
+  readonly claims: readonly SourceClaim[];
+}
+
+export interface SourceProvenanceFacts {
+  /**
+   * Paths git reported as ignored. `null` means THE ORACLE DID NOT RUN — a different fact from
+   * "nothing is ignored", and the one a naive gate reads as "everything is allowed". Measured in
+   * this repo on a sibling command: `dz sync` prints `0/0` and exits 0 when it compared nothing.
+   */
+  readonly ignoredPaths: ReadonlySet<string> | null;
+  /**
+   * Record addresses declared public in a GIT-TRACKED file. Not a `visibility` field inside the
+   * record: `.dz/` is gitignored, so a marker there appears in no diff, and the process that writes
+   * the draft can write it too. MEASURED 2026-08-22: `grep -r '"visibility"' .dz/` returns 0 — the
+   * field does not exist, and introducing it would have made "the owner opted in" mean "the
+   * generator marked itself" (ADR-001).
+   */
+  readonly publicRecords: ReadonlySet<string>;
+  /** Each `path` source resolved through the filesystem; `null` = missing or outside the repo. */
+  readonly resolved: ReadonlyMap<string, string | null>;
+  /**
+   * Resolved paths git tracks. "Not ignored" is NOT "reviewed": a file the drafting process wrote a
+   * second ago is neither, and the first version cleared it while calling it "a tracked path"
+   * (cross-family review round 3, codex `gpt-5.6-sol`, 2026-08-22).
+   */
+  readonly trackedPaths: ReadonlySet<string>;
+  /** Tracked paths with uncommitted changes — committed is what "reviewed" means here. */
+  readonly dirtyPaths: ReadonlySet<string>;
+}
+
+export interface SourceClaimResolution {
+  readonly id: string;
+  readonly source: string | null;
+  readonly verdict: SourceVerdict;
+  readonly detail: string;
+}
+
+export interface SourceProvenanceDecision {
+  readonly outcome: SourceProvenanceOutcome;
+  /** 0 allowed · 1 blocked · 3 not established. A zero is only ever a proven pass. */
+  readonly exit: 0 | 1 | 3;
+  readonly claims: readonly SourceClaimResolution[];
+  readonly reason: string;
+}
+
+/** Parse a manifest. Unparseable is `null` — which the caller must NOT read as "empty". */
+export function parseSourceManifest(text: string): SourceManifest | null {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (raw === null || typeof raw !== 'object') return null;
+  const o = raw as Record<string, unknown>;
+  if (!Array.isArray(o['claims'])) return null;
+  const claims: SourceClaim[] = [];
+  for (const c of o['claims'] as unknown[]) {
+    if (c === null || typeof c !== 'object') return null;
+    const cc = c as Record<string, unknown>;
+    claims.push({
+      id: typeof cc['id'] === 'string' ? cc['id'] : '',
+      ...(typeof cc['kind'] === 'string' ? { kind: cc['kind'] } : {}),
+      ...(typeof cc['source'] === 'string' ? { source: cc['source'] } : {}),
+    });
+  }
+  return {
+    version: typeof o['version'] === 'number' ? o['version'] : 1,
+    draft: typeof o['draft'] === 'string' ? o['draft'] : '',
+    claims,
+  };
+}
+
+/**
+ * Classify ONE claim's source.
+ *
+ * Order matters and is load-bearing. The KIND is read from the manifest and never guessed from the
+ * string: `.dz/` holds 119 git-TRACKED files (measured), so `.dz/guard-audit.jsonl` is not ignored
+ * and a shape-based guess would let it through as an ordinary repo path, skipping the public-list
+ * requirement entirely.
+ */
+export function classifySource(claim: SourceClaim, facts: SourceProvenanceFacts): SourceClaimResolution {
+  const id = claim.id === '' ? '(unnamed claim)' : claim.id;
+  const source = typeof claim.source === 'string' && claim.source.trim() !== '' ? claim.source.trim() : null;
+  const at = (verdict: SourceVerdict, detail: string): SourceClaimResolution => ({ id, source, verdict, detail });
+
+  if (source === null) return at('no-source', 'the claim names no source — a claim with no source is exactly what must not go out');
+
+  if (claim.kind === 'record') {
+    return facts.publicRecords.has(source)
+      ? at('allowed', 'named in the tracked public-records list')
+      : at('not-marked-public', 'this record is not in the tracked public list — marking one public must be a reviewable commit, not a field inside an ignored store');
+  }
+
+  if (claim.kind === 'path') {
+    const real = facts.resolved.get(source);
+    if (real === undefined || real === null) {
+      return at('unresolvable', 'the path does not resolve inside the repository — a source that cannot be resolved cannot be shown to be safe');
+    }
+    if (facts.ignoredPaths === null) {
+      // Defensive: `decideSourceProvenance` refuses before reaching here. Kept so a direct caller of
+      // classifySource cannot obtain an `allowed` from an oracle that never ran.
+      return at('unresolvable', 'the ignore oracle did not run, so no path can be cleared');
+    }
+    if (facts.ignoredPaths.has(real)) return at('ignored-path', 'git says this path is ignored — the owner\'s own boundary refuses it');
+    // Three separate questions, and the first version asked only one. A brand-new file the drafting
+    // process wrote is not ignored either, and clearing it would let the generator author its own
+    // evidence.
+    if (!facts.trackedPaths.has(real)) return at('untracked', 'git does not track this path, so nobody has reviewed it — not being ignored says nothing about a file that has never been committed');
+    if (facts.dirtyPaths.has(real)) return at('uncommitted', 'this path has uncommitted changes, so its current contents went through no review');
+    return at('allowed', 'committed, reviewed, and not refused by the owner\'s boundary');
+  }
+
+  return at('unknown-kind', `the manifest declares kind ${JSON.stringify(claim.kind ?? null)} — a kind this gate cannot check is refused, never inferred from the path's shape`);
+}
+
+/**
+ * The whole-manifest verdict.
+ *
+ * Three outcomes, and neither non-pass returns zero. The dangerous one is the third: an empty
+ * manifest does not mean "nothing confidential is cited", it means "we checked nothing".
+ */
+export function decideSourceProvenance(manifest: SourceManifest | null, facts: SourceProvenanceFacts): SourceProvenanceDecision {
+  if (manifest === null) {
+    return { outcome: 'not-established', exit: 3, claims: [], reason: 'the manifest could not be read — nothing was checked, which is not the same as nothing being wrong' };
+  }
+  if (facts.ignoredPaths === null) {
+    // BEFORE classification, and for the WHOLE batch. Measured 2026-08-22: one out-of-repo path in
+    // a `git check-ignore --stdin` batch prints the matches found so far, then dies with exit 128 —
+    // so crediting what was printed would clear every path queued behind it (ADR-003).
+    return { outcome: 'not-established', exit: 3, claims: [], reason: 'the ignore oracle did not run, so not one path was checked — this is not a pass' };
+  }
+  if (manifest.claims.length === 0) {
+    return { outcome: 'not-established', exit: 3, claims: [], reason: 'the manifest lists no claims — a draft with nothing to check has not been shown to be safe, only left unchecked' };
+  }
+  const claims = manifest.claims.map((c) => classifySource(c, facts));
+  const blocked = claims.filter((c) => c.verdict !== 'allowed');
+  if (blocked.length > 0) {
+    return {
+      outcome: 'blocked',
+      exit: 1,
+      claims,
+      reason: `${blocked.length} of ${claims.length} claim(s) cite a source that may not leave this machine`,
+    };
+  }
+  return { outcome: 'allowed', exit: 0, claims, reason: `all ${claims.length} claim(s) cite a source cleared to go out` };
+}
+
+/** What the operator sees. Every blocked claim names its id, its source and its reason. */
+export function renderSourceProvenance(decision: SourceProvenanceDecision): string[] {
+  const out: string[] = [];
+  const label = decision.outcome === 'allowed' ? 'ALLOWED' : decision.outcome === 'blocked' ? 'BLOCKED' : 'NOT ESTABLISHED';
+  for (const c of decision.claims) {
+    if (c.verdict === 'allowed') continue;
+    out.push(`  [${c.verdict}] ${c.id} — ${c.source ?? '(no source)'}: ${c.detail}`);
+  }
+  out.push(`dz provenance-check: ${label} — ${decision.reason}`);
+  if (decision.outcome === 'allowed') {
+    // Said on the PASSING path too, because that is the path where it gets forgotten: a green tick
+    // here proves where the citations came from, not that the prose is safe.
+    out.push('  note: this proves what was CITED. It cannot see a paraphrase with no citation, nor confidential text pasted by hand into an allowed file. Read the draft.');
+  }
+  return out;
+}

package/src/recall-domain-boost.ts

@@ -64,8 +64,8 @@ export function domainMatch(hitDomain: string | null | undefined, wanted: string
   return 'none';
 }
 
-export interface DomainBoostResult {
-  readonly hits: readonly RecallHit[];
+export interface DomainBoostResult<T extends RecallHit = RecallHit> {
+  readonly hits: readonly T[];
   /** How many hits MATCHED the domain (exactly / relatedly). */
   readonly exact: number;
   readonly related: number;
@@ -88,7 +88,14 @@ export interface DomainBoostResult {
  * is deterministic — the same input always yields the same output, which is what
  * makes it testable at all.
  */
-export function applyDomainBoost(hits: readonly RecallHit[], wanted: string | null | undefined): DomainBoostResult {
+/**
+ * Generic over the hit type so EXTRA FIELDS SURVIVE the boost. Narrowing to `RecallHit` silently
+ * dropped `similarity` from a `HybridHit`, and the closeness a reader is meant to act on vanished
+ * the moment `--domain` was passed. Note the deliberate asymmetry with `relevance`, which the CLI
+ * nulls under a boost because the boost invalidates the RRF ordering: closeness is
+ * ORDER-INDEPENDENT, so it stays populated.
+ */
+export function applyDomainBoost<T extends RecallHit>(hits: readonly T[], wanted: string | null | undefined): DomainBoostResult<T> {
   const target = normalizeDomain(wanted);
   if (target === '' || hits.length === 0) {
     return { hits, exact: 0, related: 0, moved: 0, noMatches: true };

package/src/recall-hook-policy.ts

@@ -180,3 +180,63 @@ export function renderHookContext(selection: HookSelection): string {
   const lines = selection.hits.map((h) => `  - [${h.score.toFixed(2)}${h.domain ? ` / ${h.domain}` : ''}] ${h.pattern}`);
   return `Learned lessons that match this prompt (dz recall, relevance ≥ ${selection.floor.toFixed(2)}):\n${lines.join('\n')}`;
 }
+
+/**
+ * The closeness token for one recall row: `sim=0.67▲` above the floor, `sim=0.29▽` below it,
+ * `sim=—` when closeness was not measured for this row.
+ *
+ * The marker is the floor comparison DONE FOR THE READER, against the same per-language floors the
+ * hook already trusts — calibrated 2026-07-09 on a 32-probe labeled set, not chosen by feel. A bare
+ * cosine means nothing without that table, and the point of this token is a number the reader can
+ * act on: `▲` is on-topic, `▽` is "ranked because something had to rank first", `—` is "unmeasured".
+ *
+ * A lexical-only hit and an engine whose score is not a cosine both get the dash. Substituting a
+ * differently-scaled number there is the precise lie this exists to remove.
+ */
+export function closenessLine(similarity: number | undefined, query: unknown, floors?: Partial<RecallFloors>): string {
+  if (typeof similarity !== 'number' || !isFinite(similarity)) return 'sim=—';
+  const floor = relevanceFloorFor(query, floors);
+  return `sim=${showCloseness(similarity, floor)}${similarity >= floor ? '▲' : '▽'}`;
+}
+
+/**
+ * The cosine, printed with enough digits that it cannot LOOK equal to the floor when it is not.
+ *
+ * Two rounds of cross-family review (codex `gpt-5.6-sol`, 2026-08-24) landed on opposite sides of one
+ * trade-off, and both were right. Comparing before rounding shows `sim=0.50▽` for 0.499 against a
+ * 0.50 floor — a figure equal to the floor, marked below it. Comparing after rounding shows
+ * `sim=0.50▲` for the same input — a marker that says on-topic for a value the calibrated floor
+ * excludes. Choosing a side cannot fix this, because the contradiction lives in the DISPLAY, not in
+ * the comparison: two decimals cannot always distinguish a value from its floor.
+ *
+ * So the comparison stays on the true value — the floors are calibrated on true cosines — and the
+ * display widens until the number visibly differs from the floor. 0.499 against 0.50 prints as
+ * `sim=0.499▽`: below the floor, and visibly so.
+ */
+function showCloseness(similarity: number, floor: number): string {
+  // Widen until the number and the FLOOR differ AS DISPLAYED at the same precision. Comparing the
+  // shown value against the raw floor was not enough: 0.5009 against a floor of 0.501 stopped at two
+  // digits and printed `0.50`, which reads as the floor once the floor is itself rounded for a human
+  // (cross-family review round 3, 2026-08-24).
+  for (let digits = 2; digits <= 6; digits++) {
+    const shown = similarity.toFixed(digits);
+    if (similarity === floor || shown !== floor.toFixed(digits)) return shown;
+  }
+  // Even at full precision the two render alike — 0.4999999 and 0.5 both print `0.500000`, and the
+  // contradiction the widening exists to remove survives the cap (cross-family review round 4,
+  // 2026-08-24). At that distance the digits are not the answer: state the RELATION instead. The
+  // reader learns "just below the floor", which is exactly what is true and what the marker says.
+  // The floor is stated AS IT IS, never rounded: with a floor of 0.4999999 a value of 0.49999995 is
+  // above the floor and below 0.50, so `>0.50` was literally false (cross-family review round 5,
+  // 2026-08-24). `String(floor)` prints exactly what the comparison used.
+  return `${similarity < floor ? '<' : '>'}${String(floor)}`;
+}
+
+/** Did anything clear the floor? Used to say so ONCE, in words, instead of per row. */
+export function anyAboveFloor(similarities: readonly (number | undefined)[], query: unknown, floors?: Partial<RecallFloors>): boolean {
+  const floor = relevanceFloorFor(query, floors);
+  // The TRUE value, matching what each row's marker uses — the footer must never contradict the
+  // markers above it, and "nothing clears the floor" printed under a visible ▲ would be worse than
+  // either alone.
+  return similarities.some((s) => typeof s === 'number' && isFinite(s) && s >= floor);
+}