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

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, 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, 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 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 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 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 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, 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 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 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.

// 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:

// 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:

// 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.
• 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 for JSON-Schema conformity.
• Acyclic Dependencies are enforced by archify/src/loader/dependencyResolver.js using topological sorting.
• Hash Verification detects data corruption via archify/src/loader/hashVerifier.js.
• Referential Integrity guarantees cross-collection links resolve correctly through 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. 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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}