@tpsdev-ai/flair 0.14.0 → 0.15.0

package/dist/fabric-upgrade.js

@@ -0,0 +1,367 @@
+/**
+ * fabric-upgrade.ts — `flair upgrade --target <fabric-url>`
+ *
+ * One-command upgrade of a Flair instance already DEPLOYED to a Harper Fabric
+ * cluster (as opposed to a local `flair upgrade`, which upgrades the globally
+ * installed npm packages on the current host).
+ *
+ * Why this exists — the manual dance it replaces:
+ *   Upgrading a deployed Fabric Flair used to require, by hand:
+ *     1. mkdir a fresh temp dir
+ *     2. write a package.json that depends on @tpsdev-ai/flair@<version> AND
+ *        carries an `overrides` block pinning @harperfast/harper to a fixed
+ *        version — because the PUBLISHED flair declares an OLD Harper
+ *        (@harperfast/harper@5.0.21 as of flair@0.14.0) whose component
+ *        packager (`packageComponent`) emits an EMPTY tarball when the package
+ *        root lives under node_modules (the real npm-install scenario).
+ *        See flair#513 — fixed in Harper >= 5.1.13.
+ *     3. npm install
+ *     4. run `flair deploy --target <url>` from that temp dir
+ *   This module bakes the Harper pin in so the whole thing is one command.
+ *
+ * `deploy()` (src/deploy.ts) is REUSED verbatim for the packaging + spawn of
+ * the bundled Harper's `harper deploy` — this module never reimplements deploy.
+ * It only: resolves the target version, prepares a clean temp deployable with
+ * the Harper override baked in, confirms the resolved Harper bin is the fix
+ * version, then hands the temp package root to deploy() via `packageRoot`.
+ */
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { createRequire } from "node:module";
+/**
+ * Minimum @harperfast/harper version whose component packager works when the
+ * package root is under node_modules (flair#513 — the empty-tarball fix landed
+ * in 5.1.13). Anything below this MUST be overridden before a Fabric deploy.
+ */
+export const MIN_HARPER_VERSION = "5.1.13";
+/**
+ * Version we pin Harper to when an override is needed and `--harper-version`
+ * isn't given and we can't resolve the registry's latest. Known-good, ships the
+ * packageComponent fix. 5.1.14 is the latest published as of this writing.
+ */
+export const DEFAULT_HARPER_PIN = "5.1.14";
+const FLAIR_PKG = "@tpsdev-ai/flair";
+const HARPER_PKG = "@harperfast/harper";
+/**
+ * Parse "5.1.14" / "5.1.14-rc.1" / "v0.14.0" into [major, minor, patch],
+ * ignoring any pre-release / build suffix for comparison. Returns null when the
+ * core can't be parsed as three numeric segments.
+ */
+export function parseSemverCore(v) {
+    if (!v)
+        return null;
+    const core = v.trim().replace(/^v/, "").split("-")[0].split("+")[0];
+    const parts = core.split(".");
+    if (parts.length < 3)
+        return null;
+    const nums = parts.slice(0, 3).map((p) => Number(p));
+    if (nums.some((n) => !Number.isFinite(n)))
+        return null;
+    return [nums[0], nums[1], nums[2]];
+}
+/** True when `a` >= `b` by numeric major.minor.patch (pre-release ignored). */
+export function semverGte(a, b) {
+    const pa = parseSemverCore(a);
+    const pb = parseSemverCore(b);
+    if (!pa || !pb)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        if (pa[i] > pb[i])
+            return true;
+        if (pa[i] < pb[i])
+            return false;
+    }
+    return true; // equal
+}
+/**
+ * Decide what (if any) @harperfast/harper override to bake into the temp
+ * deployable's package.json.
+ *
+ *   - If flair already declares Harper >= MIN_HARPER_VERSION → no override
+ *     needed; keep what it ships (pin = declared).
+ *   - Otherwise (declared is older, absent, or unparseable) → override to
+ *     `preferredPin` (caller passes --harper-version, else registry latest,
+ *     else DEFAULT_HARPER_PIN). We still require the chosen pin to satisfy
+ *     MIN_HARPER_VERSION, falling back to DEFAULT_HARPER_PIN if the caller
+ *     passed something too old.
+ *
+ * Pure — no I/O. The LOAD-BEARING bit is `overridden`: when true, the temp
+ * package.json gets `overrides: { "@harperfast/harper": pin }`.
+ */
+export function resolveHarperPin(declared, preferredPin) {
+    if (declared && semverGte(declared, MIN_HARPER_VERSION)) {
+        return {
+            pin: declared,
+            overridden: false,
+            declared,
+            reason: `flair declares ${HARPER_PKG}@${declared} (>= ${MIN_HARPER_VERSION}); no override needed`,
+        };
+    }
+    // Need an override. Choose the pin: prefer the caller's, but never below the
+    // fix floor — a stale --harper-version would silently reintroduce flair#513.
+    let pin = preferredPin && semverGte(preferredPin, MIN_HARPER_VERSION)
+        ? preferredPin
+        : DEFAULT_HARPER_PIN;
+    const declaredLabel = declared ? `${declared}` : "none";
+    const tooOldHint = preferredPin && !semverGte(preferredPin, MIN_HARPER_VERSION)
+        ? ` (requested ${preferredPin} is below the ${MIN_HARPER_VERSION} fix floor — using ${pin} instead)`
+        : "";
+    return {
+        pin,
+        overridden: true,
+        declared,
+        reason: `flair declares ${HARPER_PKG}@${declaredLabel} (< ${MIN_HARPER_VERSION}, flair#513 empty-tarball) — pinning to ${pin}${tooOldHint}`,
+    };
+}
+/**
+ * Build the package.json contents for the temp deployable. Depends on
+ * @tpsdev-ai/flair@<version> and, when the Harper pin is an override, carries
+ * the `overrides` block that forces npm to install the fix Harper under the
+ * flair package's node_modules.
+ */
+export function buildDeployablePackageJson(flairVersion, pin) {
+    const pkg = {
+        name: "flair-fabric-upgrade-stage",
+        version: "0.0.0",
+        private: true,
+        dependencies: {
+            [FLAIR_PKG]: flairVersion,
+        },
+    };
+    if (pin.overridden) {
+        pkg.overrides = { [HARPER_PKG]: pin.pin };
+    }
+    return pkg;
+}
+// ─── Default (real) dependency implementations ──────────────────────────────
+const REGISTRY = "https://registry.npmjs.org";
+async function defaultFetchLatestFlairVersion() {
+    const res = await fetch(`${REGISTRY}/${FLAIR_PKG}/latest`, {
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) {
+        throw new Error(`npm registry returned ${res.status} for ${FLAIR_PKG}/latest`);
+    }
+    const data = (await res.json());
+    if (!data.version)
+        throw new Error(`No version in registry response for ${FLAIR_PKG}`);
+    return data.version;
+}
+async function defaultFetchDeclaredHarperVersion(flairVersion) {
+    const res = await fetch(`${REGISTRY}/${FLAIR_PKG}/${flairVersion}`, {
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok)
+        return null;
+    const data = (await res.json());
+    return data.dependencies?.[HARPER_PKG] ?? null;
+}
+function defaultNpmInstall(dir) {
+    // No package spec on argv — npm reads dependencies + overrides from the
+    // package.json we wrote into `dir`. --omit=dev keeps the stage lean;
+    // --no-audit/--no-fund cut noise. Output streamed for operator visibility.
+    const r = spawnSync("npm", ["install", "--omit=dev", "--no-audit", "--no-fund"], { cwd: dir, stdio: "inherit" });
+    if (r.error)
+        throw r.error;
+    if (r.status !== 0) {
+        throw new Error(`npm install failed in staging dir (exit ${r.status})`);
+    }
+}
+/**
+ * Query the Fabric for the deployed Flair component version. Best-effort: the
+ * public REST surface exposes `/Health`, which echoes the running Flair version
+ * in newer builds; if the shape isn't recognized we return null (verification
+ * downgrades to a soft notice, never a hard failure).
+ */
+async function defaultFetchDeployedVersion(opts) {
+    const base = opts.url.replace(/\/$/, "");
+    const headers = {};
+    if (opts.fabricUser && opts.fabricPassword) {
+        const auth = Buffer.from(`${opts.fabricUser}:${opts.fabricPassword}`).toString("base64");
+        headers.Authorization = `Basic ${auth}`;
+    }
+    try {
+        const res = await fetch(`${base}/Health`, {
+            headers,
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!res.ok)
+            return null;
+        const text = await res.text();
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            return null;
+        }
+        // Tolerate a few shapes: { version }, { flair: { version } }, { flairVersion }.
+        const v = body?.version ?? body?.flairVersion ?? body?.flair?.version ?? null;
+        return typeof v === "string" ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Resolve the @harperfast/harper bin that npm installed under the staged flair. */
+export function resolveStagedHarperVersion(stagingDir) {
+    const harperPkgJson = join(stagingDir, "node_modules", FLAIR_PKG, "node_modules", HARPER_PKG, "package.json");
+    // npm dedupes: with an override the fixed Harper may hoist to the staging
+    // root rather than nest under flair. Check both.
+    const hoisted = join(stagingDir, "node_modules", HARPER_PKG, "package.json");
+    for (const candidate of [harperPkgJson, hoisted]) {
+        if (existsSync(candidate)) {
+            try {
+                const pkg = JSON.parse(readFileSync(candidate, "utf8"));
+                if (typeof pkg.version === "string")
+                    return pkg.version;
+            }
+            catch {
+                /* try next */
+            }
+        }
+    }
+    // Last resort: resolve through the staged flair's module graph.
+    try {
+        const flairPkg = join(stagingDir, "node_modules", FLAIR_PKG, "package.json");
+        const req = createRequire(flairPkg);
+        const resolved = req.resolve(`${HARPER_PKG}/package.json`);
+        const pkg = JSON.parse(readFileSync(resolved, "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Locate the staged @tpsdev-ai/flair package root (the deploy() packageRoot). */
+export function resolveStagedFlairRoot(stagingDir) {
+    const root = join(stagingDir, "node_modules", FLAIR_PKG);
+    if (!existsSync(join(root, "package.json"))) {
+        throw new Error(`Staged flair not found at ${root} — npm install may have failed`);
+    }
+    return root;
+}
+function defaultDeps() {
+    // deploy is imported lazily so unit tests can fully mock without pulling the
+    // real Harper-spawning module into their graph.
+    return {
+        fetchLatestFlairVersion: defaultFetchLatestFlairVersion,
+        fetchDeclaredHarperVersion: defaultFetchDeclaredHarperVersion,
+        npmInstall: defaultNpmInstall,
+        fetchDeployedVersion: defaultFetchDeployedVersion,
+        deploy: async (opts) => {
+            const { deploy } = await import("./deploy.js");
+            return deploy(opts);
+        },
+        log: (m) => console.log(m),
+    };
+}
+// ─── Orchestrator ───────────────────────────────────────────────────────────
+/**
+ * Build the upgrade plan (steps 1 + version diff). Pure-ish: only the two
+ * read-only registry lookups, no install, no deploy. `--check` stops here.
+ */
+export async function planFabricUpgrade(opts, deps) {
+    const project = opts.project ?? "flair";
+    const targetVersion = opts.version ?? (await deps.fetchLatestFlairVersion());
+    const declaredHarper = await deps.fetchDeclaredHarperVersion(targetVersion);
+    const harper = resolveHarperPin(declaredHarper, opts.harperVersion);
+    const currentVersion = await deps.fetchDeployedVersion({
+        url: opts.target,
+        project,
+        fabricUser: opts.fabricUser,
+        fabricPassword: opts.fabricPassword,
+    });
+    const upToDate = currentVersion != null &&
+        parseSemverCore(currentVersion) != null &&
+        parseSemverCore(targetVersion) != null &&
+        semverGte(currentVersion, targetVersion) &&
+        semverGte(targetVersion, currentVersion);
+    return { target: opts.target, project, targetVersion, currentVersion, harper, upToDate };
+}
+/**
+ * Full Fabric upgrade. Reuses deploy() for the packaging/deploy — this function
+ * only prepares the clean temp deployable (with the Harper override baked in)
+ * and verifies afterward.
+ *
+ * SAFETY: never logs creds; always cleans up the staging dir (finally); never
+ * touches the running local Flair — all work happens in an isolated temp dir
+ * and the deploy targets the remote Fabric URL only.
+ */
+export async function fabricUpgrade(opts, injected) {
+    const deps = { ...defaultDeps(), ...injected };
+    const log = deps.log ?? (() => { });
+    // Step 1 + diff.
+    const plan = await planFabricUpgrade(opts, deps);
+    log(`Fabric:  ${plan.target}`);
+    log(`Project: ${plan.project}`);
+    log(`Version: ${plan.currentVersion ?? "(unknown)"} → ${plan.targetVersion}` +
+        (plan.upToDate ? "  (already up to date)" : ""));
+    log(`Harper:  ${plan.harper.reason}`);
+    if (opts.check) {
+        log("");
+        log("--check: plan only — not deploying.");
+        return { plan, deployed: false, verifiedVersion: null, stagingDir: "" };
+    }
+    // Step 2: prepare a clean deployable in an isolated temp dir.
+    const stagingDir = mkdtempSync(join(tmpdir(), "flair-fabric-upgrade-"));
+    try {
+        const pkgJson = buildDeployablePackageJson(plan.targetVersion, plan.harper);
+        writeFileSync(join(stagingDir, "package.json"), JSON.stringify(pkgJson, null, 2));
+        log(`\nStaging ${FLAIR_PKG}@${plan.targetVersion} in ${stagingDir} ...`);
+        deps.npmInstall(stagingDir);
+        // CONFIRM the resolved Harper bin is the fix version before deploying.
+        const stagedHarper = resolveStagedHarperVersion(stagingDir);
+        if (!stagedHarper) {
+            throw new Error(`Could not resolve the staged ${HARPER_PKG} version — refusing to deploy ` +
+                `(packageComponent may emit an empty tarball, flair#513).`);
+        }
+        if (!semverGte(stagedHarper, MIN_HARPER_VERSION)) {
+            throw new Error(`Staged ${HARPER_PKG}@${stagedHarper} is below the ${MIN_HARPER_VERSION} ` +
+                `fix floor — the override did not take. Refusing to deploy (flair#513).`);
+        }
+        log(`✓ Staged ${HARPER_PKG}@${stagedHarper} (>= ${MIN_HARPER_VERSION})`);
+        const packageRoot = resolveStagedFlairRoot(stagingDir);
+        // Step 3: REUSE deploy() — do not reimplement packaging/spawn.
+        log(`Deploying ${plan.project} ${plan.targetVersion} to ${plan.target} ...`);
+        const result = await deps.deploy({
+            target: opts.target,
+            project: plan.project,
+            version: plan.targetVersion,
+            fabricUser: opts.fabricUser,
+            fabricPassword: opts.fabricPassword,
+            restart: opts.restart,
+            replicated: opts.replicated,
+            packageRoot,
+        });
+        // Step 4: verify the deployed version (best-effort).
+        let verifiedVersion = null;
+        try {
+            verifiedVersion = await deps.fetchDeployedVersion({
+                url: opts.target,
+                project: plan.project,
+                fabricUser: opts.fabricUser,
+                fabricPassword: opts.fabricPassword,
+            });
+        }
+        catch {
+            verifiedVersion = null;
+        }
+        if (verifiedVersion) {
+            const ok = semverGte(verifiedVersion, plan.targetVersion);
+            log(ok
+                ? `✓ Fabric now reports Flair ${verifiedVersion}`
+                : `⚠ Fabric reports ${verifiedVersion} (expected ${plan.targetVersion}) — may still be restarting`);
+        }
+        else {
+            log(`✓ Deployed ${result.version} (Fabric did not report a version to verify against)`);
+        }
+        return { plan, deployed: true, verifiedVersion, stagingDir };
+    }
+    finally {
+        // SAFETY: always clean up the temp dir.
+        rmSync(stagingDir, { recursive: true, force: true });
+    }
+}

package/dist/resources/A2AAdapter.js

@@ -274,7 +274,10 @@ export class A2AAdapter extends Resource {
     // (GET /a2a passes through; POST /a2a must carry TPS-Ed25519 or admin
     // Basic). The post() handler below additionally enforces sender ==
     // params.agentId for message/send so an authenticated caller can only
-    // act AS themselves, not impersonate another agent.
+    // act AS themselves, not impersonate another agent. message/send routes
+    // a DIRECTED handoff to params.toAgentId (the recipient) by setting the
+    // OrgEvent's targetIds = [toAgentId]; OrgEventCatchup filters on that, so
+    // the recipient — not the sender — receives the message.
     allowRead() { return true; }
     allowCreate() { return true; }
     async get() {
@@ -439,22 +442,45 @@ export class A2AAdapter extends Resource {
                 // Without this check, an authenticated agent could forge OrgEvents
                 // attributed to any other agent — defeats the whole signed-envelopes
                 // model that delegationChain enforces for TPS mail.
+                // NOTE: agentId is the SENDER. The recipient is params.toAgentId.
                 if (!callerIsAdmin && callerAgent !== agentId) {
                     return rpcError(id, -32001, "Forbidden", {
                         detail: `caller ${callerAgent ?? "(anon)"} cannot send as ${agentId}`,
                     });
                 }
-                const agent = await databases.flair.Agent.get(agentId).catch(() => null);
-                if (!agent) {
+                const sender = await databases.flair.Agent.get(agentId).catch(() => null);
+                if (!sender) {
                     return rpcError(id, -32004, "Agent not found", { agentId });
                 }
+                // Directed handoff: params.toAgentId (the recipient) controls
+                // OrgEvent.targetIds, which is what OrgEventCatchup filters on
+                // (`targets.includes(participantId)`). The recipient must exist.
+                // Back-compat: if toAgentId is omitted, fall back to the legacy
+                // self-scoped broadcast (targetIds = [sender]) so existing callers
+                // that only set agentId keep working. The no-spoof guard above is
+                // unchanged — toAgentId only affects WHO receives the message, never
+                // who it is sent AS, so a sender can hand off to a peer without being
+                // able to impersonate anyone.
+                const toAgentId = cleanText(params.toAgentId);
+                let targetIds;
+                if (toAgentId) {
+                    const recipient = await databases.flair.Agent.get(toAgentId).catch(() => null);
+                    if (!recipient) {
+                        return rpcError(id, -32004, "Recipient agent not found", { toAgentId });
+                    }
+                    targetIds = [toAgentId];
+                }
+                else {
+                    targetIds = [agentId];
+                }
                 const summary = truncate(firstTextPart(message) || "A2A message received", 200);
                 await publishOrgEvent({
+                    authorId: agentId,
                     kind: "a2a.message",
                     scope: agentId,
                     summary,
-                    detail: JSON.stringify({ message }),
-                    targetIds: [agentId],
+                    detail: JSON.stringify({ message, toAgentId: toAgentId || null }),
+                    targetIds,
                 });
                 return rpcResult(id, {
                     type: "message",

package/dist/resources/OrgEvent.js

@@ -23,8 +23,18 @@ export class OrgEvent extends databases.flair.OrgEvent {
         const auth = await this._auth();
         if (auth.kind === "anonymous")
             return UNAUTH();
-        if (auth.kind === "agent" && !auth.isAdmin && content.authorId !== auth.agentId) {
-            return FORBIDDEN("forbidden: authorId must match authenticated agent");
+        // No-forge attribution: a non-admin agent's events are ALWAYS attributed to
+        // its authenticated identity (from the Ed25519 signature), never the body —
+        // an agent can only publish AS itself. We overwrite `authorId` rather than
+        // 403'ing a mismatch so a CLI client never has to echo its own id into the
+        // body (mirrors A2A message/send's "sender must match params.agentId" guard
+        // and Presence's "agentId from signature, NOT from body"). Admin agents may
+        // publish on behalf of another agent (body authorId honored, else their own).
+        if (auth.kind === "agent" && !auth.isAdmin) {
+            content.authorId = auth.agentId;
+        }
+        else if (auth.kind === "agent" && auth.isAdmin) {
+            content.authorId ||= auth.agentId;
         }
         if (!content.id)
             content.id = `${content.authorId}-${new Date().toISOString()}`;

package/dist/resources/Presence.js

@@ -18,6 +18,7 @@
  */
 import { databases } from "@harperfast/harper";
 import { resolveAgentAuth } from "./agent-auth.js";
+import { b64ToArrayBuffer } from "./b64.js";
 // ─── Constants ────────────────────────────────────────────────────────────────
 const WINDOW_MS = 30_000;
 const CURRENT_TASK_MAX_LENGTH = 200;
@@ -40,15 +41,8 @@ function pruneNonces() {
     }
 }
 // ─── Crypto helpers ───────────────────────────────────────────────────────────
-function b64ToArrayBuffer(b64) {
-    const std = b64.replace(/-/g, "+").replace(/_/g, "/");
-    const bin = atob(std);
-    const buf = new ArrayBuffer(bin.length);
-    const view = new Uint8Array(buf);
-    for (let i = 0; i < bin.length; i++)
-        view[i] = bin.charCodeAt(i);
-    return buf;
-}
+// b64ToArrayBuffer lives in ./b64.ts (shared with auth-middleware.ts + agent-auth.ts
+// so the base64/base64url decoder can't drift across the three auth call sites).
 const keyCache = new Map();
 async function importEd25519Key(publicKeyStr) {
     if (keyCache.has(publicKeyStr))

package/dist/resources/SemanticSearch.js

@@ -8,6 +8,11 @@ import { wrapUntrusted } from "./content-safety.js";
 // relevance floor) lives in ./scoring.ts — a Harper-free module so it can be
 // unit-tested directly (see test/unit/temporal-scoring.test.ts).
 import { compositeScore } from "./scoring.js";
+// BM25 + union-RRF hybrid retrieval (ops-i39b / FLAIR-BM25-HYBRID-RETRIEVAL).
+// Harper-free modules so the BM25 scoring, the candidate-union RRF, and the
+// SECURITY conditions-filter are unit-tested against the shipped code.
+import { buildBM25, fuseRrfNormalized, hybridEnabled, SEM_LIMIT } from "./bm25.js";
+import { isAllowedBm25Candidate } from "./bm25-filter.js";
 // Convert HNSW cosine distance (1 - similarity) to similarity score
 function distanceToSimilarity(distance) {
     return 1 - distance;
@@ -15,6 +20,9 @@ function distanceToSimilarity(distance) {
 // Candidate multiplier: fetch more candidates than needed from the HNSW index
 // so composite re-ranking has enough headroom to reorder results.
 const CANDIDATE_MULTIPLIER = 5;
+// The BM25 + union-RRF hybrid path is feature-flagged via hybridEnabled()
+// (imported from ./bm25 — Harper-free so it's unit-testable). Flag OFF (default)
+// → byte-identical to the pre-hybrid HNSW + +0.05 keyword-bump behavior.
 export class SemanticSearch extends Resource {
     // Self-authorize via the Ed25519 agent verify instead of relying on the auth
     // gate's admin super_user elevation (removed in the auth reshape). Any
@@ -161,8 +169,122 @@ export class SemanticSearch extends Resource {
             }
         }
         const results = [];
-        // ─── HNSW vector search path ───────────────────────────────────────────
-        if (qEmb) {
+        const hybrid = hybridEnabled();
+        if (hybrid) {
+            // ─── BM25 + union-RRF hybrid path (ops-i39b) ─────────────────────────
+            // 1. Semantic candidates via HNSW (unchanged fetch). 2. BM25 lexical pass
+            //    over the SCOPED corpus. 3. SECURITY: the BM25 candidate set is filtered
+            //    by the SAME conditions[] + temporal filters BEFORE fusion (the corpus
+            //    is fetched with those conditions, AND re-checked in-process as
+            //    defense-in-depth) so no other agent's memory is ever scored or fused.
+            //    4. Candidate-union RRF → normalize → feed as rawScore to compositeScore.
+            const ctx = this.getContext?.();
+            // ── (a) Semantic candidate records (best-first) ──────────────────────
+            // Same HNSW query as the legacy path; we keep the raw records so the BM25
+            // pass + fusion can re-derive rawScore. No embedding → empty semantic list
+            // (RRF degrades naturally to BM25-only).
+            const semRecords = [];
+            const semIds = [];
+            if (qEmb) {
+                const candidateLimit = limit * CANDIDATE_MULTIPLIER;
+                const semQuery = {
+                    sort: { attribute: "embedding", target: qEmb, distance: "cosine" },
+                    select: ["id", "agentId", "content", "contentHash", "visibility", "tags", "durability",
+                        "source", "createdAt", "updatedAt", "expiresAt", "retrievalCount", "lastRetrieved",
+                        "promotionStatus", "promotedAt", "promotedBy", "archived", "archivedAt", "archivedBy",
+                        "parentId", "derivedFrom", "sessionId", "lastReflected", "supersedes", "subject",
+                        "validFrom", "validTo", "_safetyFlags", "$distance"],
+                    limit: candidateLimit,
+                };
+                if (conditions.length > 0)
+                    semQuery.conditions = conditions;
+                const semResults = withDetachedTxn(ctx, () => databases.flair.Memory.search(semQuery));
+                for await (const record of semResults) {
+                    // Same per-record temporal gate as the legacy HNSW loop.
+                    if (record.expiresAt && Date.parse(record.expiresAt) < Date.now())
+                        continue;
+                    if (sinceDate && record.createdAt && new Date(record.createdAt) < sinceDate)
+                        continue;
+                    if (asOf && record.validFrom && record.validFrom > asOf)
+                        continue;
+                    if (asOf && record.validTo && record.validTo <= asOf)
+                        continue;
+                    semRecords.push(record);
+                    semIds.push(record.id);
+                }
+            }
+            // ── (b) BM25 candidate records over the SCOPED corpus ────────────────
+            // SECURITY: fetch the corpus WITH the same conditions[] so Harper applies
+            // the agent boundary, then re-apply the identical predicate + temporal
+            // filters in-process (isAllowedBm25Candidate) BEFORE building/scoring the
+            // index. The BM25 index therefore only ever contains the caller's allowed
+            // memories — no other agent's content/term-frequency enters scoring or
+            // fusion. This is the conditions-filter-before-fusion gate.
+            // Explicit select (same fields as the HNSW path, no embedding / $distance)
+            // so the large embedding vector is never fetched into the BM25 corpus and
+            // never spread into a result payload.
+            const corpusSelect = ["id", "agentId", "content", "contentHash", "visibility", "tags", "durability",
+                "source", "createdAt", "updatedAt", "expiresAt", "retrievalCount", "lastRetrieved",
+                "promotionStatus", "promotedAt", "promotedBy", "archived", "archivedAt", "archivedBy",
+                "parentId", "derivedFrom", "sessionId", "lastReflected", "supersedes", "subject",
+                "validFrom", "validTo", "_safetyFlags"];
+            const corpusQuery = conditions.length > 0
+                ? { conditions, select: corpusSelect }
+                : { select: corpusSelect };
+            const corpusResults = withDetachedTxn(ctx, () => databases.flair.Memory.search(corpusQuery));
+            const allowedById = new Map();
+            const bm25Docs = [];
+            for await (const record of corpusResults) {
+                // Defense-in-depth: re-check the SAME conditions[] + temporal filters
+                // in-process. Even if a Harper query change ever let an out-of-scope
+                // record through, it is dropped here BEFORE it can be BM25-scored/fused.
+                if (!isAllowedBm25Candidate(record, conditions, { sinceDate, asOf }))
+                    continue;
+                allowedById.set(record.id, record);
+                bm25Docs.push({ id: record.id, content: record.content });
+            }
+            // Carry semantic candidates that survived their temporal gate into the
+            // allowed map too (so a fused id always resolves to a record). Semantic
+            // records were fetched with the SAME conditions[], so they're in-scope.
+            for (const r of semRecords) {
+                if (!allowedById.has(r.id)) {
+                    const { $distance, ...rest } = r;
+                    allowedById.set(r.id, rest);
+                }
+            }
+            // ── (c) BM25 lexical ranking → top SEM_LIMIT (only when q present) ────
+            let bm25Ids = [];
+            if (q) {
+                const bm25 = buildBM25(bm25Docs);
+                const ranked = bm25.rank(String(q));
+                // Drop zero-score docs (no query-term overlap → contribute nothing) and
+                // cap at SEM_LIMIT — the production BM25 candidate window.
+                bm25Ids = ranked.filter(r => r.score > 0).slice(0, SEM_LIMIT).map(r => r.id);
+            }
+            // ── (d) Candidate-union RRF → normalized [0,1] rawScore ──────────────
+            // Union dedupes semantic ∪ bm25 ids; absent-from-a-list = 0 contribution.
+            const fused = fuseRrfNormalized(semIds, bm25Ids);
+            for (const [id, rrfRaw] of fused) {
+                const record = allowedById.get(id);
+                if (!record)
+                    continue; // should not happen — union ⊆ allowed
+                const rawScore = rrfRaw; // already normalized to [0,1]
+                let finalScore = scoring === "raw" ? rawScore : compositeScore(rawScore, record);
+                if (temporalBoost > 1.0)
+                    finalScore *= temporalBoost;
+                const isFlagged = record._safetyFlags && Array.isArray(record._safetyFlags) && record._safetyFlags.length > 0;
+                const source = record.agentId !== agentId ? record.agentId : undefined;
+                results.push({
+                    ...record,
+                    content: isFlagged ? wrapUntrusted(record.content, source) : record.content,
+                    _score: Math.round(finalScore * 1000) / 1000,
+                    _rawScore: scoring !== "raw" ? Math.round(rawScore * 1000) / 1000 : undefined,
+                    _source: source,
+                });
+            }
+        }
+        else if (qEmb) {
+            // ─── HNSW vector search path ───────────────────────────────────────────
             const candidateLimit = limit * CANDIDATE_MULTIPLIER;
             const query = {
                 sort: { attribute: "embedding", target: qEmb, distance: "cosine" },

package/dist/resources/WorkspaceState.js

@@ -50,8 +50,18 @@ export class WorkspaceState extends databases.flair.WorkspaceState {
         // there was no authenticated agent, so anonymous could write any record).
         if (auth.kind === "anonymous")
             return UNAUTH();
-        if (auth.kind === "agent" && !auth.isAdmin && content.agentId !== auth.agentId) {
-            return FORBIDDEN("forbidden: cannot write workspace state for another agent");
+        // No-forge: a non-admin agent's workspace record is ALWAYS attributed to the
+        // authenticated identity (from the Ed25519 signature), never the body. We do
+        // NOT trust `content.agentId` — overwriting it (rather than 403'ing a
+        // mismatch) mirrors Presence.post(): "agentId from signature, NOT from body".
+        // An admin may write on behalf of another agent (content.agentId honored if
+        // present, else defaults to the admin's own id). Internal in-process callers
+        // keep whatever agentId they pass.
+        if (auth.kind === "agent" && !auth.isAdmin) {
+            content.agentId = auth.agentId;
+        }
+        else if (auth.kind === "agent" && auth.isAdmin) {
+            content.agentId ||= auth.agentId;
         }
         content.createdAt = new Date().toISOString();
         content.timestamp ||= content.createdAt;