@tpsdev-ai/flair 0.20.1 → 0.22.0

package/dist/resources/agent-auth.js

@@ -26,7 +26,7 @@ import { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuff
 export const FLAIR_AGENT_USERNAME = "flair-agent";
 // ─── Crypto + replay-guard helpers ────────────────────────────────────────────
 // WINDOW_MS, isNonceReplay/recordNonce (the ONE shared nonce store), and
-// importEd25519Key all live in ./ed25519-auth.ts (bd ops-c4op) — the single
+// importEd25519Key all live in ./ed25519-auth.ts — the single
 // shared implementation imported by auth-middleware.ts, agent-auth.ts, and
 // Presence.ts so a nonce recorded via any one of the three call sites is
 // visible to the other two, and the crypto/decoder logic can't drift.
@@ -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/agentcard-fields.js

@@ -9,7 +9,7 @@
 //
 // Kept free of any @harperfast/harper import so the real logic is unit-testable
 // without spinning up Harper (avoids the simulator-pattern that let the
-// description-fallback leak ship untested — ops-vz6j).
+// description-fallback leak ship untested).
 export function readSoulKind(entry) {
     return String(entry.kind ?? entry.key ?? "").trim().toLowerCase();
 }
@@ -20,7 +20,7 @@ export function readSoulContent(entry) {
  * The public description is ONLY an explicit `kind="description"` soul.
  *
  * There is deliberately no fallback to "the first soul with any content": that
- * was the ops-vz6j leak — an agent with no description soul would publish an
+ * was the description-fallback leak — an agent with no description soul would publish an
  * arbitrary private soul on the unauthenticated card. Absent an explicit
  * description, publish nothing.
  */

package/dist/resources/auth-middleware.js

@@ -38,7 +38,7 @@ function getAdminPass() {
 // an admin — one implementation guarantees they can't diverge.
 // ─── Crypto + replay-guard helpers ────────────────────────────────────────────
 // WINDOW_MS, isNonceReplay/recordNonce (the ONE shared nonce store), and
-// importEd25519Key all live in ./ed25519-auth.ts (bd ops-c4op) — the single
+// importEd25519Key all live in ./ed25519-auth.ts — the single
 // shared implementation imported by auth-middleware.ts, agent-auth.ts, and
 // Presence.ts so a nonce recorded via any one of the three call sites is
 // visible to the other two, and the crypto/decoder logic can't drift.
@@ -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,23 +92,50 @@ 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. POST handles Ed25519 auth internally
-        // (allowCreate=true on the Resource).
-        url.pathname === "/Presence")
+        // Office Space renderer without auth. Scoped to GET only (#604): the
+        // exact-path match used to match ANY method, so a bare `PUT /Presence`
+        // (collection-level, no id — Harper routes it to the same .put() as
+        // by-id PUT) early-returned here too, skipping this middleware entirely.
+        // A credential-less loopback PUT then reached Presence.put()'s
+        // resolveAgentAuth() call with NO tpsAnonymous/tpsAgent annotation, which
+        // fell through to raw `context.user` — populated by Harper's
+        // `authorizeLocal` (config true) ambient super_user injection for ANY
+        // credential-less loopback request — so the ownership check saw an
+        // "admin" caller (isAdmin=true) and let the write through unauthenticated
+        // (`super.put()`, no signature, no password). Mirrors the A2A GET-only
+        // pattern above: POST/PUT/DELETE now always transit the general
+        // middleware path below, which marks a genuinely headerless request
+        // tpsAnonymous BEFORE Harper's ambient elevation lands (resolveAgentAuth
+        // checks tpsAnonymous first — see agent-auth.ts's resolution order), so
+        // the ownership check in Presence.put()/delete() correctly denies it.
+        // POST (the heartbeat) is unaffected in practice: it already prefers
+        // request.tpsAgent when the middleware set it, and falls back to its own
+        // Ed25519 header parse otherwise — transiting the general path now just
+        // means a genuinely headerless POST gets marked anonymous (still 401)
+        // 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 {
@@ -120,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)
@@ -477,7 +505,7 @@ server.http(async (request, nextLayer) => {
                 if (memId) {
                     const record = await databases.flair.Memory.get(memId);
                     if (record && record.agentId && record.agentId !== agentId) {
-                        // Centralized read-scope (ops-2dm3 Layer 1): a grant only covers
+                        // Centralized read-scope (Layer 1): a grant only covers
                         // the owner's SHARED memories, never their private ones. This
                         // used to be a `visibility === "office"` bypass (any authenticated
                         // agent, no grant needed) — that's gone; the private-exclusion is

package/dist/resources/bm25-filter.js

@@ -72,7 +72,7 @@ export function passesRecordFilters(record, f = {}) {
         return false;
     if (f.asOf && record?.validTo && record.validTo <= f.asOf)
         return false;
-    // ops-9rc6: a past validTo ALWAYS means the record has been closed out —
+    // A past validTo ALWAYS means the record has been closed out —
     // either by the server supersede path (Memory.ts closeSupersededRecord sets
     // validTo without necessarily setting `archived`) or any other writer. This
     // is unconditional (not gated on `f.asOf`) so a server-superseded record

package/dist/resources/bm25.js

@@ -1,5 +1,5 @@
 // ─── BM25 + union-RRF hybrid retrieval (Harper-free, unit-testable) ──────────
-// Per spec FLAIR-BM25-HYBRID-RETRIEVAL (Kern-approved, ops-i39b). This module is
+// Per spec FLAIR-BM25-HYBRID-RETRIEVAL (Kern-approved). This module is
 // deliberately Harper-free — same rationale as ./scoring.ts — so the BM25
 // scoring, the candidate-union RRF fusion, and the security conditions-filter
 // can be unit-tested directly against the SHIPPED code without a live Harper.
@@ -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/dedup.js

@@ -30,10 +30,10 @@ export const DEDUP_MIN_CONTENT_LENGTH = 20;
  * Cosine similarity of two equal-length embedding vectors, computed directly
  * in JS. Used as a fallback for Harper's HNSW cosine-sort query omitting a
  * computed `$distance` on its top candidate when the query's post-filter
- * result set contains exactly ONE matching record (ops-ume4, found in
+ * result set contains exactly ONE matching record (found in
  * resources/Memory.ts's findConservativeDedupMatch; the identical quirk is
  * also fixed in resources/SemanticSearch.ts's scoring loop for the same
- * reason — see ops-syzm there). A mismatched length, empty vector, or
+ * reason). A mismatched length, empty vector, or
  * zero-magnitude side yields 0 (no signal, never treated as "identical" by a
  * degenerate computation).
  */

package/dist/resources/ed25519-auth.js

@@ -11,8 +11,8 @@
  * `importEd25519Key`. Three independent replay windows meant a nonce
  * recorded as "seen" via one path was invisible to the other two — a
  * defense-in-depth gap, and a drift hazard (any future fix to one copy
- * silently didn't apply to the other two). bd ops-c4op consolidates all
- * three into this one module so there is exactly ONE replay guard and ONE
+ * silently didn't apply to the other two). Consolidating all three into
+ * this one module means there is exactly ONE replay guard and ONE
  * key-import implementation, imported by all 3 sites.
  *
  * `b64ToArrayBuffer` was already unified into resources/b64.ts in a prior

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();