@tpsdev-ai/flair 0.44.9 → 0.44.10

package/dist/resources/mcp-tools.js

@@ -116,14 +116,34 @@ async function unwrap(value) {
     return value;
 }
 /**
- * flair#1188 — remove the raw `embedding` vector from a record before it is
- * returned over the MCP surface. A stored memory carries a 768-float
- * `embedding` (the HNSW vector); inlined into a tool result that is thousands
- * of noise tokens per record on chat connectors that have a fixed context
- * budget, and the caller can never do anything useful with it. Returns a
- * shallow copy WITHOUT `embedding` (never mutates the source record), and
- * passes through anything that is not a plain record — null, primitives,
- * arrays, and the `{ error, status }` shapes `unwrap` produces — untouched.
+ * flair#1188 — the internal, embedding-engine-owned fields a memory record
+ * carries that must NEVER cross the MCP surface. Both are server-managed and
+ * useless (or misleading) to a connector:
+ *
+ *   - `embedding`     — the raw 768-float HNSW vector; thousands of noise
+ *                       tokens per record on a fixed-budget chat connector, and
+ *                       the caller can do nothing with it (flair#1188).
+ *   - `embeddingModel` — the model id stamped on every write
+ *                       (resources/Memory.ts stamps `content.embeddingModel =
+ *                       getModelId()`; schemas/memory.graphql declares it
+ *                       @indexed). The WRITE wrappers already treat it as
+ *                       internal — memory_update `delete`s it from both the
+ *                       overwrite and the supersede record — so the READ path
+ *                       must strip it too, or memory_get leaks an internal
+ *                       field the write echoes hide (flair#1213, Sherlock #1).
+ *
+ * Exported so the flair#1213 conformance "no leaked internal fields" invariant
+ * enumerates the SAME list this function strips: the strip and the assertion
+ * cannot drift, and adding a field here automatically extends both.
+ */
+export const INTERNAL_MEMORY_FIELDS = ["embedding", "embeddingModel"];
+/**
+ * flair#1188 / flair#1213 — remove the internal embedding-engine fields (see
+ * `INTERNAL_MEMORY_FIELDS`) from a record before it is returned over the MCP
+ * surface. Returns a shallow copy WITHOUT those fields (never mutates the
+ * source record), and passes through anything that is not a plain record —
+ * null, primitives, arrays, and the `{ error, status }` shapes `unwrap`
+ * produces — untouched.
  *
  * `memory_search` already projects with an explicit select that omits
  * `embedding` (resources/semantic-retrieval-core.ts's DEFAULT_SELECT), and
@@ -131,13 +151,21 @@ async function unwrap(value) {
  * needed on the FULL-record read/write paths (memory_get, and the write
  * responses that echo the stored row).
  */
