@mnemoverse/mcp-memory-server 0.8.0 → 0.8.2

package/dist/scope.js

@@ -0,0 +1,480 @@
+/**
+ * Search-scope honesty — the note that turns "nothing found" from an assertion
+ * about the WORLD into a statement about where we actually looked.
+ *
+ * Why this module exists (incident 2026-08-07). Two agents lost a working day
+ * to the same silent failure: a message was written into a shared room, and an
+ * unscoped `memory_list_recent` answered "Nothing new since your watermark."
+ * The write was fine, the index was fine, and the read was fine — an UNSCOPED
+ * read simply never covers rooms.
+ *
+ * That is not a filter oversight; it is how the store is built. A room is a
+ * separate storage tenant (core ADR-019): with no `domain`, the request runs
+ * against the caller's OWN org, and room atoms live in the room's org. So the
+ * unscoped feed cannot see them and never could.
+ *
+ * The defect is therefore not the scoping — it is the WORDING. "Nothing new"
+ * is a claim about absence, and absence is only knowable within the scope you
+ * searched. An empty result from an unscoped read must therefore say what it did
+ * not cover: which rooms went unsearched and how to read them, that every room
+ * it has is archived and reachable by no path, or that it could not find out.
+ * Silence is correct in exactly one case — the caller has no rooms, so nothing
+ * was missed — and that case is a distinct state below rather than the falsy
+ * spelling of the other three.
+ *
+ * Kept out of index.ts so the copy can be unit-tested without booting the
+ * stdio transport, matching render.ts and teaching.ts.
+ */
+import { domainPhrase, exactLiteral, roomNamePhrase, withDomainEscapeLegend, } from "./names.js";
+/**
+ * How to NAME the scope inside a sentence, so the sentence is true on its own
+ * rather than corrected by a paragraph underneath it.
+ *
+ * "Nothing new since your watermark." was left untouched by the first two
+ * passes of this release — the very sentence this module's header names as the
+ * lie that cost two agents a day. A note was appended to it instead, so the
+ * assembled answer read as two voices: one asserting you were caught up, the
+ * next saying that assertion was meaningless. The sibling branch in memory_read
+ * had it right all along by naming its filters inside the sentence (review,
+ * 2026-08-08).
+ *
+ * The name inside that sentence then went through safeInline, which made the
+ * sentence false in the case that matters most: a read on `" engineering"` — the
+ * padded second store this release is about — answered `Nothing in
+ * "engineering"`, naming a DIFFERENT store, and a whitespace-only scope printed
+ * as `""`, i.e. as no scope at all. It is now the exact literal (src/names.ts),
+ * and when a name cannot be reproduced the sentence names nothing rather than
+ * naming something else.
+ *
+ * A room address stays unnamed ("that room") — unchanged, and deliberately: the
+ * address is already in the caller's hand, and this sentence has no need to
+ * print another principal's display string. Where a room's NAME is printed at
+ * all ({@link liveRoomsNote} below, the room tools in index.ts) it goes through
+ * `roomNamePhrase` (src/names.ts) — exactly, or declared unprintable — never
+ * through the lossy sanitiser, which renamed "проект" to "(unnamed room)".
+ *
+ * Lives here rather than in index.ts so the sentence can be unit-tested: this is
+ * the module about saying where we looked, and index.ts opens a stdio transport
+ * on import.
+ */
+export function scopeLabel(searched) {
+    if (!searched)
+        return "your own domains";
+    if (searched.startsWith("xroom:"))
+        return "that room";
+    return domainPhrase(searched);
+}
+/**
+ * "Nothing new since your watermark" is also what you get for a watermark in
+ * the FUTURE — a mixed-up timezone or a bad relative-date calculation reads
+ * exactly like a clean bill of health (dogfood, 2026-08-07). If the caller's
+ * `since` is ahead of now, say so and show the current time; that is the whole
+ * diagnosis, and the caller cannot reach it from "nothing new".
+ *
+ * The explaining clause claims a fact about TIME, never about any store. It
+ * used to read "nothing has been written after it YET" — an absence claim over
+ * EVERY store, printed directly above the scope disclosure admitting a room
+ * went unsearched, and premised on an admittedly-approximate client clock
+ * (review, 2026-08-08). The window is empty because it asks for entries newer
+ * than a moment that has not happened; what any store holds is not this note's
+ * to assert.
+ *
+ * `nowMs` is injected so the note is testable without freezing the clock.
+ */
+export function futureSinceNote(since, nowMs) {
+    if (!since)
+        return "";
+    const t = parseAsUtc(since);
+    if (t === null || t <= nowMs)
+        return "";
+    return (`\n\nNote: that watermark is in the FUTURE — it asks for entries newer than a ` +
+        `moment that has not happened yet, so an empty result here says nothing about ` +
+        `whether you are caught up. ` +
+        `This client's clock reads ${new Date(nowMs).toISOString().slice(0, 16)}Z ` +
+        `(the server's may differ slightly). Check the watermark you passed — a timezone ` +
+        `slip is the usual cause.`);
+}
+/**
+ * Parse an ISO-8601 instant the way the SERVER does: an offset-less value is
+ * UTC, not local time.
+ *
+ * `Date.parse("2026-08-08T13:00:00")` returns LOCAL midnight-relative millis,
+ * while both tool descriptions here and core's schema say "naive = UTC". The
+ * mismatch made this note lie in both directions (review, 2026-08-08): west of
+ * UTC a perfectly sane watermark was declared to be in the future and every
+ * clause of the note was false; east of UTC a genuinely future watermark was
+ * shifted into the past and the note stayed silent, missing the one case it
+ * exists for.
+ *
+ * Date-only values ("2026-08-08") are already parsed as UTC by spec, so only
+ * date-TIME values without an offset need the Z.
+ */
+function parseAsUtc(iso) {
+    const s = iso.trim();
+    const hasOffset = /(?:Z|[+-]\d{2}:?\d{2})$/i.test(s);
+    const isDateTime = /\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/.test(s);
+    const t = Date.parse(isDateTime && !hasOffset ? `${s.replace(" ", "T")}Z` : s);
+    return Number.isNaN(t) ? null : t;
+}
+/**
+ * The disclosure for the {@link NamedScope} arm `no-such-domain`: the caller
+ * scoped a read to a domain that is not in `/memory/stats.domains`.
+ *
+ * WHAT IT DOES, which is not what it was called. Until 0.8.1 this was
+ * `nearestDomainNote`, and the name outlived the behaviour twice over: the
+ * "nearest"/prefix guess it was named for was deleted as unsound (see the body),
+ * and even before that it was never a nearest-neighbour search. What remains is
+ * two branches, and neither is a proximity search:
+ *
+ *   1. an EXACT case-insensitive twin, when one exists in the known list and
+ *      both names can be printed reproducibly — the casing slip that silently
+ *      forks a namespace, which is the one miss a reader can act on
+ *      (dogfood, 2026-08-07);
+ *   2. otherwise a NAME-FREE statement that no store OF THE CALLER'S OWN
+ *      carries that exact name — bounded to its evidence: `/memory/stats.domains`
+ *      covers the caller's own org bucket only, so rooms and other principals'
+ *      stores are invisible to it and the sentence may not claim them (review,
+ *      2026-08-08; the destructive sibling in index.ts already said "in your
+ *      own store"). It is always safe to say and must never go quiet — silence
+ *      here is byte-identical to "the store is there, your query merely
+ *      missed".
+ *
+ * Deliberately conservative: only case differs. A whitespace or zero-width twin
+ * (`" engineering"` beside `"engineering"`) is NOT diagnosed here — extending the
+ * rule is a behaviour decision, and `memory_stats` closes that loop by printing
+ * both names exactly. Recorded in CHANGELOG's "Known and NOT fixed here".
+ */
+export function noSuchDomainNote(domain, knownDomains) {
+    // The RAW name, exactly as searched. This used to trim — a second copy of
+    // the mistake the caller had already made: a read on " engineering" searched
+    // the padded store, then this checked "engineering", matched it, and the one
+    // sentence that would have explained the miss was suppressed precisely when a
+    // stray space had caused it (review, 2026-08-08).
+    const wanted = domain;
+    if (!wanted)
+        return "";
+    const lower = wanted.toLowerCase();
+    // Match on the RAW values, print them through the EXACT renderer.
+    //
+    // This branch names two stores and invites the reader to act on one of them,
+    // so it may only print a name it can reproduce. It used to render through
+    // safeInline and guard the branch with `sanitize(x) === x`, which was correct
+    // in spirit and expensive in practice: safeInline's charset is ASCII, so
+    // every Cyrillic name — ordinary in this workspace — failed the guard and the
+    // most useful sentence this module has went silent for a whole alphabet. (An
+    // even earlier draft printed through the sanitiser without the guard, and
+    // asserted facts about ":acme", a name that exists nowhere.)
+    //
+    // src/names.ts prints exactly or returns null, so the guard is now the
+    // renderer itself and "проект" can be named as "проект". Both sides are
+    // checked: naming a twin we cannot reproduce would send the reader to a
+    // store whose name we just invented.
+    const wantedLiteral = exactLiteral(wanted);
+    const twin = wantedLiteral
+        ? knownDomains
+            .map((d) => ({ name: d, exact: exactLiteral(d) }))
+            .find((c) => c.name !== wanted && c.name.toLowerCase() === lower && c.exact !== null)
+        : undefined;
+    if (wantedLiteral && twin?.exact) {
+        return withDomainEscapeLegend(`\n\nDomain names are matched exactly, including case: ${wantedLiteral.literal} is not ` +
+            `the same store as ${twin.exact.literal}, which does exist. Did you mean that one?`, wanted, twin.name);
+    }
+    // NO "closest match" — the branch the old function NAME advertised, deleted
+    // rather than repaired. It named the FIRST element of an unordered
+    // `SELECT DISTINCT domain` having any prefix relation in either direction —
+    // so it was not a nearest neighbour, it could differ between two identical
+    // calls, and a one-character domain became the confidently-named "closest"
+    // match for every name starting with that letter. This module's own contract
+    // says a wrong guess is worse than silence, because the reader trusts it.
+    //
+    // The absence claim is narrowed twice: names match byte-for-byte, so a store
+    // whose name carries a leading space or a zero-width character is real but
+    // unreachable from a clean spelling — hence "that exact name", never "no such
+    // store". And it is bounded to the caller's OWN stores, because that is all
+    // the evidence covers: the known list is `/memory/stats.domains`, which
+    // reports one org bucket and sees no room and no other principal's store.
+    //
+    // NO pointer to memory_stats here, and the reason has CHANGED. A previous
+    // draft ended "— memory_stats quotes each name so you can see them", and that
+    // was removed because it could not work: the sanitiser collapsed and trimmed
+    // whitespace BEFORE the quotes went on, so " engineering" and "engineering"
+    // printed identically, and the reader was sent to a check that could not
+    // reveal the thing (reviews, 2026-08-08). memory_stats now prints exact
+    // literals (src/names.ts), so that objection is gone — the check works.
+    // Whether this sentence should carry the pointer again is a copy decision and
+    // not part of the renderer change; its absence stays pinned by
+    // test/scope.test.ts until someone decides. What must not come back is a
+    // pointer to a surface that cannot answer.
+    return (`\n\nNo store of your own has that exact name. Names match byte-for-byte, so a stray space, ` +
+        `a different case, or an invisible character makes a separate store — one that ` +
+        `exists and holds its own memories.`);
+}
+/** How many rooms to name before collapsing into a count. */
+const MAX_LISTED = 5;
+/** The disclosure for either kind of scope — "" only where the type says there
+ *  is genuinely nothing to disclose. */
+export function readScopeNote(scope) {
+    const known = scope.kind === "named" ? scope.named : scope.rooms;
+    return "note" in known ? known.note : "";
+}
+/**
+ * One room record, with every field narrowed to the type it claims.
+ *
+ * Returns null when the value cannot be read as a room — which makes the WHOLE
+ * payload `unknown` rather than silently contributing a room-shaped blank. A
+ * non-boolean `archived` is rejected for the same reason: we would have to guess
+ * whether the room is readable, and the guess decides whether the answer says
+ * "re-run with domain set" or "nothing in there is reachable".
+ *
+ * It is also a latent crash fixed: `safeInline` does `(s ?? "").replace(…)`, so
+ * a numeric `name` on the wire used to throw inside a renderer.
+ */
+function asRoom(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    const r = value;
+    const { archived } = r;
+    if (archived !== undefined && archived !== null && typeof archived !== "boolean") {
+        return null;
+    }
+    const str = (v) => (typeof v === "string" ? v : undefined);
+    return {
+        room_id: str(r.room_id),
+        name: str(r.name),
+        address: str(r.address),
+        role: str(r.role),
+        scope: str(r.scope),
+        archived: archived === true,
+    };
+}
+/** The opening clause every unscoped disclosure shares. */
+const SCOPE_PREFIX = `\n\nScope: your own domains only. Shared rooms are separate stores and are NOT ` +
+    `included in an unscoped read`;
+/**
+ * The rooms an unscoped read did not cover, named so they can be read.
+ *
+ * Archived rooms are deliberately NOT mentioned here. A counting clause was
+ * added and removed inside this release because it only ever rendered for
+ * owners — core filters archived rooms out of the member query entirely and
+ * hard-codes `archived=false` on joined rows — and because it promised recovery
+ * "until it is unarchived" when core has archive with no inverse (reviews,
+ * 2026-08-08). Both objections still stand for the MIXED case, which is this
+ * one: there is a readable room to point at, and that is what a reader can act
+ * on. The case where every room is archived is a different state with a
+ * different sentence (see below), because there silence is not an option: it
+ * either dangles a colon or lets the answer claim the memory is empty.
+ *
+ * The NAME is printed exactly (src/names.ts, `roomNamePhrase`) even though it is
+ * OWNER-chosen and display-only. This note used to render it through the
+ * injected sanitiser, which did not make hostile names harmless so much as it
+ * made ordinary names WRONG: two live rooms named "проект" and "план" both
+ * printed "(unnamed room)" in the very note that asks the reader to pick one
+ * (review, 2026-08-08). The exact literal keeps the anti-injection property —
+ * one line, quotes and backslashes and invisibles escaped — and a name that
+ * cannot be printed within the cap is declared unprintable rather than altered.
+ * The escape legend rides on the note itself, because this note only appears on
+ * UNSCOPED answers, where the assembling call sites pass no room names as
+ * legend candidates (they have `searched === undefined` in hand, not the list).
+ *
+ * `sanitize` (render.ts's safeInline) still guards the machine-shaped fields —
+ * `address` and `room_id`, which core charset-validates — as a defensive pass,
+ * unchanged.
+ */
+function liveRoomsNote(live, sanitize) {
+    const listed = live.slice(0, MAX_LISTED);
+    const shown = listed.map((r) => {
+        const name = roomNamePhrase(r.name);
+        const roomId = sanitize(r.room_id);
+        const address = sanitize(r.address) || (roomId ? `xroom:${roomId}` : "");
+        return address ? `  - ${name} — domain="${address}"` : `  - ${name}`;
+    });
+    const rest = live.length - shown.length;
+    const more = rest > 0 ? `\n  …and ${rest} more (memory_list_rooms)` : "";
+    return withDomainEscapeLegend(`${SCOPE_PREFIX} — ${live.length} room${live.length === 1 ? "" : "s"} ` +
+        `went unsearched:\n${shown.join("\n")}${more}\n` +
+        `Re-run with domain set to one of these to read it.`, ...listed.map((r) => r.name));
+}
+/**
+ * Every room the caller has is archived — the state that used to be spelled as
+ * an empty note plus `roomsFound: true`, i.e. as a promise of a disclosure that
+ * had been filtered out one function earlier.
+ *
+ * What it may claim, and why each clause is safe: an archived room refuses every
+ * read for owner and member alike (core resolves the room, then returns 403
+ * "Room is archived"); nothing in the client, the data plane or the portal plane
+ * clears the flag, so this connector genuinely has no operation that reopens
+ * one; and archiving is a soft flag, so the content is still there. The word
+ * "unarchive" is avoided on purpose — the withdrawn draft promised recovery
+ * "until it is unarchived", and no such operation exists to wait for.
+ *
+ * The rooms are counted, not named: there is no address that would do the reader
+ * any good, and an owner-chosen name is only worth surfacing when it is
+ * actionable.
+ */
+function archivedOnlyNote(archived) {
+    const plural = archived === 1 ? "" : "s";
+    return (`${SCOPE_PREFIX}. You have ${archived} shared room${plural}, ` +
+        `${archived === 1 ? "which is" : "all of which are"} archived. An archived room ` +
+        `refuses every read, for its owner as much as for a member, and this client has no ` +
+        `operation that reopens one. Archiving did not delete what is in there, so a memory ` +
+        `you remember writing can be real and still be unreachable from here.`);
+}
+/** We could not look. Says so, and still states the boundary — dropping the
+ *  caveat because the probe failed is the silence this module exists to end. */
+function uncheckedRoomsNote(reason) {
+    const cause = reason === "fetch-failed"
+        ? "the room list could not be fetched just now"
+        : "the room list came back in a shape this client does not recognise";
+    return (`${SCOPE_PREFIX}; ${cause}, so this answer cannot say whether any room went ` +
+        `unsearched. Check memory_list_rooms and re-run with domain set.`);
+}
+/**
+ * Classify a `/memory/rooms` body. Total: every payload maps to exactly one
+ * state, and a payload that is not a list of rooms maps to `unknown` — never to
+ * `none`, which is the substitution that turned a contract violation into "you
+ * have no rooms".
+ */
+export function classifyRooms(payload, sanitize) {
+    if (!Array.isArray(payload)) {
+        return { state: "unknown", reason: "unrecognised-shape", note: uncheckedRoomsNote("unrecognised-shape") };
+    }
+    const rooms = [];
+    for (const entry of payload) {
+        const room = asRoom(entry);
+        if (room === null) {
+            return {
+                state: "unknown",
+                reason: "unrecognised-shape",
+                note: uncheckedRoomsNote("unrecognised-shape"),
+            };
+        }
+        rooms.push(room);
+    }
+    const live = rooms.filter((r) => !r.archived);
+    const archived = rooms.length - live.length;
+    if (live.length > 0) {
+        return { state: "live", rooms, live, archived, note: liveRoomsNote(live, sanitize) };
+    }
+    if (archived > 0) {
+        return { state: "archived-only", rooms, archived, note: archivedOnlyNote(archived) };
+    }
+    return { state: "none" };
+}
+/** Fetch the caller's rooms and classify them. Never throws — a failure is a
+ *  state, not an exception, because every caller has to render it. */
+export async function probeRoomScope(fetchRooms, sanitize) {
+    try {
+        return classifyRooms(await fetchRooms(), sanitize);
+    }
+    catch {
+        return { state: "unknown", reason: "fetch-failed", note: uncheckedRoomsNote("fetch-failed") };
+    }
+}
+/**
+ * Not in the room list — and the reason is not only "wrong address or not a
+ * member", which is what this used to assert. A room the caller merely JOINED
+ * disappears from the list the moment its owner archives it (core filters
+ * `is_archived = FALSE` out of the member query), so for exactly the invited
+ * teammate this release is about, the old two-cause sentence was false.
+ */
+const NO_SUCH_ROOM_NOTE = `\n\nThat room is not in your list — the address may be wrong, you may not be a ` +
+    `member, or it may be archived: a room you only JOINED disappears from the list once ` +
+    `its owner archives it. memory_list_rooms shows the ones you can read.`;
+/** "We could not look" for a named scope, which the old code spelled as `""` —
+ *  i.e. exactly like "the store is there and your query merely missed". */
+function uncheckedNamedNote(probed, reason) {
+    const cause = reason === "fetch-failed"
+        ? "could not be fetched just now"
+        : "came back in a shape this client does not recognise";
+    return probed === "rooms"
+        ? `\n\nWhether you are a member of that room could not be checked — the room list ` +
+            `${cause}. So this empty result is not evidence that the address is wrong or that ` +
+            `you are not in it. memory_list_rooms shows the rooms you can read.`
+        : `\n\nWhether a store with that exact name exists could not be checked — the domain ` +
+            `list ${cause}. So this empty result is not evidence that the name is wrong; names ` +
+            `are matched byte-for-byte, and memory_stats lists them exactly.`;
+}
+function unchecked(name, probed, reason) {
+    return { state: "unchecked", name, probed, reason, note: uncheckedNamedNote(probed, reason) };
+}
+/**
+ * Probe for the one store a scoped read named.
+ *
+ * A ROOM ADDRESS IS CHECKED AGAINST THE ROOM LIST, never against `/memory/stats`
+ * — that exclusion is the whole reason this release exists. `memory_stats`
+ * reports the caller's own org bucket only, and not one of an account's twelve
+ * live rooms appears in its domain list, so probing it for an `xroom:` address
+ * would confidently answer "No store of your own has that exact name" about a
+ * room the caller is a member of: the false-absence claim being fixed,
+ * reintroduced by the fix (CodeRabbit, #65).
+ *
+ * The argument is the RAW value that was sent, never a trimmed copy. A read on
+ * `" engineering"` searched the padded store while a trimmed diagnosis checked
+ * `"engineering"`, found it, and stayed silent — suppressing the one note that
+ * explains the miss precisely when a stray space had caused it.
+ *
+ * Private because `name` must be non-empty, which only {@link probeReadScope}
+ * can guarantee: `searchedScope` maps `""` to `undefined`, so an empty domain is
+ * not a scope at all and takes the own-domains path.
+ */
+async function probeNamedScope(name, fetchStats, fetchRooms, sanitize) {
+    if (name.startsWith("xroom:")) {
+        let payload;
+        try {
+            payload = await fetchRooms();
+        }
+        catch {
+            return unchecked(name, "rooms", "fetch-failed");
+        }
+        const rooms = classifyRooms(payload, sanitize);
+        if (rooms.state === "unknown")
+            return unchecked(name, "rooms", rooms.reason);
+        const all = rooms.state === "none" ? [] : rooms.rooms;
+        const member = all.some((r) => r.address === name || `xroom:${r.room_id}` === name);
+        return member
+            ? { state: "present", name }
+            : { state: "no-such-room", name, note: NO_SUCH_ROOM_NOTE };
+    }
+    let payload;
+    try {
+        payload = await fetchStats();
+    }
+    catch {
+        return unchecked(name, "domains", "fetch-failed");
+    }
+    const domains = payload?.domains;
+    // Core's response model declares `domains: list[str]` with no default, so it
+    // is always present and always an array of strings on a 200. A missing key or
+    // a non-string element therefore means the body is not core's, and the only
+    // honest reading is that we did not get to look — not that the store is absent.
+    if (!Array.isArray(domains) || domains.some((d) => typeof d !== "string")) {
+        return unchecked(name, "domains", "unrecognised-shape");
+    }
+    const known = domains;
+    if (known.includes(name))
+        return { state: "present", name };
+    return { state: "no-such-domain", name, note: noSuchDomainNote(name, known) };
+}
+/**
+ * Build the {@link ReadScope} for one read: where it looked, and what we know
+ * about what it therefore did not cover. One GET per call — the room list for
+ * an unscoped read or an `xroom:` address, `/memory/stats` for a plain domain
+ * — and callers reach it on zero-result paths only. That is MORE probing than
+ * 0.8.0 did, not "exactly as before" (an earlier version of this comment):
+ * 0.8.0 made no probe at all on a domain-scoped, room-scoped or filtered read
+ * and none anywhere in the feed; only the plain unscoped read probed stats.
+ * The added reads are disclosed in the 0.8.1 CHANGELOG entry, rate cost
+ * included.
+ *
+ * `searched` must be the value that went over the wire — `searchedScope(domain)`
+ * — so that the diagnosis and the request can never describe different stores.
+ * A falsy value takes the own-domains path because that is what the request did:
+ * core filters on `domain is not None`, and `searchedScope` drops `""`.
+ */
+export async function probeReadScope(searched, fetchStats, fetchRooms, sanitize) {
+    if (!searched) {
+        return { kind: "own-domains", rooms: await probeRoomScope(fetchRooms, sanitize) };
+    }
+    return { kind: "named", named: await probeNamedScope(searched, fetchStats, fetchRooms, sanitize) };
+}
+//# sourceMappingURL=scope.js.map

package/dist/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","sourceRoot":"","sources":["../src/scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,UAAU,CAAC,QAA4B;IACrD,IAAI,CAAC,QAAQ;QAAE,OAAO,kBAAkB,CAAC;IACzC,IAAI,QAAQ,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,WAAW,CAAC;IACtD,OAAO,YAAY,CAAC,QAAQ,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAAC,KAAyB,EAAE,KAAa;IACtE,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IACtB,MAAM,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IAC5B,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,KAAK;QAAE,OAAO,EAAE,CAAC;IACxC,OAAO,CACL,+EAA+E;QAC/E,+EAA+E;QAC/E,6BAA6B;QAC7B,6BAA6B,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI;QAC3E,kFAAkF;QAClF,0BAA0B,CAC3B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAS,UAAU,CAAC,GAAW;IAC7B,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACrB,MAAM,SAAS,GAAG,0BAA0B,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACrD,MAAM,UAAU,GAAG,kCAAkC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC9D,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/E,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAc,EACd,YAA+B;IAE/B,0EAA0E;IAC1E,6EAA6E;IAC7E,6EAA6E;IAC7E,8EAA8E;IAC9E,kDAAkD;IAClD,MAAM,MAAM,GAAG,MAAM,CAAC;IACtB,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IACvB,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;IAEnC,kEAAkE;IAClE,EAAE;IACF,6EAA6E;IAC7E,0EAA0E;IAC1E,8EAA8E;IAC9E,yEAAyE;IACzE,8EAA8E;IAC9E,6EAA6E;IAC7E,0EAA0E;IAC1E,6DAA6D;IAC7D,EAAE;IACF,uEAAuE;IACvE,wEAAwE;IACxE,wEAAwE;IACxE,qCAAqC;IACrC,MAAM,aAAa,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IAC3C,MAAM,IAAI,GAAG,aAAa;QACxB,CAAC,CAAC,YAAY;aACT,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;aACjD,IAAI,CACH,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,KAAK,IAAI,CAAC,CAAC,KAAK,KAAK,IAAI,CAC/E;QACL,CAAC,CAAC,SAAS,CAAC;IACd,IAAI,aAAa,IAAI,IAAI,EAAE,KAAK,EAAE,CAAC;QACjC,OAAO,sBAAsB,CAC3B,yDAAyD,aAAa,CAAC,OAAO,UAAU;YACtF,qBAAqB,IAAI,CAAC,KAAK,CAAC,OAAO,4CAA4C,EACrF,MAAM,EACN,IAAI,CAAC,IAAI,CACV,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,mEAAmE;IACnE,4EAA4E;IAC5E,2EAA2E;IAC3E,2EAA2E;IAC3E,6EAA6E;IAC7E,0EAA0E;IAC1E,EAAE;IACF,6EAA6E;IAC7E,2EAA2E;IAC3E,8EAA8E;IAC9E,4EAA4E;IAC5E,wEAAwE;IACxE,0EAA0E;IAC1E,EAAE;IACF,0EAA0E;IAC1E,8EAA8E;IAC9E,6EAA6E;IAC7E,4EAA4E;IAC5E,yEAAyE;IACzE,wEAAwE;IACxE,wEAAwE;IACxE,8EAA8E;IAC9E,+DAA+D;IAC/D,yEAAyE;IACzE,2CAA2C;IAC3C,OAAO,CACL,6FAA6F;QAC7F,gFAAgF;QAChF,oCAAoC,CACrC,CAAC;AACJ,CAAC;AAaD,6DAA6D;AAC7D,MAAM,UAAU,GAAG,CAAC,CAAC;AA+HrB;wCACwC;AACxC,MAAM,UAAU,aAAa,CAAC,KAAgB;IAC5C,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC;IACjE,OAAO,MAAM,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,MAAM,CAAC,KAAc;IAC5B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACrF,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,MAAM,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;IACvB,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,IAAI,IAAI,OAAO,QAAQ,KAAK,SAAS,EAAE,CAAC;QACjF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,GAAG,GAAG,CAAC,CAAU,EAAsB,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACxF,OAAO;QACL,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;QACvB,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;QACjB,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;QACvB,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;QACjB,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC;QACnB,QAAQ,EAAE,QAAQ,KAAK,IAAI;KAC5B,CAAC;AACJ,CAAC;AAED,2DAA2D;AAC3D,MAAM,YAAY,GAChB,iFAAiF;IACjF,8BAA8B,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,SAAS,aAAa,CACpB,IAA4B,EAC5B,QAAkD;IAElD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;IACzC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC7B,MAAM,IAAI,GAAG,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACpC,MAAM,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QACnC,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACzE,OAAO,OAAO,CAAC,CAAC,CAAC,OAAO,IAAI,cAAc,OAAO,GAAG,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC;IACvE,CAAC,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IACxC,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,IAAI,2BAA2B,CAAC,CAAC,CAAC,EAAE,CAAC;IAEzE,OAAO,sBAAsB,CAC3B,GAAG,YAAY,MAAM,IAAI,CAAC,MAAM,QAAQ,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG;QACrE,qBAAqB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI;QAChD,oDAAoD,EACtD,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAC7B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAS,gBAAgB,CAAC,QAAgB;IACxC,MAAM,MAAM,GAAG,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;IACzC,OAAO,CACL,GAAG,YAAY,cAAc,QAAQ,eAAe,MAAM,IAAI;QAC9D,GAAG,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,kBAAkB,8BAA8B;QACjF,oFAAoF;QACpF,qFAAqF;QACrF,sEAAsE,CACvE,CAAC;AACJ,CAAC;AAED;gFACgF;AAChF,SAAS,kBAAkB,CAAC,MAAuB;IACjD,MAAM,KAAK,GACT,MAAM,KAAK,cAAc;QACvB,CAAC,CAAC,6CAA6C;QAC/C,CAAC,CAAC,mEAAmE,CAAC;IAC1E,OAAO,CACL,GAAG,YAAY,KAAK,KAAK,oDAAoD;QAC7E,iEAAiE,CAClE,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC3B,OAAgB,EAChB,QAAkD;IAElD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,oBAAoB,EAAE,IAAI,EAAE,kBAAkB,CAAC,oBAAoB,CAAC,EAAE,CAAC;IAC5G,CAAC;IACD,MAAM,KAAK,GAAkB,EAAE,CAAC;IAChC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC3B,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,OAAO;gBACL,KAAK,EAAE,SAAS;gBAChB,MAAM,EAAE,oBAAoB;gBAC5B,IAAI,EAAE,kBAAkB,CAAC,oBAAoB,CAAC;aAC/C,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC5C,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpB,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,CAAC;IACvF,CAAC;IACD,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QACjB,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,gBAAgB,CAAC,QAAQ,CAAC,EAAE,CAAC;IACvF,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AAC3B,CAAC;AAED;sEACsE;AACtE,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,UAAkC,EAClC,QAAkD;IAElD,IAAI,CAAC;QACH,OAAO,aAAa,CAAC,MAAM,UAAU,EAAE,EAAE,QAAQ,CAAC,CAAC;IACrD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,kBAAkB,CAAC,cAAc,CAAC,EAAE,CAAC;IAChG,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,iBAAiB,GACrB,iFAAiF;IACjF,sFAAsF;IACtF,uEAAuE,CAAC;AAE1E;2EAC2E;AAC3E,SAAS,kBAAkB,CAAC,MAA2B,EAAE,MAAuB;IAC9E,MAAM,KAAK,GACT,MAAM,KAAK,cAAc;QACvB,CAAC,CAAC,+BAA+B;QACjC,CAAC,CAAC,qDAAqD,CAAC;IAC5D,OAAO,MAAM,KAAK,OAAO;QACvB,CAAC,CAAC,iFAAiF;YAC/E,GAAG,KAAK,2EAA2E;YACnF,oEAAoE;QACxE,CAAC,CAAC,oFAAoF;YAClF,QAAQ,KAAK,uEAAuE;YACpF,iEAAiE,CAAC;AAC1E,CAAC;AAED,SAAS,SAAS,CAChB,IAAY,EACZ,MAA2B,EAC3B,MAAuB;IAEvB,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;AAChG,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,KAAK,UAAU,eAAe,CAC5B,IAAY,EACZ,UAAkC,EAClC,UAAkC,EAClC,QAAkD;IAElD,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9B,IAAI,OAAgB,CAAC;QACrB,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,UAAU,EAAE,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC;QAClD,CAAC;QACD,MAAM,KAAK,GAAG,aAAa,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC/C,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QAC7E,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC;QACtD,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,IAAI,IAAI,SAAS,CAAC,CAAC,OAAO,EAAE,KAAK,IAAI,CAAC,CAAC;QACpF,OAAO,MAAM;YACX,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE;YAC5B,CAAC,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC;IAC/D,CAAC;IAED,IAAI,OAAgB,CAAC;IACrB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,UAAU,EAAE,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC;IACpD,CAAC;IACD,MAAM,OAAO,GAAI,OAAoD,EAAE,OAAO,CAAC;IAC/E,6EAA6E;IAC7E,8EAA8E;IAC9E,4EAA4E;IAC5E,gFAAgF;IAChF,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,EAAE,CAAC;QAC1E,OAAO,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,oBAAoB,CAAC,CAAC;IAC1D,CAAC;IACD,MAAM,KAAK,GAAG,OAAmB,CAAC;IAClC,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IAC5D,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,IAAI,EAAE,gBAAgB,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC;AAChF,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,QAA4B,EAC5B,UAAkC,EAClC,UAAkC,EAClC,QAAkD;IAElD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC,UAAU,EAAE,QAAQ,CAAC,EAAE,CAAC;IACpF,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,CAAC;AACrG,CAAC"}

