Explanation of the File Normalization Extension in Asset v2

This page documents the purpose, scope, and design principles of the server-side file normalization extension used in Asset v2.

It is intentionally conceptual and explanatory. Actual PHP code is documented elsewhere.

Purpose of This Document

File handling in MediaWiki is complex because:

uploads occur before page save completion
file pages and content pages are separate entities
user actions may partially succeed
failures must not corrupt archival data

This document explains why a private extension is required, what it enforces, and what it explicitly does NOT do.

Big Picture

The file normalization extension is the only authoritative enforcement layer in Asset v2.

It exists to ensure that:

the uploaded file name matches the Asset identifier
file history is preserved
the system remains consistent even if JavaScript fails

All other layers are advisory or assistive.

Why an Extension Is Required

The following cannot be reliably enforced by:

Page Forms
JavaScript
Lua
Cargo

Specifically:

renaming uploaded files after save
suppressing redirect creation
preserving file history
handling failure safely

Only server-side PHP code can do this correctly.

What the Extension Does

After a successful Asset save, the extension:

identifies the Asset page being saved
determines the final Asset identifier (page name)
finds the uploaded File associated with that Asset
renames (moves) the file to:

  File:<AssetIdentifier>.<extension>

preserves the file history
suppresses redirect creation

This operation is automatic and requires no user action.

When the Extension Runs

The extension runs:

after the Asset page is successfully saved
after the file upload has completed
after Cargo storage has occurred

It does NOT run:

during form editing
during preview
during failed saves
on existing Assets during edit

This ensures transactional safety.

Rename Semantics

The rename operation:

uses MediaWiki's internal file move mechanism
keeps the full file revision history
removes the original uploaded filename
does NOT leave redirects behind

From the user's point of view:

the file simply “has the correct name”

Failure Policy

If file renaming fails:

the Asset page remains valid
the File page remains valid
Cargo data remains correct
no rollback is attempted

The system may:

log the failure
allow manual or automated retry later

Rename is mandatory but NOT blocking.

This is intentional.

Why Rename Is Not Blocking

Blocking the save would mean:

losing user input
creating frustration
increasing retry complexity

In archival systems:

metadata correctness is primary
file naming can be corrected later

Therefore: Asset creation must succeed even if renaming fails.

What the Extension Does NOT Do

The extension explicitly does NOT:

generate identifiers
validate Chapter or Context
enforce immutability rules
modify Cargo data
modify page content
interact with JavaScript

Its responsibility is narrow and enforced.

Interaction with Other Layers

The extension assumes:

Page Forms collected valid input
Lua generated a correct identifier
JavaScript assisted the user
Cargo stored the data

But it does NOT trust any of them.

It only trusts:

the saved Asset page name
the actual uploaded File object

Security and Permissions

The extension runs with:

elevated internal permissions
no user interaction
no UI exposure

Users cannot bypass it deliberately.

This is required for consistency.

Idempotency

The extension must be safe to run multiple times.

If:

the file already has the correct name

Then:

no action is taken
no error is produced

This allows:

retries
future batch repairs
safe reprocessing

Mental Model to Keep

You can safely remember:

Page Forms = input
JavaScript = assistance
Lua = calculation
Cargo = storage
Extension = enforcement

Only the extension guarantees reality.

Status

This document is stable reference documentation.

It exists to support long-term understanding and memory retention.