Jump to content

ICT:FinalConfig - Asset - v2.3 design proposal

From Costa Sano MediaWiki

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:

  1. Compute next sequence number (contextual)
  2. Generate final Asset identifier
  3. Rename file to match final identifier
  4. Move Asset page to final title
  5. Persist final Cargo data
  6. Set Status = FINAL
  7. 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:

  1. Study and validate lifecycle clarity
  2. Implement Phase separation in the private extension
  3. Test finalization robustness
  4. 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: GENERATING...

READY State (IMPLEMENTED)

READY is a **technical gate**, not a lifecycle phase.

Status transitions:

  • DRAFT → incomplete
  • READY → 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 Status = FINAL

Dashboards hide:

  • DRAFT
  • READY

Dashboard emptiness at this stage is CORRECT.

6. Hook Architecture (Critical Knowledge)

The ONLY Hook Used

PageForms::WritePageData

Correct and tested signature: 

onPFWritePageData( $formName, $title, &$wikitext )

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

/var/www/mediawiki/hook_debug.log

Typical successful output: 

PF WritePageData fired: Asset:20260222222722
Fields: Chapter='CH02', Place='BRUG', Org='', File='Berck-Casino-371-ai.jpg'
Computed status: READY
Wikitext Status updated

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

Retrieved from "https://mwiki.costasano.club/index.php?title=ICT:FinalConfig_-_Asset_-_v2.3_design_proposal&oldid=1416"