View source for ICT:FinalConfig - Asset - v2.3 design proposal

= Asset v2.3 – Lifecycle Proposal =

== 0. Purpose of this Document ==
This document defines **Asset v2.3**, a stabilization and completion step of the Asset v2.x line.

Its purposes are:
* Serve as a **conceptual study document**
* Provide a **clear implementation guide**
* Act as a **baseline for validation and later fine-tuning**

Asset v2.3 does not introduce new concepts.  
It reorganizes responsibilities, clarifies lifecycle phases, and resolves ambiguities identified in Asset v2.1.

---

== 1. Locked Runtime Baseline (Unchanged) ==
The following environment and assumptions are **strictly locked** and MUST NOT change during Asset v2.x development:

* OS: AlmaLinux 10.1
* PHP: 8.3
* MediaWiki: 1.45.x
* Page Forms: 6.x
* Cargo (external database)
* Scribunto: Lua 5.1 (Lua 5.4 explicitly excluded)
* Private MediaWiki installation

Normative constraints:
* One Asset = exactly one digital file
* Asset identifier immutability
* Compatibility with existing Asset v2.1 data

---

== 2. Core Principle (Reaffirmed) ==
''An Asset is immutable after finalization.''

Immutability applies to:
* Asset identifier (page name)
* Label
* Chapter
* Place / Organisation
* File
* OriginalFilename

All other descriptive metadata MAY be edited after finalization.

---

== 3. Explicit Asset Lifecycle (Normative) ==
Asset v2.3 introduces a **three-phase lifecycle**.
Each phase has a single responsibility and MUST NOT overlap with others.

---

=== 3.1 Phase A – Draft Creation ===
'''Goal:''' Safely persist user input without committing archival identity.

Characteristics:
* Page name: timestamp-based (e.g. <code>Asset:20260222194733</code>)
* Status: <code>DRAFT</code>
* Identifier: placeholder (<code>GENERATING…</code>)
* File: uploaded under original filename

Allowed actions:
* Upload file
* Select Chapter
* Select Place or Organisation
* Enter descriptive metadata

Forbidden actions:
* Identifier generation
* File renaming
* Page moving

Rules:
* Draft pages MUST NOT appear in dashboards
* Draft pages MUST NOT be queried as Assets

---

=== 3.2 Phase B – Finalization ===
'''Goal:''' Atomically transform a Draft Asset into a Final Asset.

Phase B is the ONLY phase in which identity is assigned.
It MUST execute exactly once per Asset.

----

==== Preconditions ====
All of the following MUST be true before Phase B starts:

* Asset page exists
* <code>Status = DRAFT</code>
* Required fields present:
** Chapter
** Place OR Organisation
** File
* No final identifier has been assigned

If any precondition fails, Phase B MUST NOT start.

----

==== Trigger ====
Phase B is triggered by an explicit user action
(e.g. a “Finalize Asset” control).

Automatic finalization is forbidden.

----

==== Atomic Actions (execution order) ====
The following steps form a single atomic operation:

# Compute next sequence number (contextual)
# Generate final Asset identifier
# Rename file to match final identifier
# Move Asset page to final title
# Persist final Cargo data
# Set <code>Status = FINAL</code>
# Lock immutable fields

If any step fails:
* ALL changes MUST be aborted
* No partial state is allowed
* The failure MUST be logged

----

==== Rules ====
* Phase B MUST run exactly once
* Re-finalization is forbidden
* Partial finalization is forbidden
* Identifier and sequence allocation occur ONLY in Phase B
* Page move and file rename occur ONLY in Phase B

----

==== Resulting State ====
After successful Phase B:

* <code>Status = FINAL</code>
* Asset identifier is permanent
* File name is permanent
* Asset becomes visible on dashboards
* Immutable fields are locked

----

==== Explicitly Forbidden ====
* Running Phase B on a FINAL Asset
* Changing immutable fields after Phase B
* Skipping or reordering atomic steps

----

---

=== 3.3 Phase C – Post-Final Editing ===
'''Goal:''' Allow safe metadata enrichment without identity corruption.

Allowed:
* Description updates
* Notes
* Parent asset relations

Forbidden:
* Any change to immutable fields
* File replacement or rename
* Page move

---

== 4. Explicit Status Field (New) ==
Asset v2.3 introduces a mandatory field:

<syntaxhighlight lang="text">
Status = DRAFT | FINAL
</syntaxhighlight>

Purpose:
* Remove implicit draft detection
* Control lifecycle hook execution
* Prevent accidental re-finalization

The Status field is authoritative.

---

== 5. Identifier and Sequence Generation (Clarified) ==
Identifier format remains unchanged:

<syntaxhighlight lang="text">
<ChapterCode>-<ContextCode>-<SequenceNumber>
</syntaxhighlight>

Rules:
* Sequence numbers are allocated ONLY during Phase B
* Numbers are never reused
* Gaps are allowed
* Counter logic is centralized

Sequence allocation MUST be implemented as a single isolated function.

---

== 6. Hook Responsibility Separation ==
Asset v2.3 enforces strict separation of concerns.

Hooks MUST NOT:
* Parse wikitext for authoritative decisions
* Combine extraction, mutation, and page/file movement
* Decide identity before save completion

