@tpsdev-ai/flair 0.44.9 → 0.44.11

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, teammateFindingsTruncated, agentId, scope, soul,
- *     memories, predicted, teammateFindings, events[, 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`
@@ -90,24 +92,62 @@ import { bestSemanticSimilarity, evaluateAbstention } from "./abstention.js";
  *   when the prose `context` is off (the /mcp default); before #1206 they lived
  *   ONLY in the prose string and were orphaned at includeContext=false.
  *
- *   flair#1199 CAP CONTRACT (corrected): `maxTokens` is the HARD cap on CONTENT
- *   SELECTION — the shared `tokenBudget` starts at `maxTokens` and every admitted
- *   soul/memory/finding line 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 structured-container JSON scaffolding and so MAY exceed `maxTokens` by
- *   that overhead — measurement (honest reporting) is deliberately decoupled from
- *   budgeting (what to select). This is the flair#1207 fix: #1199 had 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`;
- *   the overhead is a reporting concern (already captured by `tokenEstimate`),
- *   never a selection constraint, so it no longer shrinks the content budget.
+ *   CAP CONTRACT: `maxTokens` is the HARD cap on CONTENT SELECTION — the shared
+ *   `tokenBudget` starts at `maxTokens` and every admitted soul/memory/finding
+ *   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`. Each item is charged the cost of what it ACTUALLY
+ *   SHIPS on the requested surface (see contentCost): on the /mcp connector path
+ *   (includeContext=false) the prose `context` is a pointer, so only the
+ *   STRUCTURED container object ships and is charged; on the REST/CLI prose path
+ *   (includeContext=true) the prose IS the shipped surface and is charged (0.44.6
+ *   capacity — flair#1207). `tokenEstimate` HONESTLY reports the real serialized
+ *   payload (`JSON.stringify(responseBody)`). On the connector path — where the
+ *   selection charge and `tokenEstimate` measure the SAME structured bytes —
+ *   `tokenEstimate` exceeds `maxTokens` only by the FIXED JSON scaffolding
+ *   (keys/braces, counters, the sections map, hints); the connector-conformance
+ *   budgetCap asserts tokenEstimate <= maxTokens within a small tolerance for
+ *   exactly that scaffolding. On the prose path the payload ALSO carries the
+ *   structured mirror, so `tokenEstimate` may exceed `maxTokens` by that mirror —
+ *   that overage is honest measurement, and shrinking prose selection to hide it
+ *   is the flair#1207 regression (below). flair#1199 (0.44.11): charging the
+ *   PROSE line but shipping the heavier STRUCTURED object on the /mcp path let
+ *   teammate findings ride OUTSIDE the enforced budget (soulTokens 377 +
+ *   memoryTokens 3574 = 3951 prose, just under a 4000 cap, yet tokenEstimate 5337
+ *   = +33%; teammateFindingsIncluded crept 4→5) — fixed by charging structured
+ *   on the connector path. 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 flat
+ *   per-item overhead is a reporting concern (already captured by `tokenEstimate`)
+ *   and no longer shrinks the content budget — the 0.44.11 fix charges the
+ *   item's REAL shipped serialization, not a flat surcharge, and only on the path
+ *   where that serialization is the shipped surface.
+ *
+ *   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#1201/#1225 — trust-block sections that are a lifecycle-window LOAD, not
+// a retrieval surface. A trust entry from one of these carries `matchQuality:
+// null` (no relevance score to band), which is CORRECT (Kern's #1220 ruling),
+// never a scoring failure — see the `matchQualityNote` in the response tail.
+const LIFECYCLE_SECTIONS = new Set(["permanent", "recent", "predicted"]);
+// 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,
@@ -152,10 +192,10 @@ const TASK_RELEVANCE_FLOOR = 0.3;
 // line — while `tokenEstimate` keeps reporting the true serialized size, which
 // may exceed `maxTokens` by the scaffolding overhead. See the module-doc CAP
 // CONTRACT above.
-// Rough token estimate: ~4 chars per token for English text
-function estimateTokens(text) {
-    return Math.ceil(text.length / 4);
-}
+// 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
@@ -193,6 +233,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
@@ -263,16 +312,37 @@ 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. That loop `continue`s past an over-budget record silently;
-        // without a counter, a client can't tell "no relevant teammate finding" from
-        // "a relevant one existed but didn't fit the budget" (Sherlock's #1207
-        // self-describing-size-skip note; own-memory size-skips already increment
-        // `memoriesTruncated`, but that loop never did — now both do).
+        // 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
@@ -318,6 +388,34 @@ export class BootstrapMemories extends Resource {
             subject: m.subject ?? null,
             section,
         });
