Requirements for Stable IDs in Archify Comparisons: 7 Architectural Constraints for Reliable Deltas

Stable IDs in Archify must be globally unique, deterministic, persistent, URL-safe, explicitly declared, scope-limited, and immutable after authoring to enable reliable Architecture Delta comparisons.

Archify (tt-a1i/archify) relies on stable IDs as the canonical identifiers that allow two diagram snapshots to be compared deterministically. These identifiers form the backbone of the Architecture Delta view, ensuring that logical elements can be tracked across revisions regardless of visual changes.

Why Stable IDs Drive Architecture Delta Comparisons

According to archify/SKILL.md, comparisons pair components and relationships only by authored stable IDs. When you execute node archify/bin/archify.mjs compare architecture base.json head.json, Archify performs three distinct operations: it loads both JSON snapshots, pairs elements solely by their stable IDs, and classifies changes as added, removed, moved, or updated only when IDs differ or immutable fields change. This process depends entirely on the stability and predictability of the identifier scheme.

The 7 Requirements for Stable IDs in Archify

1. Global Uniqueness Within a Diagram

Every node or relationship must have a globally unique stable ID string within a single diagram. As documented in README.md#L54, this uniqueness constraint guarantees that the matcher can unambiguously pair the same element across snapshots without collision or ambiguity.

2. Determinism From Immutable Attributes

The ID must derive from immutable attributes—such as component name, kind, and logical path—and must not depend on layout, coordinates, or run-time artifacts. This determinism ensures the ID remains constant when only visual properties change, keeping the logical element stable across revisions regardless of rendering differences.

3. Persistence Across Versions

If an element is structurally unchanged between two versions, its stable ID must remain exactly the same. This persistence enables the delta algorithm to recognize "unchanged" elements and report only true additions, removals, moves, or edits rather than false positives caused by identifier volatility.

4. URL-Friendly Format

Stable IDs must be plain-text, URL-safe strings composed of letters, digits, hyphens, and underscores—spaces and special characters are prohibited. As shown in README.md#L54, IDs appear in fragment URLs such as #focus=<id> and #route=<source>~<target>, so URL safety enables direct linking, copying, and sharing without encoding issues.

5. Explicit Declaration in JSON IR

Every node or relationship in the typed JSON intermediate representation must include the stable ID field, commonly "id". The renderer and validator read this field directly from the source file; without explicit declaration, the element cannot be matched during comparison operations, as noted in README.md#L12508 regarding the Node Finder functionality.

6. Scope Limitation to Single Diagrams

IDs are scoped to a single diagram file. While the same literal ID may be reused in different diagrams, comparisons are always performed within the same artifact context, preventing cross-artifact interference and keeping the matching logic simple and predictable.

7. Immutability After Authoring

Once an author assigns a stable ID, subsequent edits to the diagram may change other properties such as labels or geometry, but must leave the ID untouched unless the element itself is removed or replaced. This immutability guarantees that only intentional deletions or creations cause ID changes, preserving the integrity of the delta view.

Technical Implementation in the JSON IR

In practice, stable IDs appear as explicit fields in the typed JSON IR. The renderer references these identifiers when building the Architecture Delta view.

{
  "id": "api-gateway",
  "kind": "backend",
  "label": "API Gateway",
  "tags": ["gateway", "http"]
}

Relationships follow the same pattern, using stable IDs to identify edges independently of their visual routing:

{
  "id": "rel-api-db",
  "source": "api-gateway",
  "target": "postgres-db",
  "label": "SQL Query"
}

Using Stable IDs in Fragment URLs

Because IDs satisfy the URL-friendly requirement, they can be used directly in browser fragments for deep linking. The Node Finder described in archify/references/viewer-runtime.md searches for elements using these exact identifiers.

#focus=api-gateway
#route=api-gateway~postgres-db

These fragments allow users to share direct links to specific nodes or edges without additional encoding or resolution steps.

Failure Modes When Requirements Are Violated

If an element lacks a stable ID or its ID changes unintentionally between versions, the comparison falls back to a "no-match" state. The delta algorithm treats the orphaned element as a new addition and the missing counterpart as a deletion, breaking the deterministic output. This behavior emphasizes why the delivery contract in archify/references/delivery-contract.md mandates stable-ID-based diagnostics for reliable receipts.

Summary

• Global uniqueness prevents ambiguous matching within a single diagram scope.
• Determinism ensures IDs reflect logical identity rather than visual layout or coordinates.
• Persistence allows the delta algorithm to detect truly unchanged elements across snapshots.
• URL-friendly formatting enables fragment links like #focus=<id> and #route=<source>~<target>.
• Explicit declaration in the JSON IR is mandatory for the renderer and validator to match elements.
• Scope limitation isolates comparisons to single artifacts, preventing cross-diagram collisions.
• Immutability after authoring maintains delta integrity by ensuring only intentional structural changes alter identifiers.

Frequently Asked Questions

What happens if a stable ID changes unintentionally between versions?

If a stable ID changes without the element being explicitly removed and recreated, Archify cannot pair the old and new representations. The comparison treats the old ID as deleted and the new ID as added, resulting in a false removal and addition rather than recognizing an edit or move. This breaks the deterministic delta output and can obscure actual architectural changes.

Can the same stable ID be reused in different diagram files?

Yes. Stable IDs are scoped to individual diagram files. The same literal string may appear in separate diagrams without collision because Archify performs comparisons within a single artifact context only, as implied by the fragment-based architecture in README.md#L54.

Are stable IDs generated automatically or assigned by authors?

Authors must explicitly assign stable IDs in the typed JSON IR. Every node and relationship must include the "id" field; without this explicit declaration, the element cannot be matched during Architecture Delta comparisons, and the validation logic will fail to locate the component.

What characters are allowed in Archify stable IDs?

Stable IDs must be URL-safe strings containing letters, digits, hyphens, and underscores. Spaces and special characters requiring percent-encoding are prohibited to ensure compatibility with fragment URLs such as #focus=<id> and #route=<source>~<target> used by the viewer runtime.

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