@tpsdev-ai/flair 0.28.0 → 0.30.0

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
@@ -107,9 +107,6 @@
  * still a separate, deliberate step from shipping this code — see the PR
  * description for that distinction.
  */
-import { join } from "node:path";
-import { existsSync } from "node:fs";
-import { homedir } from "node:os";
 const VALID_INPUT_TYPES = new Set(["document", "query"]);
 /**
  * THE GATE (flair#504 Phase 2 — flipped ON). A module-level constant, not an
@@ -189,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
@@ -220,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).
@@ -232,49 +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.
  *
- * Resolution order (everything writable, never the read-only package dir):
- *   1. FLAIR_MODELS_DIR        — explicit operator/docker override.
- *   2. <ROOTPATH>/models       — Harper's data dir (Flair passes ROOTPATH =
- *                                ~/.flair/data when it spawns Harper). User-
- *                                owned and writable even on sudo-global installs.
- *   3. <cwd>/models            — ONLY if a model already lives there. Backward
- *                                compat for existing writable installs that
- *                                downloaded into the package dir before this fix;
- *                                never used as a download target on fresh installs.
- *   4. ~/.flair/data/models    — last-resort default when ROOTPATH is unset.
- *
- * The chosen dir is always writable, so the embeddings engine can download the
- * model on first use without hitting EACCES on a root-owned package dir.
- *
- * Called by `resources/embeddings-boot.ts` (flair#694) to build the
- * `modelsDir` it passes to harper-fabric-embeddings' `register()` — both run
- * in the SAME process now (unlike the retired src/cli.ts-side computation,
- * which duplicated this exact default because it ran in a separate process
- * that set the resulting value via an env var). Still exported and tested
- * independently (test/unit/embeddings-models-dir.test.ts) as the single
- * documented source of truth for this default.
+ * 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
+ * test/unit/embeddings-models-dir.test.ts, which pins the resolution order.
  */