+        // flair#1199 (0.44.11) — the REAL cost an admitted content item adds to the
+        // serialized payload the caller RECEIVES, which is exactly what
+        // `tokenEstimate` measures. This is the fix for the teammate-findings
+        // budget blowout: the selector used to charge every memory/finding its
+        // PROSE line (`formatMemory`) but, on the /mcp connector path, ship the
+        // heavier STRUCTURED container object — and `tokenEstimate` measures the
+        // structured object. A teammate finding carries `id` + TWO ISO timestamps +
+        // `source` + `section` + JSON field names/quotes that the prose line does
+        // not, so the shipped object runs ~1.5–1.7× its prose line. Charging prose
+        // but shipping structured let several teammate findings ride OUTSIDE the
+        // enforced budget: a maxTokens=4000 bootstrap reported soulTokens 377 +
+        // memoryTokens 3574 = 3951 (prose, just under cap) yet serialized at 5337
+        // (+33%), and teammateFindingsIncluded crept 4→5. So charge what SHIPS:
+        //   - /mcp connector path (includeContext=false): the prose `context` is a
+        //     compact pointer (no bodies), so ONLY the structured container ships —
+        //     charge its serialized size. Now the sum of admitted content ≈
+        //     `tokenEstimate` minus the FIXED JSON scaffolding, so `tokenEstimate`
+        //     stays within maxTokens + the small scaffolding tolerance.
+        //   - REST/CLI prose path (includeContext=true): the prose IS the primary
+        //     shipped surface and flair#1207 deliberately fixed the selection budget
+        //     at 0.44.6 (prose) capacity — `tokenEstimate` is HONEST there and may
+        //     exceed maxTokens by the structured mirror it also ships. Charging
+        //     structured on THAT path would re-shrink prose recall below 0.44.6
+        //     (the exact #1207 regression). So keep charging prose on the prose
+        //     path. This is "fix the budget INPUT, not the cap": the figure the
+        //     selector tests against maxTokens is now the figure that becomes
+        //     `tokenEstimate` on each path.
+        const contentCost = (structured, proseLine) => includeContext ? estimateTokens(proseLine) : estimateTokens(JSON.stringify(structured));
         // --- 1. Soul records (budgeted — prioritized by key importance) ---
         // Soul is who you are, but we still need to respect token budgets.
         // Workspace files (SOUL.md, AGENTS.md) can be massive — they're already
@@ -567,17 +665,21 @@ 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); // #1207 — prose-line cost only; overhead is a reporting concern (tokenEstimate), not a selection constraint
+            const struct = leanMemory(m, "permanent");
+            // #1199 (0.44.11) — charge what SHIPS (structured on the /mcp path, prose
+            // on the REST path); see contentCost. #1207 stays honored: on the prose
+            // path this is still the prose-line cost, so REST recall is unchanged.
+            const cost = contentCost(struct, line);
             if (cost <= tokenBudget) {
                 sections.permanent.push(line);
-                includedOwnMemories.push(leanMemory(m, "permanent"));
+                includedOwnMemories.push(struct);
                 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) ---
