fix(dev): support native ARM backend setup with pinned Pillow wheels

[durutheguru]

Workstream PR Trust Bundle

Chunk

WS-ART-001-03B3B1R1 - Linux Architecture Portability

Goal

Give macOS, Windows, Linux ARM, and Linux x86_64 contributors one copy-pasteable backend setup without weakening the Linux-only image-extractor isolation boundary.

Intent And Planning Context

• Intent: remove the repository-created x86_64-only Pillow installation blocker and make the supported setup paths explicit.
• Chunk contract: .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-03B3B1R1-linux-architecture-portability.md

What Changed

• Added exact SHA-256-approved Pillow 12.3.0 manylinux wheels for CPython 3.11/3.12 on x86_64 and aarch64.
• Made the dependency gate fail closed outside Linux glibc, CPython 3.11/3.12, and the two approved architectures.
• Added a digest-pinned, native-architecture backend development image and a Compose backend service with migration, health, non-root runtime, and loopback-only published ports.
• Added safe local environment examples and a Docker-first Developer Quickstart; native setup is documented only for supported Linux hosts.
• Kept the extraction child environment fixed and secret-free while adding the narrow OPENSSL_armcap=0 ARM Docker Desktop compatibility setting.

Why It Changed

The repository approved exact Pillow artifacts only for Linux x86_64. Pillow supports ARM and contributor host platforms, but macOS, Windows, and Linux ARM developers could not install the locked backend directly. Docker is now the portable host workflow, while native installation remains limited to the extractor's real Linux/glibc boundary.

Design Chosen

Use Docker's native VM architecture, reject cross-architecture emulation, preserve exact wheel URLs and hashes, and keep macOS/Windows outside the native parser support claim.

Alternatives Rejected

• Approving macOS/Windows wheels: would misrepresent the Linux/seccomp runtime boundary.
• Allowing source distributions or index fallback: would weaken the hash-bound supply-chain policy.
• Forcing x86_64 emulation on ARM: slower and masks native architecture defects.

Scope Control

Allowed Files Changed

• The 16 paths named by the chunk contract: setup docs, Docker/Compose assets, local env example, Pillow manifest/lock/gate, extraction child environment, and focused tests.

Files Outside Stated Scope

• None

Product Behavior

• No Workstream product behavior changed.
• Product behavior changed and is explained here:

Evidence

Commands Run

docker compose build backend
docker run --rm --entrypoint /bin/sh ws-dx-001-portable-backend-setup-backend:latest -c 'python -m pytest -q tests/test_guide_extraction.py tests/test_guide_pdf.py'
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python -m pytest -q -p pytest_cov.plugin tests/test_guide_extractor_dependencies.py --cov=scripts.check_guide_extractor_dependencies --cov-branch --cov-fail-under=90
python backend/scripts/run_test_lanes.py --collect-only ...
python backend/scripts/validate_test_lane_evidence.py ...
docker compose up -d --no-deps --wait --force-recreate backend
curl --fail --silent http://127.0.0.1:8000/api/v1/health
python3 scripts/check_markdown_links.py
python3 scripts/check_stale_workstream_wording.py
python3 scripts/check_stale_authorization_docs.py
python3 scripts/check_stale_artifact_contracts.py
python3 -m unittest -v scripts.test_lightweight_agent_gates
git diff --check origin/main...HEAD

Result Summary

Exact reviewed head: b31e0d636e6b5736847c251749469408faeb5f71
Fresh image: sha256:4b5e0735a6d38e99b800aecdba257e1e5ade85a5764a39716b8543c7642a6bbf
130 extraction/PDF tests passed
54 dependency-gate tests passed; 93.82% branch coverage
34 lane-routing tests passed
3,778 exact-head test nodes collected and evidence-validated across five lanes
Full Ruff lint and changed-file format checks passed
Agent documentation/lightweight gates passed
Migration 0062 applied; backend healthy; GET /api/v1/health returned {"status":"ok"}

