Graphden documentation

Type system — architecture decisions record

Not a roadmap. The type system is at sweep-at-zero across all 2236 fn-defs (allowed-type-check-failures is #{}, Phase E hard-gate armed both directions). This file records the architectural decisions that got us there — especially the ones we rejected — so the next time someone reaches for “caller-context propagation should be easy” or “row polymorphism would clean this up”, the analysis that closed those paths is one click away.

For how the type system works in practice, see TYPES.md.

Current state

The root architectural tension

Slots in graphden are global identities (one-shot creation, immutable). Bindings overlay them. The same slot-id can be used by multiple fn-defs in structurally different flows.

When a shared slot — e.g. :get’s :coll, or a renamed-view slot like :parsed — is used in CREATE / UPDATE / DELETE flows with different record shapes, the type-checker has TWO bad options:

Neither is sound + complete. The honest answer: types must be call-context-local, not slot-local.

Three architectural answers we considered

# Approach Cost Cleanliness Status
α Per-flow rename (mechanical) — {:as :create-parsed} / {:as :update-parsed} / {:as :delete-parsed} low low superseded by α’
α’ Per-use-site anon naming + rename-leaf narrowing + effective-ref-return merge-flip mid mid-high LANDED — closed the original 10
β Caller-context propagation (downward type-flow second pass) mid high in theory ATTEMPTED + REVERTED — see below
γ True row polymorphism (HM-style row variables) high highest REJECTED — see below

β attempt — REVERTED

A first prototype of β was implemented and reverted in the same session. The core insight that killed it:

Per-name propagation through the ref-graph is unsound because graphden’s slot identities are distinct from slot NAMES. Two {:as :parsed} renames at different inline-anon sites create two DIFFERENT slot-ids — they share the AS-NAME but ARE NOT the same slot.

Multiple flows independently use the name :parsed (create / update / delete / seq-append / record-type / list-type / types-compatible — 9 distinct binders, 7 distinct shapes), and they re-use shared utility fn-defs (:_rejection-response, :html-error-response, :_request-body, …). A BFS over the ref-graph keyed on :parsed correctly narrowed the create-flow LEAVES but also leaked the narrowing to unrelated fn-defs sharing :parsed semantics elsewhere — sweep went 10 → 28-31 with new false-positive failures on update/seq-flow descendants.

Three increasing restrictions were tried (parent-slots filter, free-arg-of-child filter, walk-through-rebind filter). Each cut some false propagations but none captured the root constraint: two flows can share a free-arg name without sharing its slot identity.

Lesson — why per-name propagation is fundamentally wrong

The runtime semantics of a free-arg are tied to its slot identity (the slot-id introduced by the original rename in the parser pre-pass). The type-checker today operates one level above this: it sees the AS-NAME and treats it as the free arg’s identity. For Pass-1’s local check this is fine — the slot type doesn’t escape the fn-def’s local computation. For Pass-2 propagation across the ref-graph it ISN’T fine — the AS-NAME’s TYPE flows through distinct slot-ids that may need different types.

Revisited and REJECTED: the slot-id-keyed sketch (thread slot-id through the parser’s pre-pass and the registry’s :args map, match the BFS walker on slot-id) was evaluated in full and found infeasible-for-payoff — see ADR-slot-id-keyed-type-checker. Do not re-open it; the α’ path delivers the same correctness with smaller surface change.

Phase #170 v2 — REJECTED (composed-guard narrowing)

Phase #170 v1 (direct :some?/:nil? guards on :if/:cond test refs) landed. v2 was to extend recognition to composed guards (:_X-blank? wrapping :str-blank? + :get, :and/:or decomposition, narrowing through :get of record fields).

Driving question: does v2 make the system architecturally better OR the user’s life easier?

v1 was worth doing because :if :test (:some? :_x) :then :_y is trivially readable — the guard, target, and branch are right there in the parent shape. Composed guards (:str-blank?-shims, :and/:or decompositions, :get-through-record narrowing) don’t have that property.

Net: no architectural win, no UX win, mid-size implementation cost, real risk of regressions. Don’t do it.

Phase γ — REJECTED (row polymorphism)

Slot types parameterised over row variables — a record type [:record {fields} 'rho] where 'rho is unbound row content that can be unified per call-site. The textbook answer to “per-use-site narrowing without losing the structural abstraction.”

Why not pursued:

Revisit only if either (a) registry size becomes a real performance problem, OR (b) a queued feature genuinely needs open-record polymorphism.

Outcome

Phase Status
A — typed _X-parsed returns + typevar binding + narrowing-assertion LANDED
β — caller-context propagation ATTEMPTED + REVERTED — per-name BFS conflated flows; superseded by α’
α’ — per-use-site anon naming + rename-leaf narrowing + effective-ref-return merge-flip LANDED — closed the original 10
E — hard-gate sweep + allowlist + tests LANDED — bidirectional gate
C — :type rename localisation not needed — α’ supersedes the use case
D — editor surface LANDED implicitly — α’ writes narrowed types into the canonical :return field; editor reads via /api/types without UI change
#170 v1 — direct-predicate :if/:cond narrowing LANDED — see TYPES.md § Control-flow narrowing
#170 v2 — composed-guard narrowing REJECTED — see above
γ — row polymorphism REJECTED — see above

Final state: sweep at zero, allowlist empty, Phase E gate armed. No known type-system bugs in production.

2026-09-13 — two API-layer defects, closed (not architecture)

Found while making tutorial lesson 09 wire a callback of the reader’s own into map: the picker’s Compatible list for map’s :func ([:fn {:item a} b]) held nothing but never-returning fns, and an edge-label rename of an arg to item never made a fn eligible. Both looked like checker limits. Neither was — fn-subtype? already treats a slot-side type variable as “bound at the call site” — and neither re-opens β/γ:

Neither changes subtype?, unify or the registry’s shape; the inherited-rename ADR contract (“the fn-def :args key is a public name”) now also holds for renames made in the editor.

2026-10-19 — execution proofs and view/value boundaries

Callable contracts now carry execution support independently of effects: [:fn args return effects execution]. The checker derives support from trusted native capabilities and effective bindings. Legacy shapes keep unknown support; a value annotation, gradual hole or declared generic execution variable cannot turn unknown or server-only code into a browser proof. Local HOF specialization retains correlations without changing shared slot identities or sibling types. This extends the existing call-local approach; the historical row-polymorphism decision above remains unchanged.

UI representation has its own :ui-view marker. Precise data sinks reject a view, broad data sinks report a hint, and explicit web.html/encode-view removes only the view representation label in data positions. Secrecy remains in force. Value-producing operations may compute ordinary data; passthrough may not erase a representation label merely because a child call recomputes its result.

Runtime boundary validation reuses the same type definition through graphden.types.validator. Its builder and static ensure-type rule share a canonical type, including variants. Expansion is bounded before alias/union normalization so recursive definitions fail explicitly. The initial supported subset is data types and safe declarative refinements, not arbitrary graph predicates or callable portability validation. Failure paths omit rejected values and dynamic map keys. See TYPES.md for the supported subset.