Graphden documentation

ADR: fn identity — ids are identity, names are per-namespace labels

Status: ACCEPTED · direction set by the project owner Companion audit: AUDIT-name-vs-id-resolution.md

Decision

  1. A fn’s identity is its fn-id (uuid). Every internal mechanism — registries, dispatch, caching, redaction — must key on the id.
  2. Names are human labels, unique PER NAMESPACE, not globally. The per-branch (namespace-id, name) CRUD gate (check-fn-name-collision!) expresses the intended semantics; the package validation enforces the same pair; only base-fn labels stay globally unique because the Clojure implementation registry uses them.
  3. Name→id resolution happens at boundaries only: fns.edn authoring (the records parser), public APIs that accept names, UI search.

The two authoring worlds (why this ADR exists)

The codebase grew two different identity models without a written reconciliation:

World id minted as rename semantics
Package sync (fns.edn) uuid-v5(namespace, name) — deterministic (packages/records/ids.clj) rename = NEW identity; the old row orphans. Names here are effectively immutable ids.
Editor CRUD random-uuid (crud/entities.clj create path) rename UPDATES :name at the same id — names are mutable labels.

Both are correct for their world: deterministic ids buy the package layer idempotent re-sync (re-sync unchanged source is a no-op), while random ids buy user graphs stable identity across relabeling. The failure mode was everything BETWEEN the worlds: in-memory registries keyed by bare name silently conflated same-named fns the moment the editor world (per-ns uniqueness) produced a duplicate the sync world (global uniqueness) could not — empirically confirmed: the CRUD gate accepts dup-target in two namespaces, and the name-keyed rich-types registry then held ONE entry for the two fns (type checking, effect classification and the secrets redaction all read whichever wrote last).

Consequences

Migration ladder (per-ns names)

Stage 1 (this branch): registry re-key (above). Remaining, in order: