docs(issues): [#2466] specify bounding announce intervals to what every delivery protocol can encode

[josecelano]

Specification PR for #2466: bound core.announce_policy.interval and interval_min to what every delivery protocol can encode (i32::MAX, from BEP 15), rejected at configuration load. Documentation only; no code changes.

Related to #2466
Related to #1978
Related to #2245

Commits

1. ADR 20261007082938: a configured value that every delivery protocol sends is one protocol-agnostic value, bounded by the tightest supported protocol through a validated primitives type; adapters convert without clamping. Rejects per-protocol values, per-protocol validation, wire-only clamping, an arbitrary cap, and a configuration-only schema type. It explains why this does not conflict with the per-protocol scrape cap ADR (that one limits client input).
2. Reopen EPIC Overhaul: Configuration (schema v3.0.0) #1978: spec moved back from docs/issues/closed/ to docs/issues/open/, migrated to v1 frontmatter, closure checkpoints and the status AC reset, Bound announce intervals to what every delivery protocol can encode #2466 added as subissue 16. The live link in packages/configuration/docs/migrate-v2-to-v3.md now points to open/. Overhaul: Configuration (schema v3.0.0) #1978 was reopened on GitHub and Bound announce intervals to what every delivery protocol can encode #2466 is linked as a native sub-issue.
3. Bound announce intervals to what every delivery protocol can encode #2466 specification in docs/issues/open/2466-1978-announce-interval-upper-bound/, with the maintainer decisions recorded.
4. EPIC Review Numeric Conversion Boundaries #2243: the Review Numeric Protocol Wire Conversions #2245 row now links the follow-up Bound announce intervals to what every delivery protocol can encode #2466.
5. New reopen-issue skill, written from this first reopen (deliberately the last commit), cross-linked from cleanup-completed-issues.

Review notes

• Links to the Overhaul: Configuration (schema v3.0.0) #1978 EPIC inside other closed specs still point to docs/issues/closed/. They are archived records, the link checker excludes closed/, and the EPIC returns there on closure; the new skill documents this choice.
• The skill's single-issue path is derived from the EPIC case and not yet exercised.

Verification

• Frontmatter validator, pre-commit, and pre-push checks passed.

[Copilot]

Copilot review overview

🟡 Changes recommended

The interval_min bound lacks protocol justification, and the bug specification omits required reproduction evidence and red/green task sequencing.

Review effort: Balanced
Findings: 2 · 2

Open (4)

• Repair the reopened issue's specification link · New
• Quote typed issue references in YAML · New
• Add required Skill Links coupling and markers · New
• Use a typed issue reference instead of a lifecycle path · New

What changed in this PR

Defines #2466’s announce-interval bound, reopens configuration EPIC #1978, and documents the reusable reopening workflow.

Changes:

• Adds the architectural decision and implementation specification.
• Reopens and updates related EPIC documentation.
• Adds and cross-links the reopen-issue skill.

File	Description
packages/​configuration/​docs/​migrate-v2-to-v3.md	Updates the #1978 reference.
docs/​issues/​open/​2466-1978-announce-interval-upper-bound/​ISSUE.md	Specifies the interval-bound bug fix.
docs/​issues/​open/​2243-review-numeric-conversion-boundaries/​EPIC.md	Links the #2466 follow-up.
docs/​issues/​open/​1978-configuration-overhaul-epic/​EPIC.md	Reopens the EPIC and adds #2466.
docs/​adrs/​index.md	Registers the new ADR.
docs/​adrs/​20261007082938_bound_protocol_agnostic_values_by_the_tightest_delivery_protocol.md	Records the cross-protocol bound decision.
.github/​skills/​dev/​planning/​reopen-issue/​SKILL.md	Defines the issue-reopening workflow.
.github/​skills/​dev/​planning/​cleanup-completed-issues/​SKILL.md	Links the inverse reopening workflow.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[da2ce7]

Reviewed at 89d5623108a34735d61cc24e0ba5df59e1634f60 (round 1). Recomputed from the bytes at this head, against develop at 7836471b3.

This documents-only PR (8 files, +491/−17, five commits) adds an ADR that bounds a value every delivery protocol sends by the tightest protocol (i32::MAX for the announce interval), reopens the configuration EPIC to take the new subissue, specifies that subissue as a bug, links it from the numeric-conversion EPIC, and adds a reopen-issue skill derived from this reopen.

ADR. The code claims hold at the base: interval/interval_min are u32 (packages/primitives/src/announce.rs:33,47), HTTP encodes i64 (packages/http-protocol/src/v1/responses/announce/encoding.rs:55-56,65-66), UDP sends AnnounceInterval(pub I32) (packages/udp-protocol/src/announce.rs:80) through the clamp (packages/udp-server/src/handlers/mod.rs:35, announce.rs:135,160), so an out-of-range value diverges as stated. The linked ADRs and the scrape-cap non-conflict read as claimed; BEP encodings reported. The issue markers are unquoted (F5).

Specification. v1 frontmatter is complete and in template order; branch: is the -spec name per create-issue/SKILL.md:300-303 and matches the PR head; the stamp equals the last log entry; the six decisions trace to the issue body. As a bug spec it skips fix-bug's pre-review reproduction (F1) and test-plan rules (F2), plans no migration-guide update its parent EPIC requires (F3), and drops the toolchain-qualification policy and two template checkpoints (F4).

Reopen vs the skill. c3e7ad4ca follows Steps 2–6: move, v1 migration (trailing slash dropped per the validator's artifact pattern, syntax.rs:12), checkpoint resets, AC1's 17 (= the table's 17 rows), AC4 TODO, row 16, log entry, the migrate-v2-to-v3.md:460 repair; the child path arrives with the spec in d6657a23c. Reported and consistent with the capture: child created before the reopen comment, native parent link. Leaving nine closed records at closed/ is documented (reopen-issue/SKILL.md:99-101) and matches frontmatter-validator/src/repository.rs:131-132 and lychee.toml:9. The log dates the reopen 08:29 (F6); Step 4 omits two edits the commit made (F7).

Skill as a document. Frontmatter matches add-new-skill/SKILL.md:109-114 (description 555 chars); the remote default and Step 3 commands match siblings; the single-issue caveat is in the skill (:12-13); cross-link and 1.11 bump present. Not registered in the lifecycle index (F8); Step 2 prose names git fetch (F11).

Numeric EPIC and ADR index. The #2245 row names the follow-up with DONE untouched; a new log entry at 08:59 matches the stamp. The index row matches its neighbours' columns and is appended in date order.

Hygiene. Conventional subjects; tags match develop practice (skill commit untagged like other docs(skills) commits); subject-only messages (bodies optional per commit-changes); author = committer; times ascending 08:57:33Z–09:12:47Z; no trailers; Markdown only; no banned token; the PR body uses Related to only and its lists match the diff. The title names only the spec (note).

Findings (F1–F6 block)

• F1 Major: bug spec reviewed without the pre-review reproduction or evidence file
• F2 Minor: no red-run regression task; AC1 not matched by the planned tests
• F3 Minor: no migration-guide or documentation deliverable
• F4 Minor: verification policy omits toolchain qualification; template checkpoints dropped
• F5 Minor: unquoted issue #N markers in the ADR frontmatter
• F6 Minor: EPIC log dates the reopen at 08:29
• F7 Minor (non-blocking): skill Step 4 omits two founding-commit edits
• F8 Suggestion: register and couple the new skill
• F9 Suggestion: ADR Affected Code and code back-links
• F10 Suggestion: v2 inherits the bound through the shared type
• F11 Nit: Step 2 prose vs its block

Checked, no finding

• All 85 relative links and frontmatter paths in the changed files resolve; no other live reference to the EPIC folder.
• Consumer list covers every reader of the fields; tracker_client exists (console/tracker-client/src/bin/tracker_client.rs).
• ADR id, date, filename and template sections; rejected alternatives vs the issue decisions.
• EPIC v1 field order vs docs/templates/EPIC.md; status: in-progress; epic: null.
• PR body claims, including both review notes, stated in the skill itself.

Checks

On the loop's compute hub at this head, base develop 7836471b3 (receipt server-gates-krkavec-134): pre-commit profile gate exit 0 (81 s), tree clean after the gate; linter markdown, linter cspell, linter lychee exit 0; frontmatter-validator --all: 19 errors / 4 warnings at this head and 19 / 4 at develop 7836471b3 re-measured. GitHub checks at this head at posting time: "1 check, Docs Lint completed/success". At posting, develop is 7836471b3, this head's base.

[da2ce7]

Reviewed at 9c618ddf3e7a88dac1a1b655a0f3237a1c01edf1 (round 2). Recomputed from the bytes at this head, against develop at 24bf4746a.

The push rebases the five round-1 commits unchanged (range-diff = ×5, equal patch-ids; the develop delta since 7836471b3 touches none of the 14 files) and adds four fix commits and the audit record.

Round-1 findings at the bytes

• F1 fixed: manual-verification-evidence.md V0 records the run (10:18Z, rustc 1.99.0, tracker from 7836471b3 plus docs-only commits, :11-14), UDP 2147483647 vs HTTP 2147483648 (:104, :110), outcome Reproduced (:66-67); ISSUE.md:126 points to it. The fix is unwritten, so that tree is the defect's tree.
• F2 fixed: T2 red run, T4 fix, T7 green-plus-recheck (ISSUE.md:149-154); the tests, M1 and M2 assert field, value and limit (:135-138, :221-222), matching AC1.
• F3 fixed: In Scope :93-95, T6 :153, AC7 :206, AV row :252.
• F4 fixed: status values and Notes (:217, :225-236) follow template :178, :185-198, toolchain sentence at :230-232; checkpoints :183-184.
• F5 fixed: ADR :6-7 quoted.
• F6 fixed: EPIC :326-327 split the 08:29 decision from the 08:50 action, matching #2466's creation (08:50:29Z) and the reopen comment (08:50:40Z).
• F7 fixed: skill :89-91, :97.
• F8 fixed: docs/issues/README.md:33 and docs/issues/closed/README.md:37, in their neighbours' form; Skill Links :137-149.
• F9 fixed: ADR Affected Code :104-112; back-links planned (spec :91, T3, T5), which create-adr/SKILL.md:161-162 lets land with the code.
• F10 fixed: Out of Scope :100-102 against v2_0_0/core.rs:17.
• F11 fixed: skill :30-33 names the git pull --ff-only the block runs.

Each reply on my threads claims what the bytes show.

Audit record. 15 rows. Each Source URL is its thread's root (Copilot's four in review 5440515841, my eleven in 5440619059) and each Reply URL is on that thread; severities are the inline brackets. My F5 is F12 RE_RAISE_OF:F6 NO_ACTION/SUPERSEDED with the exact Superseded by F6: … reply; my F6, F9 and F10 are F13–F15 with my IDs recorded, the rest N/A. Every FIXED reference is a subject on the branch, and every thread is resolved. Recording no row for Copilot's overview summary follows process-pr-review/SKILL.md:50-56. My F8's coupling half overlaps Copilot's F10, but its registration half is distinct, so ORIGINAL holds. Copilot's F5 issue-body edit is GitHub state, reported, not recomputed. Residue: F12, F13.

Stamps. Spec "2026-10-07 10:24" equals its last log entry; the evidence's 10:18 is the run; the EPIC's 10:24 marks the log correction; all precede their 10:32Z commits. The ADR and the record carry no stamp.

Hygiene. Ten commits, author = committer; author times non-decreasing 08:57:33Z–10:52:49Z; committer times 10:53:19–22Z (the rebase). Conventional subjects with tags true to each diff; no bodies, trailers or banned token. Markdown plus one lychee.toml comment; project-words.txt untouched; 117 relative links and paths resolve.

Findings

• F12 Minor (blocks): the record's Completion Rules drop the template's last bullet, and Status Values are rewrapped.
• F13 Nit: two record statements no longer hold at this head.

These IDs continue my series. The audit's F12–F15 already hold my round-1 F5, F6, F9 and F10, so these two need collision-safe audit IDs.

Checked, no finding

• Evidence shape vs docs/templates/MANUAL-VERIFICATION-EVIDENCE.md and the #2245 sibling; config and outputs inline; the repeated UDP transaction id is the client's constant.
• skill-link: reopen-issue markers in the three artifacts the skill names; lychee.toml and the validator README change only by comment.
• The #2243 EPIC is unchanged since round 1.

Checks

On the loop's compute hub at this head, base develop 24bf4746a (receipt server-gates-krkavec-146): pre-commit profile gate exit 0 (73 s), tree clean after the gate; linter markdown, linter cspell, linter lychee exit 0; frontmatter-validator --all: 19 errors / 4 warnings at this head and 19 / 4 at develop 24bf4746a re-measured, so no new frontmatter finding; validate-audit-record.py --pr-number 2468 over the live review comments: 15 rows, 3 log entries, 0 failures. GitHub checks at this head at posting time: "21 checks, Publish (Release) completed/skipped; Publish (Development) completed/skipped; Context completed/success; Package Coverage Regression completed/success; Docker E2E completed/skipped; Unit (nightly) completed/success; Layer Boundary Bans completed/success; Unit (stable) in_progress/null; Documented Clippy Allows completed/success; Package Coverage (torrust-tracker-configuration) completed/success; Package Coverage (frontmatter-validator) completed/success; Test (Docker) (release) completed/success; Docs Lint completed/success; Build on windows-latest (nightly) completed/success; Build on macos-latest (nightly) completed/success; Build on ubuntu-latest (nightly) completed/success; Build on ubuntu-latest (stable) completed/success; Build on windows-latest (stable) completed/success; Build on macos-latest (stable) completed/success; Discover Package Coverage completed/success; Generate Coverage Report completed/success". At posting, develop is 24bf4746a, this head's base.

[da2ce7]

Reviewed at 6557a521418cde5b35780176d52323c896108d12 (round 3). Recomputed from the bytes at this head, against develop at c7cb2b3fa.

The 13:26Z force-push carries the ten round-2 commits onto c7cb2b3fa (range-diff = ×10; the develop delta from 24bf4746a touches none of the 14 files) plus three commits; the next push adds the round-2 audit rows.

F1–F11 sit in unchanged commits and remain fixed.

F12 fixed. Measured against docs/templates/PR-REVIEW-TEMPLATE.md at c7cb2b3fa (its verbatim markers now at :26 and :115), the record's Completion Rules are byte-identical, including the restored last bullet (template :132, PR-REVIEW.md:321). Status Values are byte-identical with the Category line wrapped as at template :38-39. The only template line not copied is the next section's <!-- Guidance omitted from an audit record; … --> comment (:45), which the reply's "apart from the template guidance comment it says to omit" names; the comment's own wording admits the exception.

F13 fixed. The Processing Log's 10:53 entry corrects the 10:49 one ("develop had moved 10 more commits", = 30e6b7127..24bf4746a; the 10:53:59Z push). F10's verification now counts the four marked files plus the record. The third rebase is logged at 13:26 ("19 commits behind", = 24bf4746a..c7cb2b3fa). Entries run 09:46 → 13:26 in order.

interval_min. 9d113aaef rewrites Decision 2: interval_min shares the type because it measures the same quantity, and "No protocol imposes the bound on it: BEP 15 has no minimum-interval field, and only HTTP sends min interval". That is true at udp-protocol/src/announce.rs:130-135 and the HTTP encoder. Its log entry dates it 13:12 as the maintainer's chat decision answering Copilot's review-overview remark (review 5440515841), which has no thread. e9a46f85a records it as a Processing Log entry with no row, consistent with process-pr-review/SKILL.md:50-52. The issue-body update it mentions is GitHub state, reported.

Audit record. 17 rows. F16 and F17 carry my F12 and F13 (Minor and Nit as posted, ORIGINAL, FIXED, RESOLVED). Their Source review ID 5441434837 and roots r4206173006 and r4206173023 match the capture. The replies r4207455245 and r4207455641 sit on those threads. The resolution reference is a subject on the branch. The 11:12 entry and the review paragraph match review 5441434837 (CHANGES_REQUESTED at the round-2 tip, 11:12:52Z, two findings). The other fifteen rows re-verify; threads.txt shows 0 of 17 unresolved.

Stamps. Spec "2026-10-07 13:12" equals its new log entry and precedes 9d113aaef (13:15:40Z); the record's log entries end at 13:26.

Hygiene. 14 commits; author = committer on all; author times non-decreasing to 13:35:57Z. Conventional subjects with [#2466] true to each diff; no bodies, trailers or banned token; project-words.txt untouched; the record's relative links resolve.

Findings

None.

Checked, no finding

• Ownership equals the merged #2465 record's after placeholder replacement.
• No other spec, ADR or EPIC line still justifies interval_min by protocol.
• The template and process-pr-review lines added on develop (out-of-tree fixes) don't touch the verbatim blocks.

Checks

On the loop's compute hub at this head, base develop c7cb2b3fa (receipt server-gates-krkavec-158): pre-commit profile gate exit 0 (96 s), tree clean after the gate; linter markdown, linter cspell, linter lychee exit 0; frontmatter-validator --all: 19 errors / 4 warnings at this head and 19 / 4 at develop c7cb2b3fa re-measured, so no new frontmatter finding; validate-audit-record.py --pr-number 2468 over the live review comments: 17 rows, 7 log entries, 0 failures. GitHub checks at this head at posting time: "18 check runs, 15 success (Package Coverage Regression success; Docker E2E skipped; Unit (nightly) success; Documented Clippy Allows success; Unit (stable) pending; Layer Boundary Bans success; Package Coverage (torrust-tracker-configuration) success; Package Coverage (frontmatter-validator) success; Test (Docker) (release) pending; Generate Coverage Report success; Discover Package Coverage success; Build on macos-latest (stable) success; Build on windows-latest (nightly) success; Build on windows-latest (stable) success; Build on ubuntu-latest (stable) success; Build on macos-latest (nightly) success; Build on ubuntu-latest (nightly) success; Docs Lint success)". At posting, develop is a43bebea9 (the merge of #2469, which touches none of this PR's files), and the merge of this head onto it is clean by git merge-tree.

[da2ce7]

ACK 6557a52 — F12 (template blocks copied verbatim) and F13 (rebases and pushes logged) fixed at the bytes, audit rows F16–F17 verified against the round-2 threads, the interval_min decision recorded in the spec and the audit, and the ten earlier commits carried unchanged onto c7cb2b3

[da2ce7]

Reviewed at 3ba843a802291103f39c05e68ad51692a2a1e994 (round 4). Recomputed from the bytes at this head, against develop at 4d8aa40d7.

The 14:49:00Z force-push carries a rebase plus the round-3 approval's record entry, and it dismissed that approval.

Rebase. The range-diff against the round-3b tip 6557a5214 shows = ×14 and one > (3ba843a80). The develop delta c7cb2b3fa..4d8aa40d7 (36 commits, 13 files) shares no file with this PR. On the PR's paths, 6557a5214..3ba843a80 differs by one added Processing Log line.

Record entry. PR-REVIEW.md:305 logs review 5443287949 at 14:37: round 3, 13:48 UTC, at the round-3b tip named by its subject, approved with no new findings, F16 and F17 verified, the interval_min rationale confirmed. reviews.json agrees: da2ce7, 13:48:41Z, at 6557a5214, now DISMISSED by the 14:49:00Z push. The stamp is in order after 13:26 and before the commit's 14:45:36Z author time. The same entry logs the rebase onto the latest develop and the dismissal, so no push goes unlogged. Rows stay at seventeen, the verbatim blocks are unchanged, and the audit validator, run offline with the captured comments and --base 4d8aa40d7, reports 17 rows, 8 log entries and 0 failures.

Hygiene. 15 commits, author = committer identity. Committer times run 14:46:14–19Z, in order and after the 14:36:28Z merge. The 14 carried commits keep their author times and subjects. The new subject matches its one-line diff. No bodies, trailers or banned token; project-words.txt untouched.

Findings

None.

Checked, no finding

• threads.txt: 0 of 17 unresolved; no new comments since 13:30Z.

Checks

On the loop's compute hub at this head, base develop 4d8aa40d7 (receipt server-gates-krkavec-160): pre-commit profile gate exit 0 (77 s), tree clean after the gate; linter markdown, linter cspell, linter lychee exit 0; frontmatter-validator --all: 19 errors / 4 warnings at this head and 19 / 4 at develop 4d8aa40d7 re-measured, so no new frontmatter finding; validate-audit-record.py --pr-number 2468 over the live review comments: 17 rows, 8 log entries, 0 failures. GitHub checks at this head at posting time: "18 check runs, 11 success (Package Coverage Regression success; Package Coverage (frontmatter-validator) success; Package Coverage (torrust-tracker-configuration) success; Docker E2E skipped; Unit (nightly) pending; Documented Clippy Allows success; Unit (stable) pending; Layer Boundary Bans success; Test (Docker) (release) pending; Build on ubuntu-latest (nightly) success; Build on windows-latest (stable) pending; Build on macos-latest (nightly) success; Build on windows-latest (nightly) pending; Build on ubuntu-latest (stable) success; Generate Coverage Report pending; Build on macos-latest (stable) success; Discover Package Coverage success; Docs Lint success)". At posting, develop is 4d8aa40d7, this head's base.

[da2ce7]

ACK 3ba843a — the 14 verified commits carried unchanged onto 4d8aa40 (range-diff = ×14) and the round-3 approval recorded truly in the audit's Processing Log

[josecelano]

ACK 3ba843a