# 7 Cross-Collection Facts Verified by Archify's Shared Loader

> Verify 7 cross-collection facts with Archify's shared loader ensuring data consistency artifact contract alignment version compatibility global identifier uniqueness and more.

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

---

**Archify's shared loader enforces seven immutable cross-collection facts—including artifact-contract alignment, semantic version compatibility, global identifier uniqueness, schema conformity, acyclic dependencies, cryptographic hash integrity, and referential integrity—to guarantee data consistency across distributed collections.**

Archify is an open-source data pipeline framework maintained in the `tt-a1i/archify` repository. The **cross-collection facts verified by Archify's shared loader** serve as atomic guarantees that prevent corrupted or inconsistent data from entering the execution environment. These validations execute once during the initial load phase, immediately terminating with a descriptive error if any invariant fails.

## The Seven Immutable Validation Facts

When `loadCollection()` is invoked in [`archify/src/loader/sharedLoader.js`](https://github.com/tt-a1i/archify/blob/main/archify/src/loader/sharedLoader.js), the system validates the following facts before allowing data to proceed downstream.

### Artifact-Contract Alignment

**Every artifact must conform to the contract schema declared for its collection.** In [`archify/src/loader/sharedLoader.js`](https://github.com/tt-a1i/archify/blob/main/archify/src/loader/sharedLoader.js), the `verifyArtifactContract()` function compares an artifact's payload against its registered contract definition. If the payload structure violates the contract, the loader throws a descriptive error and aborts the load.

### Semantic Version Compatibility

**Collection versions must be backward-compatible with their semantic contracts.** The `checkVersionCompatibility()` function in [`archify/src/loader/sharedLoader.js`](https://github.com/tt-a1i/archify/blob/main/archify/src/loader/sharedLoader.js) validates that a collection's declared version satisfies the dependency constraints of any consuming collections. This prevents breaking changes from propagating into existing workflows.

### Global Unique Identifier Integrity

**Identifiers for workflows, artifacts, and contracts must be globally unique across all collections.** The `ensureGlobalUniqueness()` function in [`archify/src/loader/sharedLoader.js`](https://github.com/tt-a1i/archify/blob/main/archify/src/loader/sharedLoader.js) maintains a registry of loaded IDs. If a duplicate identifier is detected during the load process, the operation fails immediately to prevent namespace collisions.

### Schema-Based Data Shape Validation

**All JSON data must validate against its corresponding JSON-Schema definition.** The shared loader delegates to [`archify/src/schema/validator.js`](https://github.com/tt-a1i/archify/blob/main/archify/src/schema/validator.js) to verify that loaded documents match their declared schemas. Mismatches raise validation errors before the data is used elsewhere in the system.

### Dependency Graph Acyclicity

**The directed graph of collection imports must contain no cycles.** The shared loader invokes [`archify/src/loader/dependencyResolver.js`](https://github.com/tt-a1i/archify/blob/main/archify/src/loader/dependencyResolver.js) to perform a topological sort on the import graph. If a cyclic dependency is detected, the loader rejects the configuration before initialization completes.

### Canonical Hash Verification

**Every persisted artifact must match its stored cryptographic hash.** In [`archify/src/loader/hashVerifier.js`](https://github.com/tt-a1i/archify/blob/main/archify/src/loader/hashVerifier.js), the loader recomputes the hash of each artifact on load and compares it to the stored value. This ensures data integrity and detects tampering or corruption during storage.

### Cross-Collection Referential Integrity

**References between collections must resolve to existing entities.** The [`archify/src/loader/relationshipResolver.js`](https://github.com/tt-a1i/archify/blob/main/archify/src/loader/relationshipResolver.js) module verifies that workflow steps or other entities referencing artifacts in different collections actually point to valid, loaded objects. Missing references trigger an immediate load failure.

## How the Shared Loader Enforces Validation

The entry point `loadCollection()` in [`archify/src/loader/sharedLoader.js`](https://github.com/tt-a1i/archify/blob/main/archify/src/loader/sharedLoader.js) orchestrates these checks sequentially. If any fact fails, the loader throws an exception and aborts the load, protecting downstream code from working with corrupted data.

```javascript
// Example: Loading a collection with the shared loader
import { loadCollection } from 'archify/src/loader/sharedLoader.js';

(async () => {
  try {
    const collection = await loadCollection('./collections/my-workflow.json');
    console.log('✅ Collection loaded and all cross‑collection facts verified');
  } catch (err) {
    console.error('❌ Load failed:', err.message);
  }
})();

```

Internally, the artifact-contract verification performs a strict schema check:

```javascript
// Inside the shared loader – artifact‑contract verification
function verifyArtifactContract(artifact, contract) {
  if (!contract.validate(artifact.payload)) {
    throw new Error(
      `Artifact ${artifact.id} does not satisfy its contract ${contract.id}`
    );
  }
}

```

Dependency resolution prevents circular imports before they cause runtime errors:

```javascript
// Detecting cyclic dependencies
import { resolveDependencies } from 'archify/src/loader/dependencyResolver.js';

const deps = resolveDependencies(['collectionA.json', 'collectionB.json']);
if (deps.hasCycle) {
  throw new Error('Cyclic collection dependencies detected');
}

```

## Summary

- **Artifact-Contract Alignment** ensures payloads match their declared schemas via `verifyArtifactContract()` in [`sharedLoader.js`](https://github.com/tt-a1i/archify/blob/main/sharedLoader.js).
- **Version Compatibility** validates semantic versioning constraints through `checkVersionCompatibility()`.
- **Unique Identifier Integrity** prevents ID collisions using `ensureGlobalUniqueness()`.
- **Schema Validation** delegates to [`archify/src/schema/validator.js`](https://github.com/tt-a1i/archify/blob/main/archify/src/schema/validator.js) for JSON-Schema conformity.
- **Acyclic Dependencies** are enforced by [`archify/src/loader/dependencyResolver.js`](https://github.com/tt-a1i/archify/blob/main/archify/src/loader/dependencyResolver.js) using topological sorting.
- **Hash Verification** detects data corruption via [`archify/src/loader/hashVerifier.js`](https://github.com/tt-a1i/archify/blob/main/archify/src/loader/hashVerifier.js).
- **Referential Integrity** guarantees cross-collection links resolve correctly through [`archify/src/loader/relationshipResolver.js`](https://github.com/tt-a1i/archify/blob/main/archify/src/loader/relationshipResolver.js).

## Frequently Asked Questions

### What happens when a cross-collection fact fails validation?

The shared loader immediately throws a descriptive exception and aborts the entire load operation. This fail-fast behavior prevents corrupted or inconsistent data from reaching downstream processing stages, ensuring that only verified collections enter the execution environment.

### Which source file contains the artifact-contract verification logic?

The `verifyArtifactContract()` function is implemented in [`archify/src/loader/sharedLoader.js`](https://github.com/tt-a1i/archify/blob/main/archify/src/loader/sharedLoader.js). This function validates that an artifact's payload structure conforms to the contract schema registered for that collection.

### How does Archify detect circular dependencies between collections?

The loader invokes `resolveDependencies()` from [`archify/src/loader/dependencyResolver.js`](https://github.com/tt-a1i/archify/blob/main/archify/src/loader/dependencyResolver.js), which performs a topological sort on the collection import graph. If the sort detects a cycle, the loader raises an error before any collections are instantiated.

### Is hash verification performed on every collection load?

Yes. The [`archify/src/loader/hashVerifier.js`](https://github.com/tt-a1i/archify/blob/main/archify/src/loader/hashVerifier.js) module recomputes and validates cryptographic hashes for every persisted artifact during each load operation. This ensures data integrity and verifies that stored artifacts have not been corrupted or tampered with between persistence and load events.