@@ -639,18 +741,19 @@ export class BootstrapMemories extends Resource {
         let recentSpent = 0;
         for (const m of recent) {
             const line = formatMemory(m, agentId);
-            const cost = estimateTokens(line); // #1207 — prose-line cost only; overhead is a reporting concern (tokenEstimate), not a selection constraint
+            const struct = leanMemory(m, "recent");
+            const cost = contentCost(struct, line); // #1199 (0.44.11) — charge what ships; see contentCost
             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);
-            includedOwnMemories.push(leanMemory(m, "recent"));
+            includedOwnMemories.push(struct);
             if (includeTrust)
                 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
@@ -661,10 +764,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).
@@ -672,7 +775,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
@@ -682,19 +785,19 @@ export class BootstrapMemories extends Resource {
             let predictedSpent = 0;
             for (const m of subjectMemories) {
                 const line = formatMemory(m, agentId);
-                const cost = estimateTokens(line); // #1207 — prose-line cost only; overhead is a reporting concern (tokenEstimate), not a selection constraint
+                const struct = leanMemory(m, "predicted");
+                const cost = contentCost(struct, line); // #1199 (0.44.11) — charge what ships; see contentCost
                 if (predictedSpent + cost > predictedBudget) {
-                    memoriesTruncated++;
+                    truncatedOwnIds.add(m.id); // #1207 — budget-skip (deduped against inclusions at the end)
                     continue;
                 }
                 sections.predicted.push(line);
-                includedPredicted.push(leanMemory(m, "predicted"));
+                includedPredicted.push(struct);
                 if (includeTrust)
                     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 ---
@@ -748,11 +851,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):
@@ -857,17 +962,39 @@ export class BootstrapMemories extends Resource {
                 // section double-spends.
                 for (const { memory: m } of scored) {
                     const line = formatMemory(m, agentId);
-                    const cost = estimateTokens(line); // #1207 — prose-line cost only; overhead is a reporting concern (tokenEstimate), not a selection constraint
+                    // flair#1199 (0.44.11) — build the STRUCTURED container object BEFORE
+                    // the budget check so the finding is charged the cost of what actually
+                    // ships (structured on the /mcp path), not its cheaper prose line. A
+                    // teammate finding's structured object (id + two ISO timestamps +
+                    // source + section) runs well over its prose line, and it — not the
+                    // prose — is what `tokenEstimate` measures on the connector path. This
+                    // is the fix for the teammate-findings blowout: charging prose but
+                    // shipping structured let extra findings ride outside the enforced
+                    // budget (see contentCost). Cross-agent findings (`m._source` set)
+                    // ship in `teammateFindings`; own findings in `memories`.
+                    const struct = m._source
+                        ? {
+                            id: m.id,
+                            content: m.content,
+                            durability: m.durability ?? null,
+                            createdAt: m.createdAt ?? null,
+                            updatedAt: m.updatedAt ?? null,
+                            subject: m.subject ?? null,
+                            source: m._source,
+                            section: "teammate",
+                        }
+                        : leanMemory(m, "relevant");
+                    const cost = contentCost(struct, line);
                     if (cost > tokenBudget) {
                         // flair#1207 — a size-skip in the score-ordered task-relevant loop
-                        // is no longer silent: record it on the counter matching the record's
-                        // denominator (own → memoriesTruncated, teammate → the separate
+                        // 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
-                            memoriesTruncated++;
+                            truncatedOwnIds.add(m.id);
                         continue;
                     }
                     if (m._source) {
@@ -878,16 +1005,7 @@ export class BootstrapMemories extends Resource {
                         // off. Counted separately (teammateFindingsIncluded), NOT into
                         // memoriesIncluded — that different-denominator mix is what let
                         // included exceed available.
-                        includedTeammateFindings.push({
-                            id: m.id,
-                            content: m.content,
-                            durability: m.durability ?? null,
-                            createdAt: m.createdAt ?? null,
-                            updatedAt: m.updatedAt ?? null,
-                            subject: m.subject ?? null,
-                            source: m._source,
-                            section: "teammate",
-                        });
+                        includedTeammateFindings.push(struct);
                         if (includeTrust)
                             includedTrustMemories.push({ m, section: "teammate" });
                         tokenBudget -= cost;
@@ -897,11 +1015,11 @@ export class BootstrapMemories extends Resource {
                         sections.relevant.push(line);
                         // flair#1182 — own task-relevant records join the `memories`
                         // container.
-                        includedOwnMemories.push(leanMemory(m, "relevant"));
+                        includedOwnMemories.push(struct);
                         if (includeTrust)
                             includedTrustMemories.push({ m, section: "relevant" });
                         tokenBudget -= cost;
-                        memoriesIncluded++;
+                        includedOwnIds.add(m.id); // #1207 — count by unique own-memory id
                     }
                 }
             }
@@ -1049,6 +1167,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.
@@ -1056,10 +1183,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([
@@ -1072,36 +1199,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)) {
-                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})`);
-                // flair#1206 — the SAME deduped+sliced event, structured, so a connector
-                // reading the containers gets it when prose `context` is off (the /mcp
-                // default). Same set as the prose line ⇒ `sections.events` (the count),
-                // the `tokenEstimate` charge (this array is always in the body), and the
-                // delivery all key off one thing. Optional fields (detail/targetIds/scope)
-                // are omitted when absent so the object stays lean. The targetIds
-                // relevance filter and #1200 content-signature dedup were already applied
-                // upstream (eventResults → eventBySignature), so this is a pure move from
-                // prose to structured — no scope widening, no re-introduced duplicates.
-                includedEvents.push({
+                .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,
-                    ...(evt.detail != null ? { detail: evt.detail } : {}),
+                    ...(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) {
@@ -1176,9 +1343,30 @@ export class BootstrapMemories extends Resource {
         // absent ⇒ the response is byte-identical to pre-slice-1. flair#1201 — each
         // entry carries its `section` so `matchQuality: null` on a lifecycle section
         // reads as "not a retrieval surface", not as a scoring failure on the
-        // caller's own records.
+        // caller's own records. flair#1225 (0.44.11) — the null on a lifecycle
+        // section is now SELF-EXPLAINING (matchQualityNote below), not just legible
+        // via `section`.
         const trust = includeTrust
-            ? includedTrustMemories.map(({ m, section }) => ({ id: m.id, section, ...buildTrustBlock(m) }))
+            ? includedTrustMemories.map(({ m, section }) => {
+                const block = buildTrustBlock(m);
+                // flair#1225 — Kern ruled (on #1220) that a null `matchQuality` on an
+                // own-recent (lifecycle) entry is CORRECT: lifecycle sections
+                // (permanent/recent/predicted) are a window LOAD, not a retrieval
+                // surface, so there is no similarity to band — the null means "not
+                // scored here", never a scoring failure on the caller's own records
+                // (the #1201 misread: own-recent null beside a teammate band). Behavior
+                // is unchanged (per Kern); this only makes the null self-describing in
+                // the payload — Fix 3's "any absent field says why" — so a connector
+                // reads it right without knowing the #1201 contract.
+                const matchQualityNote = block.matchQuality === null
+                    ? (LIFECYCLE_SECTIONS.has(section)
+                        ? `matchQuality is null because '${section}' is a lifecycle-window section, not a retrieval `
+                            + `surface — there is no relevance score to band. This is correct (per flair#1225), not a scoring failure.`
+                        : "matchQuality is null because no semantic similarity was attached to this result "
+                            + "(e.g. a by-id read or a keyword-only degraded match).")
+                    : undefined;
+                return { id: m.id, section, ...block, ...(matchQualityNote ? { matchQualityNote } : {}) };
+            })
             : undefined;
         // flair#744 slice 2 — opt-in abstention verdict for the task-relevance
         // surface. Present ONLY when `abstain` is requested (byte-identical to
