Graphden documentation

Audit: name-based vs id-based internal resolution

Date: 2026-07-11 · branch feat/type-per-fn-slots Principle: internal mechanisms must resolve/match/dispatch by stable ID (uuid: fn-id, slot-id, binding-id), NOT by human NAME (fn-name, arg/slot as-name). Names are for humans (readability + docs). Graphden IDs are deterministic uuid-v5(namespace,name) / uuid-v5(fn-id,slot-name); this audit originally assumed globally unique fn names. The accepted identity ADR supersedes that assumption: fn names are unique per namespace, while base-fn implementation labels stay global. Arg/slot as-names are NOT unique across flows.

Classification: FRAGILE (name not stable/unique in context → real risk) · BENIGN (unique fn-name convenience key, id derivable, no collision risk) · CORRECT-BY-ID (already id-based — the pattern to mirror).


Why name-resolution exists at all (root cause)

Graphden IDs are derived from names (deterministic uuid-v5). Combined with globally-unique fn-names, this makes name and id nearly interchangeable at the leaf — so name-keying “just worked” and accreted. It breaks precisely where names are NOT unique: slot/arg as-names ({:as :parsed} at two sites = one name, two slot-id(owner,:parsed)).

The slot-id-keyed runtime (Phase 2/4/5) was added later than the name-keyed machinery and only got half the surface: readers + public boundary are id-based; dispatch + cross-fn value-copy are still name-based. The type checker predates it entirely and is fully name-based (see ADR-slot-id-keyed-type-checker.md).


