feat(python-sidecar): secure foundation and deterministic packaged runtime

[simonhagger]

Summary

• What changed:
  • Added secure Python sidecar foundation (typed IPC contracts, preload/main bridge, lab page, PDF tokenized handoff, extension + header checks, Python tests).
  • Added deterministic packaged runtime flow for sidecar builds (build/python-runtime/<platform>-<arch> + manifest) with build/forge preflight and dist sync.
  • Added pinned runtime dependency install (requirements-runtime.txt) and assertion gate that verifies fitz import when PyMuPDF is declared.
  • Enforced packaged-build behavior to use bundled runtime only (no system Python fallback), and exposed runtime executable diagnostics in UI/contracts.
  • Updated delivery/docs/backlog for runtime determinism and future official-distribution standardization.
• Why this change is needed:
  • Ensure sidecar behavior is secure and predictable.
  • Remove machine-path drift in packaged runtime behavior.
  • Make Dev/Staging/Production packaging outcomes consistent and verifiable.
• Risk level (low/medium/high):
  • Medium

Change Groups

• Docs / Governance:
  • Updated README, desktop distribution runbook, runtime bundle docs, backlog (BL-029).
• Frontend / UX:
  • Python Sidecar Lab diagnostics now include Python Executable.
• Desktop Main / Preload / Contracts:
  • Added sidecar foundation + deterministic runtime selection, packaged fallback policy, expanded contracts/types.
• CI / Tooling:
  • Added runtime prepare/assert/sync scripts and wired forge/build preflight gates.

Validation

• pnpm nx run contracts:test
• pnpm nx run desktop-main:test
• pnpm nx run renderer:build
• pnpm nx run desktop-main:build
• Additional checks run:
  • pnpm run python-runtime:prepare-local
  • pnpm run python-runtime:assert
  • pnpm nx run desktop-main:test-python
  • pnpm forge:make:staging (verified packaged interpreter path + PyMuPDF availability from lab diagnostics)

Engineering Checklist

• Conventional Commit title used
• Unit/integration tests added or updated
• A11y impact reviewed
• I18n impact reviewed
• IPC contract changes documented
• ADR added/updated for architecture-level decisions

Security (Required For Sensitive Changes)

IMPORTANT:

• If this PR touches apps/desktop-main/**, apps/desktop-preload/**, libs/shared/contracts/**, .github/workflows/**, or docs/02-architecture/security-architecture.md, the two items below MUST be checked to pass CI.

• Security review completed

• Threat model updated or N/A explained

Security Notes

• Threat model link/update:
  • N/A (no new trust boundary added; sidecar remains local-only and main-process mediated)
• N/A rationale (when no threat model update is needed):
  • Changes harden existing boundaries (packaged runtime enforcement, typed IPC, fail-closed file checks) and reduce fallback ambiguity; no new external actor/surface introduced.