Skip to content

fix(weixin): bound _known_users to recent peers - #24826

Merged
KiroCrewCaptain merged 1 commit into
kirodotdev:mainfrom
IngridMorstrad:fix/weixin-known-users-bound
Oct 27, 2026
Merged

KiroCrewCaptain merged 1 commit into
kirodotdev:mainfrom
IngridMorstrad:fix/weixin-known-users-bound

Conversation

@IngridMorstrad

@IngridMorstrad IngridMorstrad commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Stop WeixinTransport._known_users from growing without bound for the life of the gateway.

src/kiro_crew/weixin/transport.py records one entry per distinct inbound DM
peer in receive() and evicts none of them — no TTL, no cap, no removal on any
path, unlike the _seen dedup map beside it. Under the supported
dm_policy="open" config the transport serves any DM, so the key space is every
user who ever messaged the bot and the set grows for the process's lifetime.

Why it matters

A long-lived open-policy iLink bot reachable by many users accumulates ~100 B of
never-freed memory per distinct peer, indefinitely. It is a slow leak rather than
an outage, but it has no ceiling and the retained entries are not load-bearing:
may_send_to() consults _allowed alone, so the set only advertises recent peers
as proactive-send targets.

Not a goal

  • wecom/transport.py's sibling _warm_chats set has the same shape; it is
    tracked and fixed separately, not here.

What changed (motivation → approach → change)

Observed symptom: _known_users size grows 1:1 with distinct senders and never
decreases. Root cause: it is a plain set with an unconditional .add() in
receive() and no eviction. Change: make it an OrderedDict[str, None] LRU
bounded by a named KNOWN_USERS_CAP (512). On receive, the peer is recorded
newest-last (move_to_end) and the oldest entries over the cap are dropped
(popitem(last=False)). The two read sites wrap it in set(). Because
may_send_to() consults _allowed alone, eviction never changes authorization;
an evicted peer only drops out of the advertised proactive-send targets until it
writes again, which re-admits it.

So the per-entry key size stays bounded too, a pathologically long from_user_id
(over MAX_RETAINED_USER_ID_LEN, 256) is NOT remembered in the LRU — but the
message is still served, so no DM is ever dropped. This is a retention ceiling, not a claim about the real iLink id length, so it
neither rejects nor truncates anything. Per the a-bound-bounds-every-field-it-retains review rule, the overflow is COUNTED (_known_users_evicted) and said out loud once per configured_targets() snapshot (an unavailable known_users_truncated sentinel that is never a send target and never an inferred owner), and the unresolved-target refusal past the cap carries its own SEL reason so a truncated tail is not mistaken for peers that were never configured. messaging.md is updated to describe all of this.

Backwards compatibility

Compatible: _known_users is a private instance attribute; its external
behaviour (which identities configured_targets() / resolve_configured_target()
advertise, and may_send_to()'s decisions) is unchanged for any realistic peer
count, and only differs beyond 512 distinct recent peers, where it now bounds
instead of growing.

Removes nothing: no documented capability, record, key or public function is
removed, hidden, renamed or tightened; the only behavioural change is that the
in-memory recent-peer list stops past 512 entries instead of growing forever.

Tests

test/test_weixin_transport_known_users.py drives the real receive() entry point and locks in: the set stays <= KNOWN_USERS_CAP after 1,000 distinct senders (newest kept, oldest evicted); an evicted peer that writes again is re-admitted; churning the LRU past the cap never changes may_send_to() (it consults _allowed alone); an over-long from_user_id is still dispatched but not retained (boundary inclusive at the ceiling); and the overflow is disclosed exactly once per snapshot plus in the refusal, with no sentinel before the cap is reached. test/test_channel_transport_outbound_authz.py is updated to seed the LRU by its new type.

Proof: PROVEN test/test_weixin_transport_known_users.py::test_known_users_is_bounded_under_many_distinct_senders, test/test_weixin_transport_known_users.py::test_an_evicted_peer_is_re_admitted_when_it_writes_again (head dd40573)

Manual verification

N/A — unit coverage drives the real receive() path and exercises the bound,
eviction and authorization behaviours directly.

Related Issues

Closes #24825

Sibling sweep

Swept: git grep -nE "self\._(known_users|warm_chats)\b" -- src/
Sibling: src/kiro_crew/wecom/transport.py:_warm_chats -- tracked in a separate PR -- same unbounded-peer-set shape under wecom.allow_all_users; fixed there to keep this diff single-file in production code
Sibling: src/kiro_crew/weixin/transport.py:_known_users -- changed here

Pattern harvest

Not generalizable: this is one unbounded learned-peer set; the gateway's other
long-lived maps already carry a cap, TTL, LRU or live-set prune, so there is no
recurring un-bounded-collection class a rule would catch here.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable) — N/A, no documented behaviour changes
  • No secrets, credentials, or internal references in the diff

