@tpsdev-ai/flair 0.21.0 → 0.22.0

package/dist/resources/SkillScan.js

@@ -1,4 +1,5 @@
 import { Resource } from "@harperfast/harper";
+import { allowVerified } from "./agent-auth.js";
 import { scanSkillContent } from "./scan/skill-scanner.js";
 /**
  * POST /SkillScan/
@@ -30,6 +31,20 @@ import { scanSkillContent } from "./scan/skill-scanner.js";
  *    weakening detection on actual shell content.
  */
 export class SkillScan extends Resource {
+    /**
+     * allowCreate()=allowVerified (authorizeLocal-escalation-class follow-up to
+     * #601/#604/#609/#612 — flair#614's backstop found this resource had NO
+     * allow* at all). The docstring above already says "Auth: any authenticated
+     * agent" — this was never actually enforced; Harper's own default
+     * (`user?.role.permission.super_user`, satisfiable only by a genuine admin
+     * OR authorizeLocal's forged loopback super_user) silently stood in
+     * instead. allowVerified matches the documented intent: any verified agent
+     * (not admin-only — this is a stateless text scanner, no agent/memory data
+     * touched), anonymous denied.
+     */
+    async allowCreate() {
+        return allowVerified(this.getContext?.());
+    }
     async post(data, _context) {
         const { content } = data || {};
         if (!content || typeof content !== "string") {

package/dist/resources/WorkspaceState.js

@@ -9,6 +9,7 @@
  */
 import { databases } from "@harperfast/harper";
 import { resolveAgentAuth, allowVerified } from "./agent-auth.js";
+import { invalidEntitiesResponse } from "./entity-vocab.js";
 const FORBIDDEN = (msg) => new Response(JSON.stringify({ error: msg }), { status: 403, headers: { "Content-Type": "application/json" } });
 const UNAUTH = () => new Response(JSON.stringify({ error: "authentication required" }), { status: 401, headers: { "Content-Type": "application/json" } });
 const NOT_FOUND = () => new Response(JSON.stringify({ error: "not found" }), { status: 404, headers: { "Content-Type": "application/json" } });
@@ -114,6 +115,12 @@ export class WorkspaceState extends databases.flair.WorkspaceState {
         }
         content.createdAt = new Date().toISOString();
         content.timestamp ||= content.createdAt;
+        // attention-plane vocabulary gate (flair#675): `entities`, if present,
+        // must be well-formed vocabulary strings — see resources/entity-vocab.ts.
+        // Field is additive/optional; absent entities is not an error.
+        const entitiesError = invalidEntitiesResponse(content.entities);
+        if (entitiesError)
+            return entitiesError;
         return super.post(content);
     }
     async put(content) {
@@ -123,6 +130,10 @@ export class WorkspaceState extends databases.flair.WorkspaceState {
         if (auth.kind === "agent" && !auth.isAdmin && content.agentId !== auth.agentId) {
             return FORBIDDEN("forbidden: cannot write workspace state for another agent");
         }
+        // attention-plane vocabulary gate (flair#675) — same as post() above.
+        const entitiesError = invalidEntitiesResponse(content.entities);
+        if (entitiesError)
+            return entitiesError;
         return super.put(content);
     }
     async delete(id) {

package/dist/resources/agent-auth.js

@@ -132,6 +132,52 @@ export async function verifyAgentRequest(request) {
  *      — and if a request object IS present but yields no agent → anonymous
  *   5. nothing at all → trusted internal call
  */
+/**
+ * Header names that can carry a CLIENT-PRESENTED credential. Today only the
+ * standard `authorization` header — it carries Basic, Bearer, AND our custom
+ * `TPS-Ed25519 …` scheme (all three ride the Authorization header; see
+ * doVerify() above and auth-middleware.ts, both of which read exactly this
+ * header to authenticate a caller). Kept as a LIST, read via every header-object
+ * shape below, so a future signed-header auth scheme is a one-line addition here
+ * — not a scatter of ad-hoc `req.headers.authorization` truthiness checks that
+ * would each have to be rediscovered and updated (Kern's review point).
+ *
+ * DELIBERATELY EXCLUDES the server-set trust markers `x-tps-agent` /
+ * `x-tps-anonymous`: auth-middleware.ts STAMPS those AFTER it has verified a
+ * caller — they are never presented by the client. Counting them as "credential
+ * evidence" would let an unauthenticated caller forge one and defeat this gate.
+ */
+const CREDENTIAL_HEADERS = ["authorization"];
+/**
+ * Read a header off either header-object shape Harper hands us: the Web
+ * Headers-like `.get(name)` (populated for GET/search requests) or the plain
+ * `.asObject` bag (PUT/POST). Mirrors doVerify()'s own read exactly, so the
+ * evidence check can't miss a shape the verifier would have seen.
+ */
+function readRequestHeader(reqLike, name) {
+    return (reqLike?.headers?.get?.(name) ??
+        reqLike?.headers?.asObject?.[name] ??
+        "");
+}
+/**
+ * True iff the request carries ANY client-presented credential (CREDENTIAL_HEADERS).
+ *
+ * WHY THIS EXISTS (flair#610): Harper's `authorizeLocal: true` forges
+ * `request.user = super_user` (and can populate `.username`) for a credential-
+ * LESS loopback request — one with NO Authorization header at all. A genuine
+ * Basic/Bearer/TPS-Ed25519 header SUPPRESSES that forgery. So "is a credential
+ * present?" is precisely what separates a genuinely-authenticated caller from
+ * Harper's ambient forgery — the gate resolveAgentAuth applies before trusting a
+ * `context.user` identity. Handles BOTH context shapes (`getContext().request`
+ * for GET/search, context-only for PUT/POST) by resolving `request ?? self`
+ * first, then reads both header-object shapes.
+ */
+export function hasCredentialEvidence(context) {
+    const reqLike = context?.request ?? context;
+    if (!reqLike)
+        return false;
+    return CREDENTIAL_HEADERS.some((h) => readRequestHeader(reqLike, h) !== "");
+}
 /**
  * allow* for AGENT-FACING resources: permit verified agents, admins/super_user,
  * and trusted internal calls; deny anonymous HTTP. Pass getContext(). Per-record
@@ -159,11 +205,23 @@ export async function resolveAgentAuth(context) {
     if (c.tpsAgent) {
         return { kind: "agent", agentId: String(c.tpsAgent), isAdmin: c.tpsAgentIsAdmin === true };
     }
+    // flair#610 — CREDENTIAL-EVIDENCE GATE. Harper's `authorizeLocal: true` forges
+    // `context.user = super_user` (and can populate `.username`) for a credential-
+    // LESS loopback request. Trusting that ambient identity was the forgery
+    // vector: a bare local caller resolved to admin with no signature and no
+    // password. Only trust a `context.user` identity when the request actually
+    // carries a credential (real Basic/Bearer/TPS-Ed25519 header) — the one thing
+    // authorizeLocal's forgery cannot manufacture. Without evidence, FALL THROUGH
+    // to the verifyAgentRequest fallback below: a genuine signed request still
+    // authenticates; a credential-less HTTP request lands on `anonymous` (it has a
+    // headers object but no valid agent), and a true in-process call with no
+    // request object at all lands on `internal`.
+    const credentialed = hasCredentialEvidence(c);
     const user = context?.user ?? c.user;
-    if (user?.role?.permission?.super_user === true) {
+    if (credentialed && user?.role?.permission?.super_user === true) {
         return { kind: "agent", agentId: String(user.username ?? "admin"), isAdmin: true };
     }
-    if (user?.username && user.username !== FLAIR_AGENT_USERNAME) {
+    if (credentialed && user?.username && user.username !== FLAIR_AGENT_USERNAME) {
         return { kind: "agent", agentId: String(user.username), isAdmin: false };
     }
     // A raw request with headers is present → verify it; an HTTP request that

package/dist/resources/auth-middleware.js

@@ -49,7 +49,9 @@ async function backfillEmbedding(memoryId) {
             return;
         if (record.embedding?.length > 100)
             return;
-        const embedding = await getEmbedding(record.content);
+        // flair#504 Phase 2: 'document' — a backfilled embedding IS a stored
+        // document vector, same as the three Memory.ts sites; must match.
+        const embedding = await getEmbedding(record.content, "document");
         if (!embedding)
             return;
         await patchRecord(databases.flair.Memory, memoryId, { embedding });
@@ -90,12 +92,6 @@ server.http(async (request, nextLayer) => {
         url.pathname === "/OAuthRevoke" ||
         url.pathname === "/.well-known/oauth-authorization-server" ||
         url.pathname === "/OAuthMetadata" ||
-        // ObservationCenter HTML shell is public — the page itself is just markup
-        // and inline JS, with no embedded data. The JS prompts for admin-pass and
-        // auths every API call (/Agent, /SemanticSearch, /FederationPeers, etc).
-        // Without this allow-list entry, the HTML is 401-blocked on hosted Flair
-        // instances (rockit-local works only because authorizeLocal=true).
-        url.pathname === "/ObservationCenter" ||
         // Presence roster is public-safe (field-allowlisted); GET serves the
         // Office Space renderer without auth. Scoped to GET only (#604): the
         // exact-path match used to match ANY method, so a bare `PUT /Presence`
@@ -120,12 +116,26 @@ server.http(async (request, nextLayer) => {
         // instead of skipping straight to that fallback parse.
         (request.method === "GET" && url.pathname === "/Presence"))
         return nextLayer(request);
+    // Read the Authorization header ONCE, up front — the super_user branch below
+    // needs it too (hoisted from its former position just after the branch as part
+    // of the flair#610 belt-and-suspenders check).
+    const header = request.headers.get("authorization") || request.headers?.asObject?.authorization || "";
     // If Harper has already authorized this request (e.g. Basic admin, or
     // authorizeLocal=true on localhost), trust Harper's auth decision and pass
     // through. Annotate the admin identity so resources' resolveAgentAuth recognizes
     // this as an ADMIN caller (not anonymous) — otherwise a Basic-admin request,
     // which carries no TPS-Ed25519 header, gets classified anonymous and denied.
-    if (request.user?.role?.permission?.super_user === true) {
+    //
+    // flair#610 BELT-AND-SUSPENDERS: require an Authorization header to be present
+    // before trusting a super_user `request.user`. Harper's `authorizeLocal: true`
+    // forges request.user=super_user for a credential-LESS loopback request; a
+    // genuine Basic/super_user caller always carries a header. This is defense-in-
+    // depth — the general middleware path below already marks a headerless request
+    // tpsAnonymous BEFORE Harper's ambient elevation lands, so this branch isn't a
+    // live vector today — but it keeps the trust decision from ever hinging on
+    // ambient elevation alone. (The root-cause gate lives in resolveAgentAuth; see
+    // agent-auth.ts hasCredentialEvidence.)
+    if (header && request.user?.role?.permission?.super_user === true) {
         request.tpsAgent = request.user.username ?? "admin";
         request.tpsAgentIsAdmin = true;
         try {
@@ -139,7 +149,6 @@ server.http(async (request, nextLayer) => {
     // Skip re-entry: if we already swapped auth to Basic, pass through
     if (request._tpsAuthVerified)
         return nextLayer(request);
-    const header = request.headers.get("authorization") || request.headers?.asObject?.authorization || "";
     // ── Basic admin / super_user auth ──────────────────────────────────────────
     // Allow Basic auth for CLI operations (backup, etc.). Two paths:
     // 1. HDB_ADMIN_PASSWORD env-var fast-path (user must be "admin" with exact pass)

package/dist/resources/bm25.js

@@ -9,13 +9,19 @@
 // candidate-UNION RRF (NOT naive whole-corpus RRF) recovers 4/6 into top-10 with
 // no regression on the within-cluster gate (p@3 holds 0.88).
 // ─── Feature flag: BM25 + union-RRF hybrid retrieval ────────────────────────
-// Flag OFF (default) → SemanticSearch behavior is byte-identical to the
-// pre-hybrid path (HNSW + the +0.05 exact-substring keyword bump). Flag ON → the
-// hybrid path. Toggle with FLAIR_HYBRID_RETRIEVAL=true (also "1" / "on"). Read
-// per-call so it can be flipped without a rebuild and set per-case in tests.
-// Lives here (Harper-free) so it's unit-testable.
+// ACTIVATED 2026-07-08 (ops-i39b activation follow-up to #519): default is now
+// ON. Recall-eval validated at build time (CHANGELOG 0.20.x): NEW-8
+// within-cluster gate p@3 holds 0.88 (no regression), OLD-6 severe
+// near-verbatim misses recover 0/6 → 4/6 into top-10. A fresh isolated-Harper
+// measurement at activation time (no prod contact) confirmed zero regression
+// on both severe- and within-cluster-style synthetic queries and a small
+// (~+4ms/query) latency delta. Set FLAIR_HYBRID_RETRIEVAL=false (also "0" /
+// "off") to REVERT to the pre-hybrid legacy path — byte-identical to the
+// original default-OFF behavior, no code rollback needed. Read per-call so it
+// can be flipped without a rebuild and set per-case in tests. Lives here
+// (Harper-free) so it's unit-testable.
 export function hybridEnabled() {
-    const v = (process.env.FLAIR_HYBRID_RETRIEVAL ?? "").toLowerCase();
+    const v = (process.env.FLAIR_HYBRID_RETRIEVAL ?? "true").toLowerCase();
     return v === "true" || v === "1" || v === "on";
 }
 // BM25 parameters (Kern-approved): k1≈1.2, b≈0.75; standard IDF + BM25.

package/dist/resources/collision-lib.js

@@ -0,0 +1,157 @@
+/**
+ * collision-lib.ts — pure join/rank/format logic for MemoryBootstrap's
+ * "Others in the room" collision-surfacing block (flair#681, the attention-
+ * plane flagship — spec: flair#681 "Phase 2 — collision
+ * surfacing in bootstrap").
+ *
+ * This module does NO Harper reads of its own. resources/MemoryBootstrap.ts's
+ * post() does the (already-scoped, already-gated) reads —
+ *   - entity-overlap candidates from WorkspaceState (internal server-side
+ *     path, Sherlock Option 1 — the #678 AttentionQuery pattern) and OrgEvent
+ *     (org-open read model, no per-agent scoping to respect),
+ *   - semantic-match candidates from the SAME scored candidate pool #550's
+ *     existing code already computes during bootstrap (HNSW cosine
+ *     similarity against the caller's embedded currentTask, via the bounded
+ *     retrieveCandidates() core — flair-bootstrap-scale-fix replaced the
+ *     original full-corpus JS dot-product scan with this bounded pushdown;
+ *     same `score > 0.3` relevance floor, same "no new embedding code"
+ *     property — see resources/MemoryBootstrap.ts and resources/
+ *     semantic-retrieval-core.ts),
+ *   - the freshness gate from the Presence roster (resources/
+ *     presence-internal.ts's getPresenceRoster(), the SAME internal path
+ *     #678 established — never the raw table),
+ * and hands the resulting plain-object candidates to this module to join,
+ * freshness-gate, rank, and format. Kept Harper-free so it can be unit-tested
+ * directly (test/unit/collision-lib.test.ts) — the same reason
+ * resources/memory-bootstrap-lib.ts exists for the Team-roster helpers.
+ *
+ * Per the K&S verdict's correction: Memory is the SEMANTIC surface (reused,
+ * via #550); WorkspaceState/OrgEvent are the ENTITY surface (exact index
+ * overlap). This module joins the two, never conflating them — an
+ * entity-overlap match is always high-precision (exact vocabulary-string
+ * equality) and never needs its own relevance score; a semantic-only match
+ * always carries the score #550 already floor-gated.
+ */
+/**
+ * Build a Harper query condition matching ANY of `entities` against an
+ * indexed `entities` array attribute. Harper's real query engine THROWS
+ * ("An 'or' operator requires at least two conditions") for an `operator:
+ * "or"` condition with fewer than two sub-conditions — a single-entity
+ * caller (the common case) would otherwise silently break the whole
+ * collision block (caught only by a real-Harper e2e test, never the mocked
+ * unit suite — see test/integration/bootstrap-collision-e2e.test.ts).
+ * Callers must always call this instead of hand-rolling the OR wrapper.
+ */
+export function buildEntityMatchCondition(entities, attribute = "entities") {
+    if (entities.length === 1) {
+        return { attribute, comparator: "equals", value: entities[0] };
+    }
+    return {
+        operator: "or",
+        conditions: entities.map((e) => ({ attribute, comparator: "equals", value: e })),
+    };
+}
+const MS_MIN = 60_000;
+const MS_HOUR = 3600_000;
+const MS_DAY = 24 * MS_HOUR;
+/** "4m ago" / "2h ago" / "3d ago" — mirrors the issue's own example phrasing. */
+export function formatRelativeTime(fromMs, nowMs = Date.now()) {
+    const elapsed = Math.max(0, nowMs - fromMs);
+    if (elapsed < MS_MIN)
+        return "just now";
+    if (elapsed < MS_HOUR)
+        return `${Math.floor(elapsed / MS_MIN)}m ago`;
+    if (elapsed < MS_DAY)
+        return `${Math.floor(elapsed / MS_HOUR)}h ago`;
+    return `${Math.floor(elapsed / MS_DAY)}d ago`;
+}
+function clip(s, max = 80) {
+    const t = s.trim().replace(/\s+/g, " ");
+    if (t.length === 0)
+        return t;
+    return t.length > max ? `${t.slice(0, max - 1)}…` : t;
+}
+/**
+ * The freshness gate: only agents with a Presence roster row whose
+ * `presenceStatus` is NOT "offline" are candidates at all — reuses
+ * Presence.ts's OWN derivePresenceStatus()-driven verdict (a heartbeat
+ * within the offline threshold), never a re-implemented threshold. An agent
+ * absent from the roster entirely (never heartbeated) is excluded outright —
+ * no heartbeat is the strictest possible "not fresh."
+ */
+export function freshPresenceByAgent(roster) {
+    const out = new Map();
+    for (const row of roster) {
+        const id = row?.id;
+        if (typeof id !== "string" || id.length === 0)
+            continue;
+        if (row.presenceStatus === "offline")
+            continue;
+        const hb = row.lastHeartbeatAt;
+        if (hb === null || hb === undefined)
+            continue; // no heartbeat at all → not fresh
+        const hbNum = typeof hb === "number" ? hb : Number(hb);
+        if (!Number.isFinite(hbNum))
+            continue;
+        out.set(id, row);
+    }
+    return out;
+}
+/**
+ * Join entity-overlap + semantic-match candidates against the freshness-
+ * gated presence map, rank (entity overlap first — high precision, exact
+ * match — then semantic by score desc), and format each into a single
+ * "others in the room" line. Never returns more than one entry per agent
+ * (entity detail wins over semantic when a teammate has both — the
+ * higher-precision signal leads). Never surfaces an agent absent from
+ * `freshByAgent` (the freshness gate) or the caller itself.
+ */
+export function buildCollisionEntries(entityMatches, semanticMatches, freshByAgent, callerAgentId, nowMs = Date.now()) {
+    const byAgent = new Map();
+    const sortedEntity = entityMatches
+        .filter((m) => m.agentId !== callerAgentId && m.entities.length > 0)
+        .slice()
+        .sort((a, b) => (b.timestamp || "").localeCompare(a.timestamp || ""));
+    for (const m of sortedEntity) {
+        if (byAgent.has(m.agentId))
+            continue; // best (most recent) row per agent wins
+        const presence = freshByAgent.get(m.agentId);
+        if (!presence)
+            continue; // freshness gate
+        const displayName = typeof presence.displayName === "string" && presence.displayName
+            ? presence.displayName
+            : m.agentId;
+        const hbRaw = presence.lastHeartbeatAt;
+        const hb = typeof hbRaw === "number" ? hbRaw : Number(hbRaw);
+        const entityList = m.entities.join(", ");
+        const detail = m.summary ? ` (${clip(m.summary)})` : "";
+        const line = `${displayName} is touching ${entityList}${detail} — last active ${formatRelativeTime(hb, nowMs)}`;
+        byAgent.set(m.agentId, { agentId: m.agentId, displayName, kind: "entity", line, lastHeartbeatAt: hb });
+    }
+    const sortedSemantic = semanticMatches
+        .filter((m) => m.agentId !== callerAgentId)
+        .slice()
+        .sort((a, b) => b.score - a.score);
+    for (const m of sortedSemantic) {
+        if (byAgent.has(m.agentId))
+            continue; // entity-overlap already covers this agent — higher precision wins
+        const presence = freshByAgent.get(m.agentId);
+        if (!presence)
+            continue; // freshness gate
+        const displayName = typeof presence.displayName === "string" && presence.displayName
+            ? presence.displayName
+            : m.agentId;
+        const hbRaw = presence.lastHeartbeatAt;
+        const hb = typeof hbRaw === "number" ? hbRaw : Number(hbRaw);
+        const line = `${displayName} has related work in progress (${clip(m.content)}) — last active ${formatRelativeTime(hb, nowMs)}`;
+        byAgent.set(m.agentId, { agentId: m.agentId, displayName, kind: "semantic", line, lastHeartbeatAt: hb });
+    }
+    // Entity-kind entries first (rank order preserved by insertion above is not
+    // guaranteed across the two passes' Map writes), then semantic — within
+    // each kind, most-recently-active first.
+    return [...byAgent.values()].sort((a, b) => {
+        if (a.kind !== b.kind)
+            return a.kind === "entity" ? -1 : 1;
+        return b.lastHeartbeatAt - a.lastHeartbeatAt;
+    });
+}

package/dist/resources/embeddings-boot.js

@@ -0,0 +1,149 @@
+/**
+ * embeddings-boot.ts — registers harper-fabric-embeddings as Harper's
+ * `embedding`/`default` model backend DIRECTLY, in-process, on every boot
+ * (flair#694 fix; invariants at flair#695).
+ *
+ * ─── Why this file exists (flair#694) ──────────────────────────────────────
+ * The previous mechanism (removed by this change) delivered the registration
+ * as a `models.embedding.default` block via the `HARPER_CONFIG` env var
+ * (src/cli.ts's old `buildEmbeddingsHarperConfigEnv`) — a "merge layer" that
+ * Harper's environment-manager (`@harperfast/harper`'s
+ * `config/harperConfigEnvVars.js`) reasserts on every boot AND PERSISTS into
+ * the instance-root `harper-config.yaml`. That file proved to be config-as-
+ * STATE, not config-as-intent: `flair#694`'s downgrade-and-revert CI lane
+ * (flair#692) caught a real bricking sequence —
+ *
+ *   1. A build with this feature boots and HARPER_CONFIG reasserts
+ *      `models.embedding.default.{backend,modelName,modelsDir}`, which
+ *      Harper's env-var layer persists to `harper-config.yaml` AND records
+ *      each of those THREE flattened leaf paths as `sources[path] =
+ *      'HARPER_CONFIG'` in `.harper-config-state.json` (no "original value"
+ *      stored, because the key didn't exist before this boot introduced it).
+ *   2. On ANY later boot that does not reassert `HARPER_CONFIG` for those
+ *      paths (a downgrade to a build that predates this feature; equally, a
+ *      transient resolution failure on the current build) — Harper's own
+ *      `applyRuntimeEnvConfig` treats the env var's absence as "the operator
+ *      removed this config" and calls `cleanupRemovedEnvVar`, which deletes
+ *      each of the three leaves INDIVIDUALLY (no stored original to restore
+ *      to), leaving `models.embedding.default: {}` — an empty shell —
+ *      persisted to disk.
+ *   3. The next boot's config schema validator
+ *      (`@harperfast/harper`'s `validation/configValidator.js`) resolves the
+ *      entry's backend via `Joi.alternatives().conditional('.backend', {...,
+ *      otherwise: unknownBackendEntrySchema})`; with `backend` absent, that
+ *      falls through to `unknownBackendEntrySchema = Joi.object({backend:
+ *      string.required()})`, which throws exactly: "Harper config file
+ *      validation error: 'models.embedding.default.backend' is required" —
+ *      Harper refuses to boot. Confirmed byte-identical in both @harperfast/
+ *      harper 5.1.15 and 5.1.17 (this is upstream env-var-config behavior,
+ *      not a schema difference between versions), and reproduced locally by
+ *      replaying the exact downgrade-and-revert sequence.
+ *
+ * No shape flair could put IN HARPER_CONFIG fixes this: the deletion is
+ * triggered by an OLDER build never setting the env var in the first place,
+ * which is unfixable from the newer build's side. Config that gets torn
+ * down whenever a boot doesn't reassert it is fundamentally unsafe for
+ * anything a downgrade must survive (flair#695 invariant I: "config files
+ * are state too").
+ *
+ * ─── The fix ────────────────────────────────────────────────────────────
+ * Skip Harper's config-file-driven bootstrap path ENTIRELY. Call
+ * harper-fabric-embeddings' own `register({logicalName, kind, config})`
+ * factory DIRECTLY — the same factory Harper's `bootstrapModels()` would
+ * have invoked, and (per that package's own source) the "public path for
+ * components and apps to add in-process ... backends":
+ * `models.registerBackend(kind, id, backend)` on Harper's process-wide
+ * `models` singleton. This is genuinely reassert-only: every boot calls this
+ * function again (module-scope side effect, same convention as
+ * `migration-boot.ts`), NOTHING is ever written to `harper-config.yaml`, so
+ * there is no persisted state for a downgrade to trip over — the class of
+ * bug this file fixes cannot recur by construction, not by a shape
+ * contract that has to keep being honored.
+ *
+ * Bonus: this also drops the old absolute-path workaround
+ * (`resolveEmbeddingBackendModule`'s `require.resolve` + `pathToFileURL`
+ * dance) that HARPER_CONFIG's `backend:` needed because
+ * `resolveBackendSpecifier` resolves a bare package name from the Harper
+ * INSTANCE ROOT's `node_modules`, not flair's own package dir. Importing
+ * harper-fabric-embeddings directly from flair's own code needs no such
+ * workaround — plain Node module resolution from flair's own `node_modules`
+ * always finds it, uniformly across a local install, Docker, AND a Fabric
+ * deploy (where flair runs as a non-root cluster component and
+ * `bootstrapModels()` — gated on `isRoot` — was never reachable at all; see
+ * the removed comment this replaces in `config.yaml`).
+ *
+ * ─── Loading mechanism ──────────────────────────────────────────────────
+ * Plain (non-Resource) module — same shape as `migration-boot.ts` /
+ * `embeddings-provider.ts` / `table-helpers.ts` — so Harper's `jsResource:
+ * files: dist/resources/*.js` loader (config.yaml) imports it at boot like
+ * every other flat file under `resources/`, running its top-level side
+ * effect exactly once per process. No config.yaml wiring needed.
+ *
+ * Graceful degrade preserved: if harper-fabric-embeddings isn't installed,
+ * or `globalThis.models` isn't available (this module loaded outside a real
+ * Harper boot), registration is skipped and logged — Harper falls back to
+ * keyword-only search, matching the pre-existing degrade contract.
+ */
+import { resolveModelsDir } from "./embeddings-provider.js";
+const LOGICAL_NAME = "default";
+const MODEL_NAME = "nomic-embed-text";
+/**
+ * BENCH-ONLY escape hatch — NOT a production feature flag, never documented
+ * as an operator setting, and never read anywhere else in this codebase.
+ * Mirrors `embeddings-provider.ts`'s `FLAIR_RECALL_HARNESS_FORCE_PREFIX`
+ * hatch (see that file's header for the pattern this follows): a bench-only
+ * env var, read lazily, that lets `test/bench/recall-harness/run.ts`'s
+ * `--model-file <path>` flag override model SELECTION the same way that
+ * hatch overrides prefix behavior — without editing this file's hardcoded
+ * `MODEL_NAME`/`resolveModelsDir()` call every time a bakeoff needs a
+ * different GGUF (e.g. a Q8_0 quant of the same base model).
+ *
+ * This is not a new capability grafted on — `harper-fabric-embeddings`'
+ * `register()` factory already accepts `config.modelPath` as an alternative
+ * to `modelName`+`modelsDir` (see `engineOptionsFromConfig()` in
+ * `harper-fabric-embeddings`' `dist/index.js`): an absolute path bypasses its
+ * built-in model registry and HuggingFace-download resolution entirely. This
+ * hatch is the one line that lets a caller reach that existing parameter.
+ * `EmbeddingEngine`'s `modelIdentity` (used for nomic-prefix detection, see
+ * `engine.js`'s `#applyPrefix`) becomes the file's basename in this path, so
+ * prefix behavior is unaffected as long as the GGUF's filename still
+ * contains "nomic-embed-text".
+ *
+ * No production deploy sets this env var, so the unset (overwhelmingly
+ * common) case is byte-identical to before this hatch existed.
+ */
+function benchModelPathOverride() {
+    return process.env.FLAIR_RECALL_HARNESS_MODEL_PATH || undefined;
+}
+let registered = false;
+/**
+ * Register the embedding backend. Idempotent within a process (mirrors
+ * `migration-boot.ts`'s `scheduled` guard) — safe to call more than once,
+ * only the first call does anything.
+ */
+export async function registerEmbeddingsBackend() {
+    if (registered)
+        return;
+    registered = true;
+    try {
+        const { register } = await import("harper-fabric-embeddings");
+        const modelPath = benchModelPathOverride();
+        await register({
+            logicalName: LOGICAL_NAME,
+            kind: "embedding",
+            config: modelPath ? { modelPath } : { modelName: MODEL_NAME, modelsDir: resolveModelsDir() },
+        });
+    }
+    catch (err) {
+        // Not installed, or globalThis.models isn't ready (module loaded outside
+        // a real Harper boot, e.g. some future non-Harper import path) — degrade
+        // to Harper's keyword-only fallback, the same contract the old
+        // HARPER_CONFIG-omitted path preserved.
+        console.error(`[embeddings] backend registration skipped: ${err?.message ?? String(err)}`);
+    }
+}
+/** Test-only reset — never used in production (a real process boots once). */
+export function _resetEmbeddingsBackendRegistrationForTests() {
+    registered = false;
+}
+void registerEmbeddingsBackend();