P0005 (accept + execute): async-by-default-for-long-running-tools principle (NEW)

[klappy]

What this PR does — last of the 8-proposal sweep

Combined acceptance + execution of promotion P0005 — adds a tier-2 principle doc codifying the async shape for long-running MCP tools.

Acceptance (1 file)

• docs/promotions/P0005-async-by-default-for-long-running-tools.md
  • promotion_status: proposed → accepted
  • Tags array "proposed" → "accepted"
  • Status section header → accepted (2026-05-05)
  • Review Notes filled

Execution (1 file, NEW)

• canon/principles/async-by-default-for-long-running-tools.md (new tier-2 principle doc)
  • Frontmatter:
    • tier: 2, audience: canon, status: active
    • derives_from: partial-data-with-transparency-and-background-warm, vodka-architecture, values/axioms
    • complements: partial-data-with-transparency-and-background-warm
  • Sections: The Principle (three-tool triad) / Latency Budget Recommendation / Failure Mode / Relationship to Adjacent Canon / Receipts

The three-tool triad (the principle)

For any MCP action whose work could exceed ~5s wall-clock:

1. <verb>(...) — submit; returns identifier within ~5s
2. get_<verb>_status(id) — poll
3. cancel_<verb>(id) — cancellation

Notification push is additive; polling stays the canonical floor.

Latency budgets

• Submit: ≤ 1s median, ≤ 5s p99
• Status read: ≤ 1s median
• Notification: ≤ 1s median, ≤ 5s p99
• Long-poll fallback: ≤ 5s p99

Receipts

• PTXprint-MCP v1.2: submit_typeset / get_job_status / cancel_job (Worker → ctx.waitUntil(fetch()) → Container → DO state)
• AMS hosted /mcp: ams_send (wire-accept, not peer-receive) / ams_recv (long-poll) / ams_leave (cancel)

✅ Sweep complete

#	ID	PR	Subject
1	P0009	#167	DOLCHEO+H anti-pattern callout
2	P0001	#168	Completion claims require artifacts
3	P0008	#169	Validator-deliverable convention (DOLCHEO ledger)
4	P0007	#170	Spec DoD as 5–7 agent-observable behaviors
5	P0006	#171	Vodka boundary enumeration as spec convention
6	P0003	#172	Reframe-before-trimming method (new doc)
7	P0004	#173	Docs-proxy canon-as-tool pattern (new doc; new canon/patterns/)
8	P0005	this PR	Async-by-default principle (new doc)

All 8 previously-stuck proposed promotions now have acceptance + execution PRs open against main. Once these merge, the only proposed-status promotions left in the queue will be ones filed after this sweep started.

DoD

• Proposal frontmatter promotion_status flipped
• Review Notes filled
• New canon doc created at the proposed path
• Frontmatter follows frontmatter-schema
• H1 + blockquote + descriptive headers

---

Note

Low Risk
Low risk documentation-only change that adds a new canon principle and marks the corresponding promotion as accepted; no runtime behavior is modified.

Overview
Promotes P0005 from proposed to accepted by updating its frontmatter/status and filling in review notes.

Adds a new tier-2 canon principle, canon/principles/async-by-default-for-long-running-tools.md, codifying the submit-id + poll-status + cancel tool triad for actions that may exceed ~5s, along with recommended latency budgets and example “receipts”.

^{Reviewed by Cursor Bugbot for commit e36fe25. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

Canon Quality — oddkit_audit ✅

No dead klappy:// references or legacy link patterns found in writings/. 39 files scanned.

_{Spec: klappy://docs/oddkit/specs/oddkit-audit · Workflow: .github/workflows/canon-quality.yml · Run: #46}