@tpsdev-ai/flair 0.44.9 → 0.44.11

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

@@ -23,6 +23,64 @@ export function isTeammate(record, callerId) {
         return false;
     return true;
 }
+/**
+ * Is `event` a zero-row, no-op auto-heal migration event (flair#1200)?
+ *
+ * The migration ledger (resources/migrations/ledger.ts) and the graph-heal
+ * observability path (resources/migrations/graph-heal.ts) both emit a
+ * `kind: "migration"` OrgEvent on EVERY boot — even when the migration did
+ * nothing. On a healthy store these are near-identical `verified` + `success`
+ * pairs, seconds apart, twice per version bump (per node): "migration graph-heal
+ * success (0 rows processed)" beside "HNSW graph-heal: recall verified healthy".
+ * They carry ZERO signal an agent could act on, yet each occupies one of the
+ * scarce (maxEvents-capped) bootstrap event slots AND is now token-charged
+ * (flair#1199) — so they crowd out events that matter. This suppresses them at
+ * RENDER (bootstrap's events section) only; the ledger still records every
+ * migration on the OrgEvent table (migration invariant IV is unchanged — this
+ * never touches the write path, only what bootstrap surfaces to a connector).
+ *
+ * A migration event is a suppressible no-op when its structured `detail`
+ * (a JSON string) reports:
+ *   - `rowsProcessed === 0` AND a non-failure outcome (`success`, or a ledger
+ *     shape with no explicit failure) — a migration that changed nothing; OR
+ *   - `migrationId === "graph-heal"` with `verified === true` — the graph-heal
+ *     verification half, which `run()` returns `processed: 0` for by construction
+ *     (it carries no `rowsProcessed`, so the first rule can't catch it).
+ *
+ * A migration that PROCESSED rows, HALTED, FAILED, or reported an
+ * UNCONFIRMED graph-heal (`verified: false`) is actionable and is NOT
+ * suppressed. Pure + Harper-free so bootstrap-events.test.ts can drive it
+ * directly against the exact ledger/graph-heal detail shapes.
+ */
+export function isZeroRowNoOpEvent(event) {
+    if (!event || event.kind !== "migration")
+        return false;
+    let detail = event.detail;
+    if (typeof detail === "string") {
+        try {
+            detail = JSON.parse(detail);
+        }
+        catch {
+            return false; // unparseable detail — don't guess, keep the event
+        }
+    }
+    if (!detail || typeof detail !== "object")
+        return false;
+    // Ledger event: a migration that processed no rows AND did not fail/halt is a
+    // no-op. A failed/halted migration (even at 0 rows) is actionable — keep it.
+    // (Checked FIRST: the graph-heal ledger event carries migrationId "graph-heal"
+    // too but no `verified` field, so the graph-heal branch below must not swallow
+    // it before its rowsProcessed:0 is seen.)
+    if (detail.rowsProcessed === 0 && (detail.outcome === undefined || detail.outcome === "success")) {
+        return true;
+    }
+    // Graph-heal VERIFICATION event: inherently zero-row (run() → processed:0),
+    // carries no rowsProcessed. Suppress only the CONFIRMED-healthy ones; an
+    // unconfirmed heal (verified:false) is worth surfacing.
+    if (detail.migrationId === "graph-heal" && detail.verified === true)
+        return true;
+    return false;
+}
 /**
  * Format the "## Team" roster line for a list of teammate ids, or `null`
  * when the roster is empty (caller should omit the section entirely).

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

@@ -287,3 +287,73 @@ export function dedupeCandidates(candidates, existingPendingClaims) {
     const existingNormalized = new Set(existingPendingClaims.map(normalizeClaim));
     return candidates.filter((c) => !existingNormalized.has(normalizeClaim(c.claim)));
 }
+// ─── Scope selection (the cross-user-bleed boundary — #1205b-1) ──────────────
+//
+// The per-user isolation that prevents cross-user bleed lives HERE, not in the
+// LLM: /ReflectMemories only ever hands the model the memories this predicate
+// admits, and generateCandidates() then enforces every candidate's
+// sourceMemoryIds ⊆ the gathered set (parseAndValidateCandidates,
+// "source_id_out_of_set"). So the gathered set is the *ceiling* on any
+// candidate's sources — if this predicate admits only ONE adk:<app>:<user>
+// tag's memories, a candidate physically cannot cite another user's memory.
+//
+// scope:"tagged" is the isolation mode the tag-aware nightly runner
+// (src/rem/runner.ts) drives once per active adk:<app>:<user> tag. scope:
+// "recent"/"all" are the pre-#1205b agentId-wide modes — correct for a
+// single-tenant agent, but for an ADK agentId (which collapses every
+// (app,user) into one agentId, distinguishing users only by tag) they gather
+// EVERY user's memories together, which is exactly the bleed #1205 fixes.
+//
+// Extracted as a pure predicate so the isolation is unit-testable without
+// Harper (the resource's gather loop streams from databases.flair.Memory).
+// Archived/permanent filtering stays in the resource — those are eligibility
+// rules, not scope selection.
+export function memoryMatchesReflectScope(record, params) {
+    const { scope, tag, sinceDate } = params;
+    if (scope === "tagged") {
+        // No tag ⇒ admit nothing. A tagged reflection with no tag must gather an
+        // EMPTY set (fail-closed), never fall through to admitting everything —
+        // that would silently become an agentId-wide distill (cross-user bleed).
+        if (!tag)
+            return false;
+        return (record.tags ?? []).includes(tag);
+    }
+    if (scope === "recent") {
+        if (!record.createdAt)
+            return false;
+        return new Date(record.createdAt) >= sinceDate;
+    }
+    // scope === "all" (or any unknown scope) admits everything eligible.
+    return true;
+}
+// ─── Staged candidate row (stamps the authoritative scope tag — #1205b-1) ────
+//
+// Builds the MemoryCandidate row /ReflectMemories persists. The load-bearing
+// addition over an inline object literal is `scopeTag`: when the distillation
+// ran under scope:"tagged" with a known tag, that tag is AUTHORITATIVE context
+// (the engine distilled exactly that one tag), so it is stamped onto the row.
+// Downstream promotion (src/cli.ts derivePromotedTags' stamped-tag override)
+// consumes this stamped tag directly instead of re-reading the source
+// memories — which closes the #1205a seam: an ADK-sourced candidate whose
+// sources are all later unreadable still carries its per-user scope tag and
+// promotes correctly (never tagless into the shared agentId namespace).
+//
+// Non-tagged distillations (scope:"recent"/"all") leave scopeTag ABSENT
+// (undefined) — the field is nullable/additive and promotion falls back to the
+// source-re-read classification for those, unchanged.
+export function buildStagedCandidateRow(params) {
+    const row = {
+        id: params.id,
+        agentId: params.agentId,
+        claim: params.claim,
+        sourceMemoryIds: params.sourceMemoryIds,
+        rationalePrompt: params.rationalePrompt,
+        generatedBy: params.generatedBy,
+        generatedAt: params.generatedAt,
+        status: "pending",
+    };
+    if (params.scope === "tagged" && typeof params.tag === "string" && params.tag.length > 0) {
+        row.scopeTag = params.tag;
+    }
+    return row;
+}

package/dist/resources/token-estimate.js

@@ -0,0 +1,25 @@
+/**
+ * token-estimate.ts — the ONE token estimator the bootstrap payload budget and
+ * `tokenEstimate` report are computed with.
+ *
+ * Extracted to a harper-free module (no `import ... from "harper"`) for two
+ * reasons:
+ *
+ *   1. Single source of truth. `MemoryBootstrap` computes both its content-
+ *      selection budget and the reported `tokenEstimate` with THIS function, so
+ *      there is exactly one definition of "how many tokens is this text".
+ *   2. The flair#1213 connector-conformance suite asserts the tokenEstimate
+ *      invariant — `tokenEstimate === estimateTokens(JSON.stringify(deliveredPayload))`
+ *      — with the SAME estimator, not a byte length or a different tokenizer
+ *      (Kern #1 / Sherlock #2). Importing this module (which never pulls in
+ *      Harper) lets a plain bun:test process reconstruct the estimate exactly,
+ *      so the invariant catches the flair#1199 double-serialization class
+ *      without being brittle to a future estimator change: change the formula
+ *      here and both the report and the invariant move together.
+ *
+ * The estimate is deliberately coarse (~4 chars per token for English text). It
+ * is a budgeting/reporting heuristic, never a billing figure.
+ */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}

