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. Asset:20260222194733)
Status: DRAFT
Identifier: placeholder (GENERATING…)
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
Status = DRAFT
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 Status = FINAL
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:

Status = FINAL
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:

Status = DRAFT | FINAL

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:

<ChapterCode>-<ContextCode>-<SequenceNumber>

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

Status = DRAFT → hidden
Status = FINAL → 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 document