Define the output a rewrite must preserve

A rewrite of a critical component needs an answer to a practical question before implementation begins: what must its users continue to observe? Choosing a safer language gives the project a direction. It does not define which changes in output are acceptable. A team replacing an established component should specify compatibility separately from its safety goal, then make the evidence for each claim visible.

Apple's 12 June 2026 account of its TrueType interpreter rewrite offers a useful example. It describes a C-to-Swift replacement shipped with the fall 2025 releases. Its compatibility criterion was pixel-identical rendering against the previous interpreter. The June article reports earlier deployment; it does not announce a June deployment. That distinction matters when using the account to plan another migration.

Choose an observable boundary

For a font interpreter, matching the public interface leaves an important question unanswered: does text still look the same? An interface can accept the same input types while returning visibly different results. The acceptance boundary therefore needs to reach the output that downstream users actually depend on. In another component that boundary might be an exported document, a calculated value or an ordering rule.

Write down that boundary before choosing the comparison machinery. Identify the inputs under comparison, the environment held constant and the output that decides agreement. If timing matters, describe timing separately. Combining visual equivalence and execution speed into a single label such as successful migration makes it harder to tell what the evidence establishes and what remains a decision.

An oracle is the reference used to judge a result. The old implementation can serve as a compatibility oracle without becoming the ultimate authority on correctness. This is a useful, limited role: it tells you whether behavior changed relative to a particular baseline. It does not establish that either implementation matches every requirement you would write today.

State what the corpus establishes

Apple describes differential rendering and a reduced document corpus that retained code coverage. Those are reported methods, not experiments reproduced here. They support confidence about compatibility across the exercised inputs. Coverage-preserving reduction does not turn a finite corpus into a proof about every possible font or document. These limits belong beside the test strategy, rather than appearing only after a disputed result.

For your own rewrite, a reduced corpus can make repeated comparisons practical. Keep the reason for retaining each class of input understandable. Rare inputs may matter because they exercise a distinct instruction or combination, even if they contribute little to typical traffic. Frequency and behavioral variety answer different questions. A small representative set and a larger occasional comparison can serve different purposes.

When a difference appears, preserve enough context to explain it. Record the baseline version and the input, then describe the observed output difference. An unexplained mismatch should remain a mismatch. Reclassifying it as harmless because the new code looks cleaner replaces the agreed criterion with a preference at precisely the moment that criterion is needed.

Make inherited bugs an explicit decision

The strongest objection to using the old system as an oracle is straightforward: old behavior can be wrong. Requiring exact agreement can retain a defect. That objection calls for an exception policy. It does not make compatibility irrelevant. People may rely on behavior that is undesirable in isolation, and changing it during a replacement can widen the migration beyond the intended work.

An exception should identify the behavior being changed, the reason and the person responsible for accepting the effect on users. Separate a deliberate correction from an accidental difference. If the correction changes an external contract, the release explanation should say so. A clean record lets a later maintainer distinguish an approved departure from a regression that nobody noticed.

Some components do not need exact output identity. A product may deliberately permit a tolerance or a changed format. In that case, define the permitted variation in the same dimension as the output: a numerical tolerance for a numerical result, for example. An undefined promise that the replacement is close enough gives reviewers little basis for deciding whether a difference is acceptable.

Keep reference-code requirements in their own timeline

Apple's pinned original standalone README lists macOS 26 and Xcode 26 requirements. That describes the published example at that snapshot. It does not establish the deployment requirements of the fall 2025 product. A later README or a newer safety API likewise cannot establish which tools the original deployment used.

This separation is useful whenever a retrospective links living source code. Record which artifact supports which claim. A product release, the publication of an example and a later documentation edit may each have a different date. A reviewer should be able to follow the claim without silently substituting the latest repository state for the historical artifact being discussed.

The same care applies to performance. Any numbers in Apple's account belong to Apple's workload and measurement method. They are not a forecast for another application. A migration proposal can use the account to explain a testing approach while leaving its own speed claims open until the relevant component and workload have been measured.

For a repair or modernization project, start with the outputs people rely on and the differences they can accept. Make the compatibility oracle, its limits and the exception owner part of the agreed work. That gives the rewrite a reviewable destination while leaving room to correct inherited behavior deliberately.