Mouth addressing facts: room-keyed reply cache, exact pill anchors, no lookup for notices and edits, doc says claimed

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Heimdall 2026-11-11 06:24:52 +00:00
commit fd33ffa2cd
3 changed files with 53 additions and 14 deletions

View file

@ -200,24 +200,24 @@ Persona speech goes out through Matrix, not Discord. `tools/persona-matrix-mouth
### Addressing facts (`chat_pending.v3`)
The mouth wakes no one; the heartbeat and each Persona session decide who is told a delivery (Huginn `address.rs`, ruling `eureka-body:ruling:addressed-delivery-only`). Telling every Persona every message made 71.5% of 4,351 Persona turns on 2026-11-10 do nothing. The rule stays in one place, Huginn's, because two of its inputs are not Matrix facts: the Persona's stewardship records (her projects' chat names) and the sender's role (operator or Mind). The mouth owns the other half: what Matrix itself proves, per Persona, for the delivery.
The mouth wakes no one; the heartbeat and each Persona session decide who is told a delivery (Huginn `address.rs`, ruling `eureka-body:ruling:addressed-delivery-only`). Telling every Persona every message made 71.5% of 4,351 Persona turns on 2026-11-10 do nothing. The rule stays in one place, Huginn's, because two of its inputs are not Matrix facts: the Persona's stewardship records (her projects' chat names) and the sender's role (operator or Mind). The mouth owns the other half: what Matrix itself says, per Persona, for the delivery. Matrix verifies the sender's identity and nothing else: `tag` and `room` are the sender's claim in `m.mentions` (the homeserver does not check the text against it, nor that the sender may use `@room`), and `reply` is checked against the event it targets, which the mouth reads as her account.
A client asks for the facts by the kind it polls with: `gamecult.persona.chat_pending_request.v2` (the v1 tuple, `[persona, after_seq]`) is answered with `gamecult.persona.chat_pending.v3`; a v1 request still gets the 12-field `chat_pending.v2` answer unchanged. A v3 delivery is the 12 fields of the v2 delivery, then:
| Field | Type | Meaning |
|---|---|---|
| 12 `basis` | `"direct"`, `"tag"`, `"reply"`, `"room"` or nil | Why Matrix proves the message is for this Persona, first that holds: `direct` the room is one of her DMs; `tag` `m.mentions.user_ids` lists her id, or the client sent no `m.mentions` at all and the HTML body links her `matrix.to` pill; `reply` it replies to, or is in a thread under, an event her account wrote (her Self run speaks as her account, so its words count); `room` an `@room` mention. |
| 12 `basis` | `"direct"`, `"tag"`, `"reply"`, `"room"` or nil | Why the message is for this Persona, by what Matrix says, first that holds: `direct` the room is one of her DMs; `tag` `m.mentions.user_ids` lists her id, or the client sent no `m.mentions` at all and an `<a href>` in the HTML body is exactly her `matrix.to` link; `reply` it replies to, or is in a thread under, an event her account wrote (her Self run speaks as her account, so its words count; any member's message in a thread under one of her events is a `reply` too, and the target is read once per room and event, a failure for a minute); `room` an `@room` mention. A `notice` or an `edit` costs no reply lookup. |
| 13 `form` | `"message"`, `"notice"` or `"edit"` | `m.notice` is an automated line; `m.replace` is an edit of an earlier message. Only a `message` can address anyone. |
What the mouth cannot know, and so what a nil `basis` means: **unproven, not "not for her"**. Her handle and public name in the text (any casing, with or without `@`, `'s`), the names her stewardships list, a project's repo name, and whether the sender is the operator or a Mind are all matched by Huginn, not here. A reply whose target the homeserver will not give is nil and logged. The mouth also cannot see whether a message was meant for her without naming her. Every delivery is still delivered: nothing is dropped in the mouth, so the Huginn rule cannot lose a message the mouth had no way to judge.
What the mouth cannot know, and so what a nil `basis` means: **unproven, not "not for her"**. Her handle and public name in the text (any casing, with or without `@`, `'s`), the names her stewardships list, a project's repo name, and whether the sender is the operator or a Mind are all matched by Huginn, not here. A reply whose target the homeserver will not give is nil and logged. The mouth also cannot see whether a message was meant for her without naming her. Every delivery is still delivered, claimed tags included: nothing is dropped in the mouth, so the Huginn rule cannot lose a message the mouth had no way to judge.
Proposed runtime half (follow-up `persona-wakes-on-address-only`):
1. Poll with `chat_pending_request.v2` and parse `chat_pending.v3`.
2. A delivery is *addressed* to a Persona when `form == "message"` and (`basis` is not nil, or `address::addresses` matches her names or her projects' names on the text, or the sender is the operator and the rule matches). `basis == "room"` is the runtime's policy to weigh; the mouth only reports it.
2. A delivery is *addressed* to a Persona when `form == "message"` and either `basis` is `direct`, `tag` or `reply`, or `address::addresses` matches her names or her projects' names on the text. The off-beat wake keeps the sender gate of `heartbeat.rs` `wakes` (the operator or another Mind of the roster): a stranger's tag, `@room` or DM is delivered but wakes no one off the beat. `basis == "room"` is the runtime's policy to weigh; the mouth only reports it.
3. A real-time wake, a live session's tell and the stagger apply to addressed deliveries only. A `notice` or an `edit` never wakes, whatever its basis.
4. A delivery that is not addressed is acked in sequence with the rest, so the position moves (the mouth stops reading at 500 unacked deliveries); it is not lost: Matrix is the record, and the next addressed delivery's `context` (up to 20 lines) and a beat's own room read show it. Reading the tail on a scheduled beat is a runtime read of Matrix, a follow-up of the ruling `wake-reads-room-tail`; the mouth adds no endpoint for it.
5. `basis` and `form` are evidence, not authority: if they disagree with Huginn's own reading of the text, the runtime's `address.rs` decides for names, the mouth's `basis` for what only Matrix knows.
5. `basis` and `form` are evidence, not authority: a sender's claim is weighed by the runtime's own rule (`address.rs` for names, the sender gate for who may wake her); the mouth reports what the event says and what only Matrix could look up (the author of a reply target).
Golden bytes: `tests/fixtures/persona-chat-v5/`; Huginn pins the same bytes.

View file

@ -1423,3 +1423,38 @@ test("addressing facts: the v3 answer carries basis and form; the v2 answer a v1
assert.throws(() => docs.parseDeliveryV3([...docs.deliveryTuple(made[0]), "everyone", "message"]), /unknown delivery basis/);
assert.throws(() => docs.parseDeliveryV3(docs.deliveryTuple(made[0])), /14-field/);
});
test("addressing facts: a hit read for a reply in one room is not lent to a reply in another room, and a target the server places elsewhere is null", async () => {
const mine = { ...withContent("$mine", SELF, { body: "mine" }, 1000), room_id: ROOM };
const reply = id => withContent(id, META, { body: "re", "m.relates_to": { "m.in_reply_to": { event_id: "$mine" } } });
const hs = await fakeHomeserver({
preload: { [ROOM]: [mine], "!operator:gamecult.test": [{ ...mine, room_id: "!elsewhere:gamecult.test" }] },
sync: since => since === null ? { next_batch: "b0" } : { next_batch: "b1", ...joined({ [ROOM]: { timeline: { events: [reply("$prime")] } }, "!operator:gamecult.test": { timeline: { events: [reply("$spoof")] } } }) },
});
try {
const mouth = mouthFor(hs);
await mouth.syncOnce();
assert.deepEqual(facts(await mouth.syncOnce()), [["$prime", "reply", "message"], ["$spoof", null, "message"]]);
} finally { await hs.close(); }
});
test("addressing facts: a pill is her exact matrix.to anchor: a longer id, a non-link attribute and a quoted reply are no tag", async () => {
const html = h => ({ body: "x", format: "org.matrix.custom.html", formatted_body: h });
const { made } = await deliver([
withContent("$a", META, html(`<a href="https://matrix.to/#/${SELF}.evil.org">x</a>`)),
withContent("$b", META, html(`<span data-x="https://matrix.to/#/${SELF}">x</span>`)),
withContent("$c", META, html(`<a class="x" href='https://matrix.to/#/${SELF}'>Eureka</a>`)),
]);
assert.deepEqual(made.map(d => d.basis), [null, null, "tag"]);
});
test("addressing facts: an edit or a notice replying to her costs no target fetch, and a target that failed is not refetched within a minute", async () => {
const rel = { "m.relates_to": { "m.in_reply_to": { event_id: "$gone" } } };
const { made, hs } = await deliver([
withContent("$n", META, { msgtype: "m.notice", body: "n", ...rel }),
withContent("$r1", META, { body: "a", ...rel }),
withContent("$r2", META, { body: "b", ...rel }),
]);
assert.deepEqual(facts(made), [["$n", null, "notice"], ["$r1", null, "message"], ["$r2", null, "message"]]);
assert.equal(hs.seen.filter(r => r.path.includes("/event/")).length, 1);
});

