@tpsdev-ai/flair 0.35.0 → 0.37.0

package/dist/resources/record-type-kit.js

@@ -211,6 +211,55 @@ export function makeByIdReadGate(readScope) {
         return record;
     };
 }
+// ─── (c) Scoped search — makeScopedSearch ────────────────────────────────
+/**
+ * Produces a scoped search() override that nests the caller's conditions
+ * inside the agent-scope condition as the OUTERMOST `and` block, so a
+ * caller-supplied `operator: "or"` cannot boolean-inject past the owner
+ * scope.
+ *
+ * This is the correct composition that MemoryCandidate.search() already
+ * applies (the only resource that got it right).  Memory.search() and
+ * WorkspaceState.search() both used a flat prepend — `[agentCondition,
+ * ...query.conditions]` — which lets a caller-supplied `query.operator`
+ * survive and turn the scope condition into one OR-branch.
+ *
+ * Every table that composes this gets the correct nesting by default;
+ * a fifth table added later cannot accidentally reintroduce the flat-
+ * prepend bug.
+ *
+ * `superSearch` is a caller-supplied closure so the class's own
+ * `super.search()` (which cannot be referenced from outside the class
+ * body) stays exactly where it was.
+ */
+export function makeScopedSearch(readScope) {
+    return async function scopedSearch(agentId, query, superSearch) {
+        const scope = await readScope(agentId);
+        const agentCondition = scope.condition;
+        // Object with a conditions array — nest caller's conditions inside the
+        // scope condition as the outermost AND block so a caller-supplied
+        // `operator: "or"` cannot boolean-inject past the owner scope.
+        if (query && typeof query === "object" && !Array.isArray(query)) {
+            if (Array.isArray(query.conditions) && query.conditions.length > 0) {
+                return superSearch({
+                    ...query,
+                    conditions: [agentCondition, { conditions: query.conditions, operator: query.operator || "and" }],
+                    operator: "and",
+                });
+            }
+            // No (or empty) conditions array — just scope, preserving other query
+            // properties but NOT a caller-supplied operator (force "and").
+            const { conditions: _c, operator: _o, ...rest } = query;
+            return superSearch({ ...rest, conditions: [agentCondition], operator: "and" });
+        }
+        // Plain array or no query — wrap in an object with operator "and" so
+        // the scope condition is always the outermost AND.
+        const conditions = Array.isArray(query) && query.length > 0
+            ? [agentCondition, { conditions: query, operator: "and" }]
+            : [agentCondition];
+        return superSearch({ conditions, operator: "and" });
+    };
+}
 export function stampAttribution(auth, content, field, mode, forbiddenMessage) {
     if (auth.kind !== "agent")
         return {}; // internal → always passthrough

package/dist/version-check.js

@@ -178,3 +178,48 @@ export function formatVersionNudge(result) {
         `Upgrade: npm i -g ${FLAIR_PKG_NAME}@latest`;
     return { severity: gap.severity, message };
 }
+/**
+ * The version an INSTANCE reports, or null when it cannot be determined.
+ *
+ * flair#1072. Every other line `doctor` prints about a remote target is
+ * genuinely remote; the currency claim was about the local CLI. This asks the
+ * instance instead.
+ *
+ * Returns null — never a fallback — when the instance is unreachable, answers
+ * without a version, or times out. The whole defect being fixed is a fallback
+ * to the number already in hand, and an older instance that does not expose its
+ * version is exactly the case where that fallback is most tempting and most
+ * wrong. A caller that gets null must say "unknown", not substitute its own
+ * version.
+ *
+ * Deliberately short-timeout and failure-swallowing: doctor runs against
+ * possibly-down instances by design, and "cannot determine" is a legitimate,
+ * reportable answer rather than an error to propagate.
+ */
+export async function probeInstanceVersion(baseUrl, timeoutMs = 5000, fetchImpl = fetch) {
+    const url = `${String(baseUrl).replace(/\/+$/, "")}/Health`;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(url, { signal: ctrl.signal });
+        if (!res.ok)
+            return null;
+        const body = await res.json();
+        if (!body || typeof body !== "object")
+            return null;
+        const v = body.version;
+        // "dev" and other non-semver markers are real answers from a real server,
+        // but they cannot be compared against a published version. Treat them as
+        // undeterminable rather than feeding them to a semver comparison — a
+        // Fabric peer mid-failed-deploy reports exactly this (harper#2061).
+        if (typeof v !== "string" || !/^\d+\.\d+\.\d+/.test(v))
+            return null;
+        return v;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/docs/upgrade.md

@@ -2,7 +2,7 @@
 
 This page covers the mechanics of upgrading Flair — the general path, valid across
 versions. For **what changed in a specific release** (behavior changes, new surfaces,
-breaking changes), see [`CHANGELOG.md`](../CHANGELOG.md) — each version has its own
+breaking changes), see [`CHANGELOG.md`](https://github.com/tpsdev-ai/flair/blob/main/CHANGELOG.md) — each version has its own
 `## [X.Y.Z]` section. Check the CHANGELOG entries between your current version and the
 target version before upgrading anything you depend on in production.
 
@@ -78,18 +78,23 @@ actually running:
   instead of retrying in a loop — see [Downgrade](#downgrade) for the
   restore procedure.
 
-### Pre-upgrade snapshot (opt-in)
+### Pre-upgrade snapshot (opt-in for same-engine, unconditional on engine change)
 
 flair#637 added a **physical**, byte-exact snapshot of `~/.flair/data` — the whole
 directory (RocksDB files, keys, config, `admin-pass`), not just the logical records a
-`flair backup` JSON export covers. As of 2026-07-08 this is **opt-in**: pass
-`--snapshot` to `flair upgrade` to take one before the package swap. It's off by
-default — matching how Harper's own upgrade CLI behaves (it recommends a backup before
-proceeding, but never auto-tars your data directory for you) — because the
-tested-downgrade guarantee below already covers the failure mode a snapshot exists
-for, and the old opt-out default meant every upgrade paid the cost (the data dir can
-be 800MB+; keep-last-3 retention meant up to ~2.5GB of snapshots sitting around)
-whether or not you wanted it.
+`flair backup` JSON export covers. As of 2026-07-08 this is **opt-in** for same-engine
+upgrades: pass `--snapshot` to `flair upgrade` to take one before the package swap.
+It's off by default — matching how Harper's own upgrade CLI behaves (it recommends a
+backup before proceeding, but never auto-tars your data directory for you) — because
+the downgrade-boot test (see below) covers same-engine downgrades, and the old opt-out
+default meant every upgrade paid the cost (the data dir can be 800MB+; keep-last-3
+retention meant up to ~2.5GB of snapshots sitting around) whether or not you wanted it.
+
+**When the engine (Harper) version changes** (flair#1047), the snapshot is
+**unconditional** — the tested-downgrade guarantee does not hold across engine version
+boundaries, and the backwards-boot refusal + snapshot recovery path is the invariant
+that applies. Opting out requires `--no-engine-snapshot` and prints what is being
+given up.
 
 ```bash
 flair upgrade --snapshot
@@ -365,7 +370,7 @@ flair restore ~/flair-backup-<date>.json
 
 ### Known issue — upgrading *from* an older version can still report a false rollback
 
-The 0.25.1 fix (see [`CHANGELOG.md`](../CHANGELOG.md)) makes `flair upgrade` resolve a
+The 0.25.1 fix (see [`CHANGELOG.md`](https://github.com/tpsdev-ai/flair/blob/main/CHANGELOG.md)) makes `flair upgrade` resolve a
 credentials-only post-restart-verification failure to `healthy-unverified` instead of
 rolling back. That fix is **forward-only**: it lives in the *new* CLI code, but an
 upgrade's post-restart verification is run by the CLI that was already installed
@@ -489,6 +494,20 @@ current build, writes a memory and a presence row, stops it *without* wiping the
 directory, then boots the last **npm-published** `@tpsdev-ai/flair` against that exact
 same directory and confirms it comes up healthy and can read both rows back.
 
+**The guarantee is now restated (flair#1050):** there is never a silent bad outcome.
+Either the old binary boots and serves the corpus correctly, **or** it refuses to start
+with a message naming what wrote the store, what is running, and how to recover — and a
+pre-upgrade snapshot exists to recover *from*. The first branch (clean boot) holds for
+same-engine upgrades; the second (refusal + snapshot) applies when the engine version
+changes, which is the case where downgrade was never ours to guarantee.
+
+**First known engine-version break:** Harper 5.1 → 5.2 (2026-08). 5.2.0 creates the
+`hdb_secret` store on first boot against an existing data directory, and the older binary
+will not start against it. Harper's 5.2.0 release notes document no rollback procedure.
+The backwards-boot refusal (flair#1049) catches this: the old binary refuses to start,
+naming both versions and the data directory, with recovery instructions. A pre-upgrade
+snapshot exists at the named path. Restoring it returns the store to a working state.
+
 **As observed when this suite was added (2026-07-08):** the npm-published baseline
 (0.21.0) boots cleanly against data written by a HEAD build roughly 14 commits ahead of
 it (several security-hardening and CLI-behavior changes, no Flair schema migration, and
@@ -507,7 +526,7 @@ you haven't personally tested.
 
 ## See also
 
-- [`CHANGELOG.md`](../CHANGELOG.md) — what actually changed, version by version.
+- [`CHANGELOG.md`](https://github.com/tpsdev-ai/flair/blob/main/CHANGELOG.md) — what actually changed, version by version.
 - [`docs/releasing.md`](releasing.md) — how a release gets published in the first
   place (staged npm publish with 2FA approval), if you're curious why a new version
   shows up when it does.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.35.0",
+  "version": "0.37.0",
   "packageManager": "bun@1.3.10",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",
@@ -52,8 +52,7 @@
     "prepublishOnly": "npm run build && npm run build:cli",
     "test": "bun test",
     "test:e2e": "playwright test",
-    "release": "./scripts/release.sh",
-    "postinstall": "node -e \"try{const{chmodSync,statSync}=require('fs');for(const p of ['dist/cli-shim.cjs','dist/cli.js']){try{if(statSync(p).isFile()){chmodSync(p,0o755);console.error('@tpsdev-ai/flair: chmod +x ' + p + ' OK')}}catch(e){if(e.code!=='ENOENT')console.error('postinstall warn:',e.message)}}}catch(e){console.error('postinstall warn:',e.message)}\""
+    "release": "./scripts/release.sh"
   },
   "publishConfig": {
     "access": "public"
@@ -73,7 +72,11 @@
     "tweetnacl": "1.0.3"
   },
   "overrides": {
-    "react-native-fs": "npm:empty-npm-package@1.0.0"
+    "react-native-fs": "npm:empty-npm-package@1.0.0",
+    "brace-expansion": "^5.0.9",
+    "undici": "^8.9.0",
+    "fast-uri": "^4.1.2",
+    "hono": "^4.12.34"
   },
   "devDependencies": {
     "@playwright/test": "1.59.1",