-export function resolveModelsDir() {
-    const override = process.env.FLAIR_MODELS_DIR;
-    if (override)
-        return override;
-    const rootPath = process.env.ROOTPATH;
-    if (rootPath)
-        return join(rootPath, "models");
-    // Backward compat: a prior (writable) install may have the model cached in
-    // the package dir. Reuse it rather than re-downloading — but only if present.
-    const cwdModels = join(process.cwd(), "models");
-    if (existsSync(cwdModels))
-        return cwdModels;
-    return join(homedir(), ".flair", "data", "models");
-}
+export { resolveModelsDir } from "./models-dir.js";
 // Kern: "Boot probe MUST have a 5-10s timeout ... on timeout set mode='none'
 // + log a warning. A hung probe ... must never block Harper boot."
 const PROBE_TIMEOUT_MS = 8_000;

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,4 +1,4 @@
-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";
@@ -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 {

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

package/dist/resources/mcp-tools.js

@@ -35,6 +35,7 @@
  * version bump + a new FlairClient method, out of scope for this query-only
  * slice.
  */
+import { resolveVersion } from "./version.js";
 const H = {};
 const LOADERS = {
     SemanticSearch: async () => (await import("./SemanticSearch.js")).SemanticSearch,
@@ -248,7 +249,14 @@ async function bootstrap(agent, args) {
     // ONLY when requested so a plain bootstrap delegates a byte-identical body.
     if (args?.abstain === true)
         body.abstain = true;
-    return unwrap(await h.post(body));
+    // flair#831 — attach the running Flair version to the RESPONSE (not the
+    // delegated request body) so the calling agent learns the server version
+    // on its very first call.
+    const result = unwrap(await h.post(body));
+    if (result && typeof result === "object" && !Array.isArray(result)) {
+        return { ...result, flairVersion: resolveVersion() };
+    }
+    return result;
 }
 async function soulSet(agent, args) {
     const Cls = await handler("Soul");

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

@@ -1,6 +1,6 @@
 // ─── Memory Reflection — pure logic for /ReflectMemories ────────────────────
 // Pure helpers backing resources/MemoryReflect.ts (FLAIR-NIGHTLY-REM slice 2,
-// §3A — see specs/FLAIR-NIGHTLY-REM-SLICE-2-DISTILLATION.md, issue #707).
+// §3A — see issue #707).
 //
 // Same split as resources/memory-consolidate-lib.ts: importing MemoryReflect.ts
 // pulls in the Harper runtime (`databases`/`Resource`/`models`, storage init),
@@ -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

@@ -26,7 +26,7 @@
  * the `.catch()` below is pure defense-in-depth so a bug there can never
  * take down the process either.
  */
-import { databases } from "@harperfast/harper";
+import { databases } from "harper";
 import { homedir } from "node:os";
 import { existsSync, readFileSync } from "node:fs";
 import { join, dirname } from "node:path";

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/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());
     }

package/dist/resources/migrations/runner.js

@@ -178,9 +178,11 @@ async function runCycleLocked(deps, lock) {
     if (candidates.length === 0) {
         return { ran: false, reason: "nothing pending" };
     }
-    // ── ONE shared async pre-hash for the whole cycle (K&S: computed once,
-    // after ready, before any migration's first write; failure → halt all
-    // pending candidates rather than guessing which ones are safe). ──
+    // ── ONE shared async pre-hash at cycle start (K&S: computed after ready,
+    // before any migration's first write; failure → halt all pending
+    // candidates rather than guessing which ones are safe). Re-baselined
+    // below iff an earlier migration's own writes stale it for a later
+    // full-envelope gate — see the staleness comment on the loop. ──
     setCyclePhase("pre-hash");
     let envelope;
     try {
@@ -195,8 +197,49 @@ async function runCycleLocked(deps, lock) {
         return { ran: false, reason };
     }
     setCyclePhase("running");
+    // The cycle-start envelope is a valid gate BASELINE only until a migration
+    // in this same cycle writes rows: a legitimate, already-gated, ledgered
+    // write by an EARLIER migration (e.g. visibility-backfill stamping
+    // `visibility` — a SOURCE field) would otherwise read as corruption to a
+    // later migration's count+full-envelope gate and spuriously halt it
+    // ("completion gate failed: rowsRemaining=0, hash envelope mismatch" — the
+    // CI-observed failure on PR #845). That gate exists to catch writes the
+    // GATED migration didn't declare, not its predecessors' own completed
+    // work. So: track staleness conservatively (ANY rows written by any
+    // earlier migration, source-field or not — one cheap recompute beats
+    // enumerating which fields each migration touches), and re-baseline with a
+    // fresh computeCorpusEnvelope immediately BEFORE a full-envelope consumer
+    // starts — still before that migration's own first write, which is exactly
+    // the invariant-IV wording ("computed before first write and after
+    // completion; must match"). Cycles with no full-envelope consumer after a
+    // writing migration (every production cycle today — no schema-additive
+    // migration is registered outside CI) never pay for a second corpus walk.
+    let envelopeStale = false;
     for (const migration of candidates) {
-        await runOneMigration(migration, envelope, deps, lock);
+        if (envelopeStale && postureFor(migration.riskClass).gate === "count+full-envelope") {
+            try {
+                envelope = await computeCorpusEnvelope(deps.getTable, deps.now);
+                envelopeStale = false;
+            }
+            catch (err) {
+                // Same failure class as the cycle-start pre-hash, but scoped: only
+                // THIS migration consumes the baseline, so only it halts (the
+                // cycle-start variant halts every candidate because nothing has run
+                // yet and a failing corpus walk taints them all equally). Halted ≠
+                // bricked: it is retried on the next boot's cycle.
+                setMigrationProgress({
+                    id: migration.id,
+                    rowsDone: 0,
+                    rowsRemaining: 0,
+                    state: "halted",
+                    reason: `pre-flight integrity check failed: ${err?.message ?? String(err)}`,
+                });
+                continue;
+            }
+        }
+        const wroteRows = await runOneMigration(migration, envelope, deps, lock);
+        if (wroteRows)
+            envelopeStale = true;
     }
     setCyclePhase("done");
     return { ran: true };
@@ -243,6 +286,15 @@ async function haltMigration(migration, reason, ctx) {
         /* best-effort — the in-memory progress + ledger event already recorded the halt */
     }
 }
+/**
+ * Returns whether this migration MAY have written any rows — the cycle
+ * loop's envelope-staleness signal (see runCycleLocked). Deliberately
+ * conservative: `true` whenever rows were processed OR run() threw
+ * mid-batch (a partial batch may have landed before the throw); a false
+ * `true` merely costs one extra corpus walk before the next full-envelope
+ * gate, while a false `false` would let that gate compare against a stale
+ * baseline and spuriously halt.
+ */
 async function runOneMigration(migration, envelope, deps, lock) {
     const startedAt = deps.now().toISOString();
     const state = readMigrationState(deps.statePath);
@@ -262,7 +314,7 @@ async function runOneMigration(migration, envelope, deps, lock) {
             hashEnvelopeMatch: null,
             state,
         });
-        return;
+        return false; // halted before any write
     }
     const estSnapshot = estimateSnapshotBytes(posture.snapshotScope, initialRemaining);
     const estWorkingSet = estimateWorkingSetBytes(migration.riskClass, initialRemaining);
@@ -282,7 +334,7 @@ async function runOneMigration(migration, envelope, deps, lock) {
             hashEnvelopeMatch: null,
             state,
         });
