Explain permission decisions in debug tools and documentation

[simonw]

Closes #2841.

Summary

• add a structured explanation for single permission decisions, including matching rules, specificity, same-scope deny precedence, actor restrictions, required actions and default deny
• allow the /-/check debug tool to evaluate hypothetical actor JSON while still authorizing access as the signed-in actor
• redesign the permission debug UI around Explain, Access map, Rule explorer and Activity workflows
• document the actor/action/resource mental model, rule precedence and the purpose of each debugging tool
• add focused coverage for specificity, restrictions, action dependencies, default deny and actor input validation

Why

The permissions implementation is powerful, but understanding an effective decision previously required correlating the Check, Rules, Allowed and Playground surfaces manually. This makes the resolver's mental model explicit and shows how each final verdict was reached.

Validation

• 275 passed, 3 xpassed across the focused permission suites
• full test suite: 2295 passed, 40 skipped, 6 xfailed, 15 xpassed, 141 subtests passed; the two sandbox-blocked local server fixtures passed when rerun with local binding enabled
• Sphinx documentation build
• Black, Ruff, codespell, Cog and diff checks
• desktop and mobile browser QA for allowed and denied decisions, with no console errors

[codecov]

Codecov Report

❌ Patch coverage is 0% with 88 lines in your changes missing coverage. Please review.
✅ Project coverage is 0.00%. Comparing base (db82123) to head (e231f04).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
datasette/utils/actions_sql.py	0.00%	74 Missing ⚠️
datasette/views/special.py	0.00%	12 Missing ⚠️
datasette/default_permissions/config.py	0.00%	2 Missing ⚠️

Additional details and impacted files

@@          Coverage Diff          @@
##            main   #2845   +/-   ##
=====================================
  Coverage   0.00%   0.00%           
=====================================
  Files         73      73           
  Lines      12208   12303   +95     
=====================================
- Misses     12208   12303   +95     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[simonw]

Demo of the new features:

Screen.Recording.2026-07-14.at.8.48.46.AM.mov