# Mandatory main release prerequisites

Main retains complete PHPUnit coverage and `--fail-on-skipped`. No optional
release exception has been approved. Missing tooling alone does not make a
supported integration optional. `prerequisite-inventory.json` inventories 43
methods across six test classes (including lightweight cases in those classes):

| Integration | Required prerequisites |
| --- | --- |
| ImmXfaDatasetsTest | Authentic IMM1295/IMM5476 PDFs; Python and pikepdf |
| UserPortalPstqPrefillPdfTest | Authentic ME-0104/ME-0120 PDFs; Python and pypdf |
| SubmissionPackageServiceTest / SubmissionPackageOptionsTest | pdfinfo, pdfunite, Ghostscript, PHP GD |
| DocumentExtraction/DocumentFileNormalizerTest | Pandoc, LibreOffice, PHP GD |
| QuestionnaireBankConditionalLogicTest exports | Tracked database/data/questionnaire_bank_master.json |

The scenario suite inventories all current explicit skip/incomplete sites. Tests
that intentionally simulate missing tools must still run and assert the expected
application response; provisioning must not suppress such regressions.

## Blocker: authentic official PDFs

`official-fixtures.json` declares the exact four required paths. Sources,
SHA-256 checksums and CI use permissions are currently unverified. Main detection
fails before expensive setup until every entry has reviewed metadata. No official
PDF was downloaded, fabricated, committed or uploaded during this correction.

A technical lead must verify permission for downloading, storing and transforming
the specific versions in this CI context. General policies are starting points,
not evidence that this project's use is authorized:

- https://www.canada.ca/en/canadian-heritage/services/crown-copyright-request.html
- https://www.quebec.ca/en/copyright

After that review, record each canonical official HTTPS `source_url`, verified
`sha256`, and rights fields: `status: approved-for-ci`,
`scope: ci-download-and-transform`, an official `evidence_url`, and `reviewed_by`.
Review these metadata changes as release prerequisites. Do not set approval merely
to bypass CI. If permission requires private correspondence or credentials that
cannot fit this public-source process, keep the gate failing and design a reviewed
alternative; never commit confidential evidence or restricted PDFs.

Provisioning accepts only four known paths and allowlisted official hosts. It
rejects redirects, URL credentials, queries, symlinked destinations, oversized
responses and checksum mismatches. Existing files are preserved. Authentic PDFs
are downloaded only after all approvals pass, into the disposable runner checkout;
they are neither cached nor uploaded. An upstream replacement intentionally fails
until its version, checksum and permission are reviewed.

## Tool provisioning and local use

Main backend jobs use Ubuntu 24.04. `setup-release-tools.sh` refuses execution
outside an explicitly marked GitHub-hosted CI runner and checks approvals before
apt operations. It installs Ubuntu repository packages for Python venv, pikepdf,
pypdf, Poppler, Ghostscript, Pandoc and LibreOffice Writer, then creates
`storage/app/imm/.venv` and exports absolute `IMM_PYTHON` and `PSTQ_PYTHON` paths.
PHP setup supplies GD. Package versions are logged. This is a repeatable setup
procedure using signed distribution packages, not a frozen package snapshot;
Ubuntu updates and hosted setup time still require validation. No local install
was performed. Tools and fixture data are deliberately not dependency-cache inputs.

`node ci/prerequisites.mjs validate` checks approvals, authentic file hashes,
tools, Python imports, GD and the questionnaire export before main PHPUnit.
Local comprehensive QA needs a disposable checkout with legally available files
and equivalent preinstalled tooling. Do not run provisioning in the working
application or with live service credentials. Any genuinely optional coverage
exception needs a separate human-approved policy describing purpose, exclusions
and compensating validation; no such exception is implemented here.

## Isolation and efficient selection

All CI entry points reject `.env*` except `.env.example`, cached application
configuration, unsafe DB URLs/hosts/credentials, service credentials and storage
redirects. PHPUnit requires SQLite `:memory:`. The MariaDB migration job requires
an explicit disposable marker, loopback host, fixed fixture database/credentials
and a nonprivileged port. Local safety additionally relies on a disposable copy
and network isolation: Laravel HTTP blocking does not sandbox raw sockets or
arbitrary subprocesses. Do not run migrations against an existing database.

Staging syntax checks only changed existing PHP files, including renamed paths.
Main includes app, routes, database, tests, ci, config, bootstrap and root PHP
scripts, plus changed existing PHP elsewhere. PHP 8.3+ validates batches of up to
64 files; any syntax failure is fatal. Expanded staging PHPUnit uses one union
filter for critical/domain classes and the Unit namespace, eliminating overlapping
execution while retaining selected coverage.