-        return;
+        return false; // halted before any write
     }
     // ── Ladder step 3 (+ step 4 fallback): risk-scoped snapshot, or a
     // content-only export if the snapshot mechanism itself fails. ──
@@ -307,7 +359,7 @@ async function runOneMigration(migration, envelope, deps, lock) {
         }
         catch (expErr) {
             await haltMigration(migration, `snapshot failed (${snapErr?.message ?? String(snapErr)}) and the content-only export fallback also failed (${expErr?.message ?? String(expErr)})`, { deps, startedAt, rowsDone: 0, rowsRemaining: initialRemaining, hashEnvelopeMatch: null, state });
-            return;
+            return false; // halted before any write
         }
     }
     // ── Execution: throttled batches, resumable via per-row markers ──
@@ -346,7 +398,7 @@ async function runOneMigration(migration, envelope, deps, lock) {
             hashEnvelopeMatch: null,
             state,
         });
-        return;
+        return true; // conservative: a partial batch may have landed before the throw
     }
     // ── Completion gate — strictness per risk class ──
     setMigrationProgress({ id: migration.id, rowsDone, rowsRemaining: 0, state: "completing" });
@@ -363,7 +415,7 @@ async function runOneMigration(migration, envelope, deps, lock) {
             hashEnvelopeMatch: null,
             state,
         });
-        return;
+        return rowsDone > 0;
     }
     let hashEnvelopeMatch = null;
     let gateOk = finalRemaining === 0;
@@ -417,7 +469,7 @@ async function runOneMigration(migration, envelope, deps, lock) {
                 hashEnvelopeMatch,
                 state,
             });
-            return;
+            return rowsDone > 0;
         }
     }
     else if (gateOk && posture.gate === "count+old-row-envelope+new-row-presence") {
@@ -459,7 +511,7 @@ async function runOneMigration(migration, envelope, deps, lock) {
             hashEnvelopeMatch,
             state,
         });
-        return;
+        return rowsDone > 0;
     }
     // ── Success: ledger → state → prune ──
     const evt = {
@@ -496,4 +548,5 @@ async function runOneMigration(migration, envelope, deps, lock) {
     }
     pruneMigrationSnapshots(deps.snapshotRoot);
     setMigrationProgress({ id: migration.id, rowsDone, rowsRemaining: 0, state: "completed" });
+    return rowsDone > 0;
 }

package/dist/resources/migrations/synthetic-test-migration.js

@@ -27,7 +27,7 @@
  * encodes the migration id, so "is this row done" is answered entirely by
  * re-reading the row itself (invariant IV: state lives IN the data).
  */
-import { databases } from "@harperfast/harper";
+import { databases } from "harper";
 export const SYNTHETIC_MIGRATION_ID = "synthetic-ci-schema-stamp";
 export const RESERVED_TEST_AGENT_ID = "__flair_migration_synthetic_test_agent__";
 export const SYNTHETIC_TARGET_MARKER = `${SYNTHETIC_MIGRATION_ID}-done`;