@tpsdev-ai/flair 0.29.0 → 0.31.0

package/dist/resources/embeddings-boot.js

@@ -7,7 +7,7 @@
  * 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
+ * Harper's environment-manager (`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
@@ -28,14 +28,14 @@
  *      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
+ *      (`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,
+ *      Harper refuses to boot. Confirmed byte-identical in both 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.
  *
@@ -98,19 +98,17 @@ const MODEL_NAME = "nomic-embed-text";
  * table for the exact contract this PR bumps to).
  *
  * "mean" is nomic-embed-text-v1.5's actual pooling type — NOT assumed from
- * the model's reputation, directly confirmed against the shipped GGUF:
- * `node_modules/.bin/node-llama-cpp inspect gguf
- * ~/.flair/data/models/nomic-embed-text-v1.5.Q4_K_M.gguf` reports
- * `"nomic-bert": { pooling_type: 1 }`, and llama.cpp's
+ * the model's reputation, directly confirmed against the shipped GGUF by
+ * reading its metadata: `"nomic-bert": { pooling_type: 1 }`, and llama.cpp's
  * `enum llama_pooling_type` maps 1 -> `LLAMA_POOLING_TYPE_MEAN` (0 = none,
- * 1 = mean, 2 = cls, 3 = last, 4 = rank). nomic-embed-text is a
- * NomicBertModel architecture, not Qwen3 (last-token) — flair registers no
- * Qwen3-class embedding model today (the Qwen3-Reranker-0.6B in
- * resources/rerank-provider.ts is a SEPARATE code path that calls
- * node-llama-cpp directly for generative yes/no scoring, never goes through
- * HFE's register()/init(), and has no embedding-pooling context at all — see
- * that file's header). If a Qwen3-class (last-token-pooling) embedding model
- * is ever registered here, it must declare `pooling: "last"`, not "mean".
+ * 1 = mean, 2 = cls, 3 = last, 4 = rank). (That reading was originally taken
+ * with `node-llama-cpp inspect gguf`, which flair no longer depends on —
+ * flair#893. Any GGUF inspector reports the same metadata field; install the
+ * CLI ad hoc if the check needs repeating.) nomic-embed-text is a
+ * NomicBertModel architecture, not Qwen3 (last-token), and flair registers no
+ * Qwen3-class embedding model today. If a Qwen3-class (last-token-pooling)
+ * embedding model is ever registered here, it must declare `pooling: "last"`,
+ * not "mean".
  *
  * Applies to the bench-only `modelPath` override too (`benchModelPathOverride()`
  * below): `FLAIR_RECALL_HARNESS_MODEL_PATH` lets an operator point this

package/dist/resources/embeddings-provider.js

@@ -36,11 +36,11 @@
  * what this migration removes: `models.embed` is a process-wide singleton
  * Harper initializes at boot, off the first-call dynamic-import race.
  *
- * `@harperfast/harper` is dynamic-imported here (deferred to first actual
+ * `harper` is dynamic-imported here (deferred to first actual
  * getEmbedding()/getMode()/getStatus() call), NOT statically imported like
  * every other resource's `Resource`/`databases`/`server` — those work
  * unmocked-import-free only because every test that (transitively) imports
- * them already mocks `@harperfast/harper` first. Statically importing
+ * them already mocks `harper` first. Statically importing
  * `models` here would make *any* test that imports this file for
  * `resolveModelsDir()` alone (test/unit/embeddings-models-dir.test.ts, which
  * has no reason to know about Harper at all) also eagerly load Harper's real
@@ -152,7 +152,7 @@ const EMBEDDING_PREFIXES_ENABLED = true; // Phase 2 prefix flip ON — re-baseli
  * embedding call, so this lets it override the ONE thing that matters
  * (whether `models.embed` receives `inputType`, and whether `getModelId()`
  * stamps the suffix) via the env var it already forwards to `startHarper()`
- * (the same mechanism `FLAIR_HYBRID_RETRIEVAL`/`FLAIR_RERANK_ENABLED` use).
+ * (the same mechanism `FLAIR_HYBRID_RETRIEVAL` uses).
  *
  * Bidirectional, not two separate force-on/force-off hatches: THE GATE has
  * flipped direction once already (off→on, this PR) and may again in the
@@ -186,7 +186,7 @@ function prefixesEnabled() {
  * Build the options object passed to `models.embed()`. Pulled out as its own
  * pure, harper-free function so the value-forwarding (and the reject-a-
  * wrong-value guard) is unit-testable without touching the deferred
- * `@harperfast/harper` import this file's header explains — see
+ * `harper` import this file's header explains — see
  * test/unit/embeddings-provider-input-type.test.ts.
  *
  * Gate ON (default): rejects anything other than the literal
@@ -217,7 +217,7 @@ let _modelsApi;
 /**
  * Resolve (and cache) Harper's `models` facade via a deferred import — see file header.
  *
- * NOTE for anyone using this as a reference: `models` (the `@harperfast/harper`
+ * NOTE for anyone using this as a reference: `models` (the `harper`
  * package export) and a component's `scope.models` are the SAME boot-time
  * singleton — Harper's jsLoader hands components `scope.models = <the global
  * models>` (two accessors, one object; the model registry lives on that singleton).
@@ -229,19 +229,22 @@ let _modelsApi;
 async function getModelsApi() {
     if (_modelsApi)
         return _modelsApi;
-    const harper = await import("@harperfast/harper");
+    const harper = await import("harper");
     _modelsApi = harper.models;
     return _modelsApi;
 }
 /**
  * Resolve the directory the embeddings model lives in / downloads into.
  *
- * Implementation moved to `resources/models-dir.ts` (flair#815) so the
- * reranker can share the exact same resolution without importing this module
- * (several unit-isolated tests `mock.module()` this file wholesale — see
- * models-dir.ts's header). Re-exported here so existing consumers keep their
- * import site: `resources/embeddings-boot.ts` (flair#694), which builds the
- * `modelsDir` it passes to harper-fabric-embeddings' `register()`, and
+ * Implementation lives in `resources/models-dir.ts` (extracted in flair#815)
+ * so any model consumer can share the exact same resolution without importing
+ * this module — several unit-isolated tests `mock.module()` this file
+ * wholesale, and an incomplete stub then breaks every file that imports it.
+ * See models-dir.ts's header for why that hazard makes the tiny standalone
+ * module worth keeping even now that embeddings are its only consumer.
+ * Re-exported here so existing consumers keep their import site:
+ * `resources/embeddings-boot.ts` (flair#694), which builds the `modelsDir` it
+ * passes to harper-fabric-embeddings' `register()`, and
  * test/unit/embeddings-models-dir.test.ts, which pins the resolution order.
  */
 export { resolveModelsDir } from "./models-dir.js";

package/dist/resources/federation-cleanup.js

@@ -11,13 +11,13 @@ let cleanupTimer = null;
  * and performs housekeeping on expired/unconsumed token records.
  *
  * In test environments, callers pass mock serverOp/db via `opts` so this
- * module never imports @harperfast/harper at the top level (which would
+ * module never imports harper at the top level (which would
  * crash when STORAGE_PATH isn't set).
  */
 export async function initFederationCleanup(opts) {
     const immediate = opts?.immediateTick ?? true;
     // Resolve server / databases: use caller-supplied mocks when available,
-    // otherwise lazy-import @harperfast/harper at call time.
+    // otherwise lazy-import harper at call time.
     let svr;
     let db;
     if (opts?.serverOp && opts?.db) {
@@ -26,12 +26,12 @@ export async function initFederationCleanup(opts) {
     }
     else {
         try {
-            const harper = await import("@harperfast/harper");
+            const harper = await import("harper");
             svr = opts?.serverOp ?? harper.server.operation;
             db = opts?.db ?? harper.databases;
         }
         catch (err) {
-            console.error("[federation-cleanup] failed to load @harperfast/harper:", err?.message ?? err);
+            console.error("[federation-cleanup] failed to load harper:", err?.message ?? err);
             return;
         }
     }
@@ -94,7 +94,7 @@ export async function runCleanupTick(opts = {}) {
         db = opts.db;
     }
     else {
-        const harper = await import("@harperfast/harper");
+        const harper = await import("harper");
         svr = opts.serverOp ?? harper.server.operation;
         db = opts.db ?? harper.databases;
     }

package/dist/resources/federation-nonce-store.js

@@ -44,7 +44,7 @@ async function resolveDb(opts, cache) {
     if (opts.db)
         return opts.db;
     if (!cache.db) {
-        cache.db = import("@harperfast/harper").then((h) => h.databases);
+        cache.db = import("harper").then((h) => h.databases);
     }
     return cache.db;
 }
@@ -123,7 +123,7 @@ export async function runNonceCleanupTick(opts = {}) {
         db = opts.db;
     }
     else {
-        const harper = await import("@harperfast/harper");
+        const harper = await import("harper");
         db = harper.databases;
     }
     const retentionMs = opts.retentionMs ?? DEFAULT_RETENTION_MS;
@@ -159,7 +159,7 @@ export async function runNonceCleanupTick(opts = {}) {
  * Initialise the periodic Nonce-table eviction sweep (5-min cadence).
  *
  * In test environments, callers pass a mock `db` via `opts` so this module
- * never imports @harperfast/harper at the top level (mirrors
+ * never imports harper at the top level (mirrors
  * federation-cleanup.ts's `initFederationCleanup`).
  */
 export async function initNonceStoreCleanup(opts) {
@@ -170,11 +170,11 @@ export async function initNonceStoreCleanup(opts) {
     }
     else {
         try {
-            const harper = await import("@harperfast/harper");
+            const harper = await import("harper");
             db = harper.databases;
         }
         catch (err) {
-            console.error("[federation-nonce-store] failed to load @harperfast/harper:", err?.message ?? err);
+            console.error("[federation-nonce-store] failed to load harper:", err?.message ?? err);
             return;
         }
     }

package/dist/resources/health.js

@@ -1,11 +1,11 @@
-import { Resource, databases } from "@harperfast/harper";
+import { Resource, databases } from "harper";
 import { promises as fsp, existsSync, readFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { getRerankStatus } from "./rerank-provider.js";
 import { allowVerified, resolveAgentAuth } from "./agent-auth.js";
 import { getMigrationStatusSnapshot } from "./migrations/status.js";
+import { resolveMigrationDataDirForRead } from "./migrations/data-dir.js";
 import { REM_DEDUP_STATS_PATH } from "./dedup-cluster.js";
 const db = databases;
 const redactHome = (p) => {
@@ -452,13 +452,33 @@ export class HealthDetail extends Resource {
             const lastLightAt = findLast("light");
             const lastRapidAt = findLast("rapid");
             const lastRestorativeAt = findLast("restorative");
+            // File presence only proves the scheduler templates were written —
+            // NOT that launchctl/systemctl actually loaded the job. A
+            // `systemctl --user enable --now` that fails (e.g. no session bus)
+            // still leaves the timer file on disk, so file-existence alone would
+            // report "enabled" for a scheduler that has nothing scheduled
+            // (flair#850). Query genuine active state once the file is known to
+            // exist; async + short-timeout so a slow/hung service manager can't
+            // stall this request.
             let nightlyEnabled = null;
+            let nightlyInstalled = false;
             const plat = platform();
-            if (plat === "darwin") {
-                nightlyEnabled = await exists(join(homedir(), "Library", "LaunchAgents", "dev.flair.rem.nightly.plist"));
-            }
-            else if (plat === "linux") {
-                nightlyEnabled = await exists(join(homedir(), ".config", "systemd", "user", "flair-rem-nightly.timer"));
+            if (plat === "darwin" || plat === "linux") {
+                nightlyInstalled = plat === "darwin"
+                    ? await exists(join(homedir(), "Library", "LaunchAgents", "dev.flair.rem.nightly.plist"))
+                    : await exists(join(homedir(), ".config", "systemd", "user", "flair-rem-nightly.timer"));
+                if (nightlyInstalled) {
+                    try {
+                        const { queryActiveStateAsync } = await import("../src/rem/scheduler.js");
+                        nightlyEnabled = await queryActiveStateAsync(plat);
+                    }
+                    catch {
+                        nightlyEnabled = null;
+                    }
+                }
+                else {
+                    nightlyEnabled = false;
+                }
             }
             const nightlyRecords = await tailJsonl(nightlyLog);
             const lastNightlyRec = nightlyRecords[nightlyRecords.length - 1];
@@ -496,6 +516,9 @@ export class HealthDetail extends Resource {
                 if (nightlyEnabled && lastNightlyAt && nowMs - new Date(lastNightlyAt).getTime() > 48 * 3600 * 1000) {
                     warnings.push({ level: "warn", message: "nightly REM hasn't run in >48h" });
                 }
+                if (nightlyInstalled && nightlyEnabled === false) {
+                    warnings.push({ level: "warn", message: "REM nightly scheduler files are written but not active — nothing is scheduled (see `flair rem nightly status`)" });
+                }
             }
         }
         catch {
@@ -537,12 +560,21 @@ export class HealthDetail extends Resource {
         // "pre-flight integrity check in progress" state the K&S verdict calls
         // for; a halted migration surfaces here (with `reason`) AND as a
         // warning below so it's visible without a separate lookup.
+        //
+        // flair#812: the dataDir is resolved by the shared, READ-ONLY resolver
+        // (resources/migrations/data-dir.ts) rather than the old
+        // `HDB_ROOT ?? homedir()/.flair/data` expression duplicated here — that
+        // env var is never set by anything, so the left branch was dead and the
+        // path silently disagreed with wherever the boot cycle actually wrote.
+        // `lastCycleError` is surfaced so `flair doctor` can name WHY a cycle
+        // didn't run, not merely that it didn't.
         try {
-            const migrationsDataDir = process.env.HDB_ROOT ?? join(homedir(), ".flair", "data");
+            const migrationsDataDir = resolveMigrationDataDirForRead();
             const snapshot = getMigrationStatusSnapshot(migrationsDataDir);
             stats.migrations = {
                 cyclePhase: snapshot.cyclePhase,
                 lastCycleAt: snapshot.lastCycleAt ?? null,
+                lastCycleError: snapshot.lastCycleError ?? null,
                 migrations: snapshot.migrations,
             };
             for (const m of snapshot.migrations) {
@@ -550,13 +582,25 @@ export class HealthDetail extends Resource {
                     warnings.push({ level: "warn", message: `migration '${m.id}' ${m.state}${m.reason ? `: ${m.reason}` : ""} — see \`flair doctor\`` });
                 }
             }