@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running labels Oct 27, 2026
@github-actions

github-actions Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision 5c1b81ef1a313773aaa0e9f8de6de20c49acbf19 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ✅ PASS

Premise-level review of 5c1b81ef1a313773aaa0e9f8de6de20c49acbf19 via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

The cap fixes linked issue #24825 at the cause: the set had no eviction. Every rider is required by the blocking AUTOSDE rule a-bound-bounds-every-field-it-retains (lines 1297–1311).

What this change ships

Inventory (7 items) — 3 justified

Intent: stop an open-policy Weixin bot from using more memory for every new person who ever messages it. This is a FIX.

  1. The recent-peer list now keeps only the 512 most recent senders; older ones drop out of the proactive-send targets until they write again — justified
  2. A send addressed to an evicted peer resolves as "target not configured" until that peer writes again — justified
  3. A sender id longer than 256 characters is still served but never remembered as a target — rides along; required by a-bound-bounds-every-field-it-retains (bound on each retained string)
  4. Past the cap, the target list shows an unavailable "recent-peer list truncated" entry — rides along; required by the same rule (overflow said once per snapshot)
  5. A refusal while the list is truncated writes its own SEL audit reason, unresolved_target_roster_truncated — rides along; required by the same rule (the audit reason names the truncation)
  6. Two new named module constants: KNOWN_USERS_CAP and MAX_RETAINED_USER_ID_LEN — justified
  7. The messaging.md spec now describes the bound, the eviction and the disclosure — justified

[FIRST-PRINCIPLES-REVIEWED] 5c1b81e

Description read

[DESCRIPTION-READ] 5d95f99e79f06f36b31f4714a9c0f93ef46a84156481c10c21020946a97f4c83

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 5c1b81ef1a313773aaa0e9f8de6de20c49acbf19 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the LRU cap removes a leak with no ceiling, and the only readers of the evicted entries are routes for sending to recent peers, which a peer gets back by writing again.

Notes

  • The claim that may_send_to() "consults _allowed alone" holds only on the allowlist branch. Under open it returns True for anyone, as the edited messaging.md paragraph itself says. Eviction is still harmless to authorization, but the transport comment and the test docstring should say "only on the allowlist branch".

[DESIGN-REVIEWED] 5c1b81e

Description read

[DESCRIPTION-READ] 6101bedfeb63eca1e5e900d86f8df18b70dddcf6f7ab08dd6c0beff1288815e0

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed 5c1b81ef1a313773aaa0e9f8de6de20c49acbf19 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

Notes:

  • The overflow sentinel's unavailable_reason="known_users_truncated" is a machine token. LinkedSurfacesSection.tsx:635 and :585 show it verbatim as the disabled row's sub-line and in its click toast, while the other transports supply prose here.

[OPUS-REVIEWED] 5c1b81e

@IngridMorstrad
IngridMorstrad force-pushed the fix/weixin-known-users-bound branch from 0d409b5 to 305c74d Compare October 27, 2026 09:37
@IngridMorstrad

Copy link
Copy Markdown
Contributor Author

Thanks — both notes were accurate and are addressed in 305c74d0ec (comment-only, no behaviour change):

  • transport.py:20 wecom claim. Right, wecom/_warm_chats is still an unbounded set on main; that fix is a separate PR. Reworded so the constant no longer asserts wecom already carries the bound — it now says the value lines up with the bound the sibling peer set takes.
  • "an evicted peer loses nothing". Reworded to be precise: eviction never changes authorization (may_send_to consults _allowed alone), but under dm_policy="open" an evicted peer does drop out of configured_targets() / resolve_configured_target() — so a proactive send addressed to it is unavailable until it writes again, which re-admits it.

@github-actions

github-actions Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed 5c1b81ef1a313773aaa0e9f8de6de20c49acbf19 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 5c1b81e