-function stripEmbedding(value) {
+function stripInternalFields(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return value;
-    if (!("embedding" in value))
-        return value;
-    const { embedding, ...rest } = value;
-    return rest;
+    let out = value;
+    let copied = false;
+    for (const field of INTERNAL_MEMORY_FIELDS) {
+        if (field in out) {
+            if (!copied) {
+                out = { ...out };
+                copied = true;
+            }
+            delete out[field];
+        }
+    }
+    return out;
 }
 // ── Tool implementations (thin wrappers over existing handlers) ──────────────
 //
@@ -217,7 +245,7 @@ async function memoryStore(agent, args) {
     // flair#1188 — memory_store's response goes through the same buildWriteResponse
     // echo as memory_update; strip the server-regenerated embedding so no write
     // tool ever inlines the vector. No-op when the response carries none.
-    return stripEmbedding(await unwrap(await h.post(body)));
+    return stripInternalFields(await unwrap(await h.post(body)));
 }
 /**
  * memory_update — id-targeted, dedup-BYPASSED overwrite/version path (memory-
@@ -248,8 +276,18 @@ async function memoryUpdate(agent, args) {
     // `new Cls(undefined, ctx).get(id)` returned `undefined` for the caller's own
     // record (getProperty on an unloaded instance), so memory_update 404'd
     // ("memory not found") on the connector path before it ever reached a write.
-    const existing = await Cls.get(id, delegationContext(agent));
-    if (!existing) {
+    //
+    // flair#1213 — the get MUST be `unwrap`ped (as memoryGet does), not consumed
+    // raw. Memory.get()'s makeByIdReadGate returns a NOT_FOUND() *Response* (404)
+    // for an absent or non-readable id — a TRUTHY object with no `id` — so the
+    // bare `if (!existing)` guard never fired: the code fell through and PUT a
+    // record whose id spread off the Response as `undefined`, throwing the
+    // MISDIRECTING "Invalid primary key of null" instead of a clean 404. This is
+    // the same by-id-read-on-the-connector-seam class as #1181, caught by the
+    // conformance error contract (Kern #5). Unwrap, then treat a 404/error/absent
+    // result as "not found".
+    const existing = await unwrap(await Cls.get(id, delegationContext(agent)));
+    if (!existing || existing.error != null || existing.status === 404) {
         return { error: "memory not found", status: 404 };
     }
     if (preserveHistory) {
@@ -291,7 +329,7 @@ async function memoryUpdate(agent, args) {
         // flair#1188 — the write response echoes the stored row (Memory.post
         // regenerates the embedding server-side), so strip the vector before it
         // returns over the MCP surface. No-op when the response carries none.
-        return stripEmbedding(await unwrap(await coll.post(record)));
+        return stripInternalFields(await unwrap(await coll.post(record)));
     }
     const merged = { ...existing, content, updatedAt: new Date().toISOString() };
     delete merged.embedding;
@@ -310,7 +348,7 @@ async function memoryUpdate(agent, args) {
     // Memory.put()'s own ownership gate — no scope change, same as the read.
     // flair#1188 — strip the embedding from the echoed write response (Memory.put
     // regenerates the vector server-side); no-op when the response carries none.
-    return stripEmbedding(await unwrap(await Cls.put(merged, delegationContext(agent))));
+    return stripInternalFields(await unwrap(await Cls.put(merged, delegationContext(agent))));
 }
 async function memoryGet(agent, args) {
     const Cls = await handler("Memory");
@@ -338,7 +376,7 @@ async function memoryGet(agent, args) {
     // Strip it by default so a chat connector isn't flooded with thousands of
     // useless tokens per record; return it only when the caller explicitly opts
     // in via includeEmbedding.
-    return args?.includeEmbedding === true ? result : stripEmbedding(result);
+    return args?.includeEmbedding === true ? result : stripInternalFields(result);
 }
 async function memoryDelete(agent, args) {
     const Cls = await handler("Memory");
@@ -380,6 +418,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;
+    // flair#1199 — org-event knobs. `includeEventDetail` opts the verbose per-event
+    // `detail` JSON back in (default OFF: a connector reads lean events); `maxEvents`
+    // overrides the default cap. Both forwarded ONLY when set, so a plain bootstrap
+    // delegates a byte-identical body.
+    if (args?.includeEventDetail === true)
+        body.includeEventDetail = true;
+    if (args?.maxEvents !== undefined)
+        body.maxEvents = args.maxEvents;
     // 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.
@@ -497,6 +543,51 @@ async function recordUsage(agent, args) {
         : typeof args?.memoryId === "string" ? [args.memoryId] : undefined;
     return unwrap(await h.post({ memoryIds, attribution: args?.attribution }));
 }
+/**
+ * flair#1213 completeness gate — FAIL-CLOSED (the flair#953 lesson, Sherlock
+ * #3). Every tool shipped in `tools` must carry a `.contract`; a new /mcp tool
+ * without one fails the build.
+ *
+ * The fail-closed part is the point: if the registry cannot be enumerated — it
+ * is not a plain object (a broken import left it `undefined`), or it is empty —
+ * this returns `ok:false` with `examined:0`, NEVER a vacuous "0 tools examined,
+ * 0 missing, pass". A check that could not run must not render as passed. The
+ * conformance suite asserts both `ok` AND `examined > 0` so the vacuous path
+ * cannot masquerade as coverage; the fail-closed unit test exercises every
+ * branch.
+ */
+export function checkContractCompleteness(tools) {
+    if (!tools || typeof tools !== "object" || Array.isArray(tools)) {
+        return {
+            ok: false,
+            examined: 0,
+            missing: [],
+            reason: "TOOLS registry is not an enumerable object (unloadable import?) — refusing to pass vacuously",
+        };
+    }
+    const names = Object.keys(tools);
+    if (names.length === 0) {
+        return {
+            ok: false,
+            examined: 0,
+            missing: [],
+            reason: "TOOLS registry is empty — refusing to pass vacuously (a new tool must carry a conformance contract)",
+        };
+    }
+    const missing = names.filter((n) => {
+        const entry = tools[n];
+        return !entry || !entry.contract || typeof entry.contract !== "object";
+    });
+    return {
+        ok: missing.length === 0,
+        examined: names.length,
+        missing,
+        reason: missing.length
+            ? `${missing.length} tool(s) shipped with no conformance contract: ${missing.join(", ")}. `
+                + "Add a `contract` to each in resources/mcp-tools.ts (co-located with its def+impl)."
+            : undefined,
+    };
+}
 /**
  * Verb→tool-name overrides — the three naming quirks where the shipped tool
  * name isn't record-types.ts's default `${toolPrefix}_${verb}` shape (see
@@ -547,6 +638,16 @@ export const TOOLS = {
             },
         },
         impl: memorySearch,
+        contract: {
+            summary: "{ results: MemoryRecord[] } — semantic hits scoped to the caller's own + granted memories; each hit carries content, never the raw embedding.",
+            requiredFields: ["results"],
+            fieldTypes: { results: "array" },
+            invariants: {
+                selfDescribingEmpty: [{ path: "results", type: "array" }],
+                containerRules: [{ container: "results", requiredFields: ["id", "content"], forbiddenFields: INTERNAL_MEMORY_FIELDS }],
+                fullyResolved: true,
+            },
+        },
     },
     memory_store: {
         def: {
@@ -574,6 +675,14 @@ export const TOOLS = {
             },
         },
         impl: memoryStore,
+        contract: {
+            summary: "Write echo { id, written:true, deduplicated } — the new id + confirmation. No internal embedding fields; round-trips via memory_get.",
+            requiredFields: ["id", "written"],
+            fieldTypes: { id: "string", written: "boolean", deduplicated: "boolean" },
+            forbiddenFields: INTERNAL_MEMORY_FIELDS,
+            invariants: { fullyResolved: true },
+            errorShape: { trigger: "an unrecognized visibility value (e.g. \"prvate\")", fields: ["error", "status"], mustNotLeak: INTERNAL_MEMORY_FIELDS },
+        },
     },
     memory_update: {
         def: {
@@ -592,6 +701,14 @@ export const TOOLS = {
             },
         },
         impl: memoryUpdate,
+        contract: {
+            summary: "Write echo { id, written:true } for the in-place overwrite (or supersede). No internal embedding fields; the change round-trips via memory_get.",
+            requiredFields: ["id", "written"],
+            fieldTypes: { id: "string", written: "boolean" },
+            forbiddenFields: INTERNAL_MEMORY_FIELDS,
+            invariants: { fullyResolved: true },
+            errorShape: { trigger: "updating a non-existent id", fields: ["error", "status"] },
+        },
     },
     memory_get: {
         def: {
@@ -609,6 +726,14 @@ export const TOOLS = {
             },
         },
         impl: memoryGet,
+        contract: {
+            summary: "The full memory record { id, agentId, content, durability, createdAt, ... } for the caller's own id — embedding + embeddingModel stripped by default.",
+            requiredFields: ["id", "agentId", "content", "createdAt"],
+            fieldTypes: { id: "string", agentId: "string", content: "string" },
+            forbiddenFields: INTERNAL_MEMORY_FIELDS,
+            invariants: { fullyResolved: true },
+            errorShape: { trigger: "get a non-existent / unowned id (makeByIdReadGate 404)", fields: ["error", "status"] },
+        },
     },
     memory_delete: {
         def: {
@@ -622,6 +747,11 @@ export const TOOLS = {
             },
         },
         impl: memoryDelete,
+        contract: {
+            summary: "Deletes the caller's own memory (success echo is thin). The permanent-memory guard returns { error, status:403 } for a non-admin; the row round-trips as gone via memory_get.",
+            invariants: { fullyResolved: true },
+            errorShape: { trigger: "a non-admin deletes a permanent memory", fields: ["error", "status"] },
+        },
     },
     bootstrap: {
         def: {
@@ -644,10 +774,70 @@ export const TOOLS = {
                     includeTrust: { type: "boolean", description: "Also return a `trust` array with a per-included-memory trust-evidence block (provenance, author, usage, freshness, supersession). Default false." },
                     abstain: { type: "boolean", description: "Opt into a task-relevance abstention verdict: also return an `abstention` object ({ abstained, bestScore, threshold }) reporting whether any memory covered `currentTask` above a global confidence threshold. Default false." },
                     includeContext: { type: "boolean", description: "Also return the prose `context` string — a human-readable mirror of the structured soul/memories/predicted/teammateFindings containers (which are the canonical payload). Default false here: the structured fields already carry everything, so shipping the prose too would double the payload." },
+                    maxEvents: { type: "number", description: "Cap on how many recent org events to return (default 10). Events are counted against maxTokens like every other content section." },
+                    includeEventDetail: { type: "boolean", description: "Also include each org event's verbose `detail` JSON (migration internals, etc.). Default false: bootstrap ships lean events (id/kind/summary/createdAt/targetIds/scope); `detail` mostly restates the summary and is pure bloat for a connector." },
                 },
             },
         },
         impl: bootstrap,
+        contract: {
+            summary: "Session context: { agentId, soul, memories, predicted, teammateFindings, events, sections, tokenEstimate, memoriesIncluded, ..., context, flairVersion }. "
+                + "Structured containers are canonical and always present; prose `context` is a pointer at the /mcp default (includeContext opt-in).",
+            requiredFields: [
+                "agentId", "soul", "memories", "predicted", "teammateFindings", "events",
+                "sections", "tokenEstimate", "maxTokens", "memoriesIncluded", "memoriesAvailable",
+                "memoriesTruncated", "teammateFindingsIncluded", "teammateFindingsTruncated",
+                "teammateFindingsMatched", "context", "flairVersion",
+            ],
+            fieldTypes: {
+                agentId: "string", soul: "object", memories: "array", predicted: "array",
+                teammateFindings: "array", events: "array", sections: "object",
+                tokenEstimate: "number", maxTokens: "number", memoriesIncluded: "number",
+                memoriesAvailable: "number", memoriesTruncated: "number",
+                teammateFindingsIncluded: "number", teammateFindingsTruncated: "number",
+                teammateFindingsMatched: "number", context: "string", flairVersion: "string",
+            },
+            invariants: {
+                // count == delivered — the historical count/charge/deliver drift.
+                countEqualsDelivered: [
+                    // memoriesIncluded spans BOTH own-memory containers (see the type doc).
+                    { count: "memoriesIncluded", containers: ["memories", "predicted"] }, // #1199
+                    { count: "teammateFindingsIncluded", containers: ["teammateFindings"] }, // #1199
+                    { count: "sections.events", containers: ["events"] }, // #1206
+                ],
+                // present + typed even when empty — never a bare {} / missing key (#1182).
+                selfDescribingEmpty: [
+                    { path: "soul", type: "object" }, { path: "memories", type: "array" },
+                    { path: "predicted", type: "array" }, { path: "teammateFindings", type: "array" },
+                    { path: "events", type: "array" }, { path: "sections", type: "object" },
+                ],
+                // #1200 — dedup by the SEMANTIC content key (excludes id/createdAt, which
+                // vary across physical duplicate rows). See ToolInvariants.dedupSignature.
+                dedupSignature: { container: "events", signatureFields: ["kind", "summary", "detail", "targetIds"] },
+                // #1199 — tokenEstimate via the wrapper's own estimator over the delivered
+                // payload (minus the two fields added after it was measured).
+                tokenEstimate: { field: "tokenEstimate", excludeKeys: ["tokenEstimate", "flairVersion"] },
+                // #1199 — the reported estimate must respect the requested budget: the
+                // events blowout (uncounted org events) drove maxTokens=4000 → 6286. The
+                // tolerance covers the fixed JSON scaffolding + the #1207 prose-vs-
+                // structured charge gap; uncounted content does not fit under it.
+                budgetCap: { estimate: "tokenEstimate", budget: "maxTokens", tolerance: 0.25 },
+                // #1207 — count arithmetic: included + truncated <= available, for own
+                // memories AND teammate findings (each a disjoint split of its pool).
+                countCoherence: [
+                    { included: "memoriesIncluded", truncated: "memoriesTruncated", available: "memoriesAvailable" },
+                    { included: "teammateFindingsIncluded", truncated: "teammateFindingsTruncated", available: "teammateFindingsMatched" },
+                ],
+                // #1199 — prose is a pointer at the default, not a second copy.
+                proseContextIsPointerAtDefault: { field: "context" },
+                // shape of the structured containers a connector reads; #1188 leak bites on memories.
+                containerRules: [
+                    { container: "events", requiredFields: ["id", "kind", "summary", "createdAt"] },
+                    { container: "memories", requiredFields: ["id", "content"], forbiddenFields: INTERNAL_MEMORY_FIELDS },
+                ],
+                fullyResolved: true, // #1182 — never a spread pending Promise collapsing to {flairVersion}.
+            },
+        },
     },
     soul_set: {
         def: {
@@ -663,6 +853,10 @@ export const TOOLS = {
             },
         },
         impl: soulSet,
+        contract: {
+            summary: "Writes a soul entry keyed `${agentId}:${key}`, attributed to the caller. Correctness is proven by the soul_get round-trip — this is the write flair#1181 broke on the connector path.",
+            invariants: { fullyResolved: true },
+        },
     },
     soul_get: {
         def: {
@@ -676,6 +870,12 @@ export const TOOLS = {
             },
         },
         impl: soulGet,
+        contract: {
+            summary: "The soul entry { id, agentId, key, value, createdAt } for the caller's own `${agentId}:${key}`.",
+            requiredFields: ["id", "agentId", "key", "value", "createdAt"],
+            fieldTypes: { id: "string", agentId: "string", key: "string", value: "string" },
+            invariants: { fullyResolved: true },
+        },
     },
     flair_workspace_set: {
         def: {
@@ -695,6 +895,10 @@ export const TOOLS = {
             },
         },
         impl: workspaceSet,
+        contract: {
+            summary: "Writes the caller's workspace state keyed `${agentId}:${ref}`, attributed to the caller (never the body). The echo is thin; persistence is verified in storage.",
+            invariants: { fullyResolved: true },
+        },
     },
     flair_orgevent: {
         def: {
@@ -713,6 +917,10 @@ export const TOOLS = {
             },
         },
         impl: orgEvent,
+        contract: {
+            summary: "Publishes an org event attributed to the caller (authorId from identity, never the body). The echo is thin; persistence is verified in storage.",
+            invariants: { fullyResolved: true },
+        },
     },
     attention: {
         def: {
@@ -731,6 +939,15 @@ export const TOOLS = {
             },
         },
         impl: attention,
+        contract: {
+            summary: "Grouped-by-source view { entity, windowDays, since, groups:{memory,relationship,workspaceState,presence,orgEvent}, counts } for entity E over N days.",
+            requiredFields: ["entity", "windowDays", "groups", "counts"],
+            fieldTypes: { entity: "string", windowDays: "number", groups: "object", counts: "object" },
+            invariants: {
+                selfDescribingEmpty: [{ path: "groups", type: "object" }, { path: "counts", type: "object" }],
+                fullyResolved: true,
+            },
+        },
     },
     record_usage: {
         def: {
@@ -748,6 +965,12 @@ export const TOOLS = {
             },
         },
         impl: recordUsage,
+        contract: {
+            summary: "Invariant acknowledgement { recorded:true } — byte-identical regardless of how many ids counted (no id enumeration, Sherlock).",
+            requiredFields: ["recorded"],
+            fieldTypes: { recorded: "boolean" },
+            invariants: { fullyResolved: true },
+        },
     },
 };
 /** The tool definitions for a tools/list response (exactly the 12 curated tools). */

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/rem.md

@@ -60,3 +60,9 @@ Snapshot locality follows from this: a nightly cycle's pre-run snapshot (`~/.fla
 - **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.
+
+### 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.

package/package.json

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