Link Validator

Interface Overview

The Link Validator verifies that document links embedded within chronology entries and heads of claim resolve to actual files present in the /assets/ directory structure.

It does not verify content, accuracy, or completeness of documents. It verifies only that links point to resources that exist.

What This Tool Does

The Link Validator performs three validation operations:

• Chronology Validation: Checks all document links in chronology entries
• Heads Validation: Checks all document links in appendix heads

What constitutes a validation failure?

A link fails validation if:

• The referenced file does not exist in the manifest
• The file path is malformed or unparseable
• The file has been moved or deleted after chronology creation
• The link contains incorrect encoding or path separators

Preconditions

Required System State

Before validation can run, the following must exist in system state:

• systemChronologyIndex — chronology entries with document links
• systemHeadsIndex — appendix heads with document links

These indices are created when you propagate data from the factories into system state as you create your entries.

Required Directory Manifest

Validation also requires:

• systemDirectoryIndex — a manifest of all folders/files inside /assets/

This manifest can be loaded automatically from a default location, or created manually by selecting your project directory from "Select Directory" button.

The validator requires a folder called "assets".

Manifest System

What is a Directory Manifest?

A directory manifest is a JSON-formatted inventory of all files within the /assets/ directory structure. It records:

• File paths relative to the assets root
• File sizes in bytes
• Last modification timestamps

Loading a Manifest

The Validator supports two methods of manifest loading:

1. Automatic Default Loading

On page load, the Validator attempts to load a default manifest from:

../build-logs/manifests/validation-manifest.json

If this file exists and is valid, it populates systemDirectoryIndex automatically.

2. Manual Directory Selection

If no default manifest exists, or if you wish to use a different directory, click "Select Directory" and choose your project root folder.

The Validator will scan all files within the selected directory and build systemDirectoryIndex from the selection.

Purging the Manifest

The "Purge Manifest" button removes:

• The systemDirectoryIndex from localStorage
• Any injected manifest script tags from the DOM
• Validator references to manifestData

This does not delete the original manifest file on disk. It clears only the loaded copy within the Validator localStorage.

Validation Process

How Validation Works

When you click a validation button, the Validator:

1. Retrieves the relevant system index (chronology or heads)
2. Retrieves the directory manifest (systemDirectoryIndex)
3. Extracts all document link paths from the system index
4. Normalises paths by:
   • Removing query strings and fragments
   • Converting backslashes to forward slashes
   • Anchoring paths at assets/
   • Encoding spaces as %20
5. Checks each normalised path against the manifest file list
6. Records whether each link exists or is missing
7. Generates a validation report

Reading Validation Results

Each validation result displays:

• [Present] — file exists in manifest
• [Missing] — file missing or path malformed
• [module] — which system generated the link (chronology, heads)
• Source identifier — date (chronology) or claim breakdown (heads)
• Target path — the document link being validated

Interface Controls

Manifest Controls

Validation Controls

System Controls

State Management

What is System State?

System state refers to structured data stored in browser localStorage that represents the current configuration of your chronology, matrix, and appendices. localStorage it NOT a substitute for backup.

Validator-Specific State

The Validator stores its own indices:

• systemDirectoryIndex — manifest of asset files
• systemChronologyIndex — copy for validation only
• systemHeadsIndex — copy for validation only
• systemValidationReport — latest validation results

State Synchronisation

The Validator monitors localStorage for changes. If factory data is updated while the Validator is open Validator must be reloaded

This ensures validation always reflects the current state of your data.

Workflow

Initial Setup

1. Open the Link Validator interface
2. If no default manifest loads, click "Select Directory"
3. Choose your project root folder (the one containing /assets/)
4. Confirm that systemDirectoryIndex has been created

Running Validation

1. Ensure system state exists (propagate from factories if needed)
2. Click "Validate Chronology" or "Validate Heads"
3. Review the validation report in the output panel
4. Identify any [Invalid Link] entries

Resolving Invalid Links

1. Note the source (date or claim) and target path of each invalid link
2. Verify whether the file exists but has moved, or is genuinely missing
3. If the file exists elsewhere, update the link in the relevant factory
4. If the file is missing, restore it to /assets/ or remove the link
5. Re-propagate system state from the factory
6. Re-run validation to confirm resolution

Explicit Limitations

What This Tool Does NOT Do

• Content verification: It does not check whether linked documents contain expected content
• Version control: It does not track file versions or detect content changes
• Chronology validation: It does not verify temporal ordering or factual accuracy
• Legal assessment: It does not validate claims or legal references
• Automatic repair: It does not fix broken links automatically
• Link modification: It does not alter system state or factory data
• Cross-platform paths: It may not handle all path formats correctly (relies on browser support)

Template Structure Dependency

The Link Validator is designed for use with the Reconstruction Platform template structure.

Expected structure:

project-root/
  assets/
    linked-evidence/
    correspondence/
    statutory-instruments/
    clinical-records/
    [...other document classes...]
  html/
  js/
  build-logs/
    manifests/
      validation-manifest.json

Browser Compatibility

Manual directory selection requires:

• Support for <input webkitdirectory>
• File System Access API (or equivalent)
• localStorage availability

Not all browsers support these features. If manual selection fails, use the default manifest method instead.

Design Principles

• Link validation is a continuity safeguard, not a content verifier
• Broken links indicate process failure, not factual incorrectness
• The Validator observes but does not modify system state
• Invalid links must be resolved in the originating factory
• Validation reports are diagnostic tools, not evidence artifacts
• Manual markup modifications fall outside governed continuity

Technical Notes

Path Normalisation Rules

The Validator applies these transformations during validation:

1. Extract src= value if present in link markup
2. Convert all backslashes (\) to forward slashes (/)
3. Anchor path at assets/ (discard preceding path segments, double click 'assets' folder)
4. Remove query strings (?...) and fragments (#...)
5. Encode spaces as %20 for canonical comparison
6. Trim whitespace

localStorage Keys

The Validator uses these keys:

• systemDirectoryIndex
• systemChronologyIndex
• systemMatrixIndex
• systemHeadsIndex
• systemValidationReport

Clearing these keys affects the Validator only. Factory-specific keys (e.g., chronologyEntries) remain untouched.

Troubleshooting

Problem: "No systemChronologyIndex found"

Cause: System state has not been propagated from the chronology factory.

Solution: Open the chronology search interface systemChronologyIndex will refresh every ten seconds.

Problem: "No systemDirectoryIndex found"

Cause: No manifest has been loaded.

Solution: Click "Select Directory" and choose your project folder, or ensure the default manifest file exists.

Problem: All links show as invalid despite files existing

Cause: Path encoding mismatch or directory structure mismatch.

Solution:

• Click "View State" to inspect systemDirectoryIndex
• Verify that file paths in the manifest match the format assets/...
• Check for encoding issues (spaces, special characters)
• Ensure you're using the Reconstruction Platform template structure

Problem: Validation report shows partially invalid results

Cause: Some files may have been moved or deleted after chronology creation.

Solution:

• Review each [Invalid Link] entry
• Check whether files exist elsewhere in /assets/
• Update links in the relevant factory if files moved
• Restore missing files or remove links if files deleted

Problem: "System state updated. Re-run validation." appears repeatedly

Cause: Another tab or window is modifying localStorage.

Solution: Close other instances of the factories and re-run validation once changes are complete.