@tpsdev-ai/flair 0.30.0 → 0.31.1

package/dist/resources/Agent.js

@@ -1,5 +1,6 @@
 import { databases } from "harper";
-import { resolveAgentAuth, allowVerified, allowAdmin } from "./agent-auth.js";
+import { resolveAgentAuth, allowVerified, allowAdmin, invalidateAdminCache } from "./agent-auth.js";
+import { agentRecordIsAdmin, reconcileAdminFields } from "./agent-admin.js";
 import { localInstanceId } from "./instance-identity.js";
 /**
  * Agent resource — serves as the Principal table in 1.0.
@@ -34,10 +35,18 @@ export class Agent extends databases.flair.Agent {
         content.kind ||= "agent";
         content.status ||= "active";
         content.displayName ||= content.name;
-        content.admin ??= false;
-        // Trust tier defaults per kind
+        // flair#941 — the two admin fields are reconciled BEFORE anything derives
+        // from them, so `role` and `admin` agree on disk whichever one the caller
+        // used. Replaces `content.admin ??= false`, which defaulted the mirror
+        // without ever consulting the authority: a caller who passed role:"admin"
+        // got a record that was an admin at the gate and a non-admin to every
+        // reporter. allowCreate() is allowAdmin(), so this path is admin-only.
+        reconcileAdminFields(content);
+        // Trust tier defaults per kind — derived from the SAME predicate the gate
+        // uses, so an admin principal cannot land on the non-admin default just
+        // because the caller spelled admin the other way.
         if (!content.defaultTrustTier) {
-            content.defaultTrustTier = content.admin ? "endorsed" : "unverified";
+            content.defaultTrustTier = agentRecordIsAdmin(content) ? "endorsed" : "unverified";
         }
         content.createdAt = now;
         content.updatedAt = now;
@@ -51,7 +60,25 @@ export class Agent extends databases.flair.Agent {
         }
         return super.post(content, context);
     }
-    async put(content) {
+    /**
+     * Authorization shared by BOTH mutation paths (PUT → put, PATCH → patch).
+     *
+     * It lives in one place because it previously lived only in put(), and PATCH
+     * does not route through put() — so every rule written here was enforced on
+     * one verb and not the other. Returns a Response to send, or null to proceed.
+     *
+     * Two rules:
+     *   1. Only an admin principal may modify a principal OTHER than itself.
+     *   2. Only an admin principal may change a principal's ADMIN STATUS — on any
+     *      record, including the caller's own. Rule 1 alone never covered this:
+     *      an agent editing its own record is inside its rights for ordinary
+     *      fields (runtime, displayName, subjects) and must not be for the fields
+     *      that decide whether it is an administrator.
+     *
+     * `internal` (in-process maintenance, federation merge) and admin agents pass
+     * through unchanged.
+     */
+    async authorizePrincipalWrite(content) {
         const auth = await resolveAgentAuth(this.getContext?.());
         // Anonymous denied (defense-in-depth alongside allowUpdate; the old check read
         // tpsAgent and treated a missing agent as trusted, so anonymous slipped through).
@@ -60,24 +87,91 @@ export class Agent extends databases.flair.Agent {
                 status: 401, headers: { "content-type": "application/json" },
             });
         }
