@tech-leads-club/harness-toolkit 0.2.1 → 0.3.0

package/dist/tool-failure.mjs

@@ -276,20 +276,27 @@ function readJson(path) {
     return null;
   }
 }
-async function withFileLock(lockPath, fn) {
+function isContention(error) {
+  return errorCode(error) === "EEXIST" || isRetryableFsError(error);
+}
+async function withFileLock(lockPath, fn, options = {}) {
+  const {
+    openLock = (path) => closeSync(openSync(path, "wx")),
+    lockSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    lockAttempts = 200
+  } = options;
   mkdirSync2(dirname2(lockPath), { recursive: true });
-  const attempts = 200;
   let acquired = false;
-  for (let attempt = 0;attempt < attempts; attempt++) {
+  for (let attempt = 0;attempt < lockAttempts; attempt++) {
     try {
-      closeSync(openSync(lockPath, "wx"));
+      openLock(lockPath);
       acquired = true;
       break;
     } catch (error) {
-      if (errorCode(error) !== "EEXIST") {
+      if (!isContention(error)) {
         throw error;
       }
-      await new Promise((resolve) => setTimeout(resolve, nextDelay({ attempt, baseMs: 10, capMs: 200 })));
+      await lockSleep(nextDelay({ attempt, baseMs: 10, capMs: 200 }));
     }
   }
   if (!acquired) {
@@ -304,14 +311,14 @@ async function withFileLock(lockPath, fn) {
   }
 }
 async function updateJsonAtomic(path, mutator, options) {
-  const { lockPath, afterWrite, ...atomicOptions } = options;
+  const { lockPath, afterWrite, openLock, lockSleep, lockAttempts, ...atomicOptions } = options;
   return withFileLock(lockPath, async () => {
     const current = readJson(path);
     const next = mutator(current);
     await writeJsonAtomic(path, next, atomicOptions);
     afterWrite?.(path);
     return next;
-  });
+  }, { openLock, lockSleep, lockAttempts });
 }
 
 // src/core/capability/capability.store.ts
@@ -5266,6 +5273,62 @@ function release(root, provider, session) {
   deletePresenceRecord(root, provider, session);
 }
 
+// src/core/pricing/pricing.freshness.ts
+var DEFAULT_TTL_DAYS = 7;
+var MS_PER_DAY = 86400000;
+function freshness(meta, now, ttlDays = DEFAULT_TTL_DAYS) {
+  if (meta === null) {
+    return { state: "absent" };
+  }
+  const stamp = meta.refreshedAt;
+  if (stamp === undefined || Number.isNaN(Date.parse(stamp))) {
+    return { state: "undated" };
+  }
+  const ageMs = now.getTime() - Date.parse(stamp);
+  const ageDays = Math.max(0, ageMs / MS_PER_DAY);
+  return ageDays > ttlDays ? { state: "stale", ageDays, refreshedAt: stamp } : { state: "fresh", ageDays, refreshedAt: stamp };
+}
+function shouldRefetch(state) {
+  return state.state === "absent" || state.state === "undated" || state.state === "stale";
+}
+function freshnessMessage(state, catalogue) {
+  switch (state.state) {
+    case "absent":
+      return `${catalogue}: not on this machine — run \`tlc harness prices refresh\``;
+    case "undated":
+      return `${catalogue}: present but carries no date — it will be refetched`;
+    case "fresh":
+      return `${catalogue}: ${describeAge(state.ageDays)} old`;
+    default:
+      return `${catalogue}: ${describeAge(state.ageDays)} old — run \`tlc harness prices refresh\``;
+  }
+}
+var MIN_RETAINED_RATIO = 0.5;
+function mayReplace(existingCount, incomingCount, minRatio = MIN_RETAINED_RATIO) {
+  if (incomingCount === 0) {
+    return { replace: false, reason: "parsed no entries at all — the upstream format has changed" };
+  }
+  if (existingCount === 0) {
+    return { replace: true, reason: `first catalogue, ${incomingCount} entries` };
+  }
+  if (incomingCount >= existingCount) {
+    return { replace: true, reason: `${existingCount} → ${incomingCount} entries` };
+  }
+  const retained = incomingCount / existingCount;
+  return retained >= minRatio ? { replace: true, reason: `${existingCount} → ${incomingCount} entries` } : {
+    replace: false,
+    reason: `would drop from ${existingCount} to ${incomingCount} entries, keeping the existing catalogue — the upstream format has probably changed`
+  };
+}
+function describeAge(ageDays) {
+  if (ageDays < 1) {
+    const hours = Math.max(1, Math.round(ageDays * 24));
+    return `${hours} hour${hours === 1 ? "" : "s"}`;
+  }
+  const days = Math.round(ageDays);
+  return `${days} day${days === 1 ? "" : "s"}`;
+}
+
 // src/core/release/release.decisions.ts
 import { existsSync as existsSync17, readdirSync as readdirSync5, readFileSync as readFileSync19 } from "node:fs";
 import { join as join18 } from "node:path";
@@ -5569,6 +5632,69 @@ function evaluateShellCommand(args) {
   return { kind: "allow" };
 }
 
+// src/core/shim/shim.precedence.ts
+var LAUNCHER = "tlc-exec";
+function invocationText(entry) {
+  return [entry.command ?? "", ...entry.args ?? []].join(" ");
+}
+function coversHandler(settings, handler) {
+  for (const matchers of Object.values(settings.hooks ?? {})) {
+    for (const matcher of matchers) {
+      for (const entry of matcher.hooks ?? []) {
+        const text = invocationText(entry);
+        if (text.includes(LAUNCHER) && new RegExp(`(^|\\s)${handler}(\\s|$)`).test(text)) {
+          return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+function decideShim(userSettings, handler) {
+  if (userSettings === null) {
+    return { run: true, reason: "no user-level settings — this shim is the only hook for this event" };
+  }
+  return coversHandler(userSettings, handler) ? {
+    run: false,
+    reason: `a user-level hook already runs ${handler} — standing down to avoid a second run`
+  } : { run: true, reason: `no user-level hook runs ${handler}` };
+}
+
+// src/core/skill/skill.link.ts
+var SKILL_NAME = "harness-init";
+function skillLinks(runtimeHome2, providerDirs, present) {
+  const source = `${runtimeHome2}/skills/${SKILL_NAME}`;
+  return providerDirs.filter((dir) => present(dir)).map((providerDir) => ({
+    providerDir,
+    source,
+    target: `${providerDir}/skills/${SKILL_NAME}`
+  }));
+}
+function linkHealth(target, runtimeHome2, probe) {
+  const resolved = probe.linkTarget(target);
+  if (resolved === null) {
+    return { state: "absent", target };
+  }
+  if (!probe.exists(resolved)) {
+    return { state: "dangling", target, resolved };
+  }
+  const resolveHome = probe.realpath ?? ((path) => path);
+  const home = resolveHome(runtimeHome2).replace(/\/+$/, "");
+  return resolved === home || resolved.startsWith(`${home}/`) ? { state: "ok", target, resolved } : { state: "outside-runtime", target, resolved };
+}
+function linkHealthMessage(health) {
+  switch (health.state) {
+    case "ok":
+      return `linked → ${health.resolved}`;
+    case "dangling":
+      return `points at ${health.resolved}, which does not exist — re-run \`tlc harness install\``;
+    case "outside-runtime":
+      return `points at ${health.resolved}, outside the runtime — it will break when that path goes`;
+    default:
+      return "not linked — the provider cannot see the init skill";
+  }
+}
+
 // src/core/stagnation/stagnation.resolution.ts
 import { existsSync as existsSync20, mkdirSync as mkdirSync11, readFileSync as readFileSync22, writeFileSync as writeFileSync10 } from "node:fs";
 import { join as join21 } from "node:path";
@@ -6696,6 +6822,21 @@ var coreFacade = {
     readHandoffFile,
     readForeignSlices
   },
+  shim: {
+    coversHandler,
+    decideShim
+  },
+  pricing: {
+    freshness,
+    freshnessMessage,
+    mayReplace,
+    shouldRefetch
+  },
+  skill: {
+    linkHealth,
+    linkHealthMessage,
+    skillLinks
+  },
   lesson: {
     projectLessonsInjectable,
     recordLessonFromFailure,
@@ -7641,14 +7782,9 @@ var ENTRY_SPECS2 = [
   { hookEvent: "stop", handler: "stop", timeoutSeconds: 120, loopLimit: 5 },
   { hookEvent: "afterAgentResponse", handler: "response-after", timeoutSeconds: 5, matcher: "AgentResponse" }
 ];
-function commandFor(runtime) {
-  if (process.platform === "win32") {
-    return { command: "cmd", argsPrefix: ["/c", "node", runtime.launcherPath] };
-  }
-  return { command: "node", argsPrefix: [runtime.launcherPath] };
-}
 function cursorWiring(runtime) {
-  const { command, argsPrefix } = commandFor(runtime);
+  const command = "node";
+  const argsPrefix = [runtime.launcherPath];
   const entries = ENTRY_SPECS2.map((spec) => ({
     hookEvent: spec.hookEvent,
     handler: spec.handler,

package/dist/uninstall-runtime.mjs

@@ -979,9 +979,6 @@ var RUNTIME_PAYLOAD = [
   "src",
   "tools",
   "config.example.json",
-  "model-aliases.json",
-  "model-prices.cursor.json",
-  "model-prices.json",
   "package.json"
 ];
 var OPERATOR_OWNED = ["config.json", "state", "flags"];
@@ -989,18 +986,18 @@ var NOT_SHIPPED = [join2("tools", "dev"), join2("tools", "__test__")];
 if (false) {}
 
 // tools/uninstall-runtime.ts
-function uninstallTargets(env = process.env, platform = process.platform) {
-  const windows = platform === "win32";
-  const userHome = (windows ? env.USERPROFILE : env.HOME)?.trim() || homedir2();
+function uninstallTargets(env = process.env) {
+  const userHome = homedir2();
   const binDir = env.TLC_BIN_DIR?.trim() || join3(userHome, ".local", "bin");
   return {
     home: runtimeHome(env),
-    binLink: join3(binDir, windows ? "tlc.cmd" : "tlc"),
+    binLinks: [join3(binDir, "tlc"), join3(binDir, "tlc.cmd")],
     claudeSettings: join3(claudeConfigDir(), "settings.json"),
     cursorHooks: join3(cursorConfigDir(), "hooks.json"),
-    skillLinks: windows ? [join3(userHome, ".tlc", "skills", "harness-init")] : [
+    skillLinks: [
       join3(claudeConfigDir(), "skills", "harness-init"),
-      join3(cursorConfigDir(), "skills", "harness-init")
+      join3(cursorConfigDir(), "skills", "harness-init"),
+      join3(userHome, ".tlc", "skills", "harness-init")
     ]
   };
 }
@@ -1182,7 +1179,9 @@ function planUninstall(targets, options = {}) {
   for (const link of targets.skillLinks) {
     planLink(items, link, targets.home, "skill link", "location");
   }
-  planLink(items, targets.binLink, targets.home, "the tlc launcher on PATH", "target");
+  for (const link of targets.binLinks) {
+    planLink(items, link, targets.home, "the tlc launcher on PATH", "target");
+  }
   const homeIsLink = planRuntime(items, targets.home, purge);
   planManual(items, targets.home);
   return { items, purge, homeIsLink };

package/docs/log.md

@@ -18,6 +18,13 @@ newest first. For what landed in which npm release, see `CHANGELOG.md` at the re
 - **AD-081** — The manifest npm publishes is checked here, because the release runner was the only thing reading it ([/decisions/ad-081.md](/decisions/ad-081.md))
 - **AD-082** — npm is the documented install, and the first version cannot come from CI ([/decisions/ad-082.md](/decisions/ad-082.md))
 - **AD-083** — Going public switched the branch ruleset on, and an unattended release needs the App to bypass it ([/decisions/ad-083.md](/decisions/ad-083.md))
+- **AD-084** — The rule about unpinned dependencies is applied to this repository too, and the release gate stops being a copy ([/decisions/ad-084.md](/decisions/ad-084.md))
+- **AD-085** — The flake was a test measuring a file the whole machine writes to ([/decisions/ad-085.md](/decisions/ad-085.md))
+- **AD-086** — The write lock read the wrong error code on Windows, in a module that already listed the right ones ([/decisions/ad-086.md](/decisions/ad-086.md))
+- **AD-087** — How the release works, and the six wrong shapes it took first ([/decisions/ad-087.md](/decisions/ad-087.md))
+- **AD-095** — Four defects about where things are written, and one of them made every hook run twice ([/decisions/ad-095.md](/decisions/ad-095.md))
+- **AD-096** — Prices are the machine's, in one file, and the parser that fills it was wrong twice ([/decisions/ad-096.md](/decisions/ad-096.md))
+- **AD-097** — The shell layer goes, and with it every platform branch that only existed because of it ([/decisions/ad-097.md](/decisions/ad-097.md))
 
 ## 2026-08-17
 

package/docs/measure.md

@@ -114,55 +114,59 @@ full mapping table.
 
 ## Prices
 
-Cost estimates use on-disk catalogs under `~/.tlc/harness/`, resolved provider-first:
+Fetched per machine, never versioned ([/decisions/ad-096.md](/decisions/ad-096.md)).
 
 ```bash
-tlc harness prices refresh
-tlc harness prices refresh all
-tlc harness prices refresh cursor
-tlc harness prices refresh litellm
+tlc harness prices refresh              # both planes, now
+tlc harness prices refresh cursor       # one plane
+tlc harness prices refresh --if-stale   # only past the TTL; what install and update run
 tlc harness prices lookup <model-id> [provider]
 ```
 
-| Command | Effect |
+| Trigger | Effect |
 |---------|--------|
-| `refresh` / `refresh all` | Update the Cursor catalog and the LiteLLM fallback |
-| `refresh cursor` | Write `model-prices.cursor.json` (commit when rates change) |
-| `refresh litellm` | Write `model-prices.litellm.json` (gitignored; regenerate locally) |
-| `lookup <model-id> [provider]` | Resolve catalog key, pool, and USD for 1M input + 1M output |
+| `tlc harness install` | first fetch; a network failure does not fail the install |
+| `tlc harness update` | `--if-stale`, TTL 7 days |
+| `tlc harness doctor` | reports the catalogue's age, or that it is absent |
 
-### Catalogs
+### Files
 
 | File | Role | In git |
 |------|------|--------|
-| `model-prices.<provider>.json` (e.g. `model-prices.cursor.json`) | Primary, per provider | Yes |
-| `model-prices.litellm.json` | Fallback (LiteLLM public JSON) | No |
-| `model-prices.json` | Local overrides | Empty `{}` template only |
-| `model-aliases.json` | Model id → catalog key | Yes |
+| `~/.tlc/harness/model-prices.json` | the catalogue | No |
+| `~/.tlc/harness/model-prices.local.json` | hand-written overrides | No |
+
+### Planes
+
+`planes` is keyed by who bills the call. They are not merged: the same model has one rate from its vendor and
+another from a provider reselling it.
+
+| Plane | Holds | Source |
+|-------|-------|--------|
+| `cursor` | what that provider charges | its pricing page |
+| `litellm` | vendor list prices | the LiteLLM public JSON |
+
+`_meta.planes[<plane>]` records the source, the model count and the fetch time.
 
 ### Resolution order
 
-1. `model-prices.json` (local overrides)
-2. `model-prices.<provider>.json` (this provider's own catalog)
-3. `model-prices.litellm.json`
+1. `model-prices.local.json`
+2. `planes[<asking provider>]`
+3. `planes.litellm`
 4. otherwise `cost_usd: null`
 
-Pools (neutral names in observability records; see [/decisions/ad-011.md](/decisions/ad-011.md) item 2):
-`provider_native` | `other` | `auto` | `unknown`. The on-disk catalog files still use vendor-named pool
-keys internally (`cursor_models`, `anthropic_models`, …) since pricing must name real vendors — those are
-mapped to the neutral names before they reach `core/`.
+Host ids that differ from a catalogue key are mapped in `MODEL_ALIASES` (`src/platform/pricing.ts`). Add your own
+by writing the key into the overrides file.
 
-### When to refresh
+Pools (neutral names in observability records; see [/decisions/ad-011.md](/decisions/ad-011.md) item 2):
+`provider_native` | `other` | `auto` | `unknown`. The catalogue uses vendor-named pool keys internally
+(`cursor_models`, `anthropic_models`, …) since pricing must name real vendors — those are mapped to the neutral
+names before they reach `core/`.
 
-| Situation | Command |
-|-----------|---------|
-| A provider published new rates or models | `tlc harness prices refresh cursor` (then commit) |
-| Missing LiteLLM file or obscure model | `tlc harness prices refresh litellm` |
-| Update both catalogs | `tlc harness prices refresh` |
-| Inspect one model | `tlc harness prices lookup <model-id> [provider]` |
+### Refusal
 
-`tlc harness doctor` requires at least one provider catalog to be present. LiteLLM is optional until needed
-as fallback.
+A plane is replaced only if the incoming table keeps at least half of what is on disk. Below that the refresh
+refuses, names both counts, and leaves every plane untouched.
 
 ## Project state files
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tech-leads-club/harness-toolkit",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "description": "Multi-provider agent steering: gates, follow-up, handoff, policy",
   "keywords": [
@@ -19,6 +19,9 @@
     "tlc": "bin/tlc.mjs",
     "tlc-exec": "bin/tlc-exec.mjs"
   },
+  "scripts": {
+    "prepack": "node bin/tlc-build.mjs"
+  },
   "files": [
     "bin/",
     "capabilities/",
@@ -30,11 +33,9 @@
     "!src/**/__test__",
     "!tools/__test__",
     "!tools/dev",
-    "CHANGELOG.md",
+    "!tools/test-env*",
+    "!docs/decisions",
     "config.example.json",
-    "model-aliases.json",
-    "model-prices.cursor.json",
-    "model-prices.json",
     "NOTICE"
   ],
   "publishConfig": {

package/src/core/core.facade.ts

@@ -130,6 +130,7 @@ 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 { freshness, freshnessMessage, mayReplace, shouldRefetch } from "./pricing/pricing.freshness.ts";
 import {
   allDecisionFiles,
   formatDecisionDigest,
@@ -140,6 +141,7 @@ import {
 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 { coversHandler, decideShim } from "./shim/shim.precedence.ts";
 import { appendShipLedger, hasRecentEvidence, newestChangeMs, readShipLedger } from "./ship/ship.ledger.ts";
 import {
   detectShipClaim,
@@ -148,6 +150,7 @@ import {
   recentShipClaimActive,
   touchesRuntime,
 } from "./ship/ship.service.ts";
+import { linkHealth, linkHealthMessage, skillLinks } from "./skill/skill.link.ts";
 import {
   recordResolution,
   resolutionFor,
@@ -271,6 +274,21 @@ export const coreFacade = {
     readHandoffFile,
     readForeignSlices,
   },
+  shim: {
+    coversHandler,
+    decideShim,
+  },
+  pricing: {
+    freshness,
+    freshnessMessage,
+    mayReplace,
+    shouldRefetch,
+  },
+  skill: {
+    linkHealth,
+    linkHealthMessage,
+    skillLinks,
+  },
   lesson: {
     projectLessonsInjectable,
     recordLessonFromFailure,

package/src/core/index.ts

@@ -44,8 +44,11 @@ export type {
   ProviderScoped,
 } from "./policy/policy.types.ts";
 export type { PresenceRecord } from "./presence/presence.types.ts";
+export type { CatalogueMeta, Freshness } from "./pricing/pricing.freshness.ts";
 export type { ShellEffectClass } from "./shell-policy/shell-policy.types.ts";
+export type { ProviderSettings } from "./shim/shim.precedence.ts";
 export type { ShipClaim, ShipClaimKind, ShipLedgerEvent, ShipLedgerRow } from "./ship/ship.types.ts";
+export type { LinkHealth, SkillLink } from "./skill/skill.link.ts";
 export type { FingerprintEntry, FingerprintStore } from "./stagnation/stagnation.types.ts";
 export type { ModelParam, ParentModelSnapshot } from "./subagent-policy/subagent-policy.types.ts";
 export type { AutopilotPlan } from "./turn/turn.autopilot.ts";

package/src/core/pricing/pricing.freshness.ts

@@ -0,0 +1,118 @@
+/**
+ * How old a price catalogue is, and whether that is old enough to refetch.
+ *
+ * why: prices belong to the machine, not to a release. Shipping them in the package means a rate published today
+ * reaches an operator only when they update the tool, and the catalogue in the repository was 23 days stale while
+ * three versions went out ([/decisions/ad-096.md](/decisions/ad-096.md)).
+ *
+ * hazard: `refreshedAt` was already written into every catalogue's `_meta` by the refresh command, and read by
+ * nothing. No age was reported and no refetch was ever skipped or triggered by it — a metadatum recorded and never
+ * consulted, which is the same shape as the guard that read an environment variable nobody set.
+ *
+ * invariant: no clock of its own. `now` is a parameter, because a function that reads the wall clock cannot be
+ * tested against a boundary.
+ */
+
+export const DEFAULT_TTL_DAYS = 7;
+
+const MS_PER_DAY = 86_400_000;
+
+export type CatalogueMeta = { refreshedAt?: string; source?: string };
+
+export type Freshness =
+  | { state: "absent" }
+  | { state: "undated" }
+  | { state: "fresh"; ageDays: number; refreshedAt: string }
+  | { state: "stale"; ageDays: number; refreshedAt: string };
+
+/**
+ * why: `undated` is its own answer rather than "infinitely old". A catalogue written by a version that did not
+ * record the date is present and usable; treating it as stale would refetch on every run, and treating it as fresh
+ * would never refetch. Naming it lets the caller decide once, visibly.
+ */
+export function freshness(
+  meta: CatalogueMeta | null,
+  now: Date,
+  ttlDays: number = DEFAULT_TTL_DAYS,
+): Freshness {
+  if (meta === null) {
+    return { state: "absent" };
+  }
+  const stamp = meta.refreshedAt;
+  if (stamp === undefined || Number.isNaN(Date.parse(stamp))) {
+    return { state: "undated" };
+  }
+  const ageMs = now.getTime() - Date.parse(stamp);
+  // invariant: a stamp from the future is age zero, not a negative age. A clock skew must not read as fresh
+  // forever nor as stale immediately.
+  const ageDays = Math.max(0, ageMs / MS_PER_DAY);
+  return ageDays > ttlDays
+    ? { state: "stale", ageDays, refreshedAt: stamp }
+    : { state: "fresh", ageDays, refreshedAt: stamp };
+}
+
+/** invariant: `undated` refetches. Once, on the next run that can, after which it has a date like everything else. */
+export function shouldRefetch(state: Freshness): boolean {
+  return state.state === "absent" || state.state === "undated" || state.state === "stale";
+}
+
+export function freshnessMessage(state: Freshness, catalogue: string): string {
+  switch (state.state) {
+    case "absent":
+      return `${catalogue}: not on this machine — run \`tlc harness prices refresh\``;
+    case "undated":
+      return `${catalogue}: present but carries no date — it will be refetched`;
+    case "fresh":
+      return `${catalogue}: ${describeAge(state.ageDays)} old`;
+    default:
+      return `${catalogue}: ${describeAge(state.ageDays)} old — run \`tlc harness prices refresh\``;
+  }
+}
+
+/**
+ * Whether a freshly parsed catalogue may replace the one on disk.
+ *
+ * hazard: the only guard was "did we parse zero entries". The upstream page grew from one table to three, the
+ * parser read the first and stopped, and 43 models became 3 — which is not zero, so it passed and overwrote the
+ * good catalogue. A refresh that silently loses nine tenths of its content is worse than a stale one, because the
+ * staleness is at least visible in the date ([/decisions/ad-096.md](/decisions/ad-096.md)).
+ *
+ * invariant: growing is always allowed, and a first catalogue is always allowed. Only a large drop is refused, and
+ * the refusal names both numbers so the operator can see whether upstream really shrank.
+ */
+export const MIN_RETAINED_RATIO = 0.5;
+
+export type ReplaceVerdict = { replace: boolean; reason: string };
+
+export function mayReplace(
+  existingCount: number,
+  incomingCount: number,
+  minRatio: number = MIN_RETAINED_RATIO,
+): ReplaceVerdict {
+  if (incomingCount === 0) {
+    return { replace: false, reason: "parsed no entries at all — the upstream format has changed" };
+  }
+  if (existingCount === 0) {
+    return { replace: true, reason: `first catalogue, ${incomingCount} entries` };
+  }
+  if (incomingCount >= existingCount) {
+    return { replace: true, reason: `${existingCount} → ${incomingCount} entries` };
+  }
+  const retained = incomingCount / existingCount;
+  return retained >= minRatio
+    ? { replace: true, reason: `${existingCount} → ${incomingCount} entries` }
+    : {
+        replace: false,
+        reason: `would drop from ${existingCount} to ${incomingCount} entries, keeping the existing catalogue — the upstream format has probably changed`,
+      };
+}
+
+/** why: an operator reads "3 days", not "3.4179". Hours below a day, because "0 days" reads as no information. */
+export function describeAge(ageDays: number): string {
+  if (ageDays < 1) {
+    const hours = Math.max(1, Math.round(ageDays * 24));
+    return `${hours} hour${hours === 1 ? "" : "s"}`;
+  }
+  const days = Math.round(ageDays);
+  return `${days} day${days === 1 ? "" : "s"}`;
+}