@IngridMorstrad
IngridMorstrad force-pushed the fix/weixin-known-users-bound branch from 305c74d to 2713e26 Compare October 27, 2026 09:53
@IngridMorstrad

Copy link
Copy Markdown
Contributor Author

Addressed in 2713e26b3d.

GPT 6.1 (blocking) — evicted recipients indistinguishable from never-configured. The eviction is inherent to bounding a learned-peer cache, but it was silent, which is the real gap. Added a _known_users_evicted counter (incremented on each capacity eviction) and a one-shot INFO log when the cap is first reached, stating that an addressed send to an evicted peer is unavailable until it writes again. This makes capacity eviction observable in logs and queryable on the transport without retaining any evicted identities (no unbounded history), which is the shape the finding asked for. A full per-target truncated/eviction-count field on ConfiguredChannelTarget snapshots would be a cross-channel API change beyond this fix's goal; the counter + log is the minimal honest version. Pinned by a test assertion on the counter.

Opus notes:

  • transport.py:21 WeCom claim — reworded again so it no longer asserts WeCom is bounded; it now says _warm_chats has the same growth shape and is a candidate for the same bound (the WeCom fix is a separate PR).
  • messaging.md — updated in the same commit to describe _known_users as a bounded LRU and the evicted-peer-resolves-as-not-configured-until-it-writes-again behaviour.

@IngridMorstrad
IngridMorstrad force-pushed the fix/weixin-known-users-bound branch from 2713e26 to 25913ca Compare October 27, 2026 10:14
@IngridMorstrad

Copy link
Copy Markdown
Contributor Author

Addressed in 25913ca283.

GPT 6.1 (blocking) — peer-count cap does not bound retained identifier sizes. Fair: a count cap alone leaves per-id bytes unbounded. Added a named MAX_USER_ID_LEN (256) and reject an inbound from_user_id longer than it before any retention — the guard sits ahead of the LRU insert, _dedup, and the _ctx.set context-token write, so it bounds the bytes held by every field keyed on the id, not just _known_users. An iLink id is a short opaque handle (wxid_…, <hex>@im.bot), so a megabyte-scale value is malformed; it is rejected (and SEL-audited) rather than truncated, which would forge a different recipient id. Pinned by a test that an oversized id never enters the set while an id exactly at the cap is accepted.

This also tightens the base-branch _ctx.set retention the adjudication noted, since the same guard now gates that write too.

@IngridMorstrad
IngridMorstrad force-pushed the fix/weixin-known-users-bound branch from 25913ca to ee98b25 Compare October 27, 2026 10:26
@IngridMorstrad

Copy link
Copy Markdown
Contributor Author

Reworked in ee98b25161 to satisfy both review lanes, which were pulling opposite ways on the oversized-id question.

  • First Principles (BLOCK) was right that the count cap alone fixes weixin: _known_users grows unbounded under dm_policy=open #24825, that rejecting a DM whose id exceeds an unverified 256 is out-of-goal and risks silently dropping a real user, and that the eviction counter had zero consumers. Removed the counter + one-shot log, and removed the message-dropping rejection.
  • GPT 6.1's underlying point — a count cap leaves per-entry bytes unbounded — still holds. Reconciled rather than reverted: an over-long from_user_id (> MAX_RETAINED_USER_ID_LEN, 256) is still dispatched, it is just not remembered in the LRU. That bounds retained bytes without dropping or truncating any message, and it is framed as a retention ceiling, not a claim about the real iLink id format — so it needs no protocol citation and can never cost a legitimate user a delivery.

Net diff is now the count-cap LRU + read-site set() + a retention-only length guard + the doc. Test asserts the over-long id is delivered but absent from the set, and that an id exactly at the ceiling is kept.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 27, 2026
@IngridMorstrad
IngridMorstrad force-pushed the fix/weixin-known-users-bound branch from ee98b25 to 71622e8 Compare October 27, 2026 12:54
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 27, 2026
@IngridMorstrad
IngridMorstrad force-pushed the fix/weixin-known-users-bound branch from 71622e8 to bbdae6e Compare October 27, 2026 13:11
@IngridMorstrad

Copy link
Copy Markdown
Contributor Author

