Technical note verified Sep 15, 2026

Public Research Archive and Immutable Revision Sync

KESPA established a public research repository and website bridge that publishes experiments, benchmarks, technical notes, datasets, and updates through a manifest-driven archive. The sync path resolves GitHub main to an immutable commit SHA before fetching the manifest and artifacts, eliminating stale branch-CDN reads and ensuring each sync uses one consistent repository revision.

research-archive provenance github immutable-revisions publication

MARKDOWN

README.md

4,425 bytes SHA-256 6aaa0ddc550729cf…

KESPA-NOTE-019 — Public Research Archive and Immutable Revision Sync

Date: 2026-09-15 Status: Verified — public repository / website bridge operational Project: KESPA AI / NexLabs Studios

Purpose

KESPA's research results are kept separate from the private application repository.

The public archive lives in:

ryanmurray89/KESPA-Research

and publishes curated research records through a manifest-driven structure.

Supported public entry types include:

experiments;
benchmarks;
technical notes;
datasets;
updates.

The public archive is not intended to expose private application code or raw internal research state.

Public manifest

The root index uses:

kespa.public_research_index.v1

Each entry identifies:

research ID;
type;
title;
date;
publication status;
summary;
path;
tags;
public files.

Allowed status values are:

draft / published / verified / archived

The public artifact layer is intentionally limited to text-oriented formats such as Markdown, JSON, text, and CSV.

Website bridge

The KESPA website periodically synchronizes the public repository into a local public-research cache.

Core pieces include:

scripts/research/sync_public_research.php
src/PublicResearch.php
public/research/index.php
public/research/view.php

Local state includes:

cached manifest;
sync state;
per-entry artifact directories.

The sync runs every 5 minutes.

Artifact viewer

The public artifact viewer renders a restricted Markdown subset and safely escapes JSON/text content.

It can expose:

SHA-256;
byte size;
artifact type;
GitHub source link.

This makes the public research page useful for both humans and audit/reproducibility work without turning it into a generic arbitrary-file renderer.

Mutable-branch synchronization problem

During publication of the early benchmark records, an important failure mode appeared.

The GitHub API showed the current main branch containing the new benchmark entry, while:

raw.githubusercontent.com/.../main/manifest.json

continued returning an older branch snapshot.

That meant a branch-name URL could temporarily serve stale content even though the repository itself had already advanced.

For a research archive, that can produce a worse problem than a missing page:

new manifest + old artifact

or:

old manifest + new repository state

Immutable revision fix

Sync v0.2.3 changed the process.

Instead of fetching everything directly through the mutable main reference, KESPA now:

1. resolves main to its current commit SHA through the GitHub API;

2. fetches manifest.json from that exact SHA;

3. fetches every referenced artifact from the same SHA;

4. stores the resolved commit_sha in sync state.

Conceptually:

main -> commit SHA -> manifest + all artifacts from that exact revision

This removes branch-CDN freshness from the consistency contract.

Why this matters

Research publication needs stronger consistency than an ordinary marketing website.

If the manifest says an experiment contains six artifacts, the website should not accidentally combine a manifest from one revision with files from another.

Using one immutable repository revision per sync gives KESPA a simple consistency guarantee:

A synchronized public research snapshot is internally revision-consistent.

Public/private boundary

The public archive intentionally excludes:

private application repository contents;
credentials and environment files;
raw third-party evidence bodies;
private internal telemetry payloads;
implementation secrets.

It publishes safe research summaries, methodology, aggregate measurements, recorded provenance, and artifact hashes.

Research significance

This archive turns individual experiments into a growing longitudinal research record.

It gives KESPA a public surface where benchmark failures, methodology changes, technical notes, and successful experiments can coexist without rewriting history.

That matters especially for the KESPA research thesis because negative results and architecture corrections remain visible alongside successful ones.

Limitation

The archive is curated.

It is not a complete mirror of every private research artifact, and the public sync does not independently rerun experiments.

Its job is publication consistency and provenance, not experimental validation.

TEXT

SHA256SUMS.txt

393 bytes SHA-256 bc5837267a9b25a1…

6aaa0ddc550729cf5a05d3d59e3d3254d2030da871e6612178476e86246152dc  README.md
e3c6fb0300dcd726003941da024be3bead9066e08dcc04e9cb23d787ea6db8a3  note.json
195409488784280721332a893fab03a1e2e3d56f7b22b30e531db17d4ac4bba4  metrics.csv
9e8c5870be45733f41d98000f09b74a0190678fa9c6a845bfd4eeecb9e1a92bd  methodology.md
f9e4f44d4ed8d811df2af427c709d51fe52f1ef22f32cad38129f9a9d1355f3d  provenance.json

MARKDOWN

methodology.md

995 bytes SHA-256 9e8c5870be45733f…

Methodology

Publication contract

Research records are added to the public repository through the root manifest and an entry-specific artifact directory.

Each entry declares its type, status, summary, path, tags, and public files.

Website synchronization

The website sync resolves the repository's current main branch to an immutable commit SHA.

The manifest and all referenced artifacts are then fetched from that same revision.

Successful sync state records the resolved commit SHA.

Local cache

Public research artifacts are cached under the website's storage/public_research area so the public page does not need to fetch GitHub on every page request.

Artifact safety

The viewer supports only the public text-oriented artifact formats used by the repository and safely escapes structured/text content.

Publication boundary

