Revision Model

This document defines the revision model used by WildEditorInChief (WEIC).

The revision model explains how document and fragment changes are recorded over time, how the current version is identified, and how revision history supports traceability, safe editing, rollback, and future governance workflows.

Purpose

The revision model exists to support several goals:

preserve historical versions of content
identify a current active revision without overwriting history
support safe editing and rollback
provide traceability for knowledge changes
establish a foundation for future review and publication workflows

Revisions are central to WEIC because document content is not treated as a single mutable blob. It is treated as a versioned record.

Revision-first principle

WEIC uses a revision-first model.

This means:

content changes create new revision records
existing revision records remain historical
the active version is selected using a current revision pointer
history is preserved rather than replaced

This approach applies to both documents and fragments.

Revision lifecycle

A typical revision lifecycle is:

a document or fragment exists with a current revision
a user edits the content
a new revision record is created
the parent record updates its current_revision_id
the previous revision remains available as history

This model ensures that current state and historical state are both explicit.

Revision scope

Revisions store versioned content and related change metadata.

Typical revision data includes:

body_html
revision author
created timestamp
optional revision note

Stable identity and placement metadata remain on the document or fragment record rather than being duplicated into every revision.

Current revision pointer

The current state of a document or fragment is represented by a pointer field such as:

current_revision_id

This means:

the document record identifies the active revision
the revision record stores the content
changing the current state does not require deleting old content

This is the preferred model over updating a body field in place.

Benefits of the model

The revision model provides several advantages.

Traceability

Every meaningful content change can be preserved as a revision record.

Safe editing

Editing creates a new version rather than mutating the previous state directly.

Rollback

A previous revision can be restored by selecting it as current or by creating a new revision derived from it.

Comparison

Historical revisions can be compared to understand how a document changed over time.

Governance readiness

Review, approval, and publication processes can later attach to revisions rather than to unstable mutable content.

Document revisions

For documents, revisions represent changing authored content while the document record maintains stable identity.

Typical document revision fields include:

Field	Purpose
id	revision identifier
document_id	owning document
body_html	canonical HTML body
revision_note	optional summary of changes
author	revision author
created_utc	revision creation timestamp

Each document may have many revisions but only one current revision at a time.

Fragment revisions

Fragments follow the same revision model as documents.

Typical fragment revision fields include:

Field	Purpose
id	fragment revision identifier
fragment_id	owning fragment
body_html	canonical HTML fragment body
revision_note	optional summary of changes
author	revision author
created_utc	revision creation timestamp

Using the same model for fragments keeps reusable content behavior consistent with full documents.

Revision notes

A revision may include an optional revision note.

Examples include:

corrected policy wording
updated deployment steps
aligned text with new architecture
clarified review guidance

Revision notes help provide human-readable context for why a new version exists.

Author attribution

Each revision should record the author responsible for creating it.

This supports:

traceability
auditability
future review workflows
accountability for changes

Author attribution is part of the knowledge governance model, not just a convenience field.

Revision ordering

Revisions should be ordered by creation timestamp and linked clearly to their parent document or fragment.

The system should not rely solely on user-visible version labels to determine ordering. Ordering should be based on recorded creation history and current revision pointers.

This keeps revision history explicit and robust.

Rollback behavior

Rollback should not require destroying later history.

Preferred behavior:

select an earlier revision as the basis for a new revision
or explicitly repoint current state if governance allows

In either case, rollback should preserve traceability of what happened.

The safest long-term model is:

old revision
   ↓
new correction revision derived from old content

Rather than deleting or rewriting history.

Relationship to review and publication

The revision model provides the foundation for later workflow layers such as:

review
approval
controlled publication
release history

These layers should attach to revisions because revisions are the stable representation of content state over time.

Design principles

The revision model follows several principles.

History is preserved

Content changes should leave a record.

Current state is explicit

The active version should be chosen by pointer, not inferred.

Revisions are immutable history

A revision represents a recorded content state and should not be silently rewritten.

Rollback preserves traceability

Returning to older content should not erase the path that led there.

Documents and fragments behave consistently

Both content types use the same core revision ideas.

Relationship to the Oryvin plan

Traceability is central to Oryvin. The revision model is one of the mechanisms that makes knowledge traceable over time.

authored knowledge
        ↓
revisioned records
        ↓
review, publication, evidence, and operational use

Without revisions, knowledge becomes mutable and hard to audit. With revisions, the knowledge base becomes governable.