src/graphden/executor/** — FRAGILE (ranked)

Runtime fa is deliberately hybrid: every caller value is written under BOTH its slot-id AND its ext-name. Readers use slot-id (good); the debt is name-keyed dispatch/copy around HOF wrap, ref-renames, env-bindings, and the cache key.

# Where Keys on Risk
F3 compile_eager.clj:67-88 fa-key-for-cache + renames.clj:184-230 cache-projection-frees ext-name (cache key projection) HIGHEST — latent wrong cache-hit / stale data on the hottest path (every :ref). Two distinct slots sharing an ext-name collide; name cell holds only last write → two differing calls hash equal → wrong hit. Invariant only guards missing names, not collisions.
F1 compile_eager.clj:466-474, :534-546; producer renames.clj:860-911 build-ref-renames arg-name→arg-name copy ref-rename value misroute on name collision; pure name→name, no slot-id involved.
F2 renames.clj:723-857 hof-lambda-params/alpha-equiv-lambda-params; consumed compile_eager.clj:444,516 arg-name + structural conv name wrong lambda-param → wrong wrap arity → silent all-nil rows.
F6 compile_eager.clj:263-268 make-shape-callable, merge :328/:334 lambda-param name inherits F2; lambda value overwrites a colliding fa cell. One unit with F2.
F4 bindings.clj:302-375 collect-env-bindings (dedup by env-name), write compile_eager.clj:616, read :418-419 slot-name (env-name) env-binding dedup collapses two different non-root slots sharing a name; dropped entry vanishes from fa. Value-flow is name-only (never gets a slot-id key).
F5 renames.clj:434-445, :577-591, own-rename-chain-map:44-56, compute-rename-aliases:958-987; runtime apply-rename-aliases (compile_eager.clj:606) as-name / slot-name positional {:as} deep-walk resolves via [fid name]; runtime alias copy is pure name→name on every top-level invocation.

⚠ RECONCILIATION with RUNTIME_SLOT_ID_REFACTOR.md (#104) — READ

The executor audit was run WITHOUT the #104 design record. Cross-checking it flips most of F1–F6 from “debt” to deliberate final design:

So the reclassification:

Net executor outcome: F3 fixed; F1/F2/F4/F5 are the deliberate, empirically-validated hybrid, vindicated by the design record — like Variant B, “half-built” is actually “the other half was tried and rejected for real runtime reasons.”

Each has an existing id-based analogue to mirror: deep-free-ext-entries (renames.clj:101), apply-hof-translation / build-hof-translation (renames.clj:914, compile_eager.clj:271), effective-reader-slot-id (lookups.clj:286), seq-item-builder slot-id-primary (compile_eager.clj:225), compile/deps.clj fully fn-id.

Dependency between fixes: F2+F6 are one unit; F3’s closure-capture half depends on F2. F3’s projection line alone is near-local. F1/F4/F5 each need threading (producer returns slot-id pairs + runtime copy writes slot-id keys).

CORRECT-BY-ID in executor (mirror these)

deep-free-ext-entries, translate-named-args (name-match only to accept the caller’s necessarily-named args, output is per-slot-id), effective-reader-slot-id + arg-builder :free, seq-item-builder, build-hof-translation/apply-hof-translation, compile/deps.clj, find-rename-slot/rename-for-slot/effective-binding via slot.source-slot-id FK.

BENIGN in executor (do NOT churn)

rich-type-of keyed by unique fn-name (resolution at bindings.clj:181,193, compile_runtime.clj:326); resolve-impl/has-impl? (base-fns name-registry by design); compute-fn-typed-fn-ids matching the :fn primitive name; composition/* sync boundary (the parser resolves author labels by namespace; dependency vertices and failure tracking use fn-ids); execute-by-name (explicit name-lookup public API → resolves to id then delegates).


src/graphden/{crud,storage,versioning,schema}/**

Overwhelmingly id-based and disciplined. One genuine bug, one cosmetic, a benign registry cluster.

FRAGILE

C1 (REAL BUG) — root branch protected/bootstrapped by the NAME string "main", not by structural root-ness. versioning/storage/core.clj:761 delete-branch! guards with (= "main" (:name branch)). But:

Consequence: a root branch NOT named “main” is unprotected; a non-root branch named “main” is falsely protected. Same root cause at core.clj:632 (wrap-with-versioning name-special-case) and core.clj:600-612 (ensure-main-branch! name query + random id). Fix: guard on (nil? (:base-branch-id branch)) — LOCAL. Optionally give the root a deterministic well-known id so bootstrap stops leaning on the name (small plumbing). Must fix (correctness).

BORDERLINE

C2 — sequence slot detected by name. crud/entities/seq.clj:44 (= "sequence" (:name (get fns-by-id (:type-fn-id slot)))) — dispatches on the resolved name of an id it already holds. Safe today (base-fn name unique + deterministic id). Tidy: compare (:type-fn-id slot) against the resolved sequence type-fn-id. LOCAL, cosmetic.

BENIGN (name-keyed rich-type/tag registry round-trips; decisions id-based)

crud/type_check.clj:356, crud/fn_execution/persist.clj:207 declared-effects-of, crud/entities.clj:946 chain-has-process-effect?, crud/entities.clj:318 unregister-rich-type!, crud/secret_shape.clj:29 fn-ids-with-tag (→ immediately to ids; gating compares parent-ids by id). Keying the registry by fn-id is plumbing for nil value — leave.

crud/secrets.clj vault-get-fn-id — name query, audited 2026-07-24 and kept DELIBERATELY: the base-fn filter (:return-type-fn-id set) makes the pick deterministic (base-fn bare names stay globally unique), and the per-request storage query stays correct on editor DBs whose row ids don’t match the package uuid-v5 derivation. The registry alternative ((:fn-id (rich-type-of :vault-get))) was REJECTED: the tenant per-org slice prefers an org’s own same-named entry, so a tenant composing a fn named vault-get would shadow the platform resolver — the storage query has no such precedence hazard.

CORRECT-BY-ID / boundary (no change)

Versioning resolves by (entity-name, entity-id, branch-id) throughout (resolution.clj, merge.clj matches by fn-id, :fn-name display-only); entities/seq.clj [fn-id slot-id]; renamed-view slots get deterministic records/slot-id; mi-collision-check keys by-name on purpose (it ENFORCES arg-name uniqueness). Boundary name→id: resolve-branch-ref, resolve-fn-id/resolve-fn, resolve-type-fn-id, seq JSON ref-name.

src/graphden/{packages,system,layout,services,tenancy,auth}/**

Runtime spine (executor-dispatch, reconciler, routers) is clean id. Debt clusters in authz, structural type constraints, slot-owner tie-break.

FRAGILE

BENIGN / documented-dependency

CORRECT-BY-ID

services reconciler (all service-id/fn-id), service seeding (deterministic service-id, stores fn-id), branch router (branch-id + pre-resolved handler-fn-id), app router (:app-route.handler-fn-id), layout core (fn-id/slot-id/arg-id), export/parse round-trip, org identity (slug).


SYNTHESIS — prioritized fix plan

The principle surfaced a real, distributed debt, but NONE of it is a firefight — the hot execution path is clean; the FRAGILE items are latent (structurally-possible, not currently-triggered). Root cause: deterministic name-derived ids + globally-unique fn-names made name-keying “just work”, so it accreted; it breaks only on non-unique names (slot/arg as-names) and mutable names (username, branch name).

Tier 1 — genuine correctness bugs, LOCAL, safe:

Tier 2 — executor. RESCOPED to F3 only (see § RECONCILIATION). The hybrid fa is the final design per RUNTIME_SLOT_ID_REFACTOR.md; F1/F2/F4/F5 are deliberate and their slot-id flip was tried + rejected (stack overflows). Only F3 (cache-projection by slot-id) was a real unfinished gap — DONE additively + tested. No further executor work: pursuing F1/F2/F4/F5 would repeat failed multi-day attempts for marginal benefit.

Tier 3 — plumbing robustness:

Tier 4 — cosmetic / invariant-documentation: ✅ DONE.

Type-checker (option-3): ✅ DONE (behavior-preserving consolidation; soundness untouched — re-keying was NOT attempted, it’s a lateral move per ADR-slot-id-keyed-type-checker.md). Its name-keying is mostly BENIGN (fn-name unique); the FRAGILE core is the α’ as-name narrowing, KEPT. A subagent survey mapped the real debt; verified + fixed:

Every fix: own commit, sweep-green + full bb test, skills + linters, new test pinning the id-based behaviour.

Enforcement (durable) — the CI-guard

test/graphden/id_resolution_guard_test.clj (commit d1d1ff64) makes the core anti-pattern a red build so this audit’s discipline doesn’t erode: it scans src/ and fails on dispatching by the NAME of a value held by id — (:name (get/get-in/read-entity … id)) fed into =/not=/case/ condp. Drawn narrowly to have no false positives: name EXTRACTION for display/serialisation (not in a comparison) and finding an entity BY name (loop var, not an id-deref) are both left alone. It caught P4b on its first run — an occurrence the manual pass had missed because it compares against a symbol, not a string literal. Scope: src/ mechanism layer only (package impls.clj legitimately resolve name→id at boundaries).

Incidental pre-existing bugs found + fixed along the way

Not name/id issues, but surfaced by the “clean at every stage” full bb test and fixed per the no-ignored-errors bar:

src/graphden/types/**

Fully name-based; see ADR-slot-id-keyed-type-checker.md. Narrowing keys on arg as-name (*caller-narrowings*, build-caller-narrowings) — the FRAGILE core. rich-type-of fn-name keying is BENIGN (unique). The inherited-free-arg slot identity is not locally derivable (needs the source-slot-id resolution subsystem) — the one genuinely hard case.


Synthesis / plan

pending full audit — see next section once all subsystems reported.