Private application code, environment values, raw evidence bodies, and private internal artifacts remain outside the public repository.

CSV

metrics.csv

487 bytes SHA-256 1954094887842807…

metric,value,unit_or_status
manifest_schema,kespa.public_research_index.v1,schema
supported_entry_types,5,types
supported_status_values,4,statuses
public_artifact_format_classes,4,format_classes
sync_interval,5,minutes
immutable_commit_resolution,YES,consistency
manifest_and_artifacts_same_revision,YES,consistency
commit_sha_persisted_in_sync_state,YES,provenance
github_token_required,NO,operation
private_app_repo_published,NO,boundary
raw_third_party_evidence_published,NO,boundary

JSON

note.json

3,743 bytes SHA-256 e3c6fb0300dcd726…

{
    "schema": "kespa.public_technical_note.v1",
    "id": "KESPA-NOTE-019",
    "title": "Public Research Archive and Immutable Revision Sync",
    "date": "2026-09-15",
    "status": "verified",
    "purpose": "Document the public KESPA research archive, its manifest contract, website artifact viewer, and the immutable-commit synchronization correction used to keep public research pages consistent with the GitHub repository.",
    "public_repository": {
        "repository": "https://github.com/ryanmurray89/KESPA-Research",
        "manifest_schema": "kespa.public_research_index.v1",
        "entry_types": [
            "experiment",
            "benchmark",
            "technical_note",
            "dataset",
            "update"
        ],
        "entry_statuses": [
            "draft",
            "published",
            "verified",
            "archived"
        ],
        "allowed_public_artifact_types": [
            "markdown",
            "json",
            "text",
            "csv"
        ]
    },
    "website_bridge": {
        "sync_script": "scripts/research/sync_public_research.php",
        "research_service": "src/PublicResearch.php",
        "research_index": "public/research/index.php",
        "artifact_viewer": "public/research/view.php",
        "site_cache_manifest": "storage/public_research/manifest.json",
        "site_sync_state": "storage/public_research/sync_state.json",
        "site_entry_cache": "storage/public_research/entries/<entry-id>/",
        "sync_interval_minutes": 5
    },
    "artifact_viewer": {
        "safe_markdown_subset": true,
        "json_text_escaped": true,
        "sha256_displayed": true,
        "byte_size_displayed": true,
        "github_source_link_supported": true
    },
    "stale_branch_problem": {
        "observed": true,
        "symptom": "raw.githubusercontent.com/.../main/manifest.json returned an older branch snapshot while the GitHub API showed the newer main contents.",
        "affected_publication": "KESPA-BENCH-001",
        "old_sync_behavior": "Fetch manifest/artifacts directly from the mutable main branch reference.",
        "corrected_sync_version": "forge-public-research-sync-v0.2.3"
    },
    "immutable_sync": {
        "step_1": "Resolve current main to its commit SHA through the GitHub API.",
        "step_2": "Fetch manifest.json from raw.githubusercontent.com at that immutable SHA.",
        "step_3": "Fetch all referenced public artifacts from the same immutable SHA.",
        "step_4": "Persist commit_sha in sync state.",
        "benefit": "Manifest and artifacts are guaranteed to come from one repository revision during a sync."
    },
    "publication_boundary": {
        "private_app_repository_published": false,
        "private_source_code_required": false,
        "github_token_required_for_sync": false,
        "raw_third_party_evidence_text_published": false,
        "private_credentials_or_env_published": false,
        "public_research_metadata_and_safe_artifacts_only": true
    },
    "interpretation": [
        "A public research archive is more useful when every public record is addressable through a stable manifest and artifact contract rather than ad hoc pages.",
        "Resolving a mutable branch name to an immutable commit SHA before downloading prevents manifest/artifact skew caused by CDN staleness.",
        "The archive separates reproducible public research artifacts from private implementation code and raw third-party evidence."
    ],
    "limitations": [
        "The public archive is a curated publication layer, not a complete mirror of private KESPA research storage.",
        "GitHub availability remains an external dependency for fresh synchronization.",
        "The public viewer intentionally supports only a restricted set of safe text-oriented artifact types.",
        "Publication status such as verified refers to the underlying research record and validation basis; the website sync itself does not independently re-run experiments."
    ]
}

JSON

provenance.json

1,334 bytes SHA-256 f9e4f44d4ed8d811…

{
    "schema": "kespa.public_provenance.v1",
    "research_id": "KESPA-NOTE-019",
    "source_basis": "KESPA public-research repository, website-bridge implementation records, and the recorded stale GitHub Raw branch incident during benchmark publication.",
    "source_observations": [
        "KESPA uses a separate public repository at ryanmurray89/KESPA-Research with the kespa.public_research_index.v1 manifest.",
        "The website sync caches the manifest and entry artifacts and runs every five minutes.",
        "A stale raw.githubusercontent.com main-branch response was observed while the GitHub API already showed the newer manifest contents.",
        "Sync v0.2.3 corrected this by resolving main to an immutable commit SHA and fetching both manifest and artifacts from that same SHA.",
        "The public viewer supports safe Markdown plus escaped JSON/text and exposes SHA-256, byte size, and source links.",
        "Private application code and raw third-party evidence are intentionally excluded from the public archive."
    ],
    "publication_note": "This note describes the public publication architecture and its consistency correction. It intentionally excludes private repository contents, credentials, environment data, raw third-party evidence, and private implementation details not necessary to understand the publication contract."
}