Improving the default notebook should not overwrite cells its operator wrote. Replacing every older document with a new template can create more loss than improvement. I limited automatic upgrades to wrappers whose exact shipped form can be identified, leaving other notebooks outside that replacement path.

Load the present definition before using the template label

Upgrade first loads the program, passing through the comparison between actual definition content and its retained manifest digest. Only then does it inspect the template marker and return if the current target version is already present. An old version number alone does not trigger replacement.

A template marker identifies a format, while integrity comparison identifies changed content. Neither replaces the other. This boundary reduces the chance of treating an edited document as an untouched generated file. A familiar notebook filename is not authorization to overwrite its contents.

Identify the original more precisely than by cell count

The upgrader compares the shipped wrapper's cell count and exact sources: explanation, imports, environment-based input, execution and verification. Generated name and folder portions must match their expected form too. Similar-looking code does not pass by a fuzzy comparison.

Cell count is not a quality measure here. It identifies one shipped version, not the ideal size of every notebook. Longer or differently structured documents are not worse. An added cell or edited explanation should move a document outside this automatic replacement route. The feature is designed to refrain from guessing how to overwrite a variation.

Skip an intact custom definition when it is not the original wrapper

Even matching manifest integrity is insufficient when exact-source comparison differs. An intact verified custom document and the original generated wrapper are different conditions. A reviewed custom notebook need not be erased merely to make it resemble the newest default.

A mismatched digest can instead fail loading before original-form detection. That failure must not be presented as a successful template migration. Skipping an out-of-scope document and rejecting a changed definition require different next actions, even though both avoid replacement. An accurate result should distinguish why no upgrade occurred.

Retain the notebook and manifest together before replacement

After identifying an eligible wrapper, the code copies the old notebook and manifest into a versioned backup. It writes the new workbook and updates digest and template metadata. Preserving both retains the relationship between a document and the verification state that described it.

A failure enters a path that attempts to restore the original notebook and manifest. An attempted rollback does not guarantee every write will succeed. This is not an atomic transaction across several files. When needed, recovery must inspect the retained files and backup rather than infer complete restoration from the existence of a catch block.

Check that edited source remains in place

The existing test changes the generated notebook's job-identity source and requests upgrade. It requires a changed-definition error and preservation of the edited source. Separate checks inspect the generated setup, preparation, execution and result cells. Presence of new template features and preservation of edits have their own assertions.

Those tests do not cover every custom document variation or storage fault. This writing replaces no original project notebook. Exact-form comparison and backup ordering are read from source, while the test's directly checked edit preservation retains its narrower scope. Generating a new document and migrating a live one are different completion claims.

Improving the default does not transfer ownership of existing work

A new administrator layout presents the same concern. Defaults for future documents and documents already customized by people have different ownership. Bringing everything to the latest version cannot justify erasing that distinction. Refusing to apply a change is part of the feature too.

Preservation means some notebooks need deliberate comparison and selective migration instead of automatic promotion. That maintenance cost should remain visible through retained backups and understandable decisions. A useful upgrader begins with identifying what may change, rather than merely changing many files quickly.