@@ -1217,6 +1405,36 @@ export class BootstrapMemories extends Resource {
                 + `predicted surfaces your own non-permanent memories whose subject matches one of the provided `
                 + `subjects — it fills as you store memories tagged with these subjects.`
             : undefined;
+        // flair#1182 (0.44.11) — GENERALIZE the empty-container "say why" rule
+        // beyond predictedHint. `events: []` (deliberate no-op filtering) was
+        // byte-indistinguishable from the 0.44.8 silent-drop regression, where a
+        // container that SHOULD have had content shipped empty — a connector could
+        // only tell the difference by diffing against a previous payload. The rule
+        // (now applied consistently across the structured containers): any container
+        // that ships EMPTY carries a short hint naming WHY it is empty and what
+        // fills it, so "deliberately empty" is never confused with "silently
+        // dropped". Present ONLY when the container is empty (a populated container
+        // needs no hint), so a healthy payload is unchanged.
+        // events: [] — no org event in the lookback window was relevant to the
+        // caller after zero-row no-op auto-heal filtering (#1200). Present-but-empty
+        // by design, not a drop.
+        const eventsHint = includedEvents.length === 0
+            ? "No org events in the lookback window were relevant to you (org-wide, or targeted at you) "
+                + "after zero-row no-op auto-heal filtering. This container is present-but-empty by design, not dropped."
+            : undefined;
+        // teammateFindings: [] — name WHICH legitimate empty this is (no task → no
+        // retrieval; matched-but-budget-truncated; or nothing cleared the relevance
+        // floor), so it never reads as a silent drop.
+        const teammateFindingsHint = includedTeammateFindings.length === 0
+            ? (!taskProvided
+                ? "No teammateFindings: cross-agent findings are retrieved against your currentTask, and none was provided. "
+                    + "Pass currentTask to populate this."
+                : teammateFindingsTruncated > 0
+                    ? `No teammateFindings fit the token budget: ${teammateFindingsTruncated} relevant cross-agent finding(s) `
+                        + "cleared the relevance floor but were budget-truncated. Raise maxTokens to include them."
+                    : "No cross-agent (teammate) memory cleared the task-relevance floor for this currentTask. "
+                        + "This container is present-but-empty by design, not dropped.")
+            : undefined;
         const responseBody = {
             context,
             // flair#1182 (part 1) — always-present self-describing keys: who the
@@ -1241,6 +1459,11 @@ export class BootstrapMemories extends Resource {
             events: includedEvents,
             ...(currentTaskHint ? { currentTaskHint } : {}),
             ...(predictedHint ? { predictedHint } : {}),
+            // flair#1182 (0.44.11) — empty-container hints, present only when the
+            // container ships empty (see above), so a deliberately-empty container is
+            // never confused with a silent drop.
+            ...(eventsHint ? { eventsHint } : {}),
+            ...(teammateFindingsHint ? { teammateFindingsHint } : {}),
             ...(trust ? { trust } : {}),
             ...(abstention ? { abstention } : {}),
             sections: {
@@ -1258,8 +1481,14 @@ 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
@@ -1267,24 +1496,39 @@ export class BootstrapMemories extends Resource {
             teammateFindingsIncluded,
             memoriesTruncated,
             // flair#1207 — teammate findings skipped for size in the task-relevant loop
-            // (own size-skips there increment memoriesTruncated). Surfacing this makes
-            // a size-skip self-describing: "a relevant teammate finding didn't fit"
-            // is now distinguishable from "no relevant teammate finding".
+            // (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. Measured over the assembled body (the ~1-line tokenEstimate
-        // field it omits is negligible). flair#1207 CAP CONTRACT: this is an HONEST
-        // report of the real serialized size, NOT a value bounded by `maxTokens`.
-        // `maxTokens` is the hard cap on CONTENT SELECTION (the shared tokenBudget);
-        // the structured-container JSON scaffolding is genuine payload the caller
-        // pays for, so tokenEstimate MAY exceed `maxTokens` by that overhead. Do not
-        // "fix" an over-maxTokens tokenEstimate by shrinking selection — that is the
-        // exact #1199→#1207 regression (it dropped relevant findings). If the real
-        // payload consistently overruns for a use case, raise `maxTokens`.
+        // 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). flair#1199 (0.44.11): on
+        // the /mcp connector path each content item is charged its STRUCTURED shipped
+        // cost — the same bytes tokenEstimate measures — so tokenEstimate exceeds
+        // `maxTokens` only by the FIXED structural JSON scaffolding (container
+        // keys/braces, counters, sections map, hints, char/4 rounding): genuine
+        // payload the caller pays for, small and bounded, NOT uncounted content. The
+        // connector-conformance suite asserts tokenEstimate <= maxTokens within a
+        // small tolerance for exactly that scaffolding. On the PROSE path
+        // (includeContext=true) the payload ALSO carries the structured mirror, so
+        // tokenEstimate legitimately exceeds `maxTokens` by that mirror — do NOT
+        // "fix" THAT overrun by shrinking prose selection: that is the #1199→#1207
+        // regression (it dropped relevant findings, charging a flat 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 };
     }