[Audit] v5.1.1 audit remediation #458

Epic for the 2026-08 security + quality audit of packages/core (mineral v5.1.1).

The audit ran 11 parallel review dimensions over the 516 files of packages/core; every
finding below survived an adversarial refutation pass. Findings are numbered A1-A29
to avoid collision with the H*/M* codes used by the previous audit (#424-#428).

Why this chantier exists

The security posture came out good: the bot token is never logged, IDENTIFY/RESUME
payloads stay out of the logger, inbound gateway traces go through redactSensitiveFields,
HTTPS is enforced at HttpClient construction, CI uses OIDC with SHA-pinned actions, and
all 21 Intent bits plus every Permission position were verified against the Discord spec.

The problem is elsewhere: several public paths are broken 100% of the time in the
published release.

• message.delete(), message.pin() and every reaction throw a raw TypeError (any 204).
• guild.roles.get/create/update and guild.emojis.fetch/get throw type 'Null' is not a subtype of type 'String'.
• Guild.assets.icon, .banner, .splash, settings.permissions, .afkTimeout and
  .vanityUrlCode are silently always null.
• Every voice-state deserialization throws.
• Every GIF or LOTTIE sticker throws a StateError.

Root cause (A0)

All five share one cause: the rawDiscordPayload() fixtures were written to match what the
serializer expects, not the real Discord wire shape. The suite validates the code against
itself — it is green, the analyzer is clean, and the framework does not work.

That is why #459 lands first: it rebuilds the fixtures from real payloads and adds a
round-trip assertion per serializer, turning the suite red so the wave-1 cards turn it green.
Fixing the five call sites without fixing the fixtures brings the whole class straight back.

Branch topology

• Workstream branch chantier/audit-2026-08, cut from main.
• One feature branch per card, cut from the chantier branch (never from main).
• Feature branch -> chantier branch: squash.
• Chantier branch -> main: a single squash PR, merged by the maintainer.

Sequencing

Wave 0 lands first. Waves 1-5 are otherwise parallel, except for these file collisions:

• request_bucket.dart — fix(http): restrict ResilientHttpClient retries to idempotent methods #465 before fix(security): bucket rate limits on a token-free key and add in-flight accounting (A21/A24) #473
• shard.dart — fix(wss): repair the reconnect and resume paths (A5/A6) #466 before fix(wss): stop unhandled async errors from terminating the host process (A7/A16) #467

Cards

Wave 0 — test contract (blocks wave 1)

• A0 — rebuild marshaller fixtures from real Discord payloads + round-trip assertions test(marshaller): rebuild fixtures from real Discord payloads and add round-trip assertions (A0) #459

Wave 1 — payload contracts (the shipped-broken paths)

• A13/A14 — inject guild_id before normalize in the role and emoji parts fix(marshaller): inject guild_id before normalize in the role and emoji parts (A13/A14) #460
• A15 — read guild assets/settings from the shape normalize actually produces fix(marshaller): read guild assets and settings from the shape normalize produces (A15) #461
• A28/A29 — stop voice-state and sticker deserialization from throwing fix(marshaller): stop voice-state and sticker deserialization from throwing (A28/A29) #462
• A12 — write invites under the invite cache key, not the voice-state one fix(marshaller): write invites under the invite cache key, not the voice-state one (A12) #463

Wave 2 — HTTP layer

• A3/A22 — return a typed result for 204 and non-JSON bodies fix(http): return a typed result for 204 and non-JSON response bodies (A3/A22) #464
• A4 — fail unclassified statuses instead of silently re-sending the request fix(http): restrict ResilientHttpClient retries to idempotent methods #465

Wave 3 — gateway resilience

• A5/A6 — repair the reconnect and resume paths fix(wss): repair the reconnect and resume paths (A5/A6) #466
• A7/A16 — stop unhandled async errors from terminating the host process fix(wss): stop unhandled async errors from terminating the host process (A7/A16) #467
• A18 — make READY idempotent and stop the cache clear racing GUILD_CREATE fix(gateway): make READY idempotent and stop the cache clear racing GUILD_CREATE (A18) #468

Wave 4 — consumer-facing correctness

• A8 — isolate consumer handler failures in the interactive dispatcher fix(interactions): isolate consumer handler failures in the interactive dispatcher (A8) #469
• A9 — surface command-registration failures and throttle them fix(commands): surface registration failures and route them through the rate-limit bucket (A9) #470
• A10/A11 — OR permission bitfields; serialize outbound timestamps as UTC fix(core): OR permission bitfields and serialize outbound timestamps as UTC (A10/A11) #471

Wave 5 — security & release

• A1/A2 — stop EnvPlaceholder snapshotting the whole process environment fix(security): stop EnvPlaceholder from snapshotting the whole process environment (A1/A2) #472
• A21/A24 — bucket rate limits on a token-free key; bound the registry fix(security): bucket rate limits on a token-free key and add in-flight accounting (A21/A24) #473
• A17 — isolate the publish job from dependency code; commit the lockfile ci: isolate the publish job from dependency code and commit the lockfile (A17) #474
• A23 — stop re-exporting env_guard wholesale from the public barrel refactor(api): stop re-exporting env_guard wholesale from the public barrel (A23) #475

Wave 6 — architecture & debt

• A19 — delete Event.parameters; link payload types to event identity refactor(events): delete Event.parameters and link payload types to event identity (A19) #476
• A20 — make the normalize contract explicit across the 23 datastore parts refactor(datastore): make the normalize contract explicit across the 23 parts (A20) #477
• A25 — give CommandBuilder a real interface refactor(commands): give CommandBuilder a real interface (A25) #478
• A26 — make the composition root observable and covered test(client): make the composition root observable and covered (A26) #479
• A27 — break the barrel cycle between domain contracts and infrastructure refactor(contracts): break the barrel cycle between domain contracts and infrastructure (A27) #480

Follow-up

• Triage the 26 unverified findings triage: verify the 26 unverified findings from the 2026-08 audit #481

Audit scope caveats

The verification pass was budget-capped: one refutation lens instead of two, on a smaller
model, applied to Critical/High/Medium only. 0 of 33 findings were refuted — an
abnormal rate. The evidence supports the findings (several were reproduced in standalone
Dart scripts, and env_guard/eterl sources were read in .pub-cache), but treat the
Low cards as probable rather than confirmed until the regression test is red.

Not covered by this audit: the api/ entity layer has one test file for 202 source files;
packages/cache and packages/test were out of scope.

Status — 18 of 23 cards done

The chantier branch was rebased onto main and shipped (#489). main now carries
the payload-contract, HTTP, gateway-resilience, handler-isolation, security and
CI work; all three packages are green on format, analyze and test.

Still open, and none of it fixes a user-visible bug:

• refactor(events): delete Event.parameters and link payload types to event identity (A19) #476 — delete Event.parameters, link payload types to event identity. ~2200 lines
  across three file families, one already over the repo's 1k threshold. Needs a
  decomposition pass before it can be worked in reviewable pieces.
• refactor(datastore): make the normalize contract explicit across the 23 parts (A20) #477 — its premise is wrong; see the comment on it. serialize() has two
  callers with different contracts, and the cache path bypasses normalize()
  entirely. Needs a design pass, not an implementation pass.
• refactor(contracts): break the barrel cycle between domain contracts and infrastructure (A27) #480 — overlaps refactor: consolidate public barrels and ban barrel imports under lib/src (H5/H6) #446 from the June audit. Decide which absorbs the other first.
• fix(http): restrict ResilientHttpClient retries to idempotent methods #465 — rescoped to the idempotent-retry policy alone; the A4 defect is fixed.
• triage: verify the 26 unverified findings from the 2026-08 audit #481 — triage the 26 findings the budget-capped verification never refuted.
• test(marshaller): extend round-trip coverage to the remaining 13 serializers #483 — extend round-trip coverage to the remaining 13 serializers.

Loose ends found during the work and not yet carded: see the follow-up issue
linked below.