From 940dcb51a247b89bad2cf0ba92829fc19fe4f1b7 Mon Sep 17 00:00:00 2001 From: Dotta Date: Sun, 25 Oct 2026 00:34:08 -0500 Subject: [PATCH] docs: audit Discord command registration before runtime polling removal Co-Authored-By: Paperclip --- ...2026-10-24-recurring-server-sleep-stack.md | 14 ++++ ...iscord-command-registration-sleep-audit.md | 66 +++++++++++++++++++ 2 files changed, 80 insertions(+) create mode 100644 doc/plans/2026-10-25-discord-command-registration-sleep-audit.md diff --git a/doc/plans/2026-10-24-recurring-server-sleep-stack.md b/doc/plans/2026-10-24-recurring-server-sleep-stack.md index cc4d19c72d7..9b12c208465 100644 --- a/doc/plans/2026-10-24-recurring-server-sleep-stack.md +++ b/doc/plans/2026-10-24-recurring-server-sleep-stack.md @@ -1022,3 +1022,17 @@ shared-DB attempt produced cleanup foreign-key failures after email; those are recorded, not counted as passes. Total selected coverage is 770 cases. The server build passes. The inventory SQL uses the existing company/enabled index with 40,000 retained rows (13 buffers, 0.022 ms). Full workspace and remote gates remain. + +## Health publication and next chat boundary + +Tool health is [#17554](https://github.com/paperclipai/paperclip/pull/17554), head +`2ca12f806399cfcef1a474453301534f4b96c1ef`, stacked on #17518. Local workspace +checks/build and 770 selected tests pass. CI run 40165710347 is confirmed live; +Greptile and security review are running. This is not final acceptance. + +The next runtime-discovery audit found command-registration recovery hidden +inside `reconcileDiscordRuntime`. That is a separate durable reason and must get +its own PR before removing the runtime discovery backstop. Slice 19 audits that +owner in [Discord command registration](2026-10-25-discord-command-registration-sleep-audit.md). +Runtime discovery, active lease renewal, voice, Teams, and every original pending +inventory item remain in scope. No merges are authorized. diff --git a/doc/plans/2026-10-25-discord-command-registration-sleep-audit.md b/doc/plans/2026-10-25-discord-command-registration-sleep-audit.md new file mode 100644 index 00000000000..e021c25e01f --- /dev/null +++ b/doc/plans/2026-10-25-discord-command-registration-sleep-audit.md @@ -0,0 +1,66 @@ +# Discord command-registration scheduling audit + +Parent: tool-health PR #17554, head `2ca12f806399cfcef1a474453301534f4b96c1ef`. +The parent has 770 selected passing local tests, passing workspace typecheck and +build, and live remote CI/review. It is not accepted or merged. This branch owns +one newly separated reason from the existing chat-runtime inventory. + +## Evidence and boundary + +`app.ts` calls `reconcileProviderRuntimes` from its recurring chat maintenance +lane. That service discovers eligible Discord and Photon endpoints, restores +runtime ownership, and calls `discord/runtime-reconciliation.ts`. The latter +calls `reconcileDiscordCommands` before inspecting registered command state and +runtime capabilities. Thus removing runtime inventory polling without another +owner would also remove command-registration recovery. + +The command protocol and authorization already live in +`chat-channels/discord/commands.ts`. Durable state is in existing `chat_actions` +with kind `discord_command_registration`, owned by +`chat-discord-command-registration-store.ts`. The store already has retryAt and +retryIndefinite outcomes. Registered state and an indefinite hold must not cause +periodic discovery simply because an endpoint is configured. Inspect the full +state protocol before deciding which attempted/unknown states may replay. + +This slice should give command registration its own committed-change/deadline +worker and remove command reconciliation from recurring runtime maintenance. +Keep provider protocol, native identity/credential fences, and command receipt +validation in the Discord owner. Do not copy command HTTP behavior into startup +or the generic scheduler. Keep direct setup/foreground calls compatible. + +## Required producer and lifecycle audit + +- Endpoint creation/configure/reconnect/resume, identity/guild changes, credential + rotation, removal, and connection disable/health quarantine. +- All registration-store claims, attempted/unknown/registered commits, recorded + retry outcomes, legacy restoration, and operator force/reset paths. +- Existing registered command receipt publication and runtime capability refresh: + establish a committed completion trigger without continuing a periodic scan. +- Shared receiver-ownership loss and lease contention: identify which operations + require an owned runtime, a credential lease, or only an eligible endpoint. +- Configuration changes arriving during provider work must retain the existing + generation/fingerprint fence and schedule the latest state after settlement. +- Startup reconstruction must discover missing registration state in bounded + pages, without letting early failures starve later eligible endpoints. +- Empty, inactive, registered, and indefinite-hold states must become quiet. + Due retries remain durable, respect Retry-After, survive restart, and retain + deferred work through drain. Join admitted provider work at shutdown. +- Verify normal and ambiguous provider outcomes through the existing protocol + tests; never replay an uncertain create merely to clear a scheduling blocker. + +## Separate remaining duties + +Runtime inventory discovery is still a separate migration. Its existing +eligibility is Discord/Photon, endpoint status verifying/active/attention, +active enabled connection, and no attention plus failed-health combination. +The shared receiver owner keeps a 15-second lease and renews an active listener +at one-third of its TTL. Those live-resource renewals are not empty discovery. +A standby must use the actual observed lease expiry for takeover, and local +ownership loss needs a callback that retains a wake after stop settlement. +Persistent transports remain host-sleep limitations even after discovery is quiet. + +`app.ts` also invokes `chatChannels.voice.reconcile()` and Teams maintenance in +this lane. Voice, Teams, milestones, wake notices, terminal confirmations, +interaction continuations, and GitHub history recovery remain distinct duties. +No existing backstop is removed by this audit. No implementation or passing +regression is claimed for slice 19 yet.