Mngr: Created page with "= 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 *..."

2026-02-20T13:23:27Z

Created page with "= 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 *..."

New page

= 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:
<pre>
File:<AssetIdentifier>.<extension>
</pre>
# 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.

ICT:Documentation:File Normalization Extension Asset v2 - Revision history