@tpsdev-ai/flair 0.21.0 → 0.22.1

package/dist/resources/migrations/space.js

@@ -0,0 +1,167 @@
+/**
+ * space.ts — pre-flight space check, step 1 of the ladder
+ * (flair#695, "Space pressure"):
+ *
+ * "Pre-flight space check before any write — estimate snapshot size AND the
+ * migration's own working set (supersession transforms temporarily hold
+ * old+new ≈ 2× for touched tables) vs free disk, with a headroom floor
+ * (never fill past ~90% — a full disk bricks Harper itself)."
+ *
+ * Kern verdict: "Space estimate includes HNSW rebuild overhead (re-embed
+ * rewrites every vector → index rebuild can be 2–3× raw vector size):
+ * snapshot + new vectors + index overhead vs headroom floor." —
+ * `estimateWorkingSetBytes` below is the caller's job (the runner computes
+ * it per risk class); this module just evaluates the estimate against real
+ * (or test-overridden) disk free/total space.
+ *
+ * flair#720 rewrote the rule this module enforces. The original shape
+ * (`projectedUsedFraction <= 0.9`, measured against TOTAL disk size) was
+ * designed for a flair-dedicated volume, but on a general-purpose machine
+ * — a personal Mac especially, where APFS purgeable space makes
+ * `statfs.bavail` understate real availability — the system volume
+ * routinely sits above 90% used already, so the fraction test failed
+ * before a single byte was written, regardless of how trivially the
+ * migration's own footprint fit (flair#720: 220 KB needed, 18.6 GB free,
+ * halted anyway). The fix keeps invariant III's "never fill past a
+ * cushion" intent but measures the migration's OWN impact plus an
+ * absolute reserve, instead of the disk's pre-existing fullness:
+ * `ok = neededBytes <= freeBytes AND (freeBytes - neededBytes) >= reserve`.
+ * See `RESERVE_MIN_BYTES` / `RESERVE_MAX_BYTES` / `RESERVE_FRACTION` below
+ * for how `reserve` is derived.
+ */
+import { statfsSync } from "node:fs";
+/**
+ * Reserve floor: on any disk, no migration may leave less than this much
+ * free afterward, even on a tiny volume where 5% of total would be less.
+ * 256 MiB is comfortably more than any single migration's own working set
+ * in this codebase (the largest estimate is embedding/HNSW rebuild
+ * overhead, a few KB per row) — it exists to leave room for Harper's own
+ * ordinary operation (WAL, temp files, log growth), not the migration
+ * itself.
+ */
+export const RESERVE_MIN_BYTES = 256 * 1024 * 1024; // 256 MiB
+/**
+ * Reserve cap: on a large disk, 5% of total would be an unreasonably large
+ * cushion to demand (e.g. 50 GB on a 1 TB drive) for what is, worst case,
+ * a few GB of migration working set. 2 GiB caps the reserve so the rule
+ * stays proportionate to what migrations actually need, not the disk's
+ * raw size.
+ */
+export const RESERVE_MAX_BYTES = 2 * 1024 * 1024 * 1024; // 2 GiB
+/**
+ * Between the floor and the cap, the reserve scales with disk size: 5% of
+ * total. This is the "proportionate cushion" middle ground — big enough to
+ * matter on a mid-size disk, small enough not to dominate on either
+ * extreme (RESERVE_MIN_BYTES / RESERVE_MAX_BYTES clamp the two ends).
+ */
+export const RESERVE_FRACTION = 0.05;
+/**
+ * Production escape hatch for constrained deployments (flair#720) — e.g. a
+ * small dedicated volume where even the 256 MiB floor is more cushion than
+ * the operator can spare. When set to a finite, non-negative number, this
+ * overrides the computed reserve entirely (including the floor/cap clamp
+ * — set it to 0 to disable the reserve check outright, keeping only the
+ * `neededBytes <= freeBytes` fit test). Invalid values (non-numeric,
+ * negative, NaN, Infinity) are ignored and the computed reserve is used
+ * instead — mirrors TEST_FREE_BYTES_ENV's validation below. Unset (the
+ * default) in every normal deployment.
+ */
+export const RESERVE_BYTES_ENV = "FLAIR_MIGRATION_RESERVE_BYTES";
+/**
+ * Test-only escape hatch: when set, overrides the real statfs-reported free
+ * byte count. Used by the halt-on-blocked-space integration test (real
+ * Harper spawned as a child process — the test can't inject a JS dependency
+ * into that process, only environment variables) to force the ladder's
+ * step-1 check to fail deterministically without needing an actually-full
+ * disk. Unset (the default) in every real deployment, so this is inert in
+ * production.
+ */
+export const TEST_FREE_BYTES_ENV = "FLAIR_MIGRATION_TEST_FREE_BYTES";
+function realGetFreeBytes(dataDir) {
+    const override = process.env[TEST_FREE_BYTES_ENV];
+    if (override !== undefined) {
+        const n = Number(override);
+        if (Number.isFinite(n) && n >= 0)
+            return n;
+    }
+    const st = statfsSync(dataDir);
+    return st.bavail * st.bsize;
+}
+function realGetTotalBytes(dataDir) {
+    const st = statfsSync(dataDir);
+    return st.blocks * st.bsize;
+}
+export const defaultSpaceProbe = {
+    getFreeBytes: realGetFreeBytes,
+    getTotalBytes: realGetTotalBytes,
+};
+/**
+ * Resolves the absolute reserve a migration must leave free afterward:
+ * `RESERVE_BYTES_ENV` if set to a valid (finite, >= 0) value, else
+ * `clamp(RESERVE_FRACTION * totalBytes, RESERVE_MIN_BYTES, RESERVE_MAX_BYTES)`.
+ * Exported so tests can exercise the clamp/override logic directly without
+ * going through a full `checkSpace` call.
+ */
+export function resolveReserveBytes(totalBytes, env = process.env) {
+    const override = env[RESERVE_BYTES_ENV];
+    if (override !== undefined) {
+        const n = Number(override);
+        if (Number.isFinite(n) && n >= 0)
+            return n;
+    }
+    const fractional = totalBytes * RESERVE_FRACTION;
+    return Math.min(RESERVE_MAX_BYTES, Math.max(RESERVE_MIN_BYTES, fractional));
+}
+/**
+ * Bytes → human readable (binary-based thresholds, decimal labels — same
+ * convention as src/render.ts's `humanBytes`, which this module can't
+ * import: resources/**\/*.ts and src/**\/*.ts are separate TypeScript
+ * project boundaries (tsconfig.json vs tsconfig.cli.json/tsconfig.check.src.json)
+ * — resources/ is Harper-loaded component code and never imports from the
+ * CLI's src/ tree. Small enough to duplicate locally rather than restructure
+ * the module boundary for one formatter.
+ */
+export function humanBytes(n) {
+    if (!Number.isFinite(n) || n < 0)
+        return "—";
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    if (n < 1024 * 1024 * 1024)
+        return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+    return `${(n / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+/**
+ * Evaluates the pre-flight space check (flair#720's rule): fails (ok:false)
+ * if the needed bytes don't fit in free space outright, OR if spending them
+ * would leave less than `reserveBytes` free afterward. Unlike the rule this
+ * replaced, fullness that already exists on the disk before the migration
+ * runs is irrelevant — only the migration's OWN impact on free space is
+ * judged, against an absolute (not fraction-of-total) cushion.
+ */
+export function checkSpace(input, probe = defaultSpaceProbe) {
+    const freeBytes = probe.getFreeBytes(input.dataDir);
+    const totalBytes = probe.getTotalBytes(input.dataDir);
+    const neededBytes = input.estimatedSnapshotBytes + input.estimatedWorkingSetBytes;
+    const reserveBytes = resolveReserveBytes(totalBytes);
+    const fits = neededBytes <= freeBytes;
+    const remainingAfter = freeBytes - neededBytes;
+    const withinReserve = fits && remainingAfter >= reserveBytes;
+    const ok = fits && withinReserve;
+    let reason;
+    if (!fits) {
+        reason =
+            `need ${humanBytes(neededBytes)} free (snapshot + migration working set), have ${humanBytes(freeBytes)} — ` +
+                `short by ${humanBytes(neededBytes - freeBytes)}. Set ${RESERVE_BYTES_ENV} to lower the required post-migration ` +
+                `reserve on constrained deployments (this won't help here — the migration doesn't fit even before any reserve)`;
+    }
+    else if (!withinReserve) {
+        reason =
+            `need ${humanBytes(neededBytes)} free (snapshot + migration working set); have ${humanBytes(freeBytes)}, ` +
+                `which covers it but would leave only ${humanBytes(remainingAfter)} free afterward — short of the ` +
+                `${humanBytes(reserveBytes)} minimum reserve required post-migration. Set ${RESERVE_BYTES_ENV} to a lower ` +
+                `byte count to shrink the required reserve on constrained deployments`;
+    }
+    return { ok, freeBytes, totalBytes, neededBytes, reserveBytes, reason };
+}

package/dist/resources/migrations/state.js

@@ -0,0 +1,64 @@
+/**
+ * state.ts — the health-tracked "last migration completed at version X"
+ * marker (Kern verdict, detect() fallback): "detect() cheap + read-only —
+ * bounded query (limit=1 style), never O(corpus) on boot; answers 'is there
+ * work,' not 'how much.' Fallback: a health-tracked 'last migration
+ * completed at version X' short-circuit."
+ *
+ * A small on-disk JSON sidecar (same idiom as the REM nightly log / PID
+ * file / version-check cache — plain files under the instance's own
+ * footprint, not a Harper table: adding a new table to record migration
+ * state would itself be a migration, a chicken-and-egg this avoids
+ * entirely). Lives under `<dataDir>/.migrations/state.json` — co-located
+ * with the data it protects rather than under a fixed `~/.flair`, since
+ * HDB_ROOT can point anywhere per-instance (matches resources/health.ts's
+ * own dataDir resolution).
+ *
+ * Once a migration's entry shows `completedAtVersion === <the currently
+ * running version>` and `lastOutcome === "success"`, the runner skips
+ * calling that migration's detect() ENTIRELY on this and every subsequent
+ * boot at the same version — zero query cost, not just a cheap one.
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { ensureSecureDir, writeSecureFile } from "./dir-safety.js";
+export function defaultStatePath(dataDir) {
+    return join(dataDir, ".migrations", "state.json");
+}
+export function readMigrationState(path) {
+    try {
+        if (!existsSync(path))
+            return {};
+        const raw = JSON.parse(readFileSync(path, "utf-8"));
+        return raw && typeof raw === "object" ? raw : {};
+    }
+    catch {
+        // Corrupt/unreadable state — treat as "nothing known yet", never throw.
+        // Worst case this costs one extra (cheap, bounded) detect() call.
+        return {};
+    }
+}
+export function writeMigrationStateEntry(path, id, entry) {
+    const dir = dirname(path);
+    ensureSecureDir(dir);
+    const current = readMigrationState(path);
+    current[id] = entry;
+    writeSecureFile(path, JSON.stringify(current, null, 2) + "\n", dir);
+}
+/**
+ * True when this migration can be skipped WITHOUT calling detect() at all —
+ * it already completed successfully at the currently running version.
+ */
+export function isShortCircuited(state, migrationId, runningVersion) {
+    const entry = state[migrationId];
+    return !!entry && entry.lastOutcome === "success" && entry.completedAtVersion === runningVersion;
+}
+/** For health/doctor: the most recent state-file mtime, if any (cheap "when did anything last change" signal). */
+export function statePathMtime(path) {
+    try {
+        return statSync(path).mtime.toISOString();
+    }
+    catch {
+        return null;
+    }
+}

package/dist/resources/migrations/status.js

@@ -0,0 +1,39 @@
+/**
+ * status.ts — composes the in-process progress store (progress.ts) with the
+ * on-disk state file (state.ts) into the single snapshot resources/health.ts
+ * and `flair doctor` (via /HealthDetail) surface.
+ *
+ * Falls back to the on-disk state when the in-process progress map is empty
+ * — a process can be asked for /HealthDetail before its boot's `setImmediate`
+ * callback has fired at all (a very early poll), or after a restart where
+ * this run's cycle hasn't started yet; the on-disk record of the LAST
+ * completed/halted outcome is still genuinely useful in that window instead
+ * of reporting nothing.
+ */
+import { listMigrationProgress, getCycleStatus } from "./progress.js";
+import { readMigrationState, defaultStatePath } from "./state.js";
+export function getMigrationStatusSnapshot(dataDir) {
+    const cycle = getCycleStatus();
+    let migrations = listMigrationProgress();
+    if (migrations.length === 0) {
+        const state = readMigrationState(defaultStatePath(dataDir));
+        migrations = Object.entries(state).map(([id, entry]) => {
+            const derivedState = entry.lastOutcome === "success" ? "completed" : entry.lastOutcome === "halted" ? "halted" : "failed";
+            const row = {
+                id,
+                rowsDone: entry.rowsProcessed ?? 0,
+                rowsRemaining: entry.rowsRemaining ?? 0,
+                state: derivedState,
+            };
+            if (entry.reason)
+                row.reason = entry.reason;
+            return row;
+        });
+    }
+    return {
+        cyclePhase: cycle.phase,
+        lastCycleError: cycle.lastCycleError,
+        lastCycleAt: cycle.lastCycleAt,
+        migrations,
+    };
+}

package/dist/resources/migrations/synthetic-test-migration.js

@@ -0,0 +1,93 @@
+/**
+ * synthetic-test-migration.ts — the CI-only migration variant (K&S verdict):
+ * "Synthetic CI stamp variant MUST NOT ship — registration conditional on
+ * test/CI env; a prod user must never see a spurious ci-variant migration
+ * on first boot. Flip later = swap synthetic for real, same lanes/gates."
+ *
+ * This is the payload the test suite uses to exercise the FULL runner path
+ * end-to-end (detect → pre-flight → snapshot → batches → markers →
+ * completion gate → post-hash → ledger → prune) — riskClass
+ * 'schema-additive' (batch 50, full-envelope completion gate), distinct
+ * from embedding-stamp's 'derived-only' so the suite also covers the
+ * stricter envelope-comparison gate path via a real (ephemeral) Harper.
+ *
+ * SAFETY, belt-and-suspenders even though gating (shouldRegisterSyntheticMigration
+ * below) is what actually keeps this out of production:
+ *   - Registration is conditional on FLAIR_ENABLE_TEST_MIGRATIONS === "1"
+ *     (an explicit, exact-match opt-in — never a generic NODE_ENV=test
+ *     check, which can be true in contexts nobody intended as "safe to run
+ *     a schema-touching test migration").
+ *   - Even IF it were somehow registered unconditionally, its detect/run
+ *     queries are scoped to a single reserved, never-real agentId
+ *     (RESERVED_TEST_AGENT_ID) — it can never see or touch a genuine
+ *     agent's memories.
+ *
+ * Marker: stamps `Memory.source` (an existing, currently-unused-by-any-
+ * migration nullable String field — no new schema needed) to a value that
+ * encodes the migration id, so "is this row done" is answered entirely by
+ * re-reading the row itself (invariant IV: state lives IN the data).
+ */
+import { databases } from "@harperfast/harper";
+export const SYNTHETIC_MIGRATION_ID = "synthetic-ci-schema-stamp";
+export const RESERVED_TEST_AGENT_ID = "__flair_migration_synthetic_test_agent__";
+export const SYNTHETIC_TARGET_MARKER = `${SYNTHETIC_MIGRATION_ID}-done`;
+export const ENABLE_TEST_MIGRATIONS_ENV = "FLAIR_ENABLE_TEST_MIGRATIONS";
+/**
+ * Exact-match opt-in — see the module doc. Exported so both the registry
+ * and a unit test can assert the exact condition, independent of the
+ * registry's own wiring.
+ */
+export function shouldRegisterSyntheticMigration(env = process.env) {
+    return env[ENABLE_TEST_MIGRATIONS_ENV] === "1";
+}
+function defaultMemoryTable() {
+    return databases.flair.Memory;
+}
+export function createSyntheticTestMigration(getTable = defaultMemoryTable) {
+    function pendingCondition() {
+        return [
+            { attribute: "agentId", comparator: "equals", value: RESERVED_TEST_AGENT_ID },
+            { attribute: "source", comparator: "not_equal", value: SYNTHETIC_TARGET_MARKER },
+        ];
+    }
+    return {
+        id: SYNTHETIC_MIGRATION_ID,
+        riskClass: "schema-additive",
+        affectsTables: ["Memory"],
+        async detect() {
+            const table = getTable();
+            for await (const _row of table.search({ conditions: pendingCondition(), limit: 1 })) {
+                return true;
+            }
+            return false;
+        },
+        async countPending() {
+            const table = getTable();
+            let n = 0;
+            for await (const _row of table.search({ conditions: pendingCondition() }))
+                n++;
+            return n;
+        },
+        async run(batchSize) {
+            const table = getTable();
+            const candidates = [];
+            for await (const row of table.search({ conditions: pendingCondition(), limit: batchSize })) {
+                candidates.push(row);
+            }
+            const touchedIds = [];
+            for (const row of candidates) {
+                const id = String(row.id ?? "");
+                if (!id)
+                    continue;
+                const existing = await table.get(id);
+                if (!existing)
+                    continue;
+                if (existing.source === SYNTHETIC_TARGET_MARKER)
+                    continue; // already stamped — idempotent skip
+                await table.put({ ...existing, source: SYNTHETIC_TARGET_MARKER });
+                touchedIds.push(id);
+            }
+            return { processed: touchedIds.length, touchedIds };
+        },
+    };
+}

package/dist/resources/migrations/types.js

@@ -0,0 +1,9 @@
+/**
+ * types.ts — shared shapes for the zero-touch migration runner (flair#695).
+ *
+ * Governed by flair#695 (the four invariants) and
+ * flair#695 (the runner design + K&S verdict
+ * refinements). Every migration registered in resources/migrations/registry.ts
+ * implements the `Migration` interface below.
+ */
+export {};

package/dist/resources/presence-internal.js

@@ -0,0 +1,29 @@
+function presenceDelegationContext(auth) {
+    const agentAuth = auth.kind === "agent"
+        ? { agentId: auth.agentId, isAdmin: auth.isAdmin }
+        : { agentId: "internal", isAdmin: true };
+    return { request: { _flairAgentAuth: agentAuth } };
+}
+/**
+ * The full presence roster (one row per agent — bounded, per the K&S
+ * verdict: "Presence is a bounded scan, one row/agent, tiny"), via the
+ * exported `Presence` resource's get(). Fails open to `[]` on any error
+ * (Presence being briefly unavailable should never break a caller that
+ * treats presence as one signal among several, not a hard dependency).
+ */
+export async function getPresenceRoster(auth) {
+    try {
+        const { Presence } = await import("./Presence.js");
+        const p = new Presence();
+        p.getContext = () => presenceDelegationContext(auth);
+        const roster = await p.get();
+        if (roster instanceof Response)
+            return [];
+        if (!Array.isArray(roster))
+            return [];
+        return roster;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/resources/provenance.js

@@ -0,0 +1,50 @@
+/**
+ * ─── Write-time provenance stamp (memory-provenance slice 1) ────────────────
+ *
+ * Foundational capture for an emergent-trust model: every write gets a
+ * structured, versioned `provenance` JSON blob recording what the server can
+ * actually VERIFY about the write, plus (optionally) what the caller merely
+ * CLAIMS. Deliberately minimal — verified fields only:
+ *
+ *   { v: 1,
+ *     verified: { agentId: <string|null>, timestamp: <ISO string> },
+ *     claimed?: { model: <string> } }
+ *
+ * - `verified.agentId` comes from the ALREADY-RESOLVED auth verdict
+ *   (resolveAgentAuth) — never from anything the caller can forge on the
+ *   request body. `kind: "agent"` → the Ed25519-verified agentId. Any other
+ *   verdict (in practice only `kind: "internal"` — a trusted in-process call
+ *   with no per-agent identity to attribute) stamps `null` rather than
+ *   throwing; `kind: "anonymous"` never reaches here — every write path
+ *   already 401s it before this point.
+ * - `verified.timestamp` reuses the server-clock `createdAt` the caller has
+ *   already computed by this point (never client-suppliable) — the same
+ *   "stamp a dynamic attribute the server controls" mechanism as e.g. the
+ *   `embeddingModel = getModelId()` stamp in resources/Memory.ts.
+ * - `claimed.model` is an OPTIONAL, UNVERIFIED passthrough: included only
+ *   when the incoming write payload itself already carries a non-empty
+ *   string `model` field. No client/CLI sets one today — this just means the
+ *   server won't discard it if/when a future write path does. Never
+ *   invented, never defaulted, and the `claimed` key is omitted entirely
+ *   (not stamped as `{}`) when absent.
+ *
+ * Originally introduced in resources/Memory.ts (Memory.post()/Memory.put());
+ * extracted here so Relationship.ts (and any future write path) can reuse the
+ * EXACT same shape rather than inventing a table-specific format — the
+ * K&S-approved contract for the relationship-write-path spec is "reuse
+ * buildProvenance as-is," which this module makes literal (one function, one
+ * shape, imported by every writer) instead of a copy that could drift.
+ */
+export function buildProvenance(auth, createdAt, content) {
+    const provenance = {
+        v: 1,
+        verified: {
+            agentId: auth.kind === "agent" ? auth.agentId : null,
+            timestamp: createdAt,
+        },
+    };
+    if (typeof content?.model === "string" && content.model.length > 0) {
+        provenance.claimed = { model: content.model };
+    }
+    return JSON.stringify(provenance);
+}

package/dist/resources/rate-limiter.js

@@ -6,6 +6,7 @@
  *
  *   FLAIR_RATE_LIMIT_RPM     — requests per minute per agent (default: 120)
  *   FLAIR_RATE_LIMIT_EMBED   — embedding requests per minute per agent (default: 30)
+ *   FLAIR_RATE_LIMIT_USAGE   — usage-feedback requests per minute per agent (default: 30)
  *   FLAIR_RATE_LIMIT_STORAGE — max memories per agent (default: 10000)
  *   FLAIR_RATE_LIMIT_ENABLED — "true" to enable (default: disabled for local, enabled when FLAIR_PUBLIC=true)
  */
@@ -35,7 +36,13 @@ export function checkRateLimit(agentId, bucket = "general") {
         return { allowed: true }; // admin/internal calls
     const limit = bucket === "embedding"
         ? getLimit("FLAIR_RATE_LIMIT_EMBED", 30)
-        : getLimit("FLAIR_RATE_LIMIT_RPM", 120);
+        // flair#683: usage-feedback is a write-that-affects-ranking (anti-gaming
+        // surface) — Sherlock's three-layer defense is rate-limiter (~30 RPM
+        // bucket) + per-agent dedup bound (MemoryUsage ledger) + the capped
+        // usageBoost itself. This bucket is that first layer.
+        : bucket === "usage"
+            ? getLimit("FLAIR_RATE_LIMIT_USAGE", 30)
+            : getLimit("FLAIR_RATE_LIMIT_RPM", 120);
     const key = `${agentId}:${bucket}`;
     const now = Date.now();
     const cutoff = now - WINDOW_MS;

package/dist/resources/scoring.js

@@ -40,13 +40,132 @@ export function retrievalBoost(retrievalCount) {
         return 1.0;
     return Math.min(1.0 + 0.1 * Math.log2(retrievalCount), RBOOST_CAP); // gentle, capped
 }
+// ─── usageBoost — the verified-USE signal (flair#683) ───────────────────────
+// retrievalCount/retrievalBoost above count a search HIT as "used" — a
+// rich-get-richer loop root-caused in #623 (a doc that surfaces once gets
+// boosted, surfaces more, boosts more, independent of whether it was ever
+// actually useful). usageCount is a STRONGER, distinct signal: it is only
+// ever incremented by the dedicated usage-feedback endpoint (resources/
+// MemoryUsage.ts) when a caller explicitly reports that a memory was
+// cited/used to ground an answer or decision — never auto-incremented on
+// search (schemas/memory.graphql's usageCount field doc). Dedup'd
+// (agent, memory) ≤ 1 contribution and rate-limited there, so this function
+// only ever sees a bounded, deliberately-reported count.
+//
+// SAME shape as retrievalBoost — a gentle, capped nudge (a tie-breaker, never
+// an override), floor-gated so a popular-but-irrelevant doc gets no lift.
+// K&S verdict (FLAIR-USAGE-FEEDBACK-SIGNAL.md, 2026-07-11): keep the
+// constants/shape identical to retrievalBoost's so the ONLY variable in the
+// harness rematch (test/bench/recall-harness) is signal QUALITY (what gets
+// counted), not magnitude/shape — that isolation is what makes the
+// positive/negative/noise comparison meaningful.
+export const USAGE_BOOST_CAP = 1.1; // max +10% — a tie-breaker, not an override
+export const USAGE_RELEVANCE_FLOOR = 0.5; // no boost at all for clearly-irrelevant docs
+export function usageBoost(usageCount) {
+    if (!usageCount || usageCount <= 0)
+        return 1.0;
+    return Math.min(1.0 + 0.1 * Math.log2(usageCount), USAGE_BOOST_CAP); // gentle, capped
+}
+// flair#623 (2026-07-08): SemanticSearch.ts's `scoring` param now DEFAULTS to
+// "raw" — compositeScore measurably HURTS recall-eval precision on the live
+// corpus (Δp@3 -0.38 to -0.50 vs raw). recall-harness's harder 87-record
+// corpus (test/bench/recall-harness) reproduced this in isolation at Δp@3
+// -0.900: dWeight and rFactor applied UNCONDITIONALLY — no relevance-floor
+// gate, unlike rBoost above — so an unrelated-but-`permanent`/fresh record
+// (dWeight=1.0 × rFactor=1.0, no discount at all) routinely outranked the
+// objectively best match once its `standard`/`persistent`, weeks-old
+// durability/recency discount cut 30-95% off its score.
+//
+// FIRST ATTEMPT (kept here as a documented dead end — do not re-introduce):
+// gate dWeight×rFactor by ramping it from neutral-at-floor to
+// full-strength-at-rawScore=1.0, mirroring rBoost's floor gate. Measured
+// WORSE than the original bug (p@3 0.033 vs 0.067) on recall-harness. Root
+// cause: the records compositeScore actually needs to protect are the
+// GENUINELY relevant ones, and a genuine match has a HIGH rawScore (0.9+ on
+// this corpus, not near the 0.5 floor) — so ramping the gate open as
+// rawScore rises means the *correct* answer gets the discount at nearly full
+// strength (gate≈1), while the discount was already a no-op for the
+// magnet distractors (permanent/fresh ⇒ dWeight×rFactor=1.0 regardless of any
+// gate). Ramping-by-relevance is backwards for a DISCOUNT-only multiplier: it
+// protects weak/borderline matches that were never the problem, and does
+// nothing for the strong matches that were.
+//
+// THE ACTUAL FIX: treat dWeight×rFactor the same way RBOOST_CAP treats
+// retrievalBoost — bound it to a small band around 1.0 (a gentle nudge, not
+// an override) via COMPOSITE_DISCOUNT_FLOOR, so durability/recency can never
+// cost a record more than a fixed, small percentage regardless of how stale
+// or low-durability it is. The RBOOST_RELEVANCE_FLOOR-style gate is layered
+// on top per its original intent (no adjustment at all for records that
+// don't even clear a basic relevance bar) but the CAP is what actually stops
+// the magnet: even a `standard`/95-day-old correct answer now loses at most
+// (1 - COMPOSITE_DISCOUNT_FLOOR) of its score, never the 30-95% the
+// unconditional formula could take.
+//
+// COMPOSITE_DISCOUNT_FLOOR (env: FLAIR_COMPOSITE_DISCOUNT_FLOOR) and
+// COMPOSITE_RELEVANCE_FLOOR (env: FLAIR_COMPOSITE_RELEVANCE_FLOOR, default
+// 0.5, same value as RBOOST_RELEVANCE_FLOOR): below the relevance floor the
+// durability/recency multiplier is fully neutral (1.0); at/above it, the
+// multiplier is dWeight×rFactor linearly remapped from its native [0,1] range
+// into [COMPOSITE_DISCOUNT_FLOOR, 1.0] — so a `permanent`+fresh record still
+// scores strictly higher than a `standard`+stale one among relevant
+// candidates (durability/recency remains a real, monotonic signal), but
+// never by more than the bounded amount.
+//
+// DISCOUNT_FLOOR_DEFAULT = 0.98 (max -2%) was tuned empirically against
+// recall-harness's 87-record corpus (test/bench/recall-harness/run.ts,
+// hybrid=true, 3 runs, deterministic/±0.000 SE on this corpus): 0.9 (max
+// -10%, symmetric with RBOOST_CAP's +10%) recovered p@3 to match raw exactly
+// (0.967) but MRR still trailed raw by -0.150 (0.742 vs 0.892) — the bounded
+// discount was still large enough to occasionally reorder within the top-3,
+// just not enough to push the right answer OUT of it. 0.95 narrowed the MRR
+// gap to -0.078. 0.98 closed it to +0.000 on both metrics across all 3 runs
+// — this corpus's RRF-normalized rawScore band is tight enough that even a
+// 5-10% durability/recency swing is bigger than the real relevance gap
+// between candidates. Re-run recall-harness (and recall-eval.mjs on the live
+// corpus) before changing this default or reconsidering scoring defaults.
+export const COMPOSITE_RELEVANCE_FLOOR_DEFAULT = 0.5;
+export const COMPOSITE_DISCOUNT_FLOOR_DEFAULT = 0.98; // max -2% — tuned to fully close the gap to raw on recall-harness
+export function getCompositeRelevanceFloor() {
+    const v = Number(process.env.FLAIR_COMPOSITE_RELEVANCE_FLOOR);
+    return Number.isFinite(v) && v >= 0 && v <= 1 ? v : COMPOSITE_RELEVANCE_FLOOR_DEFAULT;
+}
+export function getCompositeDiscountFloor() {
+    const v = Number(process.env.FLAIR_COMPOSITE_DISCOUNT_FLOOR);
+    return Number.isFinite(v) && v >= 0 && v <= 1 ? v : COMPOSITE_DISCOUNT_FLOOR_DEFAULT;
+}
+// flair#683 (2026-07-11, K&S-approved FLAIR-USAGE-FEEDBACK-SIGNAL.md): usage
+// REPLACES retrieval as compositeScore's reinforcement term. Kern's Q1
+// verdict: replace `retrievalBoost` OUTRIGHT rather than weight usage above
+// it — retrievalCount is the CONTAMINATED signal (a search hit counted as
+// "used"); keeping it in the formula at any weight keeps the contamination,
+// because the problem is signal QUALITY, not magnitude. usageCount is
+// strictly more informative (usage implies retrieval happened; retrieval
+// never implies usage). Clean degeneration: on a record with no reported
+// usage yet (the overwhelming majority of the corpus until usage accrues),
+// usageCount=0 → usageBoost=1.0 → compositeScore collapses to
+// semantic × durability/recency, with NO retrieval-popularity pollution at
+// all — a strictly cleaner default state than the pre-#683 formula ever had.
+// retrievalCount/retrievalBoost remain exported above (unused here) —
+// keeping retrievalCount as a fallback "weak prior" for not-yet-used records
+// is an explicitly-deferred v2 idea (FLAIR-USAGE-FEEDBACK-SIGNAL.md's K&S
+// verdict), not built in this slice.
 export function compositeScore(semanticScore, record) {
     const durability = record.durability ?? "standard";
     const dWeight = DURABILITY_WEIGHTS[durability] ?? 0.7;
     const rFactor = record.createdAt ? recencyFactor(record.createdAt, durability) : 1.0;
-    // OPS-AYGD: only apply the retrieval boost when the record is genuinely relevant to
-    // this query (semanticScore clears the floor). Below the floor, a popular doc gets
-    // no lift — kills the cross-query magnet while preserving boosts for relevant docs.
-    const rBoost = semanticScore >= RBOOST_RELEVANCE_FLOOR ? retrievalBoost(record.retrievalCount ?? 0) : 1.0;
-    return semanticScore * dWeight * rFactor * rBoost;
+    // Only apply the usage boost when the record is genuinely relevant to this
+    // query (semanticScore clears the floor) — same relevance-gate rationale
+    // OPS-AYGD established for retrievalBoost: below the floor, a heavily-used
+    // doc gets no lift, so a used-but-irrelevant-to-THIS-query record can't
+    // magnet its way into an unrelated result set.
+    const uBoost = semanticScore >= USAGE_RELEVANCE_FLOOR ? usageBoost(record.usageCount ?? 0) : 1.0;
+    // Bound dWeight×rFactor into [discountFloor, 1.0] (a gentle nudge, mirroring
+    // RBOOST_CAP), then relevance-gate it (mirroring RBOOST_RELEVANCE_FLOOR): no
+    // adjustment at all below the floor, the bounded nudge at/above it.
+    const discountFloor = getCompositeDiscountFloor();
+    const dWeightRecency = dWeight * rFactor; // native range ~[0, 1]
+    const boundedDWeightRecency = discountFloor + (1 - discountFloor) * dWeightRecency; // remapped to [discountFloor, 1]
+    const relevanceFloor = getCompositeRelevanceFloor();
+    const gatedDWeightRecency = semanticScore >= relevanceFloor ? boundedDWeightRecency : 1.0;
+    return semanticScore * gatedDWeightRecency * uBoost;
 }