# How Archify Update Checker Functionality Validates Release Integrity

> Learn how Archify's update checker validates release integrity with semantic versioning, SHA-256 hashes, and cross-artifact consistency through its CI subsystem.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-09-13

---

**Archify's update checker functionality validates every release through a CI-integrated subsystem that verifies semantic versioning, SHA-256 hashes, and cross-artifact consistency across three core scripts.**

The `tt-a1i/archify` repository implements a self-contained update checking subsystem that ensures every release artifact maintains cryptographic and semantic integrity. This **Archify update checker functionality** operates entirely within the CI pipeline, parsing git tags, validating JSON manifests, and enforcing strict version consistency across documentation, metadata, and compiled archives.

## Core Components of the Update Checking Subsystem

The subsystem consists of three interconnected scripts that enforce release contracts through automated validation.

### Stable Manifest Validator

The `scripts/check-stable-update-manifest.mjs` script performs immutable validation of the stable release manifest located at [`docs/skill-updates/archify/stable.json`](https://github.com/tt-a1i/archify/blob/main/docs/skill-updates/archify/stable.json). It accepts CLI arguments including `--root`, `--archive`, `--tag`, and `--source-ref` to locate the built archive and git reference.

The script extracts the version from annotated git tags using the regex `/^v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/` and verifies it matches both [`archify/package.json`](https://github.com/tt-a1i/archify/blob/main/archify/package.json) and the manifest's declared version. It calls `validateStableUpdateManifest` from `archify/scripts/update-contract.mjs` to verify the manifest's schema, repository reference, commit tree SHA, and artifact SHA-256.

### Release Identity Enforcer

The `scripts/check-release-identity.mjs` script conducts exhaustive cross-artifact consistency checks for every release channel. It reads [`archify/package.json`](https://github.com/tt-a1i/archify/blob/main/archify/package.json), [`CHANGELOG.md`](https://github.com/tt-a1i/archify/blob/main/CHANGELOG.md), `README*` files, [`docs/index.html`](https://github.com/tt-a1i/archify/blob/main/docs/index.html), [`docs/start.html`](https://github.com/tt-a1i/archify/blob/main/docs/start.html), and [`archify/skill-release.json`](https://github.com/tt-a1i/archify/blob/main/archify/skill-release.json) to ensure version alignment.

The script calls `validateLocalRelease` to verify skill metadata and `validateStableUpdateManifest` to confirm manifest integrity. It validates that [`archify/package-lock.json`](https://github.com/tt-a1i/archify/blob/main/archify/package-lock.json) mirrors the exact version, that [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) aligns with the core version, and that HTML generator meta tags contain the correct version string. The script also enforces the "9/9" proof receipt rule (lines 71-76) and confirms that Chinese and English README copies are byte-identical.

### Contract Utilities

The `archify/scripts/update-contract.mjs` module provides shared validation logic used by both checker scripts. It exports `parseSemver` for version parsing, `validateStableUpdateManifest` for manifest schema enforcement, and `validateCanonicalUtcTimestamp` for temporal verification.

The module defines strict key set validation through `hasExactKeys` and sanitizes free-form fields against bidirectional or control characters. It also defines the canonical SemVer regex and helper functions including `compareSemver`, `releaseChannelForVersion`, and `isStableCoreVersion`.

## How the Validation Pipeline Executes

The CI pipeline invokes the update checker functionality through two distinct entry points that run sequentially after the release build completes.

1. **Identity Verification** – The CI runs `node scripts/check-release-identity.mjs` to perform cross-artifact consistency checks. This script parses the package version using `parseSemver` to determine if the release is a development prerelease or stable build.

2. **Manifest Validation** – The CI runs `node scripts/check-stable-update-manifest.mjs --archive path/to/archify.zip --tag vX.Y.Z` to validate the specific release archive against the manifest.

During execution, the stable manifest validator reads the annotated tag's `taggerdate` field (lines 64-86 in `check-stable-update-manifest.mjs`) to confirm the `publishedAt` timestamp matches the tagger's UTC time. It then computes the SHA-256 hash of the supplied archive using `crypto.createHash('sha256')` and validates it against the manifest's `artifact.sha256` field.

## Critical Validation Checks Explained

The Archify update checker functionality enforces several cryptographic and semantic constraints that prevent invalid releases from propagating.

### Semantic Version Parsing

Both scripts rely on the canonical SemVer regex defined in `update-contract.mjs` to extract version components. The `parseSemver` function validates that tags follow the `vMAJOR.MINOR.PATCH` format and distinguishes stable releases from development prereleases through `isStableCoreVersion` checks.

```javascript
// scripts/check-stable-update-manifest.mjs
const version = /^v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/
  .exec(tag || '')
  ?.slice(1, 4).join('.') ?? null;
if (!version) fail(`--tag must be a stable vMAJOR.MINOR.PATCH tag; found ${JSON.stringify(tag)}.`);

```

### Git Tag Metadata Verification

The stable manifest validator retrieves the annotated tag's UTC date using git commands. It confirms this timestamp matches exactly with the `publishedAt` field in [`docs/skill-updates/archify/stable.json`](https://github.com/tt-a1i/archify/blob/main/docs/skill-updates/archify/stable.json), ensuring temporal consistency between git history and release metadata.

### Archive Integrity Verification

Cryptographic verification occurs through SHA-256 hashing of the built `archify.zip` archive. The script compares the computed hash against the immutable `artifact.sha256` value stored in the manifest, preventing tampering or corruption of release artifacts between build and distribution.

### Cross-Artifact Consistency

The release identity checker verifies that all documentation artifacts advertise identical version information. The `checkReadme` function confirms that README files contain exact version badges and explicit "Current stable version" or "Current development version" markers in both English and Chinese.

```javascript
// scripts/check-release-identity.mjs
function checkReadme(relativePath, source, version, language, isDevelopment) {
  const badge = `/badge/version-${shieldEscape(version)}-`;
  const markerLabel = language === 'zh'
    ? isDevelopment ? '当前开发版本：' : '当前稳定版本：'
    : isDevelopment ? 'Current development version:' : 'Current stable version:';
  const hasMarker = source.split('\n')
    .some(line => line.includes(markerLabel) && line.includes(`\`v${version}\``));
  if (!source.includes(badge) || !hasMarker) {
    fail(`${relativePath} must advertise ${isDevelopment ? 'development' : 'stable'} identity v${version} with an exact escaped badge and explicit ${isDevelopment ? 'development' : 'stable'} marker.`);
  }
}

```

## Summary

- The **Archify update checker functionality** comprises three scripts: `check-stable-update-manifest.mjs`, `check-release-identity.mjs`, and `update-contract.mjs`.
- Validation runs entirely within the CI pipeline, parsing CLI arguments to locate archives and git references.
- The system enforces strict SemVer compliance using regex patterns defined in `update-contract.mjs`.
- Cryptographic integrity is ensured through SHA-256 hashing of release archives against manifest declarations.
- Cross-artifact consistency checks verify version alignment across package files, documentation, and metadata in multiple languages.

## Frequently Asked Questions

### How does Archify validate the stable update manifest?

Archify validates the stable update manifest through the `validateStableUpdateManifest` function in `archify/scripts/update-contract.mjs`. This function checks that the manifest contains exactly the required keys (`schemaVersion`, `skillId`, `channel`, `version`, `publishedAt`, `source`, `artifact`, `summary`, `releaseNotes`, `severity`), validates the repository URL matches `EXPECTED_REPOSITORY`, confirms the git ref follows `v${value.version}` format, and verifies the tree SHA matches a 40-character hexadecimal pattern while the artifact SHA-256 matches a 64-character pattern.

### What files does the release identity checker examine?

The `scripts/check-release-identity.mjs` script examines [`archify/package.json`](https://github.com/tt-a1i/archify/blob/main/archify/package.json), [`CHANGELOG.md`](https://github.com/tt-a1i/archify/blob/main/CHANGELOG.md), all `README*` files, [`docs/index.html`](https://github.com/tt-a1i/archify/blob/main/docs/index.html), [`docs/start.html`](https://github.com/tt-a1i/archify/blob/main/docs/start.html), [`archify/skill-release.json`](https://github.com/tt-a1i/archify/blob/main/archify/skill-release.json), [`archify/package-lock.json`](https://github.com/tt-a1i/archify/blob/main/archify/package-lock.json), and [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md). It verifies that HTML meta tags, version badges, and explicit version markers remain consistent across all these artifacts, including verification that Chinese and English copies are byte-identical.

### Where is the SemVer parsing logic defined?

The SemVer parsing logic resides in `archify/scripts/update-contract.mjs` through the `parseSemver` function. This function uses a canonical regex pattern to validate version strings and supports comparison operations through `compareSemver` and channel determination via `releaseChannelForVersion`.

### What happens if validation fails in the CI pipeline?

If any validation check fails, the scripts log a prefixed error message (such as `stable update manifest:` or `release identity:`) and exit with a non-zero status code. This failure signal causes the CI job to terminate immediately, preventing the release from proceeding until all integrity constraints are satisfied.