@tpsdev-ai/flair 0.44.9 → 0.44.11

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);
         }

package/dist/resources/auto-promote-lib.js

@@ -0,0 +1,137 @@
+// ─── ADK auto-promote — pure policy for /AutoPromoteCandidates (#1205b-2) ─────
+//
+// The UNATTENDED promotion path. After the tag-aware nightly cycle (#1205b-1)
+// stages per-user MemoryCandidates each carrying a `scopeTag`, this policy
+// decides whether an ADK-sourced candidate may be auto-promoted to the user's
+// OWN memory with NO human reviewer in the loop — replacing the human
+// `rem promote` for this one narrow path.
+//
+// Because there is no human to catch a mistake, every one of Sherlock's four
+// hard requirements is a load-bearing gate here (issue #1205 authz review):
+//
+//   Req 1 (memory-only, server-side): NOT decided here. The target is
+//     hard-locked to `memory` STRUCTURALLY in resources/AutoPromoteCandidates.ts
+//     — this lib has no notion of a target at all, so no value it returns can
+//     ever route a write to Soul. Keeping the target out of the policy object is
+//     the point: a policy field could be flipped; an absent one cannot.
+//
+//   Req 2 (tag lineage, FAIL-CLOSED): decideAutoPromote REFUSES any candidate
+//     whose stamped `scopeTag` is absent/empty or not an `adk:` scope tag. A
+//     tagless promoted claim lands in the SHARED agentId namespace and becomes
+//     retrievable by every other user of the app (cross-user leak) — so a
+//     missing scope tag is a hard STOP, never a benign "promote untagged". The
+//     stamped scopeTag (resources/memory-reflect-lib.ts buildStagedCandidateRow)
+//     is AUTHORITATIVE and consumed directly — we never re-read source memories
+//     (the seam #1205b-1 closed).
+//
+//   Req 3 (content-safety, STRICT for the unattended path): the human gate was
+//     also a content-safety gate. decideAutoPromote scans the claim through the
+//     SAME scanFields path Memory.ts uses (content-safety.ts) and, unlike
+//     Memory.ts's write scan, ALWAYS refuses a flagged claim regardless of
+//     FLAIR_CONTENT_SAFETY — an unattended write must not silently promote a
+//     prompt-injection payload merely because the instance runs in `warn` mode.
+//
+//   Req 4 (non-impersonating machine reviewerId): a promoted claim records
+//     MACHINE_REVIEWER_ADK_AUTO_PROMOTE in the reserved `machine:` namespace, so
+//     audit/attribution can never mistake an automated decision for a human or
+//     agent reviewer.
+//
+// Pure and Harper-free (its only import, content-safety.ts, is pure regex), so
+// the whole fail-closed/strict-safety decision is unit-testable directly with no
+// Harper process — the same split resources/memory-reflect-lib.ts uses.
+import { scanFields } from "./content-safety.js";
+// ─── ADK scope tag (the per-user access-control boundary) ────────────────────
+// adk-flair collapses (app, user) → ONE Flair agentId, separating users ONLY by
+// a compound tag `adk:<app>:<user>`. That tag IS the access-control boundary, so
+// an auto-promoted claim that does not carry it is a cross-user leak.
+export const ADK_SCOPE_TAG_PREFIX = "adk:";
+// ─── Machine reviewer namespace (Sherlock req 4) ─────────────────────────────
+// A promotion records a reviewerId that feeds audit/attribution
+// (schemas/memory.graphql). An automated path must record one that can NEVER be
+// mistaken for a human/agent reviewer. Reserved `machine:` namespace; canonical
+// id for this consumer is machine:adk-auto-promote.
+//
+// NOTE ON DUPLICATION: src/cli.ts declares its own copies of these constants
+// (and validateHumanReviewerId, which refuses the reserved namespace on the
+// HUMAN promote path). The two live on opposite sides of the npm-packaging
+// boundary — src/ ships as the CLI bundle, resources/ ships as the Harper
+// component, and cli.ts's own header notes imports across that boundary "don't
+// survive npm packaging". They are kept in sync by the shared canonical string;
+// there is no runtime path that imports one into the other.
+export const MACHINE_REVIEWER_PREFIX = "machine:";
+export const MACHINE_REVIEWER_ADK_AUTO_PROMOTE = "machine:adk-auto-promote";
+/** Standard, honest rationale recorded on every auto-promoted claim + its
+ *  candidate row, so the audit trail states plainly that no human reviewed it. */
+export const AUTO_PROMOTE_RATIONALE = "auto-promoted from ADK session distillation (#1205) — unattended, own-memory only, scope-tag verified, content-safety scanned; no human reviewer";
+/**
+ * Per-call ceiling on auto-promotions (Kern's cost-ceiling note). Auto-promote
+ * runs once per nightly cycle, not on every write, and each promotion is a
+ * bounded DB write (plus at most one embedding compute on the Memory.put path),
+ * so this caps the blast radius of a single cycle rather than throttling a hot
+ * path. Overflow stays `pending` and is swept on subsequent cycles.
+ */
+export const DEFAULT_MAX_AUTO_PROMOTE_PER_CYCLE = 200;
+/**
+ * Decide whether an ADK-sourced candidate may be auto-promoted to own memory.
+ *
+ * FAIL-CLOSED throughout: any condition that cannot be positively confirmed
+ * results in `{ promote: false }` (the candidate is left pending for the human
+ * `rem promote` path), never a promotion. This function decides ONLY whether to
+ * promote and with what per-user scope tag / reviewer — never WHERE (the target
+ * is memory-only and enforced structurally by the resource; see this file's
+ * header, Req 1).
+ */
+export function decideAutoPromote(candidate) {
+    // Idempotency (Kern 2d): only ever act on a still-pending candidate. A
+    // re-run after a crash re-enumerates and skips anything already promoted.
+    if (candidate.status !== "pending") {
+        return { promote: false, reason: "not_pending" };
+    }
+    // Req 2 — tag lineage, FAIL CLOSED. Consume the stamped scopeTag directly
+    // (authoritative; never re-read sources). Absent, empty, or non-`adk:` ⇒
+    // refuse: a tagless claim in the shared agentId namespace is a cross-user
+    // leak, and auto-promote is ONLY for ADK-sourced (scopeTag-bearing)
+    // candidates — a non-ADK candidate still requires human `rem promote`.
+    const scopeTag = candidate.scopeTag;
+    if (typeof scopeTag !== "string" || !scopeTag.startsWith(ADK_SCOPE_TAG_PREFIX)) {
+        return { promote: false, reason: "no_adk_scope_tag" };
+    }
+    const claim = candidate.claim;
+    if (typeof claim !== "string" || claim.trim().length === 0) {
+        return { promote: false, reason: "empty_claim" };
+    }
+    // Req 3 — content-safety, STRICT for the unattended path. Same scanFields the
+    // Memory write path uses (content-safety.ts), but here a flag is ALWAYS a
+    // refusal, independent of FLAIR_CONTENT_SAFETY: an unattended promotion must
+    // never let a prompt-injection payload through merely because the instance is
+    // in `warn` mode. (The Memory.put() write scan still runs on top of this as
+    // defense-in-depth.)
+    const safety = scanFields({ content: claim }, ["content"]);
+    if (!safety.safe) {
+        return { promote: false, reason: `content_safety:${safety.flags.join(",")}` };
+    }
+    return {
+        promote: true,
+        scopeTag,
+        reviewerId: MACHINE_REVIEWER_ADK_AUTO_PROMOTE,
+        rationale: AUTO_PROMOTE_RATIONALE,
+    };
+}
+/** True iff `id` is in the reserved machine-reviewer namespace (an automated
+ *  path, never a human/agent reviewer). Mirror of src/cli.ts isMachineReviewerId
+ *  on the resources side of the packaging boundary. */
+export function isMachineReviewerId(id) {
+    return typeof id === "string" && id.startsWith(MACHINE_REVIEWER_PREFIX);
+}
+/**
+ * The tag set for an auto-promoted Memory. The per-user `scopeTag` MUST come
+ * first and is load-bearing — it is the access-control boundary that keeps the
+ * promoted claim visible only to its own user's tag filter. `auto-promoted`
+ * marks the whole class as machine-written so every auto-promoted claim is
+ * identifiable and bulk-removable if the policy is ever rolled back (Kern 2b);
+ * `nightly-rem-promoted` matches the human promote path; `from:<id>` preserves
+ * candidate lineage.
+ */
+export function buildAutoPromotedTags(candidateId, scopeTag) {
+    return [scopeTag, "nightly-rem-promoted", "auto-promoted", `from:${candidateId}`];
+}

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). */