-        // Only admin principals can modify OTHER principals; an agent updates its own.
-        if (auth.kind === "agent" && !auth.isAdmin) {
-            const existing = await super.get();
-            if (existing && existing.id !== auth.agentId) {
-                return new Response(JSON.stringify({ error: "only admin principals can modify other principals" }), {
+        if (auth.kind !== "agent" || auth.isAdmin)
+            return null;
+        const existing = await Promise.resolve(super.get()).catch(() => null);
+        // 1. Only admin principals can modify OTHER principals.
+        if (existing && existing.id !== auth.agentId) {
+            return new Response(JSON.stringify({ error: "only admin principals can modify other principals" }), {
+                status: 403, headers: { "content-type": "application/json" },
+            });
+        }
+        // 2. Only admin principals can change admin status. Compare the RESULTING
+        // status against the stored one so an ordinary self-update that simply
+        // doesn't mention either field is unaffected, and a no-op restatement of
+        // the caller's existing status is not a spurious denial.
+        const touchesPrivilegeFields = content != null && typeof content === "object" && ("role" in content || "admin" in content);
+        if (touchesPrivilegeFields) {
+            const merged = { ...(existing ?? {}), ...content };
+            const wouldBeAdmin = agentRecordIsAdmin(merged) || merged.admin === true;
+            const isAdminNow = agentRecordIsAdmin(existing) || (existing?.admin === true);
+            if (wouldBeAdmin !== isAdminNow) {
+                return new Response(JSON.stringify({ error: "only admin principals can change a principal's admin status" }), {
                     status: 403, headers: { "content-type": "application/json" },
                 });
             }
         }
+        return null;
+    }
+    async put(content) {
+        const denial = await this.authorizePrincipalWrite(content);
+        if (denial)
+            return denial;
         content.updatedAt = new Date().toISOString();
         // Protect immutable fields
         delete content.createdAt;
         delete content.publicKey; // key rotation goes through dedicated endpoint
+        // Keep the two admin fields agreeing on disk — see resources/agent-admin.ts.
+        // Only an admin can have reached here with a privilege change (see
+        // authorizePrincipalWrite), so this normalises an authorized intent; it
+        // never manufactures one.
+        reconcileAdminFields(content);
         // Write-time originatorInstanceId stamp — see post() above / Memory.ts's
         // stampOriginatorInstanceId doc. No-op if already set.
         if (content.originatorInstanceId == null) {
             content.originatorInstanceId = await localInstanceId();
         }
-        return super.put(content);
+        const result = await super.put(content);
+        invalidateAdminCache();
+        return result;
+    }
+    /**
+     * PATCH → Harper's partial update (`Resource.patch(data, query)`; see
+     * harper/dist/server/REST.js's method switch and Resource.js's static patch).
+     *
+     * This override exists because there was none. Every per-record authorization
+     * rule this resource enforces was written in put(), and PATCH does not route
+     * through put() — so none of those rules ran on a PATCH. allowUpdate() is
+     * allowVerified(), which means the only check a PATCH ever met was "are you
+     * some verified agent"; the rules that make the principal table safe (you may
+     * only edit yourself; you may not change your own admin status) were not
+     * among them.
+     *
+     * That is the shape flair#941 keeps running into: a check that reads as
+     * complete because it exists, and simply is not on the path the caller took.
+     * Both verbs now share authorizePrincipalWrite().
+     */
+    async patch(content, query) {
+        const denial = await this.authorizePrincipalWrite(content);
+        if (denial)
+            return denial;
+        if (content != null && typeof content === "object") {
+            // A partial update must not be able to leave the record's two admin
+            // fields disagreeing, so reconcile against the MERGED result rather than
+            // the patch alone — patching only `role` has to carry the mirror with it.
+            if ("role" in content || "admin" in content) {
+                const existing = await Promise.resolve(super.get()).catch(() => null);
+                const merged = reconcileAdminFields({ ...(existing ?? {}), ...content });
+                content.role = merged.role;
+                content.admin = merged.admin;
+            }
+            // Immutable fields, matching put().
+            delete content.createdAt;
+            delete content.publicKey;
+            content.updatedAt = new Date().toISOString();
+        }
+        const result = await super.patch(content, query);
+        invalidateAdminCache();
+        return result;
     }
 }

package/dist/resources/AgentSeed.js

@@ -17,7 +17,8 @@
  * Auth: admin only.
  */
 import { Resource, databases } from "harper";
-import { isAdmin, allowAdmin } from "./agent-auth.js";
+import { isAdmin, allowAdmin, invalidateAdminCache } from "./agent-auth.js";
+import { reconcileAdminFields } from "./agent-admin.js";
 const DEFAULT_SOUL_KEYS = (agentId, displayName, role, now) => ({
     name: displayName,
     role,
@@ -62,8 +63,15 @@ export class AgentSeed extends Resource {
         const existingAgent = await databases.flair.Agent.get(agentId).catch(() => null);
         let agent = existingAgent;
         if (!existingAgent) {
-            agent = { id: agentId, name, role, publicKey: "pending", createdAt: now, updatedAt: now };
+            // flair#941 — this writes the RAW table, so resources/Agent.ts's post()
+            // never runs and its field reconciliation does not apply here. Seeding
+            // role:"admin" without the mirror was the one path in the product that
+            // produced a genuine administrator every reporter displayed as an
+            // ordinary agent. Admin-only path (allowCreate + the isAdmin re-check
+            // above), so this normalises an authorized intent.
+            agent = reconcileAdminFields({ id: agentId, name, role, publicKey: "pending", createdAt: now, updatedAt: now });
             await databases.flair.Agent.put(agent);
+            invalidateAdminCache();
         }
         // ── Soul entries ──────────────────────────────────────────────────────────
         const defaults = DEFAULT_SOUL_KEYS(agentId, name, role, now);

package/dist/resources/MemoryBootstrap.js

@@ -11,7 +11,7 @@ import { buildCollisionEntries, buildEntityMatchCondition, freshPresenceByAgent,
 // The bounded HNSW candidate-pool retrieval for the task-relevant/teammate/
 // collision surfaces (flair-bootstrap-scale-fix) — the SAME pure core
 // SemanticSearch.ts's post() wraps, called bare here so an internal
-// bootstrap call never trips SemanticSearch's rate-limit/reranker/
+// bootstrap call never trips SemanticSearch's rate-limit or
 // retrievalCount hit-tracking side effects (see resources/
 // semantic-retrieval-core.ts's module doc for the full boundary).
 import { retrieveCandidates, DEFAULT_SELECT } from "./semantic-retrieval-core.js";
@@ -619,12 +619,11 @@ export class BootstrapMemories extends Resource {
                     queryEmbedding,
                     conditions: [scope.condition],
                     limit: candidatePoolK,
-                    // HNSW-leg pushdown ONLY (K&S verdict): no BM25 fusion, no
-                    // reranker for bootstrap — a different cost profile (BM25 over the
-                    // org corpus for a one-shot session-load could be MORE expensive
-                    // than HNSW-only unless cached across sessions; the reranker is a
-                    // generative call per candidate). Both are explicit opt-in
-                    // follow-ons, gated on their own harness runs.
+                    // HNSW-leg pushdown ONLY (K&S verdict): no BM25 fusion for
+                    // bootstrap — a different cost profile, since BM25 over the org
+                    // corpus for a one-shot session-load could be MORE expensive than
+                    // HNSW-only unless cached across sessions. Turning it on is an
+                    // explicit opt-in follow-on, gated on its own harness run.
                     hybrid: false,
                     // Per-set (this K-bounded pool only, never cross-applied to the
                     // permanent/recent/predicted sets above) — see this function's
@@ -679,7 +678,7 @@ export class BootstrapMemories extends Resource {
                 // `candidates` are already `_score`-sorted best-first, so filtering
                 // preserves that order). `retrieveCandidates()`'s cosine similarity
                 // replaces the raw JS dot product as the ranking signal (HNSW-only,
-                // no BM25/rerank) — the K&S-ratified, closest-to-a-wash choice; the
+                // no BM25) — the K&S-ratified, closest-to-a-wash choice; the
                 // recall harness gates any regression from this ranking-signal
                 // change (magnitude-sensitive dot product → normalized cosine).
                 const scored = candidates

package/dist/resources/MemoryUsage.js

@@ -95,6 +95,24 @@ export class MemoryUsage extends databases.flair.MemoryUsage {
             return super.put(content);
         return FORBIDDEN("forbidden: MemoryUsage rows are immutable once written");
     }
+    /**
+     * PATCH — same rule as put(), because this ledger's invariant is IMMUTABILITY,
+     * not ownership.
+     *
+     * The shared record-ownership guard (resources/record-owner-guard.ts) covers
+     * this table for cross-agent writes, but it cannot express this rule: it
+     * permits an agent to modify a row it owns, and here even the OWNER must not.
+     * Measured before this override existed: the owning agent rewrote its own
+     * row's attribution with a PATCH and got 204, because Harper routes PATCH to
+     * patch() and put()'s check never ran. A resource whose rule is stricter than
+     * "you own it" still has to say so on every verb.
+     */
+    async patch(content, query) {
+        const auth = await resolveAgentAuth(this.getContext?.());
+        if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin))
+            return super.patch(content, query);
+        return FORBIDDEN("forbidden: MemoryUsage rows are immutable once written");
+    }
     async delete(id) {
         const auth = await resolveAgentAuth(this.getContext?.());
         if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin))

package/dist/resources/Presence.js

@@ -32,6 +32,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import { resolveAgentAuth, verifyAgentRequest } from "./agent-auth.js";
+import { agentRecordIsAdmin } from "./agent-admin.js";
 import { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer, parseTpsEd25519Header } from "./ed25519-auth.js";
 // ─── Constants ────────────────────────────────────────────────────────────────
 const CURRENT_TASK_MAX_LENGTH = 200;
@@ -348,7 +349,13 @@ export class Presence extends databases.flair.Presence {
                 const entry = {
                     id: agentId,
                     displayName: agent?.displayName ?? agent?.name ?? agentId,
-                    role: agent?.role ?? "agent",
+                    // `role` is a human label on a PUBLIC roster (allowRead() is `true`),
+                    // and it is also the field that decides administrator status
+                    // (resources/agent-admin.ts). Publishing the admin sentinel would
+                    // hand an unauthenticated reader the list of privileged principals —
+                    // so the roster reports admins as ordinary agents. It is a display
+                    // label here and nothing authorizes on it (flair#941).
+                    role: agentRecordIsAdmin(agent) ? "agent" : (agent?.role ?? "agent"),
                     runtime: agent?.runtime ?? null,
                     // Current activity — only truthful while fresh; "idle" once decayed.
                     activity: activityFresh ? rawActivity : "idle",

package/dist/resources/SemanticSearch.js

@@ -4,7 +4,6 @@ import { getEmbedding, getMode } from "./embeddings-provider.js";
 import { patchRecord } from "./table-helpers.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
 import { resolveReadScope } from "./memory-read-scope.js";
-import { isRerankEnabled, getRerankTopN, getRerankBudgetMs, getRerankMinCandidates, rerankCandidates, } from "./rerank-provider.js";
 // The BM25 + union-RRF hybrid path is feature-flagged via hybridEnabled()
 // (imported from ./bm25 — Harper-free so it's unit-testable). Default is ON as
 // of 2026-07-08 (see ./bm25.ts's hybridEnabled() doc); set
@@ -15,7 +14,7 @@ import { hybridEnabled } from "./bm25.js";
 // supersede/isAllowed) now lives in the pure, side-effect-free
 // retrieveCandidates() core (flair-bootstrap-scale-fix, Kern-approved
 // extraction) — MemoryBootstrap.ts calls the SAME core bare, without
-// tripping this file's rate-limit/reranker/hit-tracking side effects. See
+// tripping this file's rate-limit/hit-tracking side effects. See
 // resources/semantic-retrieval-core.ts's module doc for the full boundary.
 import { retrieveCandidates, DEFAULT_SELECT } from "./semantic-retrieval-core.js";
 import { attachTrust } from "./trust-block.js";
@@ -181,29 +180,18 @@ export class SemanticSearch extends Resource {
             }
         }
         const hybrid = hybridEnabled();
-        // When the reranker is on, widen the legacy HNSW fetch so it has a deeper
-        // pool to re-score (retrieve topN → rerank → slice to limit). Decoupled
-        // from CANDIDATE_MULTIPLIER so composite re-ranking keeps its existing
-        // headroom. Scoped to the legacy (non-hybrid) vector path below — the
-        // hybrid path's candidate pool is already governed by CANDIDATE_MULTIPLIER
-        // (semantic leg) + SEM_LIMIT (BM25 leg) via RRF union; the
-        // reranker still applies to its output further down regardless of which
-        // path produced `filteredResults`.
-        const rerankOn = isRerankEnabled();
-        const rerankTopN = getRerankTopN();
         // The overfetch policy (how many raw candidates to pull from the
         // HNSW/BM25 legs relative to what the caller ultimately wants) is THIS
         // wrapper's decision — retrieveCandidates() never multiplies its `limit`
         // param internally (see resources/semantic-retrieval-core.ts's doc), so
         // every caller (this one, and MemoryBootstrap's own K formula) computes
-        // its own fetch depth. Hybrid's semantic leg is never rerank-widened
-        // (matches the pre-extraction behavior: only the legacy path widened for
-        // rerank).
-        const candidateLimit = hybrid
-            ? limit * CANDIDATE_MULTIPLIER
-            : (rerankOn ? Math.max(limit * CANDIDATE_MULTIPLIER, rerankTopN) : limit * CANDIDATE_MULTIPLIER);
+        // its own fetch depth. Both the hybrid path (CANDIDATE_MULTIPLIER on the
+        // semantic leg + SEM_LIMIT on the BM25 leg, fused by RRF) and the legacy
+        // vector-only path overfetch by the same multiplier, which is what gives
+        // composite re-scoring headroom to reorder before the final slice.
+        const candidateLimit = limit * CANDIDATE_MULTIPLIER;
         const ctx = this.getContext?.();
-        let filteredResults = await retrieveCandidates({
+        const filteredResults = await retrieveCandidates({
             queryEmbedding: qEmb,
             q,
             conditions,
@@ -233,10 +221,10 @@ export class SemanticSearch extends Resource {
             withSemSimilarity: abstain || includeTrust,
         });
         // ─── flair#744 slice 2 — first-class abstention ("no memory covers this")
-        // Opt-in only. Evaluated on the RETRIEVED candidate pool, BEFORE the
-        // reranker / final slice / hit-tracking, so an abstaining recall does no
-        // rerank work and never bumps retrievalCount for memories it declines to
-        // surface. The decision reads ONLY the best absolute semantic similarity
+        // Opt-in only. Evaluated on the RETRIEVED candidate pool, BEFORE the final
+        // slice / hit-tracking, so an abstaining recall never bumps retrievalCount
+        // for memories it declines to surface. The decision reads ONLY the best
+        // absolute semantic similarity
         // (never any principal/authority signal — abstention.ts is pure and
         // authority-free), against the single GLOBAL threshold. Default OFF ⇒ this
         // whole block is skipped and the response is byte-identical to pre-slice-2.
@@ -253,28 +241,12 @@ export class SemanticSearch extends Resource {
                 };
             }
         }
-        // ─── Cross-encoder rerank (best-effort, fail-open to vector order) ───────
-        // Re-scores query+candidate TOGETHER (cross-attention the pooled embedding
-        // can't do) and reorders before the final slice. Reorders whatever
-        // `filteredResults` retrieveCandidates() produced — legacy HNSW-only OR
-        // the BM25+union-RRF hybrid path — since both converge into the same
-        // shape (retrieveCandidates never exposes which leg produced a result).
-        // Still gated on `qEmb` (an embedding was actually generated); the pure
-        // keyword-only fallback (no qEmb at all) is untouched either way. The
-        // reranker overwrites `_score` with the rerank score (so margin
-        // measurement reads it) and preserves the semantic score as `_semScore`;
-        // `_rawScore` is left as-is so recall-bench's scoring:"raw" path stays
-        // reproducible. On init failure, timeout, or any throw, rerankCandidates
-        // returns the input UNCHANGED and we fall through to retrieveCandidates'
-        // own vector-order sort — recall is never blocked. retrieveCandidates
-        // already returns its output sorted best-first, so the non-rerank branch
-        // needs no additional sort here.
-        if (rerankOn && qEmb && q && filteredResults.length >= getRerankMinCandidates()) {
-            filteredResults = await rerankCandidates(String(q), filteredResults, {
-                topN: rerankTopN,
-                budgetMs: getRerankBudgetMs(),
-            });
-        }
+        // retrieveCandidates() already returns its output sorted best-first
+        // (whichever leg produced it — legacy HNSW-only, the BM25+union-RRF hybrid
+        // path, or the keyword-only fallback all converge into the same shape), so
+        // the final slice needs no additional sort. A cross-encoder rerank stage
+        // used to sit here and reorder the pool before this slice; it was removed
+        // in flair#893 after measuring Δp@3 = 0.000 at 4.1× query latency.
         const topResults = filteredResults.slice(0, limit);
         // Async hit tracking — don't block the response
         const now = new Date().toISOString();

package/dist/resources/abstention.js

@@ -100,7 +100,7 @@ export const STRONG_BAND = 0.55;
  * Reads ONLY the `_semSimilarity` number the retrieval core
  * (resources/semantic-retrieval-core.ts) attaches to each semantic-leg result
  * WHEN abstention is requested — an absolute cosine similarity in [0,1],
- * independent of the RRF normalization / rerank that make the ranking `_score`
+ * independent of the RRF normalization that makes the ranking `_score`
  * a *relative* signal (the top RRF-fused result is normalized to 1.0 regardless
  * of how weak the actual match is, so `_score` is unusable as a confidence
  * floor — this is why abstention reads the absolute similarity instead).

package/dist/resources/agent-admin.js

@@ -0,0 +1,149 @@
+/**
+ * agent-admin.ts — the ONE answer to "is this principal an administrator?".
+ *
+ * The Agent (Principal) record carries two fields that both read as if they
+ * answered that question:
+ *
+ *   role: String       — administrator when the value is exactly "admin"
+ *   admin: Boolean     — "admin principals can manage other principals"
+ *
+ * They used to be consulted by DIFFERENT consumers, which is the whole defect
+ * (flair#941):
+ *
+ *   - resources/agent-auth.ts's isAdmin() — the single gate behind allowAdmin(),
+ *     and therefore behind every admin-only resource — searched `role` and
+ *     ignored `admin` completely.
+ *   - resources/mcp-handler.ts OR-ed the two together.
+ *   - Every reporter (flair principal show/list, the admin dashboard) displayed
+ *     `admin`, and every writer except AgentSeed wrote `admin`.
+ *
+ * So the field the product wrote and displayed was not the field the gate read.
+ * `flair principal add --admin` stored `admin: true` and granted nothing, while
+ * the dashboard confidently printed "admin: yes" for a principal that
+ * allowAdmin() rejects. Both directions are silent, and one of them is silent in
+ * the direction that flatters the operator.
+ *
+ * ─── The rule ────────────────────────────────────────────────────────────────
+ *
+ * `role === ADMIN_ROLE` is the AUTHORITY. `admin` is a SERVER-MAINTAINED MIRROR
+ * of it and is never read to reach an authorization decision again.
+ *
+ * Every decider and every reporter calls {@link agentRecordIsAdmin}, so no two
+ * surfaces can answer this question differently. Every write through a flair
+ * write path calls {@link reconcileAdminFields}, so a record that says one thing
+ * in one field and the opposite in the other cannot be STORED by any path flair
+ * offers.
+ *
+ * ─── Why `role` is the authority and not `admin` ─────────────────────────────
+ *
+ * `admin: Boolean` is honestly the better-shaped field: typed, indexed,
+ * unambiguous, and already the one every creation path and every UI uses.
+ * Making it the authority would nonetheless GRANT admin, on the primary HTTP
+ * gate, to every record that currently carries `admin: true` with a non-admin
+ * `role` — the records `flair principal add --admin` has been producing all
+ * along, which have never been admins. That is a widening of live access as a
+ * side effect of a consistency fix, decided by data nobody has audited. Keeping
+ * `role` as the authority changes no existing principal's rights on the gate:
+ * every principal that is an admin today is an admin after this change, and
+ * every principal that is not, is not.
+ *
+ * Switching the authority to `admin` is a reasonable follow-up, but it is a
+ * deliberate privilege migration with an audit of existing records — not
+ * something to slip in underneath a naming fix.
+ *
+ * ─── Records that already carry a mismatch ───────────────────────────────────
+ *
+ * Nothing is rewritten in bulk; no migration runs. What happens to each shape:
+ *
+ *   role:"admin" + admin:false|absent  — an admin today, an admin after. The
+ *     mirror is stale, so the CLI and dashboard used to report "not an admin"
+ *     for a principal holding admin rights; they now report the truth. The
+ *     stored mirror is repaired the next time the record is written through the
+ *     Agent resource.
+ *
+ *   admin:true + role not "admin"  — NOT an admin today on the gate, and not
+ *     after. This is what `flair principal add --admin` produced. The CLI and
+ *     dashboard used to report "admin: yes"; they now report the truth, which is
+ *     how an operator finds out the grant never took. The remedy is to re-issue
+ *     the grant (which now writes both fields). The one behaviour that does
+ *     change is the native MCP surface, which used to honour this field on its
+ *     own — see resources/mcp-handler.ts. That surface is gated behind
+ *     FLAIR_MCP_OAUTH and is default-OFF, so no instance running the shipped
+ *     defaults is affected.
+ *
+ * Deliberately dependency-free — pure predicates over a plain record, importing
+ * neither `harper` nor any resource, so the auth gate, the resources, the
+ * reporters and the tests can all share it without an import cycle.
+ */
+/** The exact `role` value that denotes a flair administrator. */
+export const ADMIN_ROLE = "admin";
+/**
+ * THE admin predicate. Every authorization decision and every report of a
+ * principal's admin status resolves through this one function.
+ *
+ * Total over every field combination: a record with a contradictory `admin`
+ * mirror gets the SAME answer here as it does at the gate, so a contradiction
+ * can never produce two different answers on two different surfaces. It is
+ * deliberately NOT an OR over the two fields — see the module header.
+ *
+ * Note this covers Agent RECORDS only. `FLAIR_ADMIN_AGENTS` is a separate,
+ * env-configured admin source union-ed in by resources/agent-auth.ts's
+ * getAdminAgents(); it names agent ids and never touches a record.
+ */
+export function agentRecordIsAdmin(record) {
+    return record?.role === ADMIN_ROLE;
+}
+/**
+ * Make a record about to be written self-consistent, so the two fields can
+ * never be STORED disagreeing.
+ *
+ * Admin is requested by EITHER spelling — `role: "admin"` or `admin: true` —
+ * because both have been documented and both are what an operator reaches for.
+ * Whichever they used, both fields come out of here agreeing. That is what
+ * makes `flair principal add --admin` finally do what it says: it writes the
+ * Boolean, and the Boolean now carries the record into the authority field.
+ *
+ * **Honouring `admin: true` here is not a privilege widening.** Every call site
+ * is already admin-gated — Agent.post() is allowCreate()=allowAdmin, Agent's
+ * update path refuses a privilege change from a non-admin, and AgentSeed is
+ * admin-only and re-checks. A caller that can reach this could have written
+ * `role: "admin"` directly; this only means they no longer have to know which
+ * of the two fields is the real one.
+ *
+ * A non-admin `role` is free text (a human label — "researcher", "COO") and is
+ * left exactly as supplied; only the admin sentinel is normalised.
+ *
+ * Mutates `content` in place and returns it, matching the surrounding
+ * defaults-stamping style in resources/Agent.ts's post().
+ */
+export function reconcileAdminFields(content) {
+    if (!content || typeof content !== "object")
+        return content;
+    // Widened locally: `content` is generic so TypeScript will not accept writes
+    // to named properties on it, but the whole point here is to normalise those
+    // two properties in place and hand the caller back its own object.
+    const record = content;
+    if (record.role === ADMIN_ROLE || record.admin === true) {
+        record.role = ADMIN_ROLE;
+        record.admin = true;
+    }
+    else {
+        record.admin = false;
+    }
+    return content;
+}
+/**
+ * True when a stored record's two fields disagree — i.e. it was written by
+ * something other than a flair write path (a raw table write, an ops-API
+ * insert, a federation merge) and now claims one thing to a reader of `admin`
+ * and the opposite to the gate.
+ *
+ * Reporting-only. Nothing authorizes on this; it exists so a surface can SAY
+ * that a record is inconsistent instead of silently picking a side.
+ */
+export function adminFieldsDisagree(record) {
+    const r = record;
+    if (!r || typeof r !== "object")
+        return false;
+    return agentRecordIsAdmin(r) !== (r.admin === true);
+}