@tech-leads-club/harness-toolkit 0.2.1

package/src/core/core.facade.ts

@@ -0,0 +1,461 @@
+import {
+  appendAttestation,
+  attestationPath,
+  fingerprintOf,
+  readAttestations,
+  verifyChain,
+} from "./attest/attest.service.ts";
+import {
+  formatAvailableInventory,
+  formatCapabilityDigest,
+  formatDoctorWarn,
+  isAvailableNotEnabled,
+  listAvailableNotEnabled,
+  listNewlyAnnounceable,
+} from "./capability/capability.service.ts";
+import {
+  loadCatalog,
+  readProjectPolicyRaw,
+  readRuntimeSeen,
+  writeRuntimeSeen,
+} from "./capability/capability.store.ts";
+import { ENABLE_HINT } from "./capability/capability.types.ts";
+import {
+  commentViolationMessage,
+  declaresReason,
+  findAddedComments,
+  isCommentLine,
+  scanAddedComments,
+} from "./comment-policy/comment-policy.service.ts";
+import { KNOWN_EXTENSION_COUNT, unknownExtensions } from "./comment-policy/comment-syntax.store.ts";
+import {
+  duplicationMessage,
+  findDuplications,
+  MIN_RUN,
+  scanProject,
+} from "./duplication/duplication.service.ts";
+import { evaluateFloor } from "./floor/floor.service.ts";
+import { computeGateFingerprint, readLastGate, writeLastGate } from "./gate/gate.artifact.ts";
+import {
+  appendFilesVerdict,
+  isCommandResolutionFailure,
+  isRecipeRunner,
+  shouldAppendFiles,
+} from "./gate/gate.command.ts";
+import { filesFromOutput } from "./gate/gate.findings.ts";
+import { cachedVerdict, computeInputsHash, isCacheHit } from "./gate/gate.inputs.ts";
+import { describeHolder, GATE_LOCK_WAIT_MS, GateLockTimeoutError, withGateLock } from "./gate/gate.lock.ts";
+import { gapsFromArtifact } from "./gate/gate.service.ts";
+import {
+  handoffInjectable,
+  patchHandoff,
+  readForeignSlices,
+  readHandoff,
+  readHandoffFile,
+} from "./handoff/handoff.service.ts";
+import { authoredLessonId, buildAuthoredLesson } from "./lesson/lesson.authored.ts";
+import type { LessonVerdict } from "./lesson/lesson.credit.ts";
+import { effectivenessLine, helpRate, lessonEffectiveness } from "./lesson/lesson.credit.ts";
+import { gardenAndPersistLessons, promotionCount, renderLessonsMarkdown } from "./lesson/lesson.garden.ts";
+import { formatLessonLink, isStaleLesson, lessonLinkVerdict, parseLessonLink } from "./lesson/lesson.link.ts";
+import {
+  appliesHere,
+  isInjectable,
+  renderLessonBlock,
+  selectLessons as selectLessonsInner,
+} from "./lesson/lesson.select.ts";
+import { recordLessonFromFailure } from "./lesson/lesson.service.ts";
+import {
+  allLessons,
+  creditLessons as creditLessonsInner,
+  globalLessonsStorePath,
+  markGradeable,
+  projectLessonsInjectable,
+  readGlobalLessons,
+  readProjectLessons,
+  touchAccessed as touchAccessedInner,
+  upsertLesson as upsertLessonInner,
+  upsertProjectLesson as upsertProjectLessonInner,
+  writeProjectLessons as writeProjectLessonsInner,
+} from "./lesson/lesson.store.ts";
+import { durableViewVerdict, resolveSyncMode } from "./lesson/lesson.sync.ts";
+import type { HarnessLesson, LessonTier } from "./lesson/lesson.types.ts";
+import { validityReason } from "./lesson/lesson.validity.ts";
+import {
+  groupByProvider,
+  railsNeverFired,
+  sessionReportMarkdown,
+  sessionReportText,
+} from "./observability/observability.report.ts";
+import {
+  DEFAULT_OBS,
+  recordAudit,
+  recordFromEvent,
+  recordObs,
+} from "./observability/observability.service.ts";
+import { getRollup, pruneObs, pruneSpool, readSignalEvents } from "./observability/observability.store.ts";
+import {
+  decisionsFrom,
+  NOTHING_WAS_THE_HARNESS,
+  summarise,
+  whyText,
+} from "./observability/observability.why.ts";
+import {
+  isObservableRail,
+  OBSERVABLE_RAILS,
+  observeAttrs,
+  shouldObserve,
+  unobservableRails,
+} from "./observe/observe.service.ts";
+import { detectDeviations, detectPlan } from "./plan/plan.detect.ts";
+import { evaluatePlanGate, planVerdict } from "./plan/plan.service.ts";
+import { guardPolicySurface } from "./policy/policy.guard.ts";
+import {
+  acceptPolicySources,
+  allDivergedPaths,
+  checkPolicyBaseline,
+  divergedPaths,
+  policySourceFingerprint,
+  recordPolicyBaseline,
+  refreshPolicyBaselines,
+} from "./policy/policy.integrity.ts";
+import {
+  isUnderCodePaths,
+  loadPolicy,
+  resolveProjectPosture,
+  resolveProjectSyncMode,
+} from "./policy/policy.loader.ts";
+import { operatorBootstrapLines } from "./policy/policy.operator.ts";
+import { isOperatorMode, OPERATOR_MODES } from "./policy/policy.posture.ts";
+import { activeRails } from "./policy/policy.rails.ts";
+import { forProvider } from "./policy/policy.types.ts";
+import { checkCollision, heartbeat, register, release, sweepStale } from "./presence/presence.service.ts";
+import {
+  allDecisionFiles,
+  formatDecisionDigest,
+  needsAction,
+  readDecision,
+  readDecisions,
+} from "./release/release.decisions.ts";
+import { readReleaseSeen, writeReleaseSeen } from "./release/release.seen.ts";
+import { evaluateShellCommand } from "./shell-policy/shell-policy.service.ts";
+import { clearShellStall } from "./shell-policy/shell-policy.stall.ts";
+import { appendShipLedger, hasRecentEvidence, newestChangeMs, readShipLedger } from "./ship/ship.ledger.ts";
+import {
+  detectShipClaim,
+  evaluateEmptyDiffAntiShip,
+  evaluateShipEvidenceGate,
+  recentShipClaimActive,
+  touchesRuntime,
+} from "./ship/ship.service.ts";
+import {
+  recordResolution,
+  resolutionFor,
+  resolutionHistoryLine,
+} from "./stagnation/stagnation.resolution.ts";
+import { computeFingerprint } from "./stagnation/stagnation.service.ts";
+import { clearFingerprint, fingerprintHits, trackFingerprint } from "./stagnation/stagnation.store.ts";
+import {
+  readParentModelState,
+  upsertParentModelState,
+} from "./subagent-policy/subagent-policy.parent-model.ts";
+import { evaluateSubagentSpawn } from "./subagent-policy/subagent-policy.service.ts";
+import { inspectSupplyChain, isManifest, supplyChainMessage } from "./supply-chain/supply-chain.service.ts";
+import { endedWithoutActing, idleTurnMessage, readTurnActivity } from "./turn/turn.activity.ts";
+import { formatAutopilotBlock, resolveAutopilot } from "./turn/turn.autopilot.ts";
+import {
+  buildGaps,
+  classifyGateFailure,
+  formatCarriedGaps,
+  formatGapFeedback,
+  formatProgressiveContext,
+  mergeGaps,
+  suggestionFor,
+} from "./turn/turn.failure-signals.ts";
+import {
+  checkLoopCap,
+  currentLoopCount,
+  effectiveLoopCount,
+  markBooted,
+  nextLoop,
+  resetLoop,
+} from "./turn/turn.loop-counter.ts";
+import { findInRecall, recallMessage, remember } from "./untrusted/untrusted.recall.ts";
+import {
+  askIfFromUntrusted,
+  evaluateUntrustedContent,
+  rememberUntrustedOutput,
+} from "./untrusted/untrusted.service.ts";
+import { clearFramingMarker, clearRecall, readRecall } from "./untrusted/untrusted.store.ts";
+
+async function selectLessons(
+  args: Parameters<typeof selectLessonsInner>[0],
+): Promise<{ lessons: HarnessLesson[]; usedIds: string[]; omitted: number }> {
+  return await selectLessonsInner(args);
+}
+
+async function touchAccessed(root: string, ids: string[], now?: Date): Promise<void> {
+  await touchAccessedInner(root, ids, now);
+}
+
+async function upsertProjectLesson(root: string, lesson: HarnessLesson): Promise<HarnessLesson> {
+  return await upsertProjectLessonInner(root, lesson);
+}
+
+async function writeProjectLessons(root: string, lessons: HarnessLesson[]): Promise<void> {
+  await writeProjectLessonsInner(root, lessons);
+}
+
+async function upsertLesson(
+  root: string,
+  lesson: HarnessLesson,
+  tier: Exclude<LessonTier, "core">,
+): Promise<HarnessLesson> {
+  return await upsertLessonInner(root, lesson, tier);
+}
+
+async function creditLessons(
+  root: string,
+  ids: readonly string[],
+  verdict: LessonVerdict,
+  now?: Date,
+): Promise<void> {
+  await creditLessonsInner(root, ids, verdict, now);
+}
+
+export const coreFacade = {
+  capability: {
+    ENABLE_HINT,
+    loadCatalog,
+    readProjectPolicyRaw,
+    readRuntimeSeen,
+    writeRuntimeSeen,
+    isAvailableNotEnabled,
+    listAvailableNotEnabled,
+    listNewlyAnnounceable,
+    formatCapabilityDigest,
+    formatDoctorWarn,
+    formatAvailableInventory,
+  },
+  gate: {
+    GATE_LOCK_WAIT_MS,
+    GateLockTimeoutError,
+    writeLastGate,
+    readLastGate,
+    computeGateFingerprint,
+    computeInputsHash,
+    isCacheHit,
+    cachedVerdict,
+    gapsFromArtifact,
+    withGateLock,
+    describeHolder,
+    shouldAppendFiles,
+    appendFilesVerdict,
+    isRecipeRunner,
+    isCommandResolutionFailure,
+    filesFromOutput,
+  },
+  stagnation: {
+    computeFingerprint,
+    trackFingerprint,
+    fingerprintHits,
+    clearFingerprint,
+    recordResolution,
+    resolutionFor,
+    resolutionHistoryLine,
+  },
+  handoff: {
+    handoffInjectable,
+    patchHandoff,
+    readHandoff,
+    readHandoffFile,
+    readForeignSlices,
+  },
+  lesson: {
+    projectLessonsInjectable,
+    recordLessonFromFailure,
+    buildAuthoredLesson,
+    authoredLessonId,
+    selectLessons,
+    touchAccessed,
+    upsertProjectLesson,
+    upsertLesson,
+    writeProjectLessons,
+    readProjectLessons,
+    readGlobalLessons,
+    // why: the three tiers, deduped. The durable view renders from this rather than from the project store, or two
+    // of the three tiers never reach the host that depends on that file.
+    allLessons,
+    globalLessonsStorePath,
+    creditLessons,
+    markGradeable,
+    gardenAndPersistLessons,
+    renderLessonsMarkdown,
+    durableViewVerdict,
+    resolveSyncMode,
+    // why: one renderer. `src/entrypoints/support.ts` carried a copy because this was not exposed, so the tier
+    // added to the core block never reached the text the model actually receives
+    // ([/decisions/ad-040.md](/decisions/ad-040.md)).
+    renderLessonBlock,
+    promotionCount,
+    isInjectable,
+    appliesHere,
+    isStaleLesson,
+    lessonLinkVerdict,
+    parseLessonLink,
+    formatLessonLink,
+    validityReason,
+    lessonEffectiveness,
+    effectivenessLine,
+    helpRate,
+  },
+  observability: {
+    DEFAULT_OBS,
+    recordObs,
+    recordFromEvent,
+    recordAudit,
+    groupByProvider,
+    sessionReportMarkdown,
+    sessionReportText,
+    railsNeverFired,
+    readSignalEvents,
+    getRollup,
+    decisionsFrom,
+    whyText,
+    summarise,
+    NOTHING_WAS_THE_HARNESS,
+    pruneObs,
+    pruneSpool,
+  },
+  untrusted: {
+    clearRecall,
+    readRecall,
+    remember,
+    findInRecall,
+    recallMessage,
+    rememberUntrustedOutput,
+    askIfFromUntrusted,
+    evaluateUntrustedContent,
+    clearFramingMarker,
+  },
+  plan: {
+    detectPlan,
+    detectDeviations,
+    evaluatePlanGate,
+    planVerdict,
+  },
+  policy: {
+    guardPolicySurface,
+    checkPolicyBaseline,
+    policySourceFingerprint,
+    recordPolicyBaseline,
+    refreshPolicyBaselines,
+    acceptPolicySources,
+    divergedPaths,
+    allDivergedPaths,
+    activeRails,
+    operatorBootstrapLines,
+    loadPolicy,
+    resolveProjectPosture,
+    resolveProjectSyncMode,
+    OPERATOR_MODES,
+    isOperatorMode,
+    isUnderCodePaths,
+    forProvider,
+  },
+  shellPolicy: {
+    evaluateShellCommand,
+    clearShellStall,
+  },
+  subagentPolicy: {
+    evaluateSubagentSpawn,
+    upsertParentModelState,
+    readParentModelState,
+  },
+  supplyChain: {
+    isManifest,
+    inspectSupplyChain,
+    supplyChainMessage,
+  },
+  duplication: {
+    scanProject,
+    findDuplications,
+    duplicationMessage,
+    MIN_RUN,
+  },
+  commentPolicy: {
+    scanAddedComments,
+    findAddedComments,
+    isCommentLine,
+    declaresReason,
+    commentViolationMessage,
+    unknownExtensions,
+    KNOWN_EXTENSION_COUNT,
+  },
+  ship: {
+    detectShipClaim,
+    touchesRuntime,
+    recentShipClaimActive,
+    evaluateEmptyDiffAntiShip,
+    evaluateShipEvidenceGate,
+    appendShipLedger,
+    readShipLedger,
+    hasRecentEvidence,
+    newestChangeMs,
+  },
+  presence: {
+    register,
+    heartbeat,
+    checkCollision,
+    sweepStale,
+    release,
+  },
+  floor: {
+    evaluateFloor,
+  },
+  observe: {
+    shouldObserve,
+    observeAttrs,
+    OBSERVABLE_RAILS,
+    isObservableRail,
+    unobservableRails,
+  },
+  release: {
+    readDecision,
+    readDecisions,
+    allDecisionFiles,
+    needsAction,
+    formatDecisionDigest,
+    readReleaseSeen,
+    writeReleaseSeen,
+  },
+  attest: {
+    appendAttestation,
+    readAttestations,
+    verifyChain,
+    attestationPath,
+    fingerprintOf,
+  },
+  turn: {
+    readTurnActivity,
+    endedWithoutActing,
+    idleTurnMessage,
+    currentLoopCount,
+    nextLoop,
+    resetLoop,
+    checkLoopCap,
+    effectiveLoopCount,
+    markBooted,
+    resolveAutopilot,
+    formatAutopilotBlock,
+    classifyGateFailure,
+    suggestionFor,
+    buildGaps,
+    formatCarriedGaps,
+    formatGapFeedback,
+    mergeGaps,
+    formatProgressiveContext,
+  },
+};
+
+export type CoreFacade = typeof coreFacade;

