Status: ACCEPTED · direction set by the project owner Companion audit: AUDIT-name-vs-id-resolution.md
fn-id (uuid). Every internal mechanism —
registries, dispatch, caching, redaction — must key on the id.(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.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).
{:by-id {fn-id → entry} :by-name {name → fn-id}}); the id-holding
paths (executor compile, /api/execute persist/redaction, crud
guards) read rich-type-of-id; the type-checker and public
boundaries keep the name-keyed rich-type-of via the index.uuid-v5(ns, name) their
storage rows use, so a name-only write (the 220 existing test sites,
the loader, the seed passes) needs no change; crud-path writes
thread the ROW id (reconstruct-fn-def carries :fn-id).fn-id = uuid-v5(name) and re-founding sync idempotency on
a rename ledger — out of scope.Stage 1 (this branch): registry re-key (above). Remaining, in order:
alias-owners
side-table in types/core.clj); a cross-owner re-bind warn-logs
loudly instead of silently shadowing. Superseded by the per-ns
alias resolution below: each type-row now ALSO registers a
qualified :ns.path/name alias, and a bare name with ≥2 distinct
owners throws :types/ambiguous-alias at resolve time, naming the
qualified candidates — shadowing is no longer representable.anon-fn-name now mixes the host fn-def’s namespace into the
use-site identity ([namespace parent-name arg-name]), so
same-named parents in different namespaces keep distinct anon
entries. Synthetic anon names (and their derived ids) changed once
as a consequence — old anon rows in long-lived dev DBs become
unreferenced (harmless; clean deploys unaffected).records.ids/anonymous-fn-id mixes the CURRENT ORG into the
shape-keyed id on a tenant path (empty segment on the platform
tier, so package-sync ids are unchanged), and fn is
UNIQUE (org-id, anonymous-hash) NULLS NOT DISTINCT: a tenant’s
anonymous rows are org-scoped rows, and one shape-only id let org
B’s create collide with org A’s invisible row (a cross-org
existence oracle). Same shape, two orgs → two rows; within one org
the dedup is unchanged. The IDENTITY of an anonymous row is its
(org, hash); the deterministic id is only the preferred id for a
NEW row. A sync (composition/remap-anonymous-ids) and a tighten
reuse the row the org already holds for the shape — so the rows
written before the org went into the id keep their old ids and a
re-sync of the same shape lands on them instead of tripping the
unique key with a second id.:ns.path/name-qualified reference keywords are accepted in every
reference position (parents, arg refs, {:ref …}, sequence items,
inline-anon bodies, :return-type, type-row members), validated
against the dual-keyed name map, and REWRITTEN TO BARE at parse
entry (normalize-qualified-refs) — before anon expansion, so both
spellings hash identically. While stage 5 hasn’t relaxed global
uniqueness this is exactly equivalent to the bare form; the win is
authoring (self-documenting refs that fail loud on a wrong
namespace). Namespace-aware resolution through the type-checker’s
name world — and the exporter emitting qualified forms for
ambiguous names — is the remaining stage-5 work.validate-no-name-collisions!
now enforces (namespace, name) uniqueness (the pair IS the
deterministic fn-id) plus global uniqueness for BASE-FN bare names
only (the Clojure impls registry is name-keyed — code-level
identifiers, like Clojure vars). Same-named composed fn-defs in
different namespaces COEXIST end to end:
name->id, defs-by-name,
discovery, the rich-types :by-name index) — bare keys carry an
ambiguous sentinel / last-write on collision, qualified keys are
always precise;normalize-ref): the referencing module’s OWN namespace
wins, else a loud :packages/ambiguous-ref demands qualification;roundtrip-per-ns-duplicates). Namespaces that can’t be
SPELLED as readable keyword namespaces still qualify:
a version-materialized @-ns as (keyword "lib@1-2-0.sub" n),
the ROOT (nil) ns as (keyword "" n) - both legal in-memory/JSONB
values; the EDN-TEXT boundary spells them #graphden/ref
"lib@1-2-0.sub/n" / #graphden/ref "/n"
(records.wire/encode-unreadable-kws on the whole-graph bundle,
wire-readers at the loader/remote read sites; proof:
roundtrip-unspellable-ns-duplicates, wire-edn-text-roundtrip).
The old bare fallback for these corners is gone;::ns-path-annotated rows) so the checker resolves duplicates
precisely through the dual registry index;:ns/name — the natural
disambiguation display).
Residual CLOSED: the type-ALIAS registry registers
bare + qualified :ns.path/name keys per type-row
(register-type-alias! 4-arity; alias-qualified side-table);
an ambiguous bare name throws at resolve-alias with the
qualified candidates. Reference sites disambiguate by writing the
qualified keyword in the :type position — no context-aware
resolution needed (@-versioned namespaces register bare-only,
mirroring export’s EDN-keyword guard).resolveFnByName
accepts qualified ns.path/name input, and a bare name matching
several namespaces console-warns with the qualified candidates
(first match returned so pre-duplication deep-links keep working).
Original sketch (kept for context): search/deep-links show the
namespace when a bare name is ambiguous (matches the “hide
namespaces until needed” editor philosophy).