package/dist/teaching.d.ts

@@ -9,6 +9,7 @@
  * constraints stay: no over-claiming, and the never-store-secrets safety line
  * is kept on write surfaces.
  */
+import type { ReadScope } from "./scope.js";
 /**
  * Server-level instructions, passed to the McpServer constructor and landed
  * verbatim in the connected model's system prompt by MCP clients.
@@ -19,40 +20,83 @@
  * - Active polarity: no "only when the user explicitly asks" gating.
  * - Mentions every tool family: read/write/stats/feedback, delete, rooms, vault.
  */
-export declare const SERVER_INSTRUCTIONS = "You own this long-term memory. It persists across sessions and every AI tool this user connects (Claude, ChatGPT, editors). Use it as a habit: call memory_read before answering anything that may have come up before, and memory_write the moment you learn a durable fact, preference, or decision \u2014 don't wait to be asked. Rate recalls with memory_feedback so good ones surface faster; memory_stats shows counts; memory_list_recent: newest first; prune with memory_delete; memory_delete_domain wipes a domain, only with user go-ahead. Rooms (memory_create_room, memory_invite_to_room, memory_join_room, memory_list_rooms) share memory with others; vault_list names stored secrets by alias, never values. Never store passwords, API keys, payment data, MFA codes, government IDs, or health records.";
+export declare const SERVER_INSTRUCTIONS = "You own this long-term memory. It persists across sessions and every AI tool this user connects. Use it as a habit: memory_read before answering anything that may have come up; memory_write the moment you learn a durable fact, preference or decision \u2014 don't wait to be asked. Shared rooms are SEPARATE stores: to read one, pass its address as domain (memory_list_rooms); unscoped reads never cover rooms. Rate recalls with memory_feedback; memory_stats shows counts; memory_list_recent is newest-first; memory_delete prunes; memory_delete_domain wipes a domain, only with user go-ahead. Rooms: memory_create_room, memory_invite_to_room, memory_join_room. vault_list names secrets by alias, never values. Never store passwords, API keys, payment data, MFA codes, government IDs, or health records.";
 /** The pre-existing zero-result message — kept as the fail-open fallback. */
 export declare const NO_MATCH_MESSAGE = "No memories found for this query.";
 /** Hint for an UNSCOPED no-match against a non-empty store: widen the query.
  *  (No drop-the-filter clause — none was set; advising to remove a filter that
  *  does not exist nudges the model into confabulating state.) */
 export declare const NO_MATCH_HINT = " Try a broader query.";
