@tpsdev-ai/flair 0.44.8 → 0.44.10

package/dist/resources/MemoryBootstrap.js

@@ -2,7 +2,7 @@ import { Resource, databases } from "harper";
 import { allowVerified, resolveAgentAuth } from "./agent-auth.js";
 import { getEmbedding } from "./embeddings-provider.js";
 import { wrapUntrusted } from "./content-safety.js";
-import { isTeammate, formatTeamLine } from "./memory-bootstrap-lib.js";
+import { isTeammate, formatTeamLine, isZeroRowNoOpEvent } from "./memory-bootstrap-lib.js";
 import { resolveReadScope } from "./memory-read-scope.js";
 import { isValidEntity } from "./entity-vocab.js";
 import { withDetachedTxn } from "./table-helpers.js";
@@ -17,6 +17,7 @@ import { buildCollisionEntries, buildEntityMatchCondition, freshPresenceByAgent,
 import { retrieveCandidates, DEFAULT_SELECT } from "./semantic-retrieval-core.js";
 import { buildTrustBlock } from "./trust-block.js";
 import { bestSemanticSimilarity, evaluateAbstention } from "./abstention.js";
+import { estimateTokens } from "./token-estimate.js";
 /**
  * POST /MemoryBootstrap
  *
@@ -72,9 +73,10 @@ import { bestSemanticSimilarity, evaluateAbstention } from "./abstention.js";
  *   row's `entities`.
  *
  * Response:
- *   { context, sections, tokenEstimate, memoriesIncluded, memoriesAvailable,
- *     teammateFindingsIncluded, agentId, scope, soul, memories, predicted,
- *     teammateFindings[, currentTaskHint][, predictedHint] }
+ *   { context, sections, tokenEstimate, maxTokens, memoriesIncluded, memoriesAvailable,
+ *     memoriesTruncated, teammateFindingsIncluded, teammateFindingsTruncated,
+ *     teammateFindingsMatched, agentId, scope, soul, memories, predicted,
+ *     teammateFindings, events[, currentTaskHint][, predictedHint] }
  *   The self-describing keys (flair#1182 part 1) — `agentId` (resolved caller),
  *   `scope` (read model applied to the caller), `soul`/`memories`/`predicted`
  *   (the caller's OWN records as structured containers), and `currentTaskHint`
@@ -84,14 +86,48 @@ import { bestSemanticSimilarity, evaluateAbstention } from "./abstention.js";
  *   mirror (opt-in via includeContext). Cross-agent teammate findings ship in
  *   the `teammateFindings` container (own memories in `memories`), counted by
  *   `teammateFindingsIncluded` (a separate denominator from `memoriesIncluded`,
- *   which is own-scoped so it never exceeds `memoriesAvailable`). `tokenEstimate`
- *   reflects the ACTUAL serialized payload, and `maxTokens` bounds it.
+ *   which is own-scoped so it never exceeds `memoriesAvailable`). flair#1206 —
+ *   org events ship in their OWN structured `events` container (ALWAYS present,
+ *   `[]` when none), so a connector reading the structured payload gets them even
+ *   when the prose `context` is off (the /mcp default); before #1206 they lived
+ *   ONLY in the prose string and were orphaned at includeContext=false.
+ *
+ *   CAP CONTRACT: `maxTokens` is the HARD cap on CONTENT SELECTION — the shared
+ *   `tokenBudget` starts at `maxTokens` and every admitted soul/memory/finding
+ *   line AND every org event (flair#1199 — events are content too; before this
+ *   they were assembled but NEVER charged, so a maxTokens=4000 request serialized
+ *   at 6286) is gated against the remaining budget, so the sum of selected CONTENT
+ *   never exceeds `maxTokens`. `tokenEstimate` HONESTLY reports the real serialized
+ *   payload (`JSON.stringify(responseBody)`), which includes the FIXED structured-
+ *   container JSON scaffolding (keys/braces, counters, the sections map) and so may
+ *   exceed `maxTokens` slightly by that bounded overhead — measurement is decoupled
+ *   from budgeting, but the overhead is now scaffolding ONLY, never uncounted
+ *   content. The connector-conformance suite asserts tokenEstimate <= maxTokens
+ *   within a small tolerance for that scaffolding. flair#1207: #1199 had ALSO
+ *   folded a per-item structured overhead + a scaffolding reserve INTO the
+ *   selection budget, which silently shrank recall below 0.44.6 for the same
+ *   `maxTokens`; that per-item overhead is a reporting concern (already captured by
+ *   `tokenEstimate`) and no longer shrinks the content budget.
+ *
+ *   COUNT CONTRACT (flair#1207): `memoriesIncluded + memoriesTruncated <=
+ *   memoriesAvailable` — included and truncated are disjoint sets of UNIQUE own
+ *   memories (a memory budget-skipped in one section but admitted in another counts
+ *   as included, never both). `teammateFindingsMatched` is the teammate match pool
+ *   that cleared the relevance floor; `teammateFindingsIncluded +
+ *   teammateFindingsTruncated == teammateFindingsMatched`, so "truncated" means
+ *   "relevant but no budget," not "every candidate not selected."
  *   `predictedHint` is present only when subjects were provided but `predicted`
  *   came back empty.
  */
 // Collision surfacing (flair#681) tunables.
 const COLLISION_WINDOW_DAYS = 7;
 const MAX_COLLISION_ENTRIES = 10;
+// flair#1199/#1206 — the default cap on how many org events bootstrap ships.
+// Overridable per-request via `maxEvents`. Event slots are scarce AND (as of
+// #1199) token-charged, so this bounds both the count and the spend; the shared
+// tokenBudget is the harder ceiling (an event that doesn't fit is skipped even
+// under the cap).
+const MAX_ORG_EVENTS = 10;
 // ─── Bootstrap scale fix (flair-bootstrap-scale-fix) tunables ───────────────
 //
 // Own-scoped, non-permanent memories (the "recent" adaptive-window source,
@@ -123,21 +159,23 @@ const MAX_CANDIDATE_POOL = 100;
 // `minScore` request param) — preserved verbatim from the original raw
 // JS dot-product scan's `.filter((s) => s.score > 0.3)`.
 const TASK_RELEVANCE_FLOOR = 0.3;
-// flair#1199 — per-memory structured-payload overhead charged against the token
-// budget IN ADDITION to the rendered prose line. Each included memory ships as a
-// structured object ({id, content, durability, createdAt, updatedAt, agentId,
-// subject, section, ...}) which is the CANONICAL payload; its JSON keys cost
-// ~30-40 tokens beyond the prose line the fill loop measures. Charging it here
-// keeps the ACTUAL serialized payload (measured by tokenEstimate) within
-// maxTokens — the prose line alone under-charged, so the structured containers
-// crossed the cap. Sized to the non-content JSON a lean memory carries (id +
-// createdAt + updatedAt + agentId + durability + subject + section + key names,
-// ~55-70 tokens); conservative (errs slightly high, never low).
-const STRUCT_ITEM_OVERHEAD_TOKENS = 70;
-// Rough token estimate: ~4 chars per token for English text
-function estimateTokens(text) {
-    return Math.ceil(text.length / 4);
-}
+// flair#1207 — the per-item structured-payload overhead that #1199 charged
+// against the content-selection budget (a `+ STRUCT_ITEM_OVERHEAD_TOKENS = 70`
+// added to every item's cost, PLUS a `structOverheadReserve` pre-deducted from
+// the starting budget) has been REMOVED. It conflated measurement with
+// budgeting: `tokenEstimate` already measures the real serialized payload
+// (JSON.stringify(responseBody)) — the structured JSON scaffolding overhead is
+// captured there, honestly. Folding it into the SELECTION budget too
+// double-penalized and silently shrank recall below 0.44.6 for the same
+// `maxTokens` (6 findings → 3). The content budget is now `maxTokens` again
+// (0.44.6 selection capacity), and each item's cost is just the rendered prose
+// line — while `tokenEstimate` keeps reporting the true serialized size, which
+// may exceed `maxTokens` by the scaffolding overhead. See the module-doc CAP
+// CONTRACT above.
+// Token estimate (~4 chars per token for English text) now lives in the
+// harper-free ./token-estimate.js module, so the content-selection budget, the
+// reported `tokenEstimate`, and the flair#1213 conformance tokenEstimate
+// invariant are all computed with ONE definition. See that module's header.
 // `agentId` is the BOOTSTRAPPING agent (the caller) — used only to decide
 // whether to annotate attribution, never to change what's read (that
 // boundary is resolveReadScope()'s job, upstream of this function). A
@@ -175,6 +213,15 @@ export class BootstrapMemories extends Resource {
         subjects, // e.g., ["flair", "auth"] — entities to preload context for
         includeTrust = false, // flair#744 slice 1 — opt-in per-memory trust block
         abstain = false, // flair#744 slice 2 — opt-in task-relevance abstention
+        // flair#1199 — org-event knobs. `maxEvents` caps how many events ship
+        // (default MAX_ORG_EVENTS); `includeEventDetail` gates the verbose per-event
+        // `detail` JSON (default OFF — mirrors the includeContext opt-in). By
+        // default bootstrap ships LEAN events (id/kind/summary/createdAt/targetIds/
+        // scope); `detail` restates the summary + migration internals and is pure
+        // bloat for a connector, so it is opt-in. Both are also counted against the
+        // shared tokenBudget below (before #1199 the events array was assembled but
+        // NEVER charged, so a maxTokens=4000 request serialized well past budget).
+        maxEvents, includeEventDetail = false, 
         // flair#1199 — whether to assemble the prose `context` string. The
         // structured containers (soul/memories/predicted/teammateFindings) are the
         // CANONICAL payload; `context` is a human/agent-readable MIRROR of the same
@@ -222,19 +269,22 @@ export class BootstrapMemories extends Resource {
             collision: [],
             events: [],
         };
-        // flair#1199 — the structured containers (soul/memories/predicted/
-        // teammateFindings) are the CANONICAL payload, and `tokenEstimate` now
-        // reports the ACTUAL serialized bytes. Reserve headroom for the JSON
-        // scaffolding those containers and the self-describing keys (scope/sections/
-        // counters) add on top of the raw content, so `maxTokens` bounds the real
-        // payload — not just the prose. Without this the containers ship on top of
-        // the memory-line budget and blow the cap (the reported 4000→4275+ overrun).
-        const structOverheadReserve = Math.min(600, Math.floor(maxTokens * 0.15));
+        // flair#1207 — the content-SELECTION budget is `maxTokens`, matching 0.44.6
+        // capacity. #1199 pre-deducted a `structOverheadReserve` (min(600, 15% of
+        // maxTokens)) here to "reserve headroom" for the structured-container JSON
+        // scaffolding, on the theory that `maxTokens` should bound the serialized
+        // payload. That silently shrank the content budget and, combined with the
+        // per-item overhead (also removed), cut recall below 0.44.6 for the same
+        // `maxTokens` (#1207). The reserve is gone: `maxTokens` is the HARD cap on
+        // CONTENT SELECTION only. `tokenEstimate` (below) still reports the real
+        // serialized size honestly — which may exceed `maxTokens` by the scaffolding
+        // overhead, exactly as 0.44.6's payload did (0.44.6 just under-measured it).
         // Single shared budget across soul + every memory section (soul used to be
         // budgeted SEPARATELY and added ON TOP, so context alone could reach
-        // 1.4×maxTokens; #1199). Content selected therefore stays within
-        // maxTokens − reserve, and the serialized payload within maxTokens.
-        let tokenBudget = Math.max(0, maxTokens - structOverheadReserve);
+        // 1.4×maxTokens; #1199 folded soul into this shared budget — that part
+        // stays). Every admitted line is gated against the remaining budget, so the
+        // sum of selected CONTENT never exceeds `maxTokens`.
+        let tokenBudget = Math.max(0, maxTokens);
         // Own memories included in the payload (permanent + recent + predicted +
         // own task-relevant). Denominator is `memoriesAvailable` (own-scoped), so
         // memoriesIncluded ≤ memoriesAvailable always holds (#1199 coherent
@@ -242,10 +292,38 @@ export class BootstrapMemories extends Resource {
         let memoriesIncluded = 0;
         let memoriesAvailable = 0;
         let memoriesTruncated = 0;
+        // flair#1207 — count arithmetic by UNIQUE own-memory id, not raw increments.
+        // The invariant `memoriesIncluded + memoriesTruncated <= memoriesAvailable`
+        // MUST hold (0.44.9 reported available:3 included:2 truncated:2 — 2+2 > 3).
+        // Two bugs produced the over-count, both fixed by keying off these sets:
+        //   (1) a memory truncated for budget in an EARLY section (e.g. recent's
+        //       40% sub-budget) reappears in the task-relevant candidate pool and is
+        //       counted AGAIN (truncated twice, or truncated-then-included) — the
+        //       same physical memory in two denominators; and
+        //   (2) the task-relevant loop's "already included" exclusion set was built
+        //       POSITIONALLY (recent.filter by index) and omitted `predicted`, so a
+        //       predicted memory could be re-admitted to `relevant`.
+        // `includedOwnIds` is now THE authoritative "own memory already placed" set
+        // (used as the exclusion set in the predicted + task-relevant loops, replacing
+        // the positional hack); `truncatedOwnIds` records own budget-skips. Final
+        // counts are DERIVED from these sets (truncated = truncated-but-not-included),
+        // so both are disjoint subsets of memoriesAvailable and the invariant holds.
+        const includedOwnIds = new Set();
+        const truncatedOwnIds = new Set();
         // flair#1199 — cross-agent teammate findings included (a DIFFERENT
         // denominator than own memories): counting these into `memoriesIncluded`
         // is what let one client see included(9) > available(3).
         let teammateFindingsIncluded = 0;
+        // flair#1207 — teammate findings SKIPPED for size in the task-relevant
+        // packing loop (cleared the relevance floor but didn't fit the BUDGET).
+        // Reported ALONGSIDE `teammateFindingsMatched` (the whole floor-clearing pool
+        // considered), so "truncated" unambiguously means "relevant-but-no-budget",
+        // NOT "every candidate not selected" — 0.44.9's `truncated:89` beside
+        // `included:4` read as "89 relevant findings cut" with no pool to anchor it
+        // (heskew's #1207 nit). Both are disjoint-and-exhaustive over the matched
+        // pool (each matched teammate finding is EITHER included OR truncated), so
+        // teammateFindingsIncluded + teammateFindingsTruncated == teammateFindingsMatched.
+        let teammateFindingsTruncated = 0;
         // flair#1182 (part 1) — self-describing bootstrap. These structured
         // container keys are ALWAYS emitted on the response (empty `{}`/`[]` when
         // the caller has nothing), so a client can tell an *empty* instance from
@@ -267,6 +345,17 @@ export class BootstrapMemories extends Resource {
         // them. Kept SEPARATE from `memories`/`predicted` (which stay own-only per
         // the #1182 boundary) and clearly attributed via `source`.
         const includedTeammateFindings = [];
+        // flair#1206 — org events get their OWN structured container. Before #1206
+        // they lived ONLY in the prose `context` string ("## Recent Org Events"),
+        // so at includeContext=false (the /mcp default) they were counted in
+        // `sections.events` and measured into `tokenEstimate` (when prose was on) but
+        // NEVER delivered in any field a connector could read — orphaned. Populated
+        // from the SAME deduped+sliced set the prose lines are (so count, charge and
+        // delivery all key off one thing), ALWAYS emitted (`[]` when none), and the
+        // targetIds relevance filter is already applied upstream (see the OrgEvent
+        // read below). Declared out here so it is in scope for the response body even
+        // if the events read (in a try/catch) yields nothing.
+        const includedEvents = [];
         const leanMemory = (m, section) => ({
             id: m.id,
             content: m.content,
@@ -528,17 +617,17 @@ export class BootstrapMemories extends Resource {
         const permanent = permanentRows.filter((m) => !permanentSupersededIds.has(m.id));
         for (const m of permanent) {
             const line = formatMemory(m, agentId);
-            const cost = estimateTokens(line) + STRUCT_ITEM_OVERHEAD_TOKENS; // #1199 structured cost
+            const cost = estimateTokens(line); // #1207 — prose-line cost only; overhead is a reporting concern (tokenEstimate), not a selection constraint
             if (cost <= tokenBudget) {
                 sections.permanent.push(line);
                 includedOwnMemories.push(leanMemory(m, "permanent"));
                 if (includeTrust)
                     includedTrustMemories.push({ m, section: "permanent" });
                 tokenBudget -= cost;
-                memoriesIncluded++;
+                includedOwnIds.add(m.id); // #1207 — count by unique own-memory id
             }
             else {
-                memoriesTruncated++;
+                truncatedOwnIds.add(m.id); // #1207 — budget-skip, deduped against inclusions at the end
             }
         }
         // --- 3. Recent memories (adaptive window) ---
@@ -600,9 +689,9 @@ export class BootstrapMemories extends Resource {
         let recentSpent = 0;
         for (const m of recent) {
             const line = formatMemory(m, agentId);
-            const cost = estimateTokens(line) + STRUCT_ITEM_OVERHEAD_TOKENS; // #1199 structured cost
+            const cost = estimateTokens(line); // #1207 — prose-line cost only; overhead is a reporting concern (tokenEstimate), not a selection constraint
             if (recentSpent + cost > recentBudget) {
-                memoriesTruncated++;
+                truncatedOwnIds.add(m.id); // #1207 — budget-skip; may still be admitted later via the task-relevant loop (deduped at the end)
                 continue;
             }
             sections.recent.push(line);
@@ -611,7 +700,7 @@ export class BootstrapMemories extends Resource {
                 includedTrustMemories.push({ m, section: "recent" });
             recentSpent += cost;
             tokenBudget -= cost;
-            memoriesIncluded++;
+            includedOwnIds.add(m.id); // #1207 — count by unique own-memory id
         }
         // --- 3b. Subject-predicted context ---
         // When subjects are provided (e.g., ["flair", "auth"]), load memories
@@ -622,10 +711,10 @@ export class BootstrapMemories extends Resource {
             ? subjects.map((s) => s.toLowerCase())
             : [];
         if (predictedSubjects.length > 0 && tokenBudget > 200) {
-            const includedIds = new Set([
-                ...permanent.map((m) => m.id),
-                ...recent.filter((_, i) => i < sections.recent.length).map((m) => m.id),
-            ]);
+            // flair#1207 — exclude by the AUTHORITATIVE included-own set (permanent +
+            // recent actually admitted), not the old positional `recent.filter(by
+            // index)` hack, which mis-tracked when the recent loop skipped an early
+            // memory for budget and admitted a later one.
             // Draws from the SAME bounded own-scoped, non-permanent set "recent"
             // uses (nonPermanentActive — see that fetch's doc above for the
             // shared-source rationale and OWN_NONPERMANENT_FETCH_LIMIT's bound).
@@ -633,7 +722,7 @@ export class BootstrapMemories extends Resource {
             // query's own condition but kept for parity/clarity with the
             // pre-refactor filter shape.
             const subjectMemories = nonPermanentActive
-                .filter((m) => !includedIds.has(m.id) &&
+                .filter((m) => !includedOwnIds.has(m.id) &&
                 m.subject &&
                 predictedSubjects.includes(m.subject.toLowerCase()) &&
                 m.durability !== "permanent" // already loaded
@@ -643,9 +732,9 @@ export class BootstrapMemories extends Resource {
             let predictedSpent = 0;
             for (const m of subjectMemories) {
                 const line = formatMemory(m, agentId);
-                const cost = estimateTokens(line) + STRUCT_ITEM_OVERHEAD_TOKENS; // #1199 structured cost
+                const cost = estimateTokens(line); // #1207 — prose-line cost only; overhead is a reporting concern (tokenEstimate), not a selection constraint
                 if (predictedSpent + cost > predictedBudget) {
-                    memoriesTruncated++;
+                    truncatedOwnIds.add(m.id); // #1207 — budget-skip (deduped against inclusions at the end)
                     continue;
                 }
                 sections.predicted.push(line);
@@ -654,8 +743,7 @@ export class BootstrapMemories extends Resource {
                     includedTrustMemories.push({ m, section: "predicted" });
                 predictedSpent += cost;
                 tokenBudget -= cost;
-                memoriesIncluded++;
-                includedIds.add(m.id);
+                includedOwnIds.add(m.id); // #1207 — count by unique own-memory id; also the task-relevant loop's exclusion set (no predicted→relevant double-admit)
             }
         }
         // --- 3c. Active relationships for predicted subjects ---
@@ -709,11 +797,13 @@ export class BootstrapMemories extends Resource {
             }
             catch { }
             if (queryEmbedding) {
-                // Score all non-included memories by relevance
-                const includedIds = new Set([
-                    ...permanent.map((m) => m.id),
-                    ...recent.filter((_, i) => i < sections.recent.length).map((m) => m.id),
-                ]);
+                // flair#1207 — exclude own memories ALREADY placed via the authoritative
+                // set (permanent + recent + predicted actually admitted). The old set was
+                // built positionally (recent.filter by index) AND omitted `predicted`, so
+                // a predicted memory could be re-admitted here — double-counting it into
+                // memoriesIncluded and shipping it twice (once in `predicted`, once in
+                // `memories`). Keying off includedOwnIds fixes both.
+                const includedIds = includedOwnIds;
                 // Bounded HNSW candidate pool (flair-bootstrap-scale-fix) — replaces
                 // the full-corpus JS dot-product scan (`allMemories` × queryEmbedding,
                 // O(org corpus size) every bootstrap). K formula (Kern-approved):
@@ -818,9 +908,19 @@ export class BootstrapMemories extends Resource {
                 // section double-spends.
                 for (const { memory: m } of scored) {
                     const line = formatMemory(m, agentId);
-                    const cost = estimateTokens(line) + STRUCT_ITEM_OVERHEAD_TOKENS; // #1199 structured cost
-                    if (cost > tokenBudget)
+                    const cost = estimateTokens(line); // #1207 — prose-line cost only; overhead is a reporting concern (tokenEstimate), not a selection constraint
+                    if (cost > tokenBudget) {
+                        // flair#1207 — a size-skip in the score-ordered task-relevant loop
+                        // is no longer silent: record it on the denominator matching the
+                        // record's origin (own → truncatedOwnIds, teammate → the separate
+                        // teammateFindingsTruncated), so a client can distinguish "no relevant
+                        // finding" from "a relevant finding didn't fit the budget".
+                        if (m._source)
+                            teammateFindingsTruncated++;
+                        else
+                            truncatedOwnIds.add(m.id);
                         continue;
+                    }
                     if (m._source) {
                         sections.teammate.push(line);
                         // flair#1199 — cross-agent teammate findings join their OWN
@@ -852,7 +952,7 @@ export class BootstrapMemories extends Resource {
                         if (includeTrust)
                             includedTrustMemories.push({ m, section: "relevant" });
                         tokenBudget -= cost;
-                        memoriesIncluded++;
+                        includedOwnIds.add(m.id); // #1207 — count by unique own-memory id
                     }
                 }
             }
@@ -1000,6 +1100,15 @@ export class BootstrapMemories extends Resource {
                 const isRelevant = !targets || targets.length === 0 || targets.includes(agentId);
                 if (!isRelevant)
                     continue;
+                // flair#1200 — suppress zero-row no-op auto-heal migration events at
+                // render. On a healthy store every boot emits a "migration graph-heal
+                // success (0 rows processed)" ledger event beside an "HNSW graph-heal:
+                // recall verified healthy" observability event — near-identical, zero
+                // signal, and (as of #1199) token-charged. Filtered HERE only: the
+                // ledger still records every migration on the table (invariant IV is
+                // untouched — this is a display filter, never a write-path change).
+                if (isZeroRowNoOpEvent(event))
+                    continue;
                 eventResults.push(event);
             }
             // flair#1200 — collapse byte-identical duplicate events before rendering.
@@ -1007,10 +1116,10 @@ export class BootstrapMemories extends Resource {
             // that double-fires, or the same broadcast emitted from two paths); each
             // physical row has a distinct id/createdAt (OrgEvent.post keys the id off
             // a millisecond timestamp), so they aren't caught by primary-key upsert
-            // and render as exact dupes. Org-event slots are scarce (10), so dedup
-            // BEFORE the slice — otherwise ~half the slots are wasted on duplicates.
-            // Keyed on the CONTENT (kind + summary + detail + targets), keeping the
-            // most-recent occurrence per signature.
+            // and render as exact dupes. Org-event slots are scarce, so dedup BEFORE
+            // admission — otherwise ~half the slots are wasted on duplicates. Keyed on
+            // the CONTENT (kind + summary + detail + targets), keeping the most-recent
+            // occurrence per signature.
             const eventBySignature = new Map();
             for (const evt of eventResults) {
                 const sig = JSON.stringify([
@@ -1023,18 +1132,76 @@ export class BootstrapMemories extends Resource {
                 if (!prev || (evt.createdAt || "") > (prev.createdAt || ""))
                     eventBySignature.set(sig, evt);
             }
+            // flair#1199 — admit events in RECENCY order (most recent first, the
+            // score-analogue for events) against the SHARED tokenBudget, capped at
+            // `maxEvents`. Before #1199 the events array was assembled uncounted and
+            // NEVER charged: a maxTokens=4000 request serialized at 6286 (+57%), the
+            // bulk being 10 events each shipping a `detail` JSON. Now each event's
+            // REAL serialized cost (the structured object that actually ships — lean by
+            // default, `detail` only under includeEventDetail) is charged against the
+            // remaining budget, so events respect maxTokens the same way every other
+            // content section does. An event that doesn't fit is skipped, not silently
+            // over-budget; smaller later events may still fit (hence continue, not
+            // break), and admission stops at the maxEvents cap.
+            const eventCap = Number.isFinite(maxEvents) && maxEvents >= 0
+                ? Math.floor(maxEvents)
+                : MAX_ORG_EVENTS;
             const dedupedEvents = [...eventBySignature.values()]
-                .sort((a, b) => (a.createdAt || "").localeCompare(b.createdAt || ""));
-            for (const evt of dedupedEvents.slice(0, 10)) {
+                .sort((a, b) => (b.createdAt || "").localeCompare(a.createdAt || ""));
+            for (const evt of dedupedEvents) {
+                if (sections.events.length >= eventCap)
+                    break;
+                // The structured object a connector actually reads (flair#1206). Lean by
+                // default; `detail` (the verbose migration-internals/summary-restating
+                // JSON) only when explicitly requested. Optional fields are omitted when
+                // absent so the object stays compact.
+                const structured = {
+                    id: evt.id,
+                    kind: evt.kind,
+                    summary: evt.summary,
+                    ...(includeEventDetail && evt.detail != null ? { detail: evt.detail } : {}),
+                    ...(Array.isArray(evt.targetIds) && evt.targetIds.length > 0 ? { targetIds: evt.targetIds } : {}),
+                    createdAt: evt.createdAt ?? null,
+                    ...(evt.scope != null ? { scope: evt.scope } : {}),
+                };
+                // Charge the REAL serialized cost of what ships (structured object on the
+                // /mcp path; the prose line is a subset of it). This is the #1199 fix:
+                // events are content and must be budgeted like content.
+                const cost = estimateTokens(JSON.stringify(structured));
+                if (cost > tokenBudget)
+                    continue;
                 const elapsed = Date.now() - new Date(evt.createdAt).getTime();
                 const mins = Math.floor(elapsed / 60_000);
                 const relTime = mins < 60 ? `${mins}min ago` : `${Math.floor(mins / 60)}h ago`;
                 sections.events.push(`- ${evt.kind}: ${evt.summary} (${relTime})`);
+                // Same admitted event ⇒ `sections.events` (the count), the `tokenEstimate`
+                // charge, and the structured delivery all key off ONE thing.
+                includedEvents.push(structured);
+                tokenBudget -= cost;
             }
         }
         catch {
             // non-fatal: OrgEvent table may not exist yet
         }
+        // flair#1207 — derive the own-memory counters from the unique-id sets so the
+        // invariant memoriesIncluded + memoriesTruncated <= memoriesAvailable holds.
+        // `truncated` counts only own memories that were budget-skipped AND never
+        // ultimately admitted (a memory skipped in `recent` but later admitted via
+        // the task-relevant loop is INCLUDED, not truncated) — so included/truncated
+        // are disjoint subsets of the own corpus (memoriesAvailable), never
+        // double-counting the same physical memory across sections.
+        memoriesIncluded = includedOwnIds.size;
+        let memoriesTruncatedUnique = 0;
+        for (const id of truncatedOwnIds)
+            if (!includedOwnIds.has(id))
+                memoriesTruncatedUnique++;
+        memoriesTruncated = memoriesTruncatedUnique;
+        // flair#1207 — the teammate MATCH POOL considered (cleared the relevance
+        // floor, drawn from the bounded candidate pool): every matched teammate
+        // finding is EITHER included OR budget-truncated, so this equals their sum.
+        // Reporting it anchors `teammateFindingsTruncated` as "relevant-but-no-budget"
+        // rather than an unexplained large number beside a small `included`.
+        const teammateFindingsMatched = teammateFindingsIncluded + teammateFindingsTruncated;
         // --- Build context string ---
         const parts = [];
         if (sections.soul.length > 0) {
@@ -1165,6 +1332,13 @@ export class BootstrapMemories extends Resource {
             // (always present, `[]` when none), so a connector that consumes the
             // containers still gets them when prose `context` is off.
             teammateFindings: includedTeammateFindings,
+            // flair#1206 — org events as a structured container (always present, `[]`
+            // when none, same self-describing-empty-state pattern as the containers
+            // above). Before #1206 events lived ONLY in the prose `context`, so at the
+            // /mcp default (includeContext=false) they were counted+measured but never
+            // delivered. Deduped (#1200) and targetIds-scoped (same set as the prose
+            // "## Recent Org Events" lines), so count/charge/delivery all agree.
+            events: includedEvents,
             ...(currentTaskHint ? { currentTaskHint } : {}),
             ...(predictedHint ? { predictedHint } : {}),
             ...(trust ? { trust } : {}),
@@ -1184,22 +1358,50 @@ export class BootstrapMemories extends Resource {
             },
             soulTokens,
             memoryTokens,
+            // flair#1199 — the content-selection budget this response was built
+            // against (echoed so a connector can relate tokenEstimate to the budget it
+            // asked for — and so the conformance tokenEstimate<=maxTokens invariant is
+            // self-contained). Defaults to 4000 when unset.
+            maxTokens,
             // flair#1199 — own memories included (denominator: memoriesAvailable, also
-            // own-scoped), so memoriesIncluded ≤ memoriesAvailable always holds.
+            // own-scoped). flair#1207 — DERIVED from unique own-memory ids, so
+            // memoriesIncluded + memoriesTruncated <= memoriesAvailable always holds.
             memoriesIncluded,
             memoriesAvailable,
             // Cross-agent teammate findings included — a SEPARATE denominator, labelled
             // so it's never confused with the own-memory counters.
             teammateFindingsIncluded,
             memoriesTruncated,
+            // flair#1207 — teammate findings skipped for size in the task-relevant loop
+            // (own size-skips there feed truncatedOwnIds). Surfacing this makes a
+            // size-skip self-describing: "a relevant teammate finding didn't fit" is
+            // now distinguishable from "no relevant teammate finding".
+            teammateFindingsTruncated,
+            // flair#1207 — the teammate match POOL considered (cleared the relevance
+            // floor). teammateFindingsIncluded + teammateFindingsTruncated ==
+            // teammateFindingsMatched, so "truncated" reads as "relevant-but-no-budget"
+            // against a stated pool, not an unanchored large number.
+            teammateFindingsMatched,
         };
         // flair#1199 — tokenEstimate must reflect the ACTUAL serialized payload the
         // caller receives (the structured containers included), not just the prose
         // `context`. The old `soulTokens + memoryTokens` counted only the context
         // string, so it under-reported by ~2× once the structured fields shipped
-        // alongside — the reported "maxTokens 4000 → tokenEstimate 4275 while the
-        // real payload was well over the cap". Measured over the assembled body
-        // (the ~1-line tokenEstimate field it omits is negligible).
+        // alongside. Measured over the assembled body (the ~1-line tokenEstimate
+        // field it omits is negligible). CAP CONTRACT: this is an HONEST report of
+        // the real serialized size. Every CONTENT section — soul, memories, findings,
+        // AND events (flair#1199) — is now gated against the shared `maxTokens`
+        // budget, so no section blows the budget with uncounted content the way the
+        // 0.44.9 events array did (maxTokens=4000 → 6286). tokenEstimate may still
+        // exceed `maxTokens` slightly, by the FIXED structural JSON scaffolding
+        // (container keys/braces, counters, sections map, char/4 rounding) — that is
+        // genuine payload the caller pays for, and it is small and bounded, NOT
+        // uncounted content. The connector-conformance suite asserts
+        // tokenEstimate <= maxTokens within a small tolerance for exactly that
+        // scaffolding. Do NOT "fix" a small over-maxTokens tokenEstimate by shrinking
+        // memory selection — that is the #1199→#1207 regression (it dropped relevant
+        // findings, charging a per-item overhead against the content budget). If the
+        // real payload consistently overruns for a use case, raise `maxTokens`.
         const tokenEstimate = estimateTokens(JSON.stringify(responseBody));
         return { ...responseBody, tokenEstimate };
     }

package/dist/resources/MemoryReflect.js

@@ -40,7 +40,7 @@ import { Resource, databases, models, logger } from "harper";
 import { randomBytes } from "node:crypto";
 import { isAdmin, allowVerified } from "./agent-auth.js";
 import { patchRecordSilent } from "./table-helpers.js";
-import { buildReflectionPrompt, buildExecutePrompt, resolveReflectActor, generateCandidates, dedupeCandidates, } from "./memory-reflect-lib.js";
+import { buildReflectionPrompt, buildExecutePrompt, resolveReflectActor, generateCandidates, dedupeCandidates, memoryMatchesReflectScope, buildStagedCandidateRow, } from "./memory-reflect-lib.js";
 export class ReflectMemories extends Resource {
     // Self-authorize via the Ed25519 agent verify (auth reshape removes the gate's
     // admin elevation). Any verified agent may reflect; the isAdmin checks in post()
@@ -75,15 +75,12 @@ export class ReflectMemories extends Resource {
                 continue;
             if (record.durability === "permanent")
                 continue; // permanent memories don't need reflection
-            if (scope === "tagged") {
-                if (!tag || !(record.tags ?? []).includes(tag))
-                    continue;
-            }
-            else if (scope === "recent") {
-                if (!record.createdAt || new Date(record.createdAt) < sinceDate)
-                    continue;
-            }
-            // scope="all" passes everything
+            // Scope selection — the cross-user-bleed boundary (#1205b-1). See
+            // memoryMatchesReflectScope's doc: scope:"tagged" admits ONLY the one
+            // adk:<app>:<user> tag's memories, so a candidate distilled here can
+            // never cite another user's memory.
+            if (!memoryMatchesReflectScope(record, { scope, tag, sinceDate }))
+                continue;
             const { embedding, ...rest } = record;
             memories.push(rest);
             if (memories.length >= maxMemories)
@@ -152,7 +149,11 @@ export class ReflectMemories extends Resource {
         const generatedAt = new Date().toISOString();
         const staged = [];
         for (const c of toStage) {
-            const row = {
+            // #1205b-1: buildStagedCandidateRow stamps `scopeTag` when this run was
+            // scope:"tagged" — the authoritative per-user tag promotion consumes
+            // directly (closing the #1205a source-re-read seam). Non-tagged runs
+            // leave scopeTag absent, unchanged.
+            const row = buildStagedCandidateRow({
                 id: `cand_${randomBytes(8).toString("hex")}`,
                 agentId,
                 claim: c.claim,
@@ -160,8 +161,9 @@ export class ReflectMemories extends Resource {
                 rationalePrompt: executePrompt,
                 generatedBy: resolvedModel,
                 generatedAt,
-                status: "pending",
-            };
+                scope,
+                tag,
+            });
             await databases.flair.MemoryCandidate.put(row);
             staged.push(row);
         }