Addressed in bbdae6ea5a (rebased onto main after #24774 landed; the earlier shard-2 cascade is gone).

GPT 6.1 (blocking) — eviction loses truncation provenance (a-bound-bounds-every-field-it-retains). Implemented exactly what the rule requires:

  • Counted: _known_users_evicted increments on each cap eviction.
  • Disclosed once per snapshot: configured_targets() appends a single unavailable known_users_truncated sentinel when evictions have occurred. It is not a user: target and is available=False, so sole_direct_target never treats it as a candidate — no owner can be inferred from it and a genuine sole available peer is still the owner.
  • Refusal names the truncation: when resolve_configured_target returns None past the cap it emits a distinct SEL reason (unresolved_known_users_truncated), so capacity eviction is distinguishable from a never-known recipient rather than borrowing target_not_configured.

This reconciles the earlier First Principles note that flagged a bare counter as "zero consumers": the counter now feeds the snapshot and the refusal, which is precisely the consumer the rule mandates. Tests pin the once-per-snapshot disclosure, the refusal, and that no sentinel appears before the cap is reached.

@IngridMorstrad
IngridMorstrad force-pushed the fix/weixin-known-users-bound branch from bbdae6e to dd40573 Compare October 27, 2026 13:32
@IngridMorstrad

Copy link
Copy Markdown
Contributor Author

Both blocking findings fixed in dd405731be — they were defects in the audit code the previous push added, and they pulled in opposite directions on the same branch, so I fixed the whole thing rather than patch one line.

  • GPT 6.1 (security) — credential in SEL caller. Correct: log_api_access(caller=value, …) put the raw target id into caller_identity, which SEL does not redact (only operation/resources/error). The refusal now passes a fixed caller="weixin" and names the truncation in the redacted resources (known_users_truncated=true cap=512). A test asserts a credential-shaped target id never reaches caller or any logged value.
  • Opus 5.5 — truncation reason applied to never-seen ids. Correct: once any eviction had happened, every unresolved user: id got labelled a capacity eviction, which destroys the distinction. Since an evicted id and an unknown id are indistinguishable once dropped (and remembering evicted ids would reintroduce the unbounded growth the cap removes), the audit no longer claims this id was evicted — it states, as a property of the roster, that the roster is truncated (unresolved_target_roster_truncated). The AUTOSDE rule's requirement ("a refusal past the cap names the truncation") is met without the false per-id claim.
  • Opus's note on the sentinel label: dropped the misleading per-event count; it now reads "recent-peer list truncated at the 512-peer cap".

WeixinTransport._known_users recorded one entry per distinct inbound DM
peer and evicted nothing. Under the supported dm_policy="open" config the
transport serves any DM, so the key space is every user who ever messaged
the bot and the set grew for the life of the gateway process -- a slow
leak with no ceiling.

Make it an OrderedDict LRU bounded by a named KNOWN_USERS_CAP (512): on
receive, record the peer newest-last and pop the oldest over the cap. The
two read sites that advertise recent peers as proactive-send targets wrap
it in set(). may_send_to already consults _allowed alone, so an evicted
peer loses nothing and is re-admitted the moment it writes again. The
sibling wecom transport bounds its _warm_chats peer LRU to the same value.
@IngridMorstrad
IngridMorstrad force-pushed the fix/weixin-known-users-bound branch from dd40573 to 5c1b81e Compare October 27, 2026 13:40
@IngridMorstrad

Copy link
Copy Markdown
Contributor Author

5c1b81ef1a: the Internal Content Scan flagged the credential-shaped fixture I added for the SEL test (a non-canonical AKIA…-shaped literal). Replaced it with a neutral secret-shaped token (secret-ZZ…) — the test's point (a credential-shaped target id must not reach SEL's unredacted caller) holds for any shape, so no AWS-key literal is needed. No behaviour change; the two review fixes from the previous push are unchanged.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 27, 2026
@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) October 27, 2026 16:08

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tier 1 auto-approve: fix (4 files). Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, security checklist all-NO, no reviewer-lane findings, readiness signal fresh for this head SHA, declared category matches the diff. Category: bounds the Weixin recent-peer set to an LRU of 512 short ids and discloses the truncation; may_send_to still reads the allowlist alone; with tests. Spec files changed as a ride-along (a minority of the diff on both file count and changed lines), not reviewed as a design decision: docs/system-specs/modules/messaging.md.

@KiroCrewCaptain
KiroCrewCaptain merged commit 3ce6a8b into kirodotdev:main Oct 27, 2026
105 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

weixin: _known_users grows unbounded under dm_policy=open

2 participants