Aelira Core v0.9.9: Why We Shipped a Hotfix

Why v0.9.9 exists

Aelira Core v0.9.9 is a corrective release for a PDF remediation defect in v0.9.8. We shipped it one day later because the defect affected the core promise of the remediation workflow: every finding must remain visible, sourced, and accounted for through the result.

During post-release testing, a PDF scan returned three medium-severity findings: the document did not start with an H1 heading, its title metadata was missing, and its XMP metadata did not include a PDF/UA identifier. When the same document moved into remediation, the job could not provide a trustworthy outcome for each finding.

That was enough to stop. A remediation artifact is not useful if an operator cannot tell which observed issues were fixed, which still require review, and whether the reported outcomes belong to the original findings. We released v0.9.9 rather than leaving that ambiguity in the current version.

What went wrong in v0.9.8

The scanner and strict remediator described issue categories differently at one important boundary.

The PDF scanner emits production findings using fields such as issue_type, rule, and message. The strict remediator could recognize many categories, but it did not recognize every built-in scanner issue type directly. In particular, the production-shaped combination of an H1 rule, a missing-title issue type, and a versioned PDF/UA rule label exposed the mismatch.

Our integration test did not catch it because the test added a derived type field to scanner findings before passing them to remediation. That helper made the test payload easier for the remediator to classify, but the production path did not perform the same transformation. The test therefore exercised a cleaner contract than the one users actually ran.

The v0.9.8 verification results were real, including the packaged browser journey. The mistake was treating those passing scenarios as coverage of the whole scanner-to-remediator seam. They did not exercise this raw three-finding payload, and the integration helper concealed the difference.

What v0.9.9 changes

The correction starts at the contract boundary. Strict PDF remediation now recognizes every built-in scanner issue type, including versioned PDF/UA labels, without requiring an intermediate enrichment step.

It also adds an accounting invariant: every input finding must finish in one explicit state. A finding is fixed, left for manual review, failed, or skipped. If a future category is not supported, it remains visible as manual work instead of disappearing from the result.

The dashboard now loads persisted fix records and pairs them with scan findings one-to-one. It distinguishes fixed, proposed, approved, rejected, failed, and unattributed outcomes from stored evidence. Duplicate-looking findings are consumed one at a time, so one recorded fix cannot be reused to imply that a second issue was also fixed. Where the available evidence cannot support issue-level attribution, the dashboard says so.

Zero-issue jobs now return an authoritative total as well. This removes another place where an absent value could be mistaken for an incomplete result.

The release also updates the CLI dependency tree to js-yaml 4.3.2, closing the security advisory identified by the release gate while v0.9.9 was being prepared.

The test now crosses the real seam

The old enrichment helper has been removed from the scan-to-remediation integration test. Raw scanner output now goes directly into strict remediation, exactly as it does in the product.

The reported three-finding case is also a permanent regression fixture. It requires all three findings to be represented as fixed, with zero manual, failed, or skipped outcomes. A broader fixture requires the sum of fixed, manual, failed, and skipped findings to equal the original total.

Dashboard tests cover the other half of the path. They verify one-to-one matching, duplicate handling, failed and rejected states, approved proposals that have not yet been applied, and the conservative fallback used when aggregate counts do not prove attribution.

Before publication, the correction passed the full local backend suite, remediation-focused tests, dashboard unit tests, CLI tests, release-safety checks, dependency audits, and production builds. An independent browser walkthrough at desktop and mobile widths showed all three incident findings with sourced outcomes and no horizontal overflow.

Why this could not wait for the next feature release

This was not a cosmetic reporting problem. It sat in the main sequence an operator relies on: scan a document, remediate it, then review what happened.

The safe rule is simple. If the system cannot account for a finding, it cannot ask the operator to trust the result. v0.9.9 restores that accounting and makes the same class of omission fail visibly in future tests.

We also wanted the public release record to stay accurate. v0.9.8 remains available as the version that introduced substantial evidence, review, observability, and deployment improvements. v0.9.9 is a separate release that records the corrective change rather than rewriting the earlier tag after publication.

What operators need to do

No database migration or new environment variable is required for v0.9.9.

Deploy the API, worker, and dashboard from the same v0.9.9 release. Re-run any remediation that failed under v0.9.8, then confirm that the fixed, manual, failed, and skipped counts add up to the total before relying on the artifact.

All v0.9.8 operator requirements still apply, including the database backup and restore check, production environment reconciliation, worker-health checks, and explicit review of work that remains manual or review-required.

Read the complete compatibility notes and release evidence in the Aelira Core v0.9.9 release. The implementation and review history are available in pull request #340.

The lesson we are carrying forward

Integration tests must preserve the shape of the data that crosses a real product boundary. A helper that makes two components agree can be useful inside a unit test, but it can also remove the exact mismatch an integration test exists to find.

The permanent safeguard in v0.9.9 is concrete: raw scanner output crosses the seam unchanged, every finding must be accounted for, and the dashboard only presents outcomes supported by persisted evidence.

That is the standard Aelira Core needs to meet. Accessibility remediation must remain inspectable when it succeeds, explicit when it cannot proceed, and honest about the evidence in between.