package/docs/mcp-clients.md

@@ -240,6 +240,14 @@ Writes are scoped per-agent (your `FLAIR_AGENT_ID`) and enforced by Flair's serv
 
 Which memories are non-private is decided at write time, and the default is not "shared". `memory_store` defaults `durability` to `standard`, and the server derives visibility from durability — `permanent`/`persistent` → `shared`, `standard`/`ephemeral` → `private` — so **a bare `memory_store` call writes an owner-only memory that no other agent can read.** Pass `visibility: "shared"` (or `"private"`, to be explicit) to say what you mean; the tool reports the visibility the write actually landed on so an agent can confirm it rather than assume.
 
+### Reading the `bootstrap` payload
+
+`bootstrap` returns the canonical structured containers — `soul`, `memories`, `predicted`, `teammateFindings`, `events` — plus counts and a `tokenEstimate`. The containers are **always present** (empty `[]`/`{}` when there's nothing), so an empty container is distinguishable from an unsupported one.
+
+**Empty containers say why they're empty (flair#1182).** When a structured container ships empty, the payload carries a short hint naming the reason and what fills it — `eventsHint`, `teammateFindingsHint`, `predictedHint`. This is present *only* when the container is empty, so a deliberately-empty container is never confused with a silent drop (a connector never has to diff against a previous payload to tell the two apart).
+
+**`matchQuality` is null on lifecycle sections — by design (flair#1225).** With `includeTrust: true`, each included memory carries a per-memory trust block, section-tagged, whose `matchQuality` is a `strong`/`moderate`/`breadcrumb` confidence band. On the **lifecycle sections** (`permanent`, `recent`, `predicted`) `matchQuality` is `null`: those are a lifecycle-window *load*, not a retrieval surface, so there is no relevance score to band. This is **correct, not a scoring failure** — an own-recent `null` next to a teammate's band does not mean your own records "scored worse". A retrieval band is only meaningful on the retrieval sections (`relevant`, `teammate`). The entry's `section` field makes this legible, and a `matchQualityNote` on any null entry states the reason inline.
+
 ---
 
 ## Configuration reference

package/docs/rem.md

@@ -1,6 +1,6 @@
 # REM — reflection, distillation, and review
 
-REM (Reflect · Extract · Merge) is Flair's memory-curation cycle: it reads an agent's recent memories, distills them into candidate insights, and stages those candidates for explicit human/agent review — nothing is ever auto-promoted. `flair rem rapid` runs it on demand; `flair rem nightly enable` runs it on a schedule. See [`docs/notes/rem-ux.md`](notes/rem-ux.md) for the full trigger model, locality guarantees, and the review-loop UX this page's commands feed into.
+REM (Reflect · Extract · Merge) is Flair's memory-curation cycle: it reads an agent's recent memories, distills them into candidate insights, and stages those candidates for explicit human/agent review — nothing is auto-promoted except the narrow ADK per-user path (see [Auto-promote](#auto-promote-adk-only)). `flair rem rapid` runs it on demand; `flair rem nightly enable` runs it on a schedule. See [`docs/notes/rem-ux.md`](notes/rem-ux.md) for the full trigger model, locality guarantees, and the review-loop UX this page's commands feed into.
 
 > **⚠️ Prerequisite: a configured generative backend.** All REM commands (`rapid`, `nightly`, `candidates`, `promote`, `reject`) require Harper's `models.generate()` to be wired — without it, REM calls fail with `Reflection error: No generative backend configured`. Set up a backend first (see [Configuration](#configuration) below) before running any REM command. The fastest path is Ollama with a non-thinking model, which needs zero credentials and keeps all traffic local.
 
@@ -59,4 +59,21 @@ Snapshot locality follows from this: a nightly cycle's pre-run snapshot (`~/.fla
 - **Interactive (`flair rem rapid`):** one bounded, synchronous distillation call — gather cap 50 memories, bounded output tokens, seconds not minutes. Executes by default, staging candidates and printing a summary; `--prompt-only` returns the reflection prompt instead, for the bring-your-own-model handoff.
 - **Nightly (`flair rem nightly enable` / `run-once`):** fully detached — the scheduler runs the full cycle (snapshot → maintenance → distillation), candidates land as pending rows, and an audit row lands in `~/.flair/logs/rem-nightly.jsonl`. The operator reviews in the morning via `flair rem candidates`.
 
-Either path, the review loop is the same: `flair rem candidates` lists pending rows, `flair rem promote <id> --rationale "<why>"` / `flair rem reject <id> --reason "<why>"` decide them. Nothing self-promotes — see [`docs/notes/rem-ux.md`](notes/rem-ux.md) for why that gate is load-bearing and how the surface is expected to evolve.
+Either path, the review loop is the same: `flair rem candidates` lists pending rows, `flair rem promote <id> --rationale "<why>"` / `flair rem reject <id> --reason "<why>"` decide them. Nothing self-promotes except the narrow ADK per-user path ([Auto-promote](#auto-promote-adk-only)) — see [`docs/notes/rem-ux.md`](notes/rem-ux.md) for why that gate is load-bearing and how the surface is expected to evolve.
+
+### ADK agents — per-user (per-tag) distillation
+
+adk-flair collapses every `(app, user)` into **one** Flair agentId, separating users only by a per-user tag `adk:<app>:<user>`. Distilling such an agentId with the default `scope:"recent"` would mix every user's sessions into shared claims — cross-user bleed. The nightly cycle therefore detects the agent's active `adk:<app>:<user>` tags (from the memories it already loads for the snapshot, with a recency cutoff that skips idle users and is scoped to the agent's own records) and runs distillation **once per tag** under `scope:"tagged"`, so each user's candidates come only from that user's own sessions. Agents with no `adk:` tags distill agentId-wide exactly as before.
+
+A candidate distilled under a tag records that tag in its `scopeTag` field. `flair rem promote` reads `scopeTag` as the authoritative per-user lineage tag and propagates it onto the promoted memory — so the promoted claim stays in that user's retrieval scope even if the source episodes are later archived or deleted. The single-node timer rule above is unchanged; the per-tag loop runs inside the one cycle on the one node. The non-thinking-model requirement (above) still holds — the per-tag path calls the same `models.generate()` route.
+
+#### Auto-promote (ADK only)
+
+For ADK agents, the nightly cycle **auto-promotes** these `scopeTag`-bearing candidates to the user's own persistent memory immediately after distillation — the one place REM does not wait for a human `rem promote`. The safety argument is blast-radius, not identity: the claim is distilled from a user's own sessions into that same user's own tag scope, so no cross-agent or Soul trust boundary is crossed. The promotion is enforced entirely server-side (`POST /AutoPromoteCandidates`), never by a CLI flag a compromised agent key could flip, and holds four invariants:
+
+- **Memory only, never Soul.** The target is hard-locked to `memory`; there is no Soul code path (Soul is agentId-scoped and cannot carry a per-user tag, so an ADK-sourced Soul promotion would be cross-user by construction).
+- **Fail-closed tag lineage.** A candidate is promoted only if it carries an authoritative `adk:<app>:<user>` scope tag, which the promoted memory then carries. The promoted memory is written `visibility:"private"` (owner-only) — not the org-open `shared` default a `persistent` write would otherwise get — so it is reachable only through the app agent's own tag-filtered search (which re-verifies the tag), invisible both to another user's tag filter and to every other agent on the instance. A candidate whose scope tag is absent or blank is left pending, never promoted tagless into the shared agentId namespace.
+- **Content-safety, strict.** The claim is scanned for prompt injection and refused on a flag regardless of `FLAIR_CONTENT_SAFETY` — an unattended write does not fall back to warn-and-tag.
+- **Non-impersonating reviewer.** The promoted memory and its candidate record `machine:adk-auto-promote`, never a value mistakable for a human or agent reviewer.
+
+Anything ineligible (no scope tag, flagged content, already decided) is left pending for the human `rem promote` path. The step is bounded per cycle and non-fatal; `flair rem nightly run-once` reports the count auto-promoted. **Non-ADK candidates never auto-promote** — the human review gate below is unchanged for them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.44.9",
+  "version": "0.44.11",
   "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",

package/schemas/memory.graphql

@@ -210,4 +210,13 @@ type MemoryCandidate @table(database: "flair") @export {
   reviewRationale: String          # required on promote/reject (no rubber-stamp)
   decidedAt: String
   supersedes: String @indexed      # previous rejected candidate this replaces
+  scopeTag: String                 # #1205b-1: the authoritative scope:"tagged" tag this candidate was
+                                   # distilled under (e.g. adk:<app>:<user>). Stamped at distillation time by
+                                   # resources/MemoryReflect.ts when scope="tagged", so promotion can consume
+                                   # the per-user scope tag DIRECTLY (src/cli.ts derivePromotedTags' stamped-tag
+                                   # override) instead of re-reading source memories — closing the #1205a seam
+                                   # where an ADK-sourced candidate with all-unreadable sources yields no adk:
+                                   # evidence and would promote tagless (a cross-user leak). Nullable/additive —
+                                   # pre-#1205b candidates and non-tagged (scope:"recent"/"all") distillations
+                                   # read null, unchanged behavior (clean-upgrade-path gate).
 }