-/** Hint for a DOMAIN-SCOPED no-match: here a filter genuinely exists, so
- *  suggesting to drop it is honest and actionable. */
-export declare const NO_MATCH_SCOPED_HINT = " Try a broader query, or drop the domain filter to search all domains.";
 /**
- * First-contact greeting: shown ONLY when a read comes back empty AND the
- * store holds zero memories — i.e. the very first read of this account's life.
- * Seeds the ANSWER, not the store: one functional paragraph that says what
- * this store is, how to save the first memory, and one next step. It can never
- * appear again once anything is stored (total_atoms > 0 takes the other branch).
+ * Hint for a DOMAIN-SCOPED no-match: widen the query, or try another domain —
+ * and NEVER drop the scope.
+ *
+ * This doc used to read "here a filter genuinely exists, so suggesting to drop
+ * it is honest and actionable", which described a draft that no longer exists:
+ * the clause "…or drop the domain filter to search all domains" was deleted, and
+ * a test now forbids it. The advice was actively harmful when the domain is a
+ * room — an unscoped read does not cover rooms at all, so dropping the filter is
+ * the one move guaranteed to lose the content the reader is hunting, and it is
+ * the step that cost two agents a day on 2026-08-07.
+ */
+export declare const NO_MATCH_SCOPED_HINT = " Try a broader query, or a different domain.";
+/**
+ * The honest line for an account whose OWN domains are empty but whose rooms
+ * are not — an invited teammate whose every memory lives in shared rooms.
+ *
+ * Without this, such a caller was greeted with EMPTY_STORE_WELCOME: "your
+ * memory is empty, nothing has been saved yet, which is why this search
+ * returned nothing" — three false clauses, immediately contradicted by the
+ * scope note appended underneath, in the same payload (review, 2026-08-08).
+ * That reader is precisely the person from the incident this release is about.
+ *
+ * ENDS WITH A COLON, so it is only ever emitted together with the disclosure
+ * that follows it. That pairing used to be two independent decisions and they
+ * disagreed: this line was chosen from a flag counting ALL rooms while the
+ * disclosure was built from the LIVE ones, so an account whose only room was
+ * archived received the colon and nothing after it. Both now come out of the
+ * same {@link RoomScope} arm, and the arm that has nothing to disclose has no
+ * `note` field to forget.
+ */
+export declare const EMPTY_PERSONAL_STORE_WITH_ROOMS = "Nothing in your own domains \u2014 they hold no memories yet. That is not the whole picture:";
+/**
+ * The same situation with the room probe UNANSWERED. Says the one true thing —
+ * the personal store measured zero and the rest could not be checked — and
+ * deliberately does NOT say "nothing has been saved yet", which was reachable
+ * here and is a claim about a scope this client failed to reach.
+ */
+export declare const EMPTY_PERSONAL_STORE_ROOMS_UNCHECKED = "Nothing in your own domains \u2014 they hold no memories yet. Whether that is the whole picture could not be checked:";
+/**
+ * First-contact greeting: shown ONLY when a read comes back empty, the personal
+ * store holds zero memories, AND the room probe answered that there are no rooms
+ * — i.e. the very first read of this account's life, established rather than
+ * assumed. Seeds the ANSWER, not the store: one functional paragraph that says
+ * what this store is, how to save the first memory, and one next step.
  */
 export declare const EMPTY_STORE_WELCOME: string;
 /**
- * Decide what a zero-result memory_read should say.
- *
- * DOMAIN-SCOPED reads (`scopedToDomain` — the caller passed a `domain` arg,
- * e.g. a shared room) never greet and never probe: the stats call measures the
- * PERSONAL store, so on a scoped read it could claim "the store is empty"
- * about a domain that has memories the query merely missed (review finding).
- * The scoped copy suggests dropping the filter — honest, one actually exists.
- *
- * UNSCOPED reads make ONE stats call (only ever on the zero-result path) to
- * distinguish "store is truly empty" from "no match for this query":
- * - total_atoms === 0     → EMPTY_STORE_WELCOME (first-contact greeting)
- * - total_atoms > 0       → no-match + the broaden hint (no filter clause)
- * - stats throws/malformed → the plain old no-match message (fail-open to the
- *   pre-greeting behavior; never surfaces an error, never writes anything)
+ * Assemble the WHOLE answer for a zero-result read: the head sentence and the
+ * disclosure that belongs with it, in one place.
+ *
+ * They are assembled together on purpose. While the head came from here and the
+ * tail was concatenated by the caller, the two could be — and were — derived
+ * from different facts: a head promising "that is not the whole picture:" with
+ * an empty tail after it, and a first-contact greeting under a tail admitting
+ * the room list could not be fetched. Every arm below returns a complete answer,
+ * so a head cannot outlive the evidence for it.
+ *
+ * A NAMED scope never greets and never probes stats: that probe measures the
+ * PERSONAL store, so on a scoped read it could claim "the store is empty" about
+ * a domain whose memories the query merely missed. Its four arms are the four
+ * things we can know about the name.
+ *
+ * An UNSCOPED scope makes ONE stats call, on this path only:
+ * - stats unreachable / no number → the plain no-match message + the disclosure
+ * - total_atoms > 0               → no-match + broaden hint + the disclosure
+ * - total_atoms === 0             → one head per room state, each with its own
+ *   disclosure; only `rooms.state === "none"` may claim the memory is empty,
+ *   because only there has the claim been established.
  */
 export declare function buildReadEmptyResponse(fetchStats: () => Promise<{
     total_atoms?: number;
-}>, scopedToDomain?: boolean): Promise<string>;
+}>, scope: ReadScope): Promise<string>;