Skip to content

Fragment Model

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

Fragments are reusable units of content that can be managed independently and inserted into full documents. They allow repeated language, shared instructions, and standardized text to be maintained centrally instead of copied into multiple places.

The fragment model extends the same core principles used for WEIC documents: stable identity, revisioned content, canonical HTML storage, and controlled rendering behavior.

Purpose

The fragment model exists to support several goals:

  • centralize reusable content
  • reduce duplication across documents
  • allow shared language to be updated in one place
  • preserve fragment revision history
  • support controlled rendering and export behavior

Fragments are an important part of making a knowledge system maintainable at scale.

What a fragment is

A fragment is a reusable content unit stored separately from a full document.

A fragment may represent:

  • standard policy language
  • repeated operational guidance
  • common disclaimers or notices
  • reusable instruction blocks
  • shared narrative sections

Fragments are not separate because they are small. They are separate because they are reused or managed independently.

Fragment identity

A fragment has stable identity separate from its changing content.

Typical fragment fields include:

Field Purpose
id stable fragment identifier
name fragment name
current_revision_id pointer to the active fragment revision
created_utc creation timestamp
updated_utc last update timestamp

The fragment record identifies the reusable content unit. Its actual body content lives in revisions.

Fragment revisions

Fragment content is revisioned in the same way as document content.

Typical fragment revision fields include:

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

This means reusable content remains traceable over time.

Canonical HTML storage

Fragments are stored in HTML as their canonical body format.

This provides several benefits:

  • fragments and documents share the same content model
  • inserted content does not require Markdown-to-HTML conversion
  • structure and formatting are preserved
  • export and rendering paths remain consistent

This is one of the reasons HTML was chosen as the canonical WEIC storage format.

Fragment inclusion behavior

Fragment use should remain explicit and predictable.

A document may include fragment content by:

  • storing a fragment reference for render-time expansion
  • materializing fragment content during export or publication
  • resolving fragments in a controlled preprocessing step

The exact inclusion mechanism may evolve, but the architectural rule is that fragment insertion should be traceable and deterministic.

Render-time versus materialized use

Two broad models are possible.

Render-time inclusion

The document stores a reference to a fragment and expands it when rendering.

Benefits include:

  • centralized updates
  • less duplication
  • shared content stays aligned

Materialized inclusion

The fragment content is copied or expanded into a derived output such as a publication artifact.

Benefits include:

  • self-contained outputs
  • easier external export
  • predictable offline distribution

WEIC may support both approaches depending on workflow, but the distinction should remain explicit.

Fragment change impact

Because fragments are reusable, fragment changes may affect multiple documents.

This means fragment changes should be treated with care.

A fragment revision may require:

  • review before becoming current
  • visibility into which documents reference the fragment
  • controlled publication or re-rendering of affected documents

This is one of the reasons fragments need first-class identity and revision history.

Fragment governance

Fragments should support the same governance expectations as documents.

This includes:

  • author attribution
  • revision history
  • optional revision notes
  • future review workflows
  • predictable rendering behavior

Reusable content can affect many documents at once, so governance is especially important for fragments.

Relationship to documents

Documents and fragments are closely related but serve different roles.

Item Role
document full knowledge item with hierarchy and ownership
fragment reusable content block managed independently

Both use:

  • stable identity
  • revision history
  • canonical HTML storage
  • controlled rendering expectations

This symmetry keeps the WEIC content model coherent.

Search and indexing implications

Fragments may need their own indexing strategy depending on how they are used.

Possible approaches include:

  • index fragments directly as reusable knowledge items
  • index rendered document output that includes fragments
  • support both, depending on search requirements

The important architectural point is that fragments should not become invisible simply because they are reused.

Design principles

The fragment model follows several principles.

Reuse without duplication

Shared content should be managed centrally where appropriate.

Stable identity

A fragment remains the same reusable entity even as its content changes.

Revision traceability

Fragment history should be preserved just like document history.

HTML consistency

Fragments and documents should use the same canonical content format.

Controlled impact

Changes to reusable content should be understandable and governable.

Relationship to the Oryvin plan

The fragment model supports scalable knowledge management inside WEIC.

shared knowledge block
        ↓
fragment identity and revisions
        ↓
document reuse, rendering, export, and governance

Fragments help WEIC manage repeated operational and policy language without turning the knowledge base into duplicated content.