View file

@ -298,23 +298,27 @@ export function createMouth({
if (directRooms.has(roomId)) return "direct";
const mentions = event.content["m.mentions"];
if (Array.isArray(mentions?.user_ids) ? mentions.user_ids.includes(selfId) : mentions === undefined && pillFor(event.content.formatted_body)) return "tag";
if (await repliesToMe(roomId, event.content["m.relates_to"])) return "reply";
if (formOf(event.content) === "message" && await repliesToMe(roomId, event.content["m.relates_to"])) return "reply"; // an edit or a notice wakes no one: no fetch for it
return mentions?.room === true ? "room" : null;
}
const pillFor = html => typeof html === "string" && [selfId, encodeURIComponent(selfId)].some(id => html.includes(`https://matrix.to/#/${id}`));
const authors = new Map(); // event id -> sender, read successes only, bounded
// A pill is an anchor whose href is exactly her matrix.to link; a longer id, an attribute that merely contains one and a quoted reply do not count.
const pillFor = html => typeof html === "string" && [...html.matchAll(/<a\s[^>]*?href\s*=\s*(["'])(.*?)\1/gi)].some(([, , href]) => [selfId, encodeURIComponent(selfId)].some(id => href === `https://matrix.to/#/${id}`));
const authors = new Map(); // `${room id} ${event id}` -> { sender, at }: read results, a failure kept for NEGATIVE_MS, bounded; the key holds the room so another room's reply cannot borrow a hit
const NEGATIVE_MS = 60 * 1000;
async function authorOf(roomId, eventId) {
if (authors.has(eventId)) return authors.get(eventId);
const key = `${roomId} ${eventId}`;
const known = authors.get(key);
if (known && (known.sender !== null || now() - known.at < NEGATIVE_MS)) return known.sender;
let sender = null;
try {
const target = await matrix("GET", `/rooms/${encodeURIComponent(roomId)}/event/${encodeURIComponent(eventId)}`, undefined, API, AbortSignal.timeout(sendTimeoutMs));
if (target?.room_id !== undefined && target.room_id !== roomId) return null; // an id from another room is not an answer about this one
authors.set(eventId, target.sender);
if (authors.size > DELIVERED_INDEX) authors.delete(authors.keys().next().value);
return target.sender;
if (target?.room_id === undefined || target.room_id === roomId) sender = typeof target?.sender === "string" ? target.sender : null; // an id from another room is not an answer about this one
} catch (error) {
say(`reply target ${eventId} not read: ${error.message}`);
return null;
}
authors.set(key, { sender, at: now() });
if (authors.size > DELIVERED_INDEX) authors.delete(authors.keys().next().value);
return sender;
}
async function repliesToMe(roomId, relates) {
const targets = new Set([relates?.["m.in_reply_to"]?.event_id, relates?.rel_type === "m.thread" ? relates.event_id : undefined].filter(id => typeof id === "string" && id !== ""));