package/src/core/duplication/duplication.service.ts

@@ -0,0 +1,219 @@
+import type { AddedLine } from "../../platform/git.ts";
+import { matchesSyntax } from "../comment-policy/comment-policy.service.ts";
+import { syntaxFor } from "../comment-policy/comment-syntax.store.ts";
+
+/**
+ * A run of lines this turn added that already exists somewhere else in the project.
+ *
+ * why: the harness watches for the agent solving a problem the codebase already solved — the failure an operator
+ * notices weeks later as two copies drifting apart. It is a diff-scoped question, like the comment gate: only
+ * what this turn wrote is judged, and what was already duplicated is not this turn's to answer for
+ * ([/decisions/ad-071.md](/decisions/ad-071.md)).
+ *
+ * invariant: lines, never syntax. Nothing here parses a language, so the rail behaves the same in Go, Python and
+ * TypeScript — the constraint the comment syntax catalog exists to satisfy
+ * ([/decisions/ad-058.md](/decisions/ad-058.md)).
+ */
+export type Duplication = {
+  file: string;
+  line: number;
+  /** Where the same run already lives. */
+  matchFile: string;
+  matchLine: number;
+  runLength: number;
+};
+
+/**
+ * hazard: below six lines the matches are punctuation. Measured on this repository at a four-line window, the
+ * top hits were import blocks and `} catch { return null; }` — true duplicates, and none of them a defect. Six
+ * is the length at which a match started being something worth reading.
+ */
+export const MIN_RUN = 6;
+
+/** why: a line that is only a brace, a bracket or a keyword carries no design, so it neither starts nor extends a run. */
+export const MIN_LINE_CHARS = 8;
+
+/**
+ * why: whitespace and the trailing comma are the two things a paste changes without changing the code, so the
+ * comparison ignores both. Nothing else is rewritten: renaming an identifier makes it a different line, on
+ * purpose, because a rail that matched through renames would report every similar-shaped function.
+ */
+export function normaliseLine(text: string): string | null {
+  const collapsed = text.trim().replace(/\s+/g, " ").replace(/,$/, "");
+  return collapsed.length < MIN_LINE_CHARS ? null : collapsed;
+}
+
+/**
+ * hazard: the first calibration run reported 137 duplications at a six-line window and the top of the list was
+ * every import block in the repository — `import assert from "node:assert/strict"` next to `import { test } from
+ * "node:test"` is identical in every test file and is not a defect. The words below open a dependency
+ * declaration in most languages, which keeps this a vocabulary rule rather than a parser.
+ */
+const DEPENDENCY_LINE = /^\s*(?:import|from|export|require|#include|use|using|package|namespace|open)\b/;
+
+/** invariant: a comment is not code. Two identical licence headers are not a duplicated implementation. */
+export function isCodeLine(text: string, file: string): boolean {
+  if (DEPENDENCY_LINE.test(text)) {
+    return false;
+  }
+  const syntax = syntaxFor(file);
+  return syntax === null ? true : !matchesSyntax(text, syntax);
+}
+
+/**
+ * hazard: with dependency lines excluded the calibration still reported 116 runs, and reading the top of the list
+ * showed every one of them was *data*: a re-export name list, a config object literal, a type's field
+ * declarations, a test fixture. Repeated shape is what those are for. A run has to carry operations — a call, an
+ * assignment, a branch, a return — before two copies of it mean anything, and a majority of the run has to carry
+ * them or one `foo()` inside a literal would qualify it.
+ */
+const OPERATIONAL = /[(=]|\b(?:if|for|while|switch|return|throw|await|new|catch)\b/;
+
+export const MIN_OPERATIONAL_RATIO = 0.5;
+
+function operationalEnough(window: readonly { key: string }[]): boolean {
+  const operations = window.filter((entry) => OPERATIONAL.test(entry.key)).length;
+  return operations >= Math.ceil(window.length * MIN_OPERATIONAL_RATIO);
+}
+
+export type SourceLine = { file: string; line: number; text: string };
+
+export type RunSite = { file: string; line: number };
+
+/**
+ * hazard: one site per run was not enough. The project index contains the lines this turn added, so a run whose
+ * first occurrence happened to be the new copy compared equal to itself and every duplication vanished — the
+ * calibration reported zero at every window length, which is what exposed it. Two sites are the minimum that can
+ * answer "is there a copy somewhere other than here".
+ */
+export const SITES_PER_RUN = 2;
+
+export type RunIndex = Map<string, RunSite[]>;
+
+function runKey(window: readonly string[]): string {
+  return window.join("\n");
+}
+
+/**
+ * why: one entry per distinct run, keyed by its text. The first place a run is seen wins, so a report names one
+ * prior home rather than every copy — an operator asked to look at eleven identical sites reads none of them.
+ */
+export function indexRuns(lines: readonly SourceLine[], minRun = MIN_RUN): RunIndex {
+  const index: RunIndex = new Map();
+  const usable = lines
+    .map((entry) => ({
+      ...entry,
+      key: isCodeLine(entry.text, entry.file) ? normaliseLine(entry.text) : null,
+    }))
+    .map((entry) => (entry.key === null ? null : { file: entry.file, line: entry.line, key: entry.key }));
+
+  for (let start = 0; start + minRun <= usable.length; start += 1) {
+    const window = usable.slice(start, start + minRun);
+    // hazard: a run has to be contiguous in the file as well as in this array, or a match spans a gap the reader
+    // cannot see. Two files concatenated into one array would otherwise produce a run that exists nowhere.
+    if (window.some((entry) => entry === null)) {
+      continue;
+    }
+    const solid = window as { file: string; line: number; key: string }[];
+    const head = solid[0] as { file: string; line: number; key: string };
+    if (solid.some((entry, offset) => entry.file !== head.file || entry.line !== head.line + offset)) {
+      continue;
+    }
+    if (!operationalEnough(solid)) {
+      continue;
+    }
+    const key = runKey(solid.map((entry) => entry.key));
+    const sites = index.get(key) ?? [];
+    if (sites.length < SITES_PER_RUN) {
+      index.set(key, [...sites, { file: head.file, line: head.line }]);
+    }
+  }
+  return index;
+}
+
+/**
+ * why: the added lines are indexed the same way the project is, then intersected. A run this turn added that the
+ * project already had, somewhere the turn did not write, is the finding.
+ */
+export function findDuplications(
+  added: readonly AddedLine[],
+  project: RunIndex,
+  minRun = MIN_RUN,
+): Duplication[] {
+  const found: Duplication[] = [];
+  const reported = new Set<string>();
+  for (const [key, sites] of indexRuns(added, minRun)) {
+    const where = sites[0] as RunSite;
+    // invariant: a run matching itself is not a duplication, and the project index contains the very lines this
+    // turn added — so the answer is the first site that is somewhere else.
+    const prior = (project.get(key) ?? []).find(
+      (site) => site.file !== where.file || site.line !== where.line,
+    );
+    if (prior === undefined) {
+      continue;
+    }
+    const seen = `${where.file}:${where.line}`;
+    if (reported.has(seen)) {
+      continue;
+    }
+    reported.add(seen);
+    found.push({
+      file: where.file,
+      line: where.line,
+      matchFile: prior.file,
+      matchLine: prior.line,
+      runLength: minRun,
+    });
+  }
+  return found.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+}
+
+export function duplicationMessage(hits: readonly Duplication[]): string {
+  return [
+    `BLOCKED: this turn added ${hits.length} run(s) of ${MIN_RUN}+ lines that already exist in this project.`,
+    "TRIED: compared the lines this turn added against the rest of the repository, ignoring",
+    "comments, blank lines and whitespace. A run already duplicated before this turn is not counted.",
+    "NEED: call the existing code, or extract what both need. If the duplication is deliberate —",
+    "the two will diverge, or the shared form would couple them — say which, in one line, and continue.",
+    "",
+    ...hits
+      .slice(0, 10)
+      .map((hit) => `${hit.file}:${hit.line}  already at  ${hit.matchFile}:${hit.matchLine}`),
+  ].join("\n");
+}
+
+/**
+ * hazard: hook latency is a product property ([/decisions/ad-012.md](/decisions/ad-012.md)), and the honest
+ * version of this scan reads every tracked file on every stop. These bounds are what keep a large repository
+ * from paying for the rail in wall-clock; the report says when one was reached, because a scan that silently
+ * covered half a project reads as a clean answer.
+ */
+export const MAX_SCAN_FILES = 2000;
+export const MAX_SCAN_BYTES = 8_000_000;
+
+export type ProjectScan = { index: RunIndex; filesRead: number; truncated: boolean };
+
+export type ReadFile = (relativePath: string) => string | null;
+
+export function scanProject(files: readonly string[], readFile: ReadFile, minRun = MIN_RUN): ProjectScan {
+  const lines: SourceLine[] = [];
+  let bytes = 0;
+  let filesRead = 0;
+  let truncated = false;
+  for (const file of files) {
+    if (filesRead >= MAX_SCAN_FILES || bytes >= MAX_SCAN_BYTES) {
+      truncated = true;
+      break;
+    }
+    const text = readFile(file);
+    if (text === null) {
+      continue;
+    }
+    bytes += text.length;
+    filesRead += 1;
+    for (const [index, line] of text.split("\n").entries()) {
+      lines.push({ file, line: index + 1, text: line });
+    }
+  }
+  return { index: indexRuns(lines, minRun), filesRead, truncated };
+}