# How Archify Validators Are Generated and Shipped: A Complete Technical Guide

> Learn how Archify validators are automatically generated from TypeScript JSON schemas at build time and shipped with the npm package for efficient runtime validation.

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

---

**Archify validators are automatically generated from TypeScript JSON schemas at build time, bundled into a deterministic ZIP archive, and shipped with the npm package so downstream projects can perform runtime validation without installing development dependencies.**

The `tt-a1i/archify` repository implements a sophisticated build pipeline where validation logic is derived directly from source schemas. This approach ensures that workflow definitions, skill manifests, and update contracts are validated against the exact same structural rules at both compile time and runtime.

## Schema Definitions as the Single Source of Truth

All validation logic originates in the **TypeScript schema files** located in `archify/src/schema/`. These modules—such as [`archify/src/schema/workflow.ts`](https://github.com/tt-a1i/archify/blob/main/archify/src/schema/workflow.ts)—define the canonical shape of workflow contracts, skill metadata, and update manifests using strong typing.

By maintaining schemas as the definitive source, the system guarantees that any change to a data structure automatically propagates to its corresponding validator. This eliminates drift between documentation, type definitions, and runtime checks.

## The Generator Pipeline: From Types to Validators

The transformation from static schemas to executable validation code is handled by `scripts/write-deterministic-zip.mjs`. This Node.js script imports the schema modules and uses internal `zod`/`ajv` helpers to transpile them into **plain-JavaScript validator functions**.

Unlike generic validation libraries that parse schemas at runtime, these generated functions are static code optimized for performance. The script writes the output into a temporary directory structure that mirrors the final package layout.

### Creating the Deterministic Archive

Once the JavaScript files are generated, [`scripts/build-zip.sh`](https://github.com/tt-a1i/archify/blob/main/scripts/build-zip.sh) packages them into `archify.zip`. This archive contains the compiled validator modules under a `validators/` directory.

The build process ensures the ZIP is **deterministic**, meaning identical source inputs always produce byte-for-byte identical archives. This property is critical for reproducible releases and cryptographic verification of the distributed package.

## Packaging and Distribution

The generated validators are integrated into the release workflow defined in [`.github/workflows/release.yml`](https://github.com/tt-a1i/archify/blob/main/.github/workflows/release.yml). When maintainers publish a new version, the CI pipeline executes the generator scripts and includes the resulting `archify.zip` within the npm tarball.

Consumers install the package via `npm i archify` and access validators directly from the `archify/validators` namespace. The validators ship as production dependencies, requiring no additional build tooling in downstream projects.

## Runtime Usage and Validation

Client code imports specific validators as needed. For example, to validate a workflow definition:

```javascript
// Import a generated validator
import { workflowValidator } from "archify/validators/workflow.js";

// Validate a workflow definition
const result = workflowValidator(myWorkflow);
if (!result.success) {
  console.error("Invalid workflow:", result.error);
}

```

These validators are **pure functions** that return a boolean status or throw detailed error objects. This design enables both compile-time type safety through TypeScript and defensive runtime checks in production environments.

## Summary

- **Single source of truth**: Schemas in `archify/src/schema/` define all valid data structures, ensuring validators never drift from specifications.
- **Automated generation**: `scripts/write-deterministic-zip.mjs` converts TypeScript schemas into optimized JavaScript validation functions using `zod`/`ajv` helpers.
- **Deterministic bundling**: [`scripts/build-zip.sh`](https://github.com/tt-a1i/archify/blob/main/scripts/build-zip.sh) creates reproducible `archify.zip` archives containing the `validators/` directory, guaranteeing identical builds across environments.
- **Zero-dependency consumption**: The CI pipeline in [`.github/workflows/release.yml`](https://github.com/tt-a1i/archify/blob/main/.github/workflows/release.yml) ships generated validators with the npm package, allowing runtime validation via `archify/validators` without development tooling.

## Frequently Asked Questions

### Why does Archify generate validators instead of using a runtime validation library?

**Archify generates validators to eliminate runtime overhead and distribution bloat.** When schemas are parsed by libraries like `ajv` or `zod` at runtime, they incur both memory and CPU costs. By generating plain-JavaScript functions at build time, Archify ships only the necessary validation logic, resulting in smaller bundle sizes and faster execution while maintaining perfect synchronization with the source schemas.

### What makes the ZIP archive "deterministic" and why does it matter?

**A deterministic archive produces identical byte-for-byte output when given the same input.** The [`scripts/build-zip.sh`](https://github.com/tt-a1i/archify/blob/main/scripts/build-zip.sh) process sorts files, normalizes timestamps, and uses consistent compression settings to ensure `archify.zip` is reproducible. This matters for security auditing, build caching, and verifying that published packages match the source code exactly, preventing supply-chain attacks where build artifacts might differ unexpectedly.

### How do I regenerate validators if I modify the source schemas?

**Run the generator script locally and rebuild the archive.** Execute `node scripts/write-deterministic-zip.mjs` to transpile the updated TypeScript schemas in `archify/src/schema/` into JavaScript validators. Then run `bash scripts/build-zip.sh` to recreate the deterministic ZIP. These steps are automatically performed by the CI pipeline in [`.github/workflows/release.yml`](https://github.com/tt-a1i/archify/blob/main/.github/workflows/release.yml) during publication, but maintainers can run them manually for local testing.

### Are the generated validators compatible with TypeScript type checking?

**Yes, the validators provide runtime enforcement that complements compile-time types.** While TypeScript checks types during development, the generated validators from `archify/validators/` verify data at runtime—for example, when ingesting external JSON payloads. This dual-layer approach catches structural violations that bypass type systems, such as malformed API responses or corrupted configuration files.