+            // The boot trigger sets `scheduled` synchronously at module load, so
+            // `idle` here means resources/migration-boot.js never loaded — the
+            // instance is running a build whose migration trigger is absent or
+            // failed to import, and NO migration will ever run on it.
+            if (snapshot.cyclePhase === "idle" && snapshot.migrations.length > 0) {
+                warnings.push({
+                    level: "warn",
+                    message: "migration boot cycle never fired on this instance (cyclePhase=idle) — no migration will run until this is resolved; see `flair doctor`",
+                });
+            }
         }
         catch {
             stats.migrations = null;
         }
         // ── Disk ──
+        // flair#812: same shared read-only resolution as the migrations section
+        // above, so `disk.dataDir` names the directory migrations actually use.
         try {
-            const dataDir = process.env.HDB_ROOT ?? join(homedir(), ".flair", "data");
+            const dataDir = resolveMigrationDataDirForRead();
             const snapshotDir = join(homedir(), ".flair", "snapshots");
             const dirSize = async (root, maxDepth = 6) => {
                 if (!(await exists(root)))
@@ -635,22 +679,6 @@ export class HealthDetail extends Resource {
         catch {
             stats.bridges = null;
         }
-        // ── Reranker ──
-        // Cross-encoder rerank stage. Reports flag/model/mode + live counters so we
-        // can see if it's silently degrading (fallbackCount climbing) in prod.
-        try {
-            const rr = getRerankStatus();
-            stats.rerank = rr;
-            if (rr.enabled && rr.state === "failed") {
-                warnings.push({ level: "warn", message: `reranker enabled but unavailable: ${rr.error ?? "init failed"} — recall falling back to vector order` });
-            }
-            if (rr.enabled && rr.rerankCount > 0 && rr.fallbackCount > rr.rerankCount) {
-                warnings.push({ level: "warn", message: `reranker falling back more than reranking (${rr.fallbackCount} fallbacks / ${rr.rerankCount} reranks) — check latency budget / topN` });
-            }
-        }
-        catch {
-            stats.rerank = null;
-        }
         // ── Warnings ──
         stats.warnings = warnings;
         // ── Process info ──

package/dist/resources/in-process.js

@@ -0,0 +1,225 @@
+/**
+ * ─── The in-process call seam (one incantation, one place) ───────────────────
+ *
+ * How code running INSIDE the Harper process invokes a flair resource AS a
+ * specific agent — flair's own native MCP handler (resources/mcp-tools.ts), and
+ * any co-located application component that loads flair as a sub-component and
+ * calls it directly instead of over HTTP.
+ *
+ * Three things an in-process caller has to get right, none of which is visible
+ * from a resource's own source and none of which used to fail in a way that
+ * points at the cause:
+ *
+ * 1. **Identity.** Every flair resource resolves its caller through
+ *    resources/agent-auth.ts's `resolveAgentAuth()`, whose FIRST hop is the
+ *    `tpsAgent` annotation the HTTP auth middleware stamps on a verified
+ *    request. There is no HTTP request in-process, so the caller supplies that
+ *    annotation itself — {@link agentContext}.
+ *
+ * 2. **Not accidentally becoming an administrator.** A context with no usable
+ *    agent id resolves to flair's trusted `internal` verdict, which is
+ *    UNFILTERED. See the safety-design block below: this module's API shape is
+ *    built around making that unreachable by accident.
+ *
+ * 3. **Collection binding.** A resource's `post()` — the create path — only
+ *    works on a resource instance Harper has marked as a COLLECTION. That mark
+ *    is a PRIVATE field (`#isCollection`) set inside Harper's own
+ *    `getResource()`; the public `isCollection` is a GETTER WITH NO SETTER on
+ *    `Resource.prototype`. So the obvious `new Cls(undefined, ctx)` +
+ *    `h.isCollection = true` does not "not work" quietly — under ESM (always
+ *    strict mode) the assignment throws
+ *    `TypeError: Cannot set property isCollection ... which has only a getter`,
+ *    and dropping the assignment instead yields
+ *    `405 The <X> does not have a post method implemented` from Harper's base
+ *    `Resource.post()`. {@link collectionResource} is the one supported way in:
+ *    hand `getResource()` an `{ isCollection: true }` option and let Harper set
+ *    its own private field.
+ *
+ * flair itself got (3) wrong in four MCP tool paths before this module existed —
+ * the same mistake a consumer reading only the resource classes would make.
+ *
+ * ─── SAFETY DESIGN: the dangerous thing has to look dangerous ────────────────
+ *
+ * MEASURED, against the real resolver:
+ *
+ *   resolveAgentAuth({ request: { tpsAgent: undefined } })  ->  { kind: "internal" }
+ *   resolveAgentAuth({ request: { tpsAgent: ""        } })  ->  { kind: "internal" }
+ *   allowAdmin({ request: { tpsAgent: undefined } })        ->  true
+ *
+ * `resolveAgentAuth` tests `tpsAgent` for TRUTHINESS, so a missing or empty id
+ * is indistinguishable from "no identity was supplied at all" — and that is the
+ * trusted verdict. The consequence is that the most ordinary application bug
+ * there is — `agentContext(session.agentId)` where the field is undefined, a
+ * typo'd property, a lookup that found nothing — would not fail closed. It
+ * would silently grant unfiltered cross-agent reads and writes, and pass the
+ * admin-only gate on admin-only resources. No error, no 403, no log line.
+ *
+ * That is the same defect class as a check that cannot fail: **the failure mode
+ * of "I forgot the id" must never be "you are now an administrator."** So:
+ *
+ *   - {@link agentContext} THROWS on a missing, empty or blank id. It is always
+ *     a programming error, and an exception is the only outcome that cannot be
+ *     mistaken for success.
+ *   - {@link agentContext} takes NO options. It is structurally incapable of
+ *     producing an admin context, so spreading a caller-influenced object into
+ *     its arguments cannot escalate.
+ *   - Admin is a SEPARATE, NAMED export ({@link adminContext}), and so is the
+ *     unfiltered maintenance verdict ({@link internalContext}). Both are
+ *     greppable: `git grep -n "adminContext\|internalContext"` enumerates every
+ *     privileged call site in a codebase.
+ *   - {@link collectionResource} REQUIRES a context and throws without one, so
+ *     the privileged path can never be reached by leaving an argument off. The
+ *     dangerous path is now the LONGEST path, not the shortest.
+ *
+ * These guards are runtime, not types, on purpose: an embedding application may
+ * be plain JavaScript, where a `string` parameter annotation buys exactly
+ * nothing. test/integration/in-process-agents.test.ts pins both the guards and
+ * the hazard they exist for, against a real Harper.
+ *
+ * ── Deliberately dependency-free ─────────────────────────────────────────────
+ * No `import { databases } from "harper"` (see resources/memory-visibility.ts
+ * for why that import is load-bearing to avoid): these helpers are pure shape,
+ * and an embedding app may want them before any table is resolved.
+ */
+/**
+ * Thrown when an in-process call is built in a way that would have silently
+ * escalated. Its own type so a caller can distinguish "I wired this wrong" from
+ * a resource's business-logic refusal (which arrives as a `Response`, not a
+ * throw).
+ */
+export class InProcessContextError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InProcessContextError";
+    }
+}
+/** Reject anything that would resolve to the trusted `internal` verdict, or to a nonsense id. */
+function requireAgentId(agentId, fnName) {
+    if (typeof agentId !== "string" || agentId.trim() === "") {
+        const got = agentId === undefined ? "undefined"
+            : agentId === null ? "null"
+                : typeof agentId !== "string" ? `a ${typeof agentId}`
+                    : agentId === "" ? "an empty string"
+                        : "a blank string";
+        throw new InProcessContextError(`${fnName}() requires a non-empty agent id, but received ${got}. ` +
+            "This is refused rather than defaulted because flair resolves a missing or empty " +
+            "tpsAgent to its trusted `internal` verdict, which reads and writes UNFILTERED across " +
+            "every agent and passes the admin-only gate — so returning a context here would have " +
+            "turned a missing id into silent administrator access. Resolve the agent id from your " +
+            "own server-side state before calling, and never from request data.");
+    }
+    return agentId;
+}
+/**
+ * The resource context that makes an in-process call act as ONE SPECIFIC agent.
+ * This is the call an application makes; the other two constructors below are
+ * privileged and deliberately harder to type.
+ *
+ * **`agentId` is asserted, not proven.** flair reads it and acts as that agent:
+ * no signature, no lookup against the `Agent` table, no registration
+ * requirement. That is right for a caller already inside the trust boundary —
+ * it could write the raw table anyway — and it is exactly why the id must come
+ * from YOUR OWN server-side state (the session you authenticated, the job
+ * record you dequeued) and **never from request data**. An agent id that
+ * reaches here from a body field, a query param, or a header you did not verify
+ * yourself is privilege escalation with no error and no trace.
+ *
+ * Throws {@link InProcessContextError} on a missing, empty or blank id — see the
+ * safety-design block at the top of this file for why that is not merely
+ * defensive.
+ *
+ * Takes no options, and in particular no way to ask for admin: use
+ * {@link adminContext} for that, so the escalation is a word you had to type.
+ *
+ * ```ts
+ * const Memory = server.resources.get("Memory").Resource;
+ * const h = await collectionResource(Memory, agentContext("planner"));
+ * const { id } = await h.post({ agentId: "planner", content: "…" });
+ * ```
+ */
+export function agentContext(agentId) {
+    return {
+        request: {
+            tpsAgent: requireAgentId(agentId, "agentContext"),
+            tpsAgentIsAdmin: false,
+        },
+    };
+}
+/**
+ * Like {@link agentContext}, but with flair-admin authority: unfiltered
+ * cross-agent reads, and writes attributed to agents other than this one.
+ *
+ * Asserted, never checked — nothing validates that the named agent is actually
+ * an admin principal. **Treat a call to this exactly as you would a root
+ * shell:** provisioning and maintenance only, never a request handler's
+ * default, and never with an id or a flag derived from anything a caller
+ * supplied.
+ *
+ * It is a separate export rather than an option so that (a) no options object
+ * spread into {@link agentContext} can escalate, and (b) every privileged call
+ * site in a codebase is findable by name.
+ *
+ * Throws {@link InProcessContextError} on a missing, empty or blank id.
+ */
+export function adminContext(agentId) {
+    return {
+        request: {
+            tpsAgent: requireAgentId(agentId, "adminContext"),
+            tpsAgentIsAdmin: true,
+        },
+    };
+}
+/**
+ * The TRUSTED, UNATTRIBUTED, UNFILTERED context — flair's `internal` verdict.
+ * Reads see every agent's private records; writes are owned by nobody.
+ *
+ * This exists for work that is genuinely infrastructure rather than an agent's:
+ * provisioning a principal, a migration, a maintenance sweep. It is the same
+ * verdict a context-less call used to fall into by accident; naming it means an
+ * application can no longer reach it by forgetting an argument, and means
+ * `git grep internalContext` enumerates every place flair or an embedder took
+ * that authority deliberately.
+ *
+ * There is no id to validate: the verdict comes precisely from the ABSENCE of
+ * an identity annotation, so the returned object carries none. The marker field
+ * is inert — it documents intent at a debugger breakpoint and is read by
+ * nothing.
+ *
+ * ```ts
+ * // Registering a principal — infrastructure, not an agent's own write.
+ * const h = await collectionResource(Agent, internalContext());
+ * await h.post({ id, name: id, publicKey });
+ * ```
+ */
+export function internalContext() {
+    return { request: {}, __flairInternal: true };
+}
+/**
+ * A resource instance bound to `context` and marked as a COLLECTION, so its
+ * `post()` (the create path) works — see this module's header for why that mark
+ * cannot be applied from outside Harper.
+ *
+ * `context` is REQUIRED. Passing nothing used to yield the unfiltered
+ * `internal` verdict, which made the privileged path the shortest one to type;
+ * it now throws. Pass {@link agentContext} for an agent's own work,
+ * {@link adminContext} or {@link internalContext} when the authority is
+ * genuinely intended.
+ *
+ * Reads do not need this — `Cls.get(id, context)` and `Cls.search(query,
+ * context)` (Harper's static resource methods) already thread the context and
+ * start their own transaction.
+ */
+export async function collectionResource(Cls, context) {
+    if (context == null || typeof context !== "object") {
+        throw new InProcessContextError("collectionResource() requires an explicit context, but received " +
+            (context === undefined ? "undefined" : context === null ? "null" : `a ${typeof context}`) +
+            ". Omitting it would resolve to flair's trusted `internal` verdict — unfiltered reads and " +
+            "unattributed writes across every agent — so the privileged path is never the one you get " +
+            "by leaving an argument off. Pass agentContext(id) to act as an agent, or internalContext() " +
+            "if this really is infrastructure work.");
+    }
+    // `{}` is a sufficient RequestTarget here: getResource() reads only `.id` off
+    // it (undefined ⇒ Harper mints the primary key), and takes the collection
+    // mark from the options argument.
+    return (await Cls.getResource({}, context, { isCollection: true }));
+}

package/dist/resources/instance-identity.js

@@ -1,4 +1,4 @@
-import { databases } from "@harperfast/harper";
+import { databases } from "harper";
 /**
  * ─── Local instance identity (federation-edge-hardening slice 1) ────────────
  *

package/dist/resources/mcp-client-metadata-fields.js

@@ -39,7 +39,7 @@
  * `allowedHosts` configured → rejected; leaked private `d` in a JWK →
  * rejected by the plugin even if our own build-time guard were bypassed).
  *
- * Kept free of any @harperfast/harper import (mirrors agentcard-fields.ts)
+ * Kept free of any harper import (mirrors agentcard-fields.ts)
  * so the document shape is unit-testable without spinning up Harper.
  */
 /** The grant this agent's CIMD document targets — formalized by oauth#161, accepted by the published 2.2.0 validator. See module header. */

package/dist/resources/mcp-handler.js

@@ -23,7 +23,7 @@
  * Harper HTTP listeners return `{ status, body, headers? }`. MCP messages are
  * JSON-RPC 2.0, so we serialize the JSON-RPC response object as the body.
  */
-import { databases } from "@harperfast/harper";
+import { databases } from "harper";
 import { randomBytes } from "node:crypto";
 import { TOOLS, listToolDefs } from "./mcp-tools.js";
 // The MCP protocol revision we implement (initialize handshake).

package/dist/resources/mcp-oauth.js

@@ -17,7 +17,7 @@
  * only meaningful when an operator has set the issuer + enabled the flag (see
  * docs). The plugin serves DCR / authorize / token / JWKS / discovery.
  */
-import * as harper from "@harperfast/harper";
+import * as harper from "harper";
 import { mcpOAuthEnabled, mcpAuthConfig } from "./mcp-oauth-flag.js";
 async function defaultLoadWithMCPAuth() {
     // Dynamic import so the dep is only required when the surface is enabled.
@@ -53,7 +53,7 @@ export async function registerMcpOAuthRoute(deps = {}) {
     const handler = deps.mcpHandler ?? (await import("./mcp-handler.js")).mcpHandler;
     // Read `server` lazily off the namespace (it's a runtime global on the Harper
     // module, not a static named export) so this module links cleanly even where a
-    // stub build of @harperfast/harper lacks the export.
+    // stub build of harper lacks the export.
     const srv = deps.server ?? (harper.server);
     // Primary registration: urlPath subroute → own chain (flair's auth-middleware
     // does not run here). `getConfig` pins iss/resource to the AS's values so the