@tpsdev-ai/flair 0.29.0 → 0.31.0

package/dist/resources/mcp-tools.js

@@ -36,6 +36,7 @@
  * slice.
  */
 import { resolveVersion } from "./version.js";
+import { agentContext, adminContext, collectionResource } from "./in-process.js";
 const H = {};
 const LOADERS = {
     SemanticSearch: async () => (await import("./SemanticSearch.js")).SemanticSearch,
@@ -78,16 +79,22 @@ export function __setHandlers(overrides) {
  * agent, never anonymous, never a header re-verify.
  */
 function delegationContext(agent) {
-    return {
-        request: {
-            tpsAgent: agent.agentId,
-            tpsAgentIsAdmin: agent.isAdmin,
-            headers: {
-                get: (k) => (k.toLowerCase() === "x-tps-agent" ? agent.agentId : undefined),
-            },
-        },
-        user: undefined,
+    // Shape single-sourced from resources/in-process.ts — the same context an
+    // embedding Harper app builds to act as one of its agents — plus the
+    // `x-tps-agent` header shim the delegated handlers' own header-reading paths
+    // expect.
+    //
+    // The admin branch is spelled out rather than passed as a flag: adminContext()
+    // is the greppable name for "this call carries flair-admin authority". Both
+    // constructors THROW on an empty agent id, which is the outcome we want here —
+    // a token that resolved to no principal must fail the tool call, never fall
+    // through to flair's unfiltered `internal` verdict.
+    const ctx = agent.isAdmin ? adminContext(agent.agentId) : agentContext(agent.agentId);
+    ctx.request.headers = {
+        get: (k) => (k.toLowerCase() === "x-tps-agent" ? agent.agentId : undefined),
     };
+    ctx.user = undefined;
+    return ctx;
 }
 /**
  * Unwrap a handler return value into a plain object/string for the MCP result.
@@ -128,8 +135,7 @@ async function memorySearch(agent, args) {
 }
 async function memoryStore(agent, args) {
     const Cls = await handler("Memory");
-    const h = new Cls(undefined, delegationContext(agent));
-    h.isCollection = true;
+    const h = await collectionResource(Cls, delegationContext(agent));
     // agentId is the RESOLVED agent — Memory.post also re-checks ownership via
     // resolveAgentAuth, so a mismatched body agentId would 403 anyway; we set it
     // to the verified id so the write is correctly owned.
@@ -204,8 +210,10 @@ async function memoryUpdate(agent, args) {
         // version's provenance records which client authored this update.
         if (agent.clientId)
             record.claimedClient = agent.clientId;
-        h.isCollection = true;
-        return unwrap(await h.post(record));
+        // A create needs a COLLECTION-bound instance (see resources/in-process.ts);
+        // `h` above is the by-id handle the get()/put() branches use.
+        const coll = await collectionResource(Cls, delegationContext(agent));
+        return unwrap(await coll.post(record));
     }
     const merged = { ...existing, content, updatedAt: new Date().toISOString() };
     delete merged.embedding;
@@ -281,8 +289,7 @@ async function soulGet(agent, args) {
 }
 async function workspaceSet(agent, args) {
     const Cls = await handler("WorkspaceState");
-    const h = new Cls(undefined, delegationContext(agent));
-    h.isCollection = true;
+    const h = await collectionResource(Cls, delegationContext(agent));
     // No agentId in the body — WorkspaceState.post attributes the record to the
     // authenticated identity (from the context), never the body. Same no-forge
     // contract as the flair-mcp stdio tool.
@@ -304,8 +311,7 @@ async function workspaceSet(agent, args) {
 }
 async function orgEvent(agent, args) {
     const Cls = await handler("OrgEvent");
-    const h = new Cls(undefined, delegationContext(agent));
-    h.isCollection = true;
+    const h = await collectionResource(Cls, delegationContext(agent));
     // No authorId in the body — OrgEvent.post attributes to the authenticated
     // identity, never the body (no forging as another agent).
     const body = { kind: args?.kind, summary: args?.summary };

package/dist/resources/memory-read-scope.js

@@ -1,4 +1,4 @@
-import { databases } from "@harperfast/harper";
+import { databases } from "harper";
 import { PRIVATE_VISIBILITY, isPrivateVisibility } from "./memory-visibility.js";
 /**
  * ─── Centralized Memory read-scoping (the original grant-gated read model → within-org-read-open) ─

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

@@ -44,7 +44,7 @@ export const GENERATE_TEMPERATURE = 0.2;
 //
 // Passed as `responseFormat: { schema: CANDIDATES_SCHEMA }` to models.generate()
 // so backends that honor structured output (Ollama, OpenAI — verified against
-// the pinned @harperfast/harper 5.1.17's bundled backends) return conformant
+// the pinned harper 5.1.17's bundled backends) return conformant
 // JSON directly. Not every backend enforces it (Anthropic's Messages API has
 // no equivalent and Harper documents that it silently ignores the option) —
 // this module never trusts the backend to have enforced the schema; every
@@ -226,7 +226,7 @@ export function parseAndValidateCandidates(raw, gatheredMemoryIds) {
 /**
  * Name Harper's models facade sets on the error it throws when no backend is
  * registered for the requested logical name (`ModelBackendNotFoundError`,
- * resources/models/backendRegistry.ts in @harperfast/harper 5.1.17). That
+ * resources/models/backendRegistry.ts in harper 5.1.17). That
  * class isn't part of the package's public export surface (only its
  * `Models`/type surface is re-exported from the package root), so detecting
  * it here is a documented duck-type on `.name` rather than `instanceof` —
@@ -237,7 +237,7 @@ export const MODEL_BACKEND_NOT_FOUND_ERROR_NAME = "ModelBackendNotFoundError";
  * Calls generate(), validates the result, and on malformed/mismatched output
  * retries exactly once with an explicit `responseFormat: 'json'` (the
  * "json-fallback path" — spec §3A items 2 & 3: build-time check confirmed
- * `GenerateOpts.responseFormat` supports `{ schema }` in @harperfast/harper
+ * `GenerateOpts.responseFormat` supports `{ schema }` in harper
  * 5.1.17's types, but not every backend enforces it, so the first attempt
  * requests schema mode and the fallback attempt requests plain json mode).
  * Both attempts run through the SAME parseAndValidateCandidates — a parse

package/dist/resources/memory-visibility.js

@@ -9,18 +9,18 @@
  *   - src/cli.ts's runFederationSyncOnce() — the federation-sync PUSH filter
  *     that must not replicate `private` memories to peer instances.
  *
- * Deliberately has ZERO imports — not even "@harperfast/harper". That is
+ * Deliberately has ZERO imports — not even "harper". That is
  * intentional and load-bearing: src/cli.ts is a standalone CLI entrypoint
  * that runs OUTSIDE any running Harper instance (e.g. `flair federation
  * sync` invoked from a cron/launchd job). resources/memory-read-scope.ts
- * imports `databases` from "@harperfast/harper", and that package's
+ * imports `databases` from "harper", and that package's
  * top-level init eagerly resolves storage paths and THROWS when there is no
  * live Harper runtime backing it (confirmed empirically — it takes down
  * even `flair --help`). So src/cli.ts must never import
  * resources/memory-read-scope.ts (or anything else that drags that
  * side-effecting import in) directly. This module is the safe seam: a pure
  * function + constant that both sides can import without dragging in
- * "@harperfast/harper".
+ * "harper".
  *
  * ── The migration invariant (non-negotiable, mirrors memory-read-scope.ts) ──
  * A record with NO `visibility` field (written before the field existed) is

package/dist/resources/migration-boot.js

@@ -25,20 +25,43 @@
  * `runMigrationCycle` itself never throws (see runner.ts's module doc) —
  * the `.catch()` below is pure defense-in-depth so a bug there can never
  * take down the process either.
+ *
+ * ─── flair#812: this path must never fail silently ────────────────────────
+ * `runMigrationCycle` REPORTS why a cycle didn't run (`{ ran: false, reason
+ * }`) — it does not log it, because it is a library. This file, the only
+ * caller, previously DISCARDED that value, which is what turned a
+ * recoverable environment problem into an invisible one: on a provisioned
+ * install where `~/.flair/data` isn't creatable, the runner's very first
+ * step (`acquireMigrationLock` → `mkdirSync`) threw `EACCES`, the runner
+ * caught it and returned `reason: "lock error: ..."`, and nothing anywhere
+ * said a word. `.migrations/state.json` was never written, no
+ * `[flair-migrations]` marker ever appeared, and EVERY migration — shipped
+ * and future — was skipped on that instance forever.
+ *
+ * So: the data dir is now resolved to a candidate PROVEN writable before
+ * the cycle is handed one (resources/migrations/data-dir.ts), and every
+ * non-benign outcome — an unresolvable data dir, tables that never became
+ * ready, a runner-reported failure, an unexpected throw — is BOTH logged
+ * with a `[flair-migrations]` marker AND recorded as a `failed` progress
+ * entry per registered migration. That progress entry is what makes the
+ * condition visible where an operator will actually meet it:
+ * `/HealthDetail` (with a warning), `flair doctor`'s Migrations section
+ * (counted as an issue) and `flair quality`'s `instance.migrationsClean`.
+ *
+ * The one deliberately-quiet outcome is `single-flight` — another thread or
+ * process holds the lock and is running the cycle. That is the guard doing
+ * its job, not a failure, and Harper boots N worker threads that each load
+ * this module; logging it would emit N-1 scary lines on every healthy boot.
  */
-import { databases } from "@harperfast/harper";
-import { homedir } from "node:os";
+import { databases } from "harper";
 import { existsSync, readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { buildRegistry } from "./migrations/registry.js";
 import { runMigrationCycle } from "./migrations/runner.js";
-import { seedIdleProgress } from "./migrations/progress.js";
+import { markIdleMigrationsFailed, seedIdleProgress, setCyclePhase } from "./migrations/progress.js";
+import { describeUnresolvableDataDir, resolveWritableMigrationDataDir, } from "./migrations/data-dir.js";
 import { getMode } from "./embeddings-provider.js";
-/** Same dataDir resolution as resources/health.ts's disk section. */
-export function resolveMigrationDataDir() {
-    return process.env.HDB_ROOT ?? join(homedir(), ".flair", "data");
-}
 /** Same "resolve the running package's own version" idiom as resources/health.ts. */
 export function resolveRunningVersion() {
     try {
@@ -103,6 +126,26 @@ async function waitForEmbeddingsSettled(maxWaitMs = 8_500, intervalMs = 150) {
         await new Promise((r) => setTimeout(r, intervalMs));
     }
 }
+/**
+ * Records a boot-path failure everywhere an operator might look: the
+ * process log (with the `[flair-migrations]` marker the runbook greps for),
+ * the cycle status (`lastCycleError`, surfaced by `/HealthDetail` and named
+ * by `flair doctor`), and a `failed` entry for each migration that never
+ * started — because a boot path that cannot run is not a per-migration
+ * problem, it is an instance-wide one, and `flair doctor` / `flair quality`
+ * read per-migration state.
+ *
+ * `failed` (not `halted`) is deliberate for these: nothing was attempted
+ * against the corpus, so there is no halted work to resume. And the marking
+ * deliberately touches only migrations still `idle` — see
+ * `markIdleMigrationsFailed` for why overwriting a terminal state would be
+ * a downgrade rather than extra information.
+ */
+function reportBootFailure(registry, reason) {
+    console.error(`[flair-migrations] ${reason}`);
+    setCyclePhase("done", reason);
+    markIdleMigrationsFailed(registry.list().map((m) => m.id), reason);
+}
 let scheduled = false;
 export function scheduleMigrationBoot() {
     if (scheduled)
@@ -110,30 +153,57 @@ export function scheduleMigrationBoot() {
     scheduled = true;
     const registry = buildRegistry();
     seedIdleProgress(registry.list().map((m) => m.id));
+    // Proof-of-life, set SYNCHRONOUSLY at module load: from here on,
+    // `cyclePhase === "idle"` means this module never loaded at all — the
+    // one hypothesis flair#812 could not otherwise rule out from the outside.
+    setCyclePhase("scheduled");
     setImmediate(() => {
         void (async () => {
             const ready = await waitForTablesReady();
             if (!ready) {
-                console.error("[flair-migrations] Memory/Relationship tables never became ready — skipping this boot's migration cycle (will retry next boot)");
+                reportBootFailure(registry, "Memory/Relationship tables never became ready within 30s — this boot's migration cycle was skipped (it retries on the next restart)");
                 return;
             }
             await waitForEmbeddingsSettled();
+            // Resolve a data dir PROVEN writable before handing one to the runner
+            // — the runner's first act is to take a file lock there, and a
+            // failure at that point is reported back rather than thrown, which is
+            // precisely how flair#812 stayed invisible. See data-dir.ts.
+            const resolved = resolveWritableMigrationDataDir();
+            if (!resolved.dataDir) {
+                reportBootFailure(registry, describeUnresolvableDataDir(resolved.tried));
+                return;
+            }
             try {
-                await runMigrationCycle({
+                const result = await runMigrationCycle({
                     registry,
                     getTable,
-                    dataDir: resolveMigrationDataDir(),
+                    dataDir: resolved.dataDir,
                     runningVersion: resolveRunningVersion(),
                 });
+                // `nothing pending` is the healthy no-op; `single-flight` is the
+                // lock guard working as designed on a multi-threaded boot. Anything
+                // else is a cycle that WANTED to run and couldn't, and must be loud.
+                if (!result.ran && result.reason && !isBenignSkip(result.reason)) {
+                    reportBootFailure(registry, `migration cycle did not run: ${result.reason}`);
+                }
             }
             catch (err) {
                 // Defense-in-depth only — runMigrationCycle is documented to never
                 // throw. A boot-path exception must never surface here regardless.
-                console.error(`[flair-migrations] unexpected error from runMigrationCycle: ${err?.message ?? String(err)}`);
+                reportBootFailure(registry, `unexpected error from runMigrationCycle: ${err?.message ?? String(err)}`);
             }
         })();
     });
 }
+/**
+ * The two `{ ran: false }` reasons that are NOT failures: nothing was
+ * pending, or another holder is already running the cycle. Matched on the
+ * prefixes runner.ts constructs (`"nothing pending"`, `"single-flight: …"`).
+ */
+export function isBenignSkip(reason) {
+    return reason === "nothing pending" || reason.startsWith("single-flight:");
+}
 // Test-only reset so a unit/integration test can re-trigger scheduling
 // within the same process (never used in production — a real process only
 // ever boots once).

package/dist/resources/migrations/data-dir.js

@@ -0,0 +1,205 @@
+/**
+ * data-dir.ts — resolves the directory the migration subsystem owns
+ * (`<dataDir>/.migrations/{state.json,lock,snapshots,exports}`), and proves
+ * it is actually usable BEFORE the boot cycle commits to it.
+ *
+ * ─── Why this file exists (flair#812) ──────────────────────────────────────
+ * The previous resolution was a single expression, duplicated in
+ * `resources/migration-boot.ts` and `resources/health.ts`:
+ *
+ *     process.env.HDB_ROOT ?? join(homedir(), ".flair", "data")
+ *
+ * Both halves of that were wrong in a way that only shows up off the
+ * developer/default shape:
+ *
+ * 1. `HDB_ROOT` IS NEVER SET BY ANYTHING. It is not a Harper process env
+ *    var — Harper's own root-path env var is `ROOTPATH`
+ *    (`harper`'s `utility/common_utils.ts` reads
+ *    `process.env['ROOTPATH']`; `HDB_ROOT` appears only as a legacy *config
+ *    key* alias in `utility/hdbTerms.ts`, and Harper never reads or writes
+ *    it on `process.env`). flair's own spawner (`src/cli.ts`) exports
+ *    `ROOTPATH`, never `HDB_ROOT`, and `resources/models-dir.ts` already
+ *    reads `ROOTPATH` for exactly this reason. So the `??` left branch was
+ *    dead code and the effective resolution was UNCONDITIONALLY
+ *    `~/.flair/data`, regardless of where Harper's real root actually is.
+ *
+ * 2. `~/.flair/data` is right only by coincidence — it is `flair init`'s
+ *    default data dir, so on a default local install the two happen to
+ *    coincide. On a PROVISIONED install (a service-managed spoke, a
+ *    container, a Harper Fabric component deployment) the process's
+ *    `homedir()` is whatever the service account has: possibly read-only,
+ *    possibly nonexistent, and in general nothing to do with the instance's
+ *    data.
+ *
+ * When `~/.flair/data` is not creatable, EVERY consumer of the old
+ * expression failed — and, critically, failed SILENTLY: the very first
+ * thing `runMigrationCycle` does is `acquireMigrationLock`, whose
+ * `mkdirSync(dirname(lockPath), { recursive: true, mode: 0o700 })` throws
+ * `EACCES`/`ENOENT`, which the runner catches and turns into
+ * `{ ran: false, reason: "lock error: ..." }` — a value `migration-boot.ts`
+ * then discarded. No log line, no state file, no health signal, and every
+ * migration ever shipped skipped forever on that instance. (Contrast
+ * `resources/embeddings-boot.ts`, loaded by the SAME `jsResource` glob:
+ * it touches no filesystem path of its own, which is exactly why embeddings
+ * kept working on the affected shapes while migrations did not.)
+ *
+ * ─── The resolution ─────────────────────────────────────────────────────
+ * An ordered candidate list, first USABLE one wins:
+ *
+ *   1. `FLAIR_MIGRATION_DATA_DIR` — explicit operator override. The escape
+ *      hatch for any deployment shape whose data dir this module cannot
+ *      infer; naming it in the failure message below is what makes an
+ *      unresolvable instance actionable rather than merely reported.
+ *   2. `HDB_ROOT` — retained purely for compatibility with anything that
+ *      may have started setting it because flair once read it. Never set by
+ *      Harper or by flair.
+ *   3. `homedir()/.flair/data` — the historical default, and `flair init`'s
+ *      own data dir. DELIBERATELY still ahead of `ROOTPATH`: on every
+ *      currently-working install this is where the state file already
+ *      lives, and reordering would silently relocate it (costing a
+ *      re-detect pass and orphaning the existing audit record) on instances
+ *      that have no problem at all. This fix is about instances where the
+ *      cycle cannot run, not about relocating ones where it can.
+ *   4. `ROOTPATH` — Harper's real root path. The rescue candidate: it is
+ *      writable by definition on a running instance (Harper is writing its
+ *      own databases there), so a shape whose `homedir()` is unusable still
+ *      gets a stable, per-instance location instead of nothing.
+ *   5. The Harper root INFERRED from this module's own location, but only
+ *      when the running layout is unambiguously a deployed component (see
+ *      `deployedComponentRootPath`). `ROOTPATH` is an env var, and a
+ *      deployment that configures `rootPath` in Harper's config file
+ *      instead of the environment leaves candidate 4 empty — this covers
+ *      that case without guessing.
+ *
+ * "Usable" is probed by DOING THE REAL OPERATION the runner would do —
+ * create `<dir>/.migrations` at 0700 and check it is writable — not by a
+ * proxy check that could disagree with it. The probe is idempotent and, on
+ * a healthy instance, is satisfied by the first candidate without touching
+ * the others.
+ *
+ * If NO candidate is usable, `resolveWritableMigrationDataDir` returns
+ * `dataDir: null` WITH the per-candidate reasons, and the boot path turns
+ * that into a loud console error plus a `failed` progress entry per
+ * registered migration — visible in `/HealthDetail`, `flair doctor` and
+ * `flair quality`'s `instance.migrationsClean`. An instance that cannot run
+ * migrations now says so; that silence was the actual defect.
+ */
+import { accessSync, constants, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Explicit operator override for the migration data dir (see module doc). */
+export const MIGRATION_DATA_DIR_ENV = "FLAIR_MIGRATION_DATA_DIR";
+/** The subdirectory the migration subsystem owns inside whichever dataDir wins. */
+export const MIGRATIONS_SUBDIR = ".migrations";
+/**
+ * Harper's root path, inferred from where THIS module is running, but ONLY
+ * when the layout is unambiguously a deployed component:
+ *
+ *     <rootPath>/components/<name>/dist/resources/migrations/data-dir.js
+ *
+ * i.e. the directory two levels above `dist/` must itself be named
+ * `components` — Harper's `componentsRoot` convention, and the layout
+ * `deploy_component` produces. That check is what keeps this from firing on
+ * a source checkout or an npm install, where the same arithmetic would
+ * point at an arbitrary parent directory. Returns null whenever the layout
+ * doesn't match, so a non-match contributes no candidate rather than a
+ * guess.
+ *
+ * `moduleUrl` is a parameter purely so a unit test can exercise both the
+ * matching and non-matching layouts without relocating the built file.
+ */
+export function deployedComponentRootPath(moduleUrl = import.meta.url) {
+    try {
+        const here = dirname(fileURLToPath(moduleUrl)); // <component>/dist/resources/migrations
+        const componentDir = dirname(dirname(dirname(here))); // <component>
+        const componentsRoot = dirname(componentDir); // .../components
+        if (basename(componentsRoot) !== "components")
+            return null;
+        return dirname(componentsRoot);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Ordered candidates for the migration data dir. See the module doc for why
+ * this order is what it is — in particular, why `homedir()/.flair/data`
+ * stays ahead of `ROOTPATH`.
+ */
+export function migrationDataDirCandidates(env = process.env, moduleUrl = import.meta.url) {
+    const out = [];
+    const add = (p) => {
+        const trimmed = p?.trim();
+        if (trimmed && !out.includes(trimmed))
+            out.push(trimmed);
+    };
+    add(env[MIGRATION_DATA_DIR_ENV]);
+    add(env.HDB_ROOT);
+    add(join(homedir(), ".flair", "data"));
+    add(env.ROOTPATH);
+    add(deployedComponentRootPath(moduleUrl));
+    return out;
+}
+/**
+ * Probes a candidate by performing the exact operation the runner's lock
+ * acquisition performs (`mkdir -p <dir>/.migrations` at 0700), then
+ * confirming the result is writable. Idempotent: on an already-working
+ * instance this is a no-op stat/mkdir against a directory that already
+ * exists.
+ */
+export function probeMigrationDataDir(dir) {
+    const owned = join(dir, MIGRATIONS_SUBDIR);
+    try {
+        mkdirSync(owned, { recursive: true, mode: 0o700 });
+        accessSync(owned, constants.W_OK | constants.X_OK);
+        return { dir, ok: true };
+    }
+    catch (err) {
+        return { dir, ok: false, reason: err?.message ?? String(err) };
+    }
+}
+/**
+ * Resolves a migration data dir that is proven writable, or reports why not.
+ * Used by the boot path (`resources/migration-boot.ts`), which must not
+ * commit to a directory the runner will then fail to lock.
+ */
+export function resolveWritableMigrationDataDir(env = process.env) {
+    const tried = [];
+    for (const candidate of migrationDataDirCandidates(env)) {
+        const probe = probeMigrationDataDir(candidate);
+        tried.push(probe);
+        if (probe.ok)
+            return { dataDir: candidate, tried };
+    }
+    return { dataDir: null, tried };
+}
+/**
+ * Operator-facing explanation of a total resolution failure — carries the
+ * actor (each path tried), the state (why each was rejected) and the remedy
+ * (the override env var), so the message is actionable at 3am rather than
+ * merely accurate.
+ */
+export function describeUnresolvableDataDir(tried) {
+    const detail = tried.length
+        ? tried.map((t) => `${t.dir} (${t.reason ?? "unusable"})`).join("; ")
+        : "no candidate paths at all";
+    return (`no writable migration data directory — tried ${detail}. ` +
+        `Migrations cannot run on this instance until one exists: point ${MIGRATION_DATA_DIR_ENV} ` +
+        `at a writable directory (or make one of the paths above writable by the account this ` +
+        `instance runs as) and restart.`);
+}
+/**
+ * READ-ONLY counterpart for `/HealthDetail`, which must never create
+ * directories as a side effect of a GET. Prefers whichever candidate
+ * already carries a `.migrations` directory (i.e. the one a boot actually
+ * chose), falling back to the first candidate so the field is never empty.
+ */
+export function resolveMigrationDataDirForRead(env = process.env) {
+    const candidates = migrationDataDirCandidates(env);
+    for (const candidate of candidates) {
+        if (existsSync(join(candidate, MIGRATIONS_SUBDIR)))
+            return candidate;
+    }
+    return candidates[0] ?? join(homedir(), ".flair", "data");
+}

package/dist/resources/migrations/embedding-stamp.js

@@ -62,8 +62,8 @@
  * embeddings engine to settle before running migrations at all.
  *
  * flair#807 — completion-gate false-negative on 0.10-era / cross-version
- * stores, root-caused against the installed `@harperfast/harper@5.1.22`
- * source (node_modules/@harperfast/harper/resources/search.ts): for an
+ * stores, root-caused against the installed `harper@5.1.22`
+ * source (node_modules/harper/resources/search.ts): for an
  * INDEXED attribute (`embeddingModel` IS `@indexed` — schemas/memory.graphql),
  * a non-negated `not_equal`/`ne` leaf condition takes `searchByIndex`'s
  * `index && !skipIndex` branch, which reconstructs a SYNTHETIC partial record
@@ -125,7 +125,7 @@
  * resources/migrations/graph-heal.ts). Before enabling any FUTURE bulk
  * re-embed, ship a structural reindex trigger with it.
  */
-import { databases } from "@harperfast/harper";
+import { databases } from "harper";
 import { getModelId } from "../embeddings-provider.js";
 function defaultMemoryTable() {
     return databases.flair.Memory;

package/dist/resources/migrations/graph-heal.js

@@ -9,7 +9,7 @@
  * every pre-this-change install) against the schema and, because
  * `canonicalizeIndexOptions` does NOT inject defaults (`{type:"HNSW"}` and
  * `{type:"HNSW",M:16}` are DIFFERENT canonical keys — verified against the
- * installed @harperfast/harper source, resources/databases.js:
+ * installed harper source, resources/databases.js:
  * canonicalizeIndexOptions + the `indexOptionsChanged` reset of
  * `lastIndexedKey` to undefined), clears the graph store and rebuilds it
  * CLEANLY from the already-correct stored vectors. That rebuild heals the
@@ -57,7 +57,7 @@
  * correctness — it re-PUTs the same vector through the incremental path and
  * does not rebuild the graph.
  */
-import { databases } from "@harperfast/harper";
+import { databases } from "harper";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";

package/dist/resources/migrations/ledger.js

@@ -17,7 +17,7 @@
  * resources/MemoryReindex.ts's `_reindex` path already rely on for
  * server-internal writes with no HTTP caller behind them.
  */
-import { databases } from "@harperfast/harper";
+import { databases } from "harper";
 function defaultOrgEventTable() {
     return databases.flair.OrgEvent;
 }

package/dist/resources/migrations/progress.js

@@ -25,6 +25,39 @@ export function seedIdleProgress(ids) {
         }
     }
 }
+/**
+ * Marks every migration that never got off the starting line as `failed`
+ * with `reason` — and ONLY those (flair#812).
+ *
+ * The boot path calls this when a cycle couldn't run, so that a condition
+ * which is really instance-wide (no writable data dir, tables never ready,
+ * the lock itself unobtainable) shows up per-migration, which is the shape
+ * `flair doctor` and `flair quality`'s `instance.migrationsClean` actually
+ * read.
+ *
+ * Restricting it to `idle` entries is load-bearing, not tidiness: a cycle
+ * can fail AFTER some migrations already reached a terminal state — the
+ * pre-hash path, for instance, halts each candidate with its own precise
+ * reason and THEN reports cycle failure. Overwriting those would replace a
+ * specific `halted` (which the runner retries on the next boot, per its
+ * documented contract) with a blanket `failed`, and would flip migrations
+ * that genuinely completed this cycle to failed. Only an entry still `idle`
+ * is one nothing has said anything about yet.
+ *
+ * Returns the ids actually marked, so a caller can tell "nothing had
+ * started" from "the cycle died partway".
+ */
+export function markIdleMigrationsFailed(ids, reason) {
+    const marked = [];
+    for (const id of ids) {
+        const current = progressById.get(id);
+        if (current && current.state !== "idle")
+            continue;
+        progressById.set(id, { id, rowsDone: 0, rowsRemaining: 0, state: "failed", reason });
+        marked.push(id);
+    }
+    return marked;
+}
 export function _resetProgressForTests() {
     progressById.clear();
     cycleStatus = { phase: "idle" };

package/dist/resources/migrations/registry.js

@@ -1,11 +1,13 @@
 /**
  * registry.ts — the MigrationRegistry: an ordered list of registered
- * migrations. embedding-stamp and graph-heal always register; the synthetic
- * CI-only variant registers ONLY when shouldRegisterSyntheticMigration() is
- * true (see synthetic-test-migration.ts's doc for the exact gating rule).
+ * migrations. embedding-stamp, graph-heal, and visibility-backfill always
+ * register; the synthetic CI-only variant registers ONLY when
+ * shouldRegisterSyntheticMigration() is true (see synthetic-test-
+ * migration.ts's doc for the exact gating rule).
  */
 import { createEmbeddingStampMigration } from "./embedding-stamp.js";
 import { createGraphHealMigration } from "./graph-heal.js";
+import { createVisibilityBackfillMigration } from "./visibility-backfill.js";
 import { createSyntheticTestMigration, shouldRegisterSyntheticMigration } from "./synthetic-test-migration.js";
 export class MigrationRegistry {
     migrations = [];
@@ -24,17 +26,24 @@ export class MigrationRegistry {
     }
 }
 /**
- * Builds the production registry. Always includes embedding-stamp and
- * graph-heal; conditionally includes the CI-only synthetic migration.
+ * Builds the production registry. Always includes embedding-stamp,
+ * graph-heal, and visibility-backfill; conditionally includes the CI-only
+ * synthetic migration.
  *
  * Order note: graph-heal registers AFTER embedding-stamp so that if a boot
  * ever runs both, the (verify-only) recall check ledgers the state AFTER any
  * re-embed work that cycle already applied — never a stale pre-embed reading.
+ * visibility-backfill registers last — it touches an unrelated field
+ * (`visibility`, never `embedding`/`embeddingModel`) and has no ordering
+ * dependency on either of the other two; appended after them simply as
+ * newest-added-last, matching how graph-heal was appended after
+ * embedding-stamp.
  */
 export function buildRegistry(env = process.env) {
     const registry = new MigrationRegistry();
     registry.register(createEmbeddingStampMigration());
     registry.register(createGraphHealMigration());
+    registry.register(createVisibilityBackfillMigration());
     if (shouldRegisterSyntheticMigration(env)) {
         registry.register(createSyntheticTestMigration());
     }