Hosted Backend lanes remain authoritative for exact-head custody and the current guide-compilation coverage floor.

Acceptance Criteria Proof

• Exact, hash-bound CPython 3.11/3.12 x86_64/aarch64 manylinux wheels; no sdist/fallback.
• Unsupported OS, libc, Python, architecture, and foreign-emulation paths fail closed.
• Native-architecture Docker build, migration, health, extraction, and PDF paths pass.
• macOS/Windows are directed to Docker; native setup is scoped to supported Linux.
• Services publish to loopback; .env remains ignored; tracked values are local-only.
• Existing service workflows and upstream's digest-pinned PostgreSQL image are preserved.

Test Delta

Tests Added

• Architecture/platform/glibc/marker/wheel-matrix rejection and acceptance cases.
• Fixed extraction-child environment coverage.
• Docker/README setup contract coverage.

Tests Modified

• Focused extractor tests account for the fixed ARM OpenSSL environment.

Tests Removed Or Skipped

• None

Internal Reviewer Results

Reviewed code SHA: b31e0d636e6b5736847c251749469408faeb5f71

Reviewed at: 2026-08-10

Reviewer run IDs: docs_senior_review, qa_ci_review, security_arch_review

Reviewer	Result	Blocking Findings	Notes
Senior engineering	PASS	None	Final-base review
QA/test	PASS	None	Exact-head focused suites and lane inventory
Security/auth	PASS	None	Fixed secret-free child env and fail-closed platform boundary
Product/ops	PASS	None	Setup, migration, health, shutdown/reset reviewed
Architecture	PASS	None	Native architecture and isolation model preserved
CI integrity	PASS	None	Current-main gates and routing verified
Docs	PASS	None	Docker/native/root command contexts verified
Reuse/dedup	PASS	None	No competing setup abstraction found
Test delta	PASS	None	Focused additions and modified assertions reviewed

External Review

Source	Status	Notes
CodeRabbit	Pending	Initial review's only actionable wording issue was addressed; final-head rereview pending
GitHub checks	Pending	Required test and agent-gates

CI And Gate Integrity

• No workflow weakening.
• No lint/test/docstring gate weakening.
• No coverage threshold weakening.
• No package script weakening.
• No unpinned new GitHub Action.
• Checkout credential persistence disabled where checkout is used.

Remaining Risks

• This manifest change must receive fresh independent repository-owner/member/collaborator approval on the exact final head.
• Existing dependency advisories remain outside this scoped no-upgrade change: pypdf resource-exhaustion advisories are bounded by parser input, CPU, memory, wall-time, and seccomp controls; the cryptography advisory affects an unused PKCS#7 decryption API; pytest's advisory is dev/test-only.

Follow-Up Work

• Review and reapprove a separately scoped pypdf upgrade to the fixed release.
• Consider making the dev image capable of running the repository-root hosted AUTH preflight; focused Docker checks are the current documented contract.

Human Review Focus

Please inspect:

• The four approved Pillow URLs/hashes and mutually exclusive markers.
• The no-emulation and Linux/glibc platform gates.
• The Docker image digests, loopback bindings, local-only credentials, and fixed extraction child environment.
• The README's Docker versus native-support claims.

Human Merge Ownership

• I can explain what changed.
• I can explain why it changed.
• I know what could break.
• I accept the remaining risks.
• The user explicitly approved this specific PR for merge.

Summary by CodeRabbit

• New Features

  • Added Docker-based backend development with database migrations, live reload, health checks, and safer local service bindings.
  • Added native Linux support for x86_64 and aarch64 systems using approved Python 3.11 and 3.12 dependencies.
  • Added validated, hash-verified runtime artifacts with fail-closed platform compatibility checks.

• Documentation

  • Updated setup guides with Docker and native Linux workflows, supported platforms, testing, troubleshooting, and security guidance.
  • Added a local environment configuration example and contributor quickstart instructions.

[coderabbitai]

📝 Walkthrough

Walkthrough

This change adds Linux aarch64 support for approved Pillow artifacts, expands fail-closed runtime validation, isolates ARM extraction behavior, and documents native Linux and Docker development workflows.

Changes

Linux architecture portability

Layer / File(s)	Summary
Portability contract and verification .agent-loop/initiatives/.../WS-ART-001-03B3B1R1-linux-architecture-portability.md	Defines approved platforms, validation rules, Docker checks, repository checks, and review roles.
Architecture-specific dependency approval backend/config/guide_extractor_dependencies.json, backend/pyproject.toml, backend/scripts/check_guide_extractor_dependencies.py, backend/tests/test_guide_extractor_dependencies.py, docs/operations_backend_testing.md, docs/spec_artifact_storage_service.md	Adds hashed Pillow wheels for Linux x86_64 and aarch64. Validation now checks CPython, Linux, machine, glibc version, exact wheel suffixes, and complete platform coverage. Tests cover unsupported and approved combinations.
ARM extraction runtime isolation backend/app/modules/artifacts/guide_extraction.py, backend/tests/test_guide_extraction.py	Adds OPENSSL_armcap=0 to the extraction worker environment and verifies the complete environment mapping.
Docker development workflow .dockerignore, docker/backend/Dockerfile.dev, docker-compose.yml, backend/.env.example, README.md, CONTRIBUTING.md	Adds native-architecture Docker setup, backend startup and health checks, local service port configuration, environment settings, and contributor onboarding instructions.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Developer
  participant DockerCompose
  participant BackendContainer
  participant DependencyValidator
  participant ExtractionWorker
  Developer->>DockerCompose: Start backend profile
  DockerCompose->>BackendContainer: Build and run native image
  BackendContainer->>DependencyValidator: Validate locked extractor dependencies
  DependencyValidator-->>BackendContainer: Approve CPython/Linux/glibc platform
  BackendContainer->>ExtractionWorker: Launch sanitized extraction process
  ExtractionWorker-->>BackendContainer: Return extraction result

Loading

Possibly related PRs

• Flow-Research/workstream#228: Defines the dependency-approval scope extended here for Linux aarch64.
• Flow-Research/workstream#230: Covers the guide-extractor allowlist and validation extended by this change.
• Flow-Research/workstream#141: Updates the same artifact-extraction dependency and runtime validation areas.

Suggested reviewers: abiorh001, abiorh-claw

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the main change: native ARM backend setup with pinned Pillow wheels.
Description check	✅ Passed	The description follows the trust-bundle template and documents scope, design, evidence, acceptance criteria, risks, reviews, and ownership.

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/ws-dx-001-portable-backend-setup

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@README.md`:
- Around line 318-322: Update the architecture description in the README to
refer to the Docker host’s native x86_64 or aarch64 architecture instead of
implying Docker always uses a VM. Mention the Docker Desktop VM only as a Docker
Desktop-specific detail, while preserving the guidance about avoiding foreign
platform emulation and clearing DOCKER_DEFAULT_PLATFORM.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 7ed620ce-f0e4-4cb9-b425-18d6d8d4667f

📥 Commits

Reviewing files that changed from the base of the PR and between 5e459a8 and 38468c1.

⛔ Files ignored due to path filters (1)

• backend/uv.lock is excluded by !**/*.lock

📒 Files selected for processing (15)

• .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-03B3B1R1-linux-architecture-portability.md
• .dockerignore
• CONTRIBUTING.md
• README.md
• backend/.env.example
• backend/app/modules/artifacts/guide_extraction.py
• backend/config/guide_extractor_dependencies.json
• backend/pyproject.toml
• backend/scripts/check_guide_extractor_dependencies.py
• backend/tests/test_guide_extraction.py
• backend/tests/test_guide_extractor_dependencies.py
• docker-compose.yml
• docker/backend/Dockerfile.dev
• docs/operations_backend_testing.md
• docs/spec_artifact_storage_service.md