Hooks SHOULD:
* Detect lifecycle phase
* Validate preconditions
* Delegate work to dedicated functions

Wikitext inspection MAY be used for diagnostics only.

---

== 7. Page Move Strategy ==
Page moves are explicitly **post-save operations**.

Rationale:
* MediaWiki requires stable content before moving pages
* Page Forms target manipulation is fragile

Rule:
''A page MUST exist before it is moved.''

---

== 8. File Handling Strategy ==
* File upload occurs in Phase A
* File rename occurs only in Phase B
* Original filename is captured exactly once

After Phase B:
* File becomes immutable
* Further file operations are forbidden

---

== 9. Dashboard Visibility Rules ==
* <code>Status = DRAFT</code> → hidden
* <code>Status = FINAL</code> → visible

Dashboards MUST display only finalized Assets.

---

== 10. Migration and Compatibility ==
Asset v2.3:
* Does NOT invalidate Asset v2.1 Assets
* Introduces no breaking schema changes
* Adds lifecycle clarity without requiring data migration

---

== 11. Status ==
Asset v2.3 is a **design-level proposal**.

Next steps:
# Study and validate lifecycle clarity
# Implement Phase separation in the private extension
# Test finalization robustness
# Fine-tune UX only after correctness is proven

---

''End of first part of document''


------Actual status --------------

= Asset v2.3 – Current Working State (Checkpoint) =
''Date: 2026-02-22''

This page documents the **last known good state** of the Asset v2.3 system.
It exists to allow safe recovery if later experiments break functionality.

----

== 1. Scope ==
This document describes:
* What is implemented and validated
* What is intentionally NOT implemented yet
* Which architectural decisions are locked
* Where development must resume next

----

== 2. Environment (Locked) ==
* MediaWiki 1.45.x
* Page Forms 6.x
* Cargo (external database)
* PHP 8.3
* AlmaLinux
* Private MediaWiki installation

These were tested together and MUST NOT be changed mid-development.

----

== 3. Asset Lifecycle (Current Implementation) ==

=== Phase A – Draft Creation (IMPLEMENTED) ===
* Assets are created via Dashboard + Form:Asset
* Page name is timestamp-based (e.g. Asset:20260222222722)
* File is uploaded under its original filename
* Identifier is placeholder: <code>GENERATING...</code>

=== READY State (IMPLEMENTED) ===
READY is a **technical gate**, not a lifecycle phase.

Status transitions:
* <code>DRAFT</code> → incomplete
* <code>READY</code> → all required fields present

Required fields:
* Chapter
* Place OR Organisation
* File

READY detection is:
* Automatic
* Hook-based
* User-invisible
* Reversible

READY assets are still hidden from dashboards.

----

== 4. What Is Explicitly NOT Implemented Yet ==
* Phase B (Finalization)
* Identifier generation
* Sequence allocation
* File rename
* Page move
* Cargo writes during finalization
* Dashboard visibility of Assets

This is intentional.

----

== 5. Dashboard Rules (Locked) ==
Dashboards show:
* ONLY <code>Status = FINAL</code>

Dashboards hide:
* <code>DRAFT</code>
* <code>READY</code>

Dashboard emptiness at this stage is CORRECT.

----

== 6. Hook Architecture (Critical Knowledge) ==

=== The ONLY Hook Used ===
<code>PageForms::WritePageData</code>

Correct and tested signature:
<syntaxhighlight lang="php">
onPFWritePageData( $formName, $title, &$wikitext )
</syntaxhighlight>

Important rules:
* NO type hints in parameters
* Hook fires BEFORE page creation
* Hook MUST NOT assume page exists

=== What the Hook Does ===
* Reads fields from wikitext
* Computes READY vs DRAFT
* Writes <code>Status</code> back into wikitext
* Writes debug logs

=== What the Hook MUST NOT Do ===
* Write to Cargo
* Rename files
* Move pages
* Trigger second saves
* Perform Phase B logic

Violating these rules caused page creation to fail.

----

== 7. Logging ==
A debug log is used to confirm hook execution:

<syntaxhighlight lang="text">
/var/www/mediawiki/hook_debug.log
</syntaxhighlight>

Typical successful output:
<syntaxhighlight lang="text">
PF WritePageData fired: Asset:20260222222722
Fields: Chapter='CH02', Place='BRUG', Org='', File='Berck-Casino-371-ai.jpg'
Computed status: READY
Wikitext Status updated
</syntaxhighlight>

If logs stop appearing:
* The hook signature is wrong
* Or the extension is not loaded

----

== 8. Current Stable Code Reference ==
The current working hook:
* Updates wikitext only
* Does not touch Cargo
* Does not break saves

This state is backed up via full VM disk copies.

----

== 9. Known UX Side Effect ==
Because wikitext is modified in the Page Forms hook:
* MediaWiki shows the classic save confirmation screen

This is acceptable for now.
It will be removed later during Phase B refactoring.

----

== 10. Where to Resume Development ==
Next work session must start with:

'''Phase B – Finalization'''

Specifically:
* Trigger from the form (Finalize Asset button)
* Post-save logic only
* Atomic operations:
** sequence allocation
** identifier generation
** file rename
** page move
** Cargo persistence

Phase A MUST NOT be modified further.

----

''End of checkpoint document''