Skip to main content

​
Summary

Cross-system fingerprinting with Blake3 enables integrity verification when sprites (capability containers) flow across system boundaries. The IRIS MERIDIAN adapter implements DEC-005 compliance by using a canonical field exclusion pipeline—excluding volatile metadata (id, created_at, fingerprint)—so independent systems (iris-service, iris-sdk, adapter) compute identical hashes without coordination.

​
The Problem

When a sprite moves across systems, three separate hash computations must align. But field evolution breaks naive “all hashes must equal” checks. When iris-service adds an optional version field, old hashes become invalid even though the sprite structure is unchanged.

​
The Solution

Define an explicit exclude list: fields that shouldn’t contribute to the hash (volatile: id, created_at, fingerprint; infrastructure: source, updated_at). Everything else—name, domain, capabilities, metadata—flows into the hash. Why this works: Structural correctness (does the sprite contain the capabilities we expect?) matters more than byte-for-byte equality. When iris-service evolves, the exclude list automatically filters out new fields. Verification stays robust. Use case-insensitive comparison. Blake3 hex output is case-agnostic; different systems may render hashes differently.

​
Implementation

The FingerprintVerifier (see SKILL.md for code) computes a fresh hash, compares it case-insensitively to stored hashes, and returns verified=true only if all present hashes match. Store all three hashes (iris, computed, meridian) for audit trails.

​
Operational Impact

  • Sprite creators (iris-service): Compute Blake3 with canonical pipeline; store hash alongside sprite (already doing this per DEC-005 spec).
  • Sprite consumers (adapter): Fetch sprite, recompute hash locally, compare case-insensitively. Divergence indicates corruption or schema mismatch.
  • Audit trail: Three-way hash comparison enables rapid troubleshooting (“iris-service says hash X, we computed Y—what changed?”)
  • Scalability: Multiple systems verify independently without central coordination.
  • Implementation: See iris-meridian-adapter/SKILL.md (10-point pattern guide) for code and design patterns
  • File reference: src/adapter/fingerprint.py:20-80 (FingerprintVerifier implementation)
  • Integration test: tests/test_fingerprint.py (6 verification tests, all passing)
  • Spec reference: iris-specs/DEC-005-fingerprinting.md
  • Engine reference: iris-sdk-python/fingerprint/engine.py

​
Business Impact

  • Security: Hash verification detects tampering with sprites in transit.
  • Compliance: DEC-005 mandates cross-system fingerprinting; this learning documents compliance implementation.
  • Operational confidence: Audit trail (iris_hash, computed_hash, meridian_hash) enables rapid troubleshooting.
  • Scalability: Canonical pipeline enables multiple systems to verify independently without central coordination.