@tpsdev-ai/flair 0.11.0 → 0.13.0

package/dist/resources/auth-middleware.js

@@ -1,6 +1,7 @@
 import { patchRecord } from "./table-helpers.js";
 import { server, databases } from "@harperfast/harper";
 import { getEmbedding } from "./embeddings-provider.js";
+import { isAdmin, FLAIR_AGENT_USERNAME } from "./agent-auth.js";
 // --- Admin credentials ---
 // Admin auth is sourced exclusively from Harper's own environment variables
 // (HDB_ADMIN_PASSWORD / FLAIR_ADMIN_PASSWORD). No filesystem token file.
@@ -31,34 +32,10 @@ function getAdminPass() {
 const WINDOW_MS = 30_000;
 const nonceSeen = new Map();
 // ─── Admin resolution ─────────────────────────────────────────────────────────
-// Admin agents: from FLAIR_ADMIN_AGENTS env var (comma-separated) OR
-// Agent records with role === "admin". Both sources are OR-combined.
-// Result is cached for 60s to avoid per-request DB hits.
-let adminCacheExpiry = 0;
-let adminCache = new Set();
-async function getAdminAgents() {
-    const now = Date.now();
-    if (now < adminCacheExpiry)
-        return adminCache;
-    const from_env = (process.env.FLAIR_ADMIN_AGENTS ?? "")
-        .split(",").map((s) => s.trim()).filter(Boolean);
-    let from_db = [];
-    try {
-        const results = await databases.flair.Agent.search([{ attribute: "role", value: "admin", condition: "equals" }]);
-        for await (const row of results) {
-            if (row?.id)
-                from_db.push(row.id);
-        }
-    }
-    catch { /* Agent table might not be populated yet */ }
-    adminCache = new Set([...from_env, ...from_db]);
-    adminCacheExpiry = now + 60_000;
-    return adminCache;
-}
-export async function isAdmin(agentId) {
-    const admins = await getAdminAgents();
-    return admins.has(agentId);
-}
+// `isAdmin` (FLAIR_ADMIN_AGENTS env + Agent role==="admin", 60s-cached) now lives
+// in agent-auth.ts as the single source of truth, imported above. During the
+// auth reshape this gate and the per-resource allow* helpers must agree on who's
+// an admin — one implementation guarantees they can't diverge.
 // ─── Crypto helpers ───────────────────────────────────────────────────────────
 function b64ToArrayBuffer(b64) {
     // Handle both standard and URL-safe base64
@@ -149,9 +126,20 @@ server.http(async (request, nextLayer) => {
         // (allowCreate=true on the Resource).
         url.pathname === "/Presence")
         return nextLayer(request);
-    // If Harper has already authorized this request (e.g. authorizeLocal=true on localhost),
-    // trust Harper's auth decision and pass through without requiring additional headers.
+    // 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) {
+        request.tpsAgent = request.user.username ?? "admin";
+        request.tpsAgentIsAdmin = true;
+        try {
+            request.headers.set("x-tps-agent", request.tpsAgent);
+            if (request.headers.asObject)
+                request.headers.asObject["x-tps-agent"] = request.tpsAgent;
+        }
+        catch { /* frozen headers — annotation on request object still applies */ }
         return nextLayer(request);
     }
     // Skip re-entry: if we already swapped auth to Basic, pass through
@@ -224,8 +212,19 @@ server.http(async (request, nextLayer) => {
                 }
             }
         }
-        catch { /* fall through to Ed25519 check */ }
-        return new Response(JSON.stringify({ error: "invalid_admin_credentials" }), { status: 401 });
+        catch { /* fall through to anonymous */ }
+        // NON-REJECTING (auth-rbac flip): a Basic header that matched no admin/super_user/
+        // pair path → annotate anonymous + pass through (don't 401 — a sibling component's
+        // Basic auth on a shared Harper must not be rejected by flair's gate). Resource
+        // allow* denies if the path is flair-protected.
+        request.tpsAnonymous = true;
+        try {
+            request.headers.set("x-tps-anonymous", "1");
+            if (request.headers.asObject)
+                request.headers.asObject["x-tps-anonymous"] = "1";
+        }
+        catch { /* frozen headers */ }
+        return nextLayer(request);
     }
     // ── Ed25519 agent auth ────────────────────────────────────────────────────
     const m = header.match(/^TPS-Ed25519\s+([^:]+):(\d+):([^:]+):(.+)$/);
@@ -244,7 +243,19 @@ server.http(async (request, nextLayer) => {
                 },
             });
         }
-        return new Response(JSON.stringify({ error: "missing_or_invalid_authorization" }), { status: 401 });
+        // NON-REJECTING GATE (auth-rbac flip): no valid agent → annotate anonymous and
+        // pass through. Per-resource allow* (resolveAgentAuth → anonymous → deny) is the
+        // enforcement; the gate no longer 401s instance-wide, which was breaking sibling
+        // components on a shared Harper / composite hub. Anonymous reaches only public
+        // allow-listed paths + resources whose allow* permit it.
+        request.tpsAnonymous = true;
+        try {
+            request.headers.set("x-tps-anonymous", "1");
+            if (request.headers.asObject)
+                request.headers.asObject["x-tps-anonymous"] = "1";
+        }
+        catch { /* frozen headers — annotation on the request object still applies */ }
+        return nextLayer(request);
     }
     const [, agentId, tsRaw, nonce, signatureB64] = m;
     const ts = Number(tsRaw);
@@ -277,33 +288,50 @@ server.http(async (request, nextLayer) => {
     request._tpsAuthVerified = true;
     request.tpsAgentIsAdmin = await isAdmin(agentId);
     // Grant Harper-level permissions for the cryptographically-verified agent by
-    // setting request.user directly to the admin super_user.
+    // setting request.user directly. Setting request.user is the supported
+    // extension path (and the only one that works post-5.0.9: Harper resolves
+    // request.user from the Authorization header BEFORE this middleware runs, and
+    // a TPS-Ed25519 header matches no Basic/Bearer strategy, so request.user
+    // arrives null — see #456). getUser(name, null) looks up the record WITHOUT
+    // password validation, safe here because the Ed25519 signature already proved
+    // identity cryptographically.
     //
-    // Prior approach swapped the Authorization header to "Basic admin:<pass>" so
-    // Harper's auth pipeline would re-authenticate with full (HNSW-capable)
-    // permissions. That silently broke under Harper 5.0.9: its authentication
-    // layer (security/auth.ts `authentication()`) reads the Authorization header
-    // and resolves request.user BEFORE invoking this middleware via nextHandler.
-    // A TPS-Ed25519 header matches no Basic/Bearer strategy, so Harper sets
-    // request.user = null and never re-reads the header — our post-hoc swap was
-    // ignored, the request ran unauthenticated, and Harper surfaced it downstream
-    // as a generic "Login failed" 401. (Broke at the 2026-05-27 daemon restart,
-    // which loaded 5.0.9 fresh; the prior long-running process held an older
-    // in-memory Harper where the late header read still worked.)
+    // RESHAPE (auth-rbac) — THE FLIP: per-agent DE-ELEVATION. A cryptographically-
+    // verified NON-admin agent resolves to the least-privilege `flair-agent` user,
+    // NOT admin super_user. The flair_agent role grants exactly the table CRUD agents
+    // need; with no operations grant, /sql + /graphql are natively 403 (the hand-
+    // rolled raw-query block below becomes belt-and-suspenders). Admins still resolve
+    // to admin. getUser(name, null) looks up WITHOUT password validation — safe
+    // because the Ed25519 signature already proved identity. Row-level ownership stays
+    // enforced via x-tps-agent / resolveAgentAuth, independent of request.user.
     //
-    // Setting request.user directly is the supported extension path and is honored
-    // by all downstream resources, including HNSW vector search. getUser(admin,
-    // null) looks up the admin record WITHOUT password validation — safe here
-    // because the Ed25519 signature verified above already proves agent identity
-    // cryptographically; no Basic credential is presented. This preserves the
-    // prior privilege model (verified agents act with admin perms; per-agent data
-    // isolation is still enforced downstream via the x-tps-agent header below).
+    // GRACEFUL FALLBACK: if the flair-agent user isn't provisioned on this instance
+    // yet (pre-migration — ensureFlairAgentUser hasn't run), fall back to admin so
+    // agents keep working. De-elevation activates per-instance once the user exists.
     try {
-        request.user = await server.getUser("admin", null, request);
+        if (request.tpsAgentIsAdmin) {
+            request.user = await server.getUser("admin", null, request);
+        }
+        else {
+            let deElevated = null;
+            try {
+                deElevated = await server.getUser(FLAIR_AGENT_USERNAME, null, request);
+            }
+            catch { /* not provisioned */ }
+            // getUser(name, null) returns a ROLE-LESS phantom `{ username }` (not null,
+            // not a throw) for a nonexistent user — harper security/user.js
+            // findAndValidateUser: `if (!userTmp) { if (!validatePassword) return { username } }`.
+            // A phantom is truthy, so `deElevated ?? admin` would keep it and the request
+            // would carry NO role → 403 AccessViolation. Require a real role to use the
+            // de-elevated user; otherwise fall back to admin (pre-migration instances).
+            request.user = (deElevated && deElevated.role)
+                ? deElevated
+                : await server.getUser("admin", null, request);
+        }
     }
     catch {
-        // Admin record unavailable — request proceeds as the verified tpsAgent
-        // without elevated perms; resource-level scoping still applies.
+        // No usable user record — request proceeds as the verified tpsAgent without
+        // elevated perms; resource-level scoping (x-tps-agent) still applies.
     }
     // Propagate authenticated agent to downstream resources via header.
     // Resources can read this to enforce agent-level scoping.

package/dist/resources/memory-consolidate-lib.js

@@ -0,0 +1,72 @@
+// ─── Memory Consolidation — pure evaluation logic ───────────────────────────
+// Pure helpers extracted from MemoryConsolidate.ts (Flair #502) so they can be
+// unit-tested directly. Importing MemoryConsolidate.ts pulls in the Harper
+// runtime (`databases` / `Resource`, storage init) and can't run outside a live
+// Harper; this module has no Harper dependency, so
+// test/unit/memory-consolidate.test.ts exercises the real shipped code.
+export function parseDuration(s) {
+    const m = s.match(/^(\d+)([dhm])$/);
+    if (!m)
+        return 30 * 86400_000;
+    const n = Number(m[1]);
+    if (m[2] === "d")
+        return n * 86400_000;
+    if (m[2] === "h")
+        return n * 3600_000;
+    if (m[2] === "m")
+        return n * 60_000;
+    return 30 * 86400_000;
+}
+/**
+ * Classify a single memory record as a promote/archive/keep candidate.
+ *
+ * Idle age is `now - (lastRetrieved ?? createdAt)`: a memory that was just
+ * written and never read has lastRetrieved=null, so without the createdAt
+ * fallback its idle age would be Infinity and a minutes-old memory would read
+ * as maximally stale and be archived (Flair #502). The createdAt fallback
+ * measures "never retrieved" from when the memory was born.
+ *
+ * A grace window (olderThanMs — the maintenance olderThan) guarantees a
+ * freshly-created memory is never an archive candidate regardless of retrieval
+ * count: archival only considers memories that have had a fair chance to be read.
+ */
+export function evaluate(record, now, olderThanMs) {
+    const ageMs = record.createdAt ? now - new Date(record.createdAt).getTime() : 0;
+    const count = record.retrievalCount ?? 0;
+    const lastUse = record.lastRetrieved ?? record.createdAt;
+    const idleMs = lastUse ? now - new Date(lastUse).getTime() : 0;
+    const daysIdle = idleMs / 86400_000;
+    const everRetrieved = record.lastRetrieved != null;
+    const { embedding, ...memory } = record;
+    // Promote: high retrieval + persistent durability
+    if (record.durability === "persistent" && count >= 5) {
+        return { memory, suggestion: "promote", reason: `Retrieved ${count} times — strong promotion candidate for permanent` };
+    }
+    // Promote: standard → persistent if retrieved frequently
+    if (record.durability === "standard" && count >= 3 && ageMs > 7 * 86400_000) {
+        return { memory, suggestion: "promote", reason: `Retrieved ${count} times over ${Math.round(ageMs / 86400_000)} days — worth persisting` };
+    }
+    // Grace window: a freshly-created memory is never an archive candidate,
+    // regardless of retrieval count (Flair #502). Archive branches below are
+    // reachable only for memories older than the maintenance window.
+    if (ageMs <= olderThanMs) {
+        return { memory, suggestion: "keep", reason: everRetrieved
+                ? `Retrieved ${count} times, ${Math.round(daysIdle)} days since last retrieval`
+                : `Created ${Math.round(ageMs / 86400_000)} days ago, not yet retrieved (within grace window)` };
+    }
+    // Archive: old + never retrieved
+    if (daysIdle > 30 && count === 0) {
+        return { memory, suggestion: "archive", reason: everRetrieved
+                ? `Not retrieved in ${Math.round(daysIdle)} days, ${Math.round(ageMs / 86400_000)} days old`
+                : `Never retrieved, ${Math.round(ageMs / 86400_000)} days old` };
+    }
+    // Archive: idle > 60 days with few retrievals
+    if (daysIdle > 60 && count < 2) {
+        return { memory, suggestion: "archive", reason: everRetrieved
+                ? `Not retrieved in ${Math.round(daysIdle)} days (only ${count} total retrievals)`
+                : `Never retrieved, ${Math.round(ageMs / 86400_000)} days old (0 total retrievals)` };
+    }
+    return { memory, suggestion: "keep", reason: everRetrieved
+            ? `Retrieved ${count} times, ${Math.round(daysIdle)} days since last retrieval`
+            : `Created ${Math.round(ageMs / 86400_000)} days ago, not yet retrieved` };
+}

package/dist/resources/scoring.js

@@ -0,0 +1,52 @@
+// ─── Temporal Decay + Relevance Scoring ─────────────────────────────────────
+// Pure scoring functions extracted from SemanticSearch.ts (OPS-AYGD) so they can
+// be unit-tested directly. Importing SemanticSearch.ts pulls in the Harper runtime
+// (storage init) and can't run outside a live Harper; this module has no Harper
+// dependency, so test/unit/temporal-scoring.test.ts exercises the real shipped code.
+export const DURABILITY_WEIGHTS = {
+    permanent: 1.0,
+    persistent: 0.9,
+    standard: 0.7,
+    ephemeral: 0.4,
+};
+// Half-life in days for exponential decay per durability level
+export const DECAY_HALF_LIFE_DAYS = {
+    permanent: Infinity, // never decays
+    persistent: 90,
+    standard: 30,
+    ephemeral: 7,
+};
+export function recencyFactor(createdAt, durability) {
+    const halfLife = DECAY_HALF_LIFE_DAYS[durability] ?? 30;
+    if (halfLife === Infinity)
+        return 1.0;
+    const ageDays = (Date.now() - Date.parse(createdAt)) / (1000 * 60 * 60 * 24);
+    const lambda = Math.LN2 / halfLife;
+    return Math.exp(-lambda * ageDays);
+}
+// OPS-AYGD: the retrieval boost was unbounded and OVERRODE semantic ranking —
+// recall-eval 2026-06-19 showed composite p@3 0.83 vs raw 1.00, with a popular doc
+// magnetised into 5/6 queries (its rBoost lifted a 0.55-0.65 semantic score above
+// the correct docs). Bounded to a gentle nudge that breaks near-ties without
+// overriding a clear semantic winner. Tuned offline against the real corpus
+// (floor 0.5 + cap 1.1 → composite p@3 recovers to 1.00, magnet eliminated).
+// A query-relative tie-breaker gate (boost only within ~0.05 of the top raw score)
+// is the principled follow-up for graduated boosting; it needs the search loop to
+// pass the candidate-set top score, so it's deferred to its own change.
+export const RBOOST_CAP = 1.1; // max +10% — a tie-breaker, not an override
+export const RBOOST_RELEVANCE_FLOOR = 0.5; // no boost at all for clearly-irrelevant docs
+export function retrievalBoost(retrievalCount) {
+    if (!retrievalCount || retrievalCount <= 0)
+        return 1.0;
+    return Math.min(1.0 + 0.1 * Math.log2(retrievalCount), RBOOST_CAP); // gentle, capped
+}
+export function compositeScore(semanticScore, record) {
+    const durability = record.durability ?? "standard";
+    const dWeight = DURABILITY_WEIGHTS[durability] ?? 0.7;
+    const rFactor = record.createdAt ? recencyFactor(record.createdAt, durability) : 1.0;
+    // OPS-AYGD: only apply the retrieval boost when the record is genuinely relevant to
+    // this query (semanticScore clears the floor). Below the floor, a popular doc gets
+    // no lift — kills the cross-query magnet while preserving boosts for relevant docs.
+    const rBoost = semanticScore >= RBOOST_RELEVANCE_FLOOR ? retrievalBoost(record.retrievalCount ?? 0) : 1.0;
+    return semanticScore * dWeight * rFactor * rBoost;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",
   "license": "Apache-2.0",