Abs — the type system
Abs is short for abstract value (abstract interpretation). Nudo’s goal is to show variables close to runtime inside the source. Abs is the representation that makes that possible: not a broad type name, but a symbolic set of possible JavaScript values with identity and constraints.
An Abs may hold a single concrete value (42, "hello") or all values that share characteristics (“any number”, “the literal 1”).
Abs (shape × term × pred × conf) is the only type system: a computable value whose constraints participate in algebra (x > 0 ⇒ x + 1 > 1). Analysis, inlay display, signatures, and projections (.d.ts / zod / guards) all consume Abs directly; there is no separate IR. Production analysis is Abs-native — nothing reads a projection back.
The Four Components
- shape — the extensional carrier: what the value looks like. Kinds:
prim(with alitterm for exact values),obj,arr,tuple,fn,eff(promise<…>/generator<…>),brand(nominal instances),sum(unions),never,any(unconstrained),unknown(inference failed — see any vs unknown). - term — abstract value identity:
lit(concrete),var(symbolic α likeA1), orapp(an application like(x + 2)). - pred — constraints relative to the term:
(x + 2) > 3. - conf — how exact the abstraction is. Grades (strong → weak):
exact→path→widened→mock→partial→opaque(join keeps the weaker side).
| conf | Meaning |
|---|---|
exact | Literal / precisely evaluable (25 #exact) |
path | Depends on path constraints / symbolic term ((x+1) · > 1 #path) |
widened | Structure lost; conservative extensional domain (loop join, budget) |
mock | Declared mock / harvest face, not observed evaluation |
partial | Incomplete set contents |
opaque | No usable content (budget truncation, eval failure) |
Only exact / path project into dts / schema details.
Abs anatomy — four components, one example (x + 1 / number / > 1 / path).
See the core API for constructors (num(), strLit(…), obj({…}), …) and the core functions (leqAbs, formatAbs, checkSource, …).
Literals
A prim shape with a lit term represents exactly one concrete value — what the engine produces from a literal in code or a concrete @nudo:case argument:
25 #exact // the number 25, precisely
"localhost" #exact // one specific string
Primitives
A prim shape without a lit term is the whole domain — the value is known to be of that type but not a specific value:
number // any number
string // any string
boolean // true or false
Objects, Arrays, Tuples
obj carries known slots ({ value, optional? } per key), arr one element type, tuple a fixed-length per-element list:
{ host: "localhost", port: 8080, debug: false }
[2, 4, 6] // tuple of literals — arr when elements are abstract
number[] // abstract element
Functions and Promises
fn carries parameter names (or a paramTypes/returnType signature); eff wraps async effects and renders lowercase:
load: (id) => ? // function value, result not yet precise
promise<{ id: 7, name: "u7" }> // async result
Unions
sum is the union of member Abs — a value that could be any of its members:
25 | 9 // two exact numbers (from two call sites)
number | string // heterogeneous union
never is the empty set (unreachable).
any vs unknown
These are not the same product concept and must never be collapsed in docs or CLI output:
any | unknown | |
|---|---|---|
| Meaning | Unconstrained: the union of JS values; developer refines | Inference failed / engine has no information; Nudo must fix |
| Source | Unannotated entry params, explicit any(), refine parse fallback | Evaluation failure, unmodeled native, truncation, leak, opaque |
| Operations | Real JS union semantics; not “analysis failed” | Must not pretend to be a legal contract; trigger engine-debt diagnostics |
| Narrowing | Conditionals can narrow (typeof / === / Array.isArray / switch / truthiness / discriminant) | User conditions cannot “legalize” it; fix inference or add env/mock/refine |
| Display | any (optionally with a type-var like A1) | unknown + conf annotation |
| Product story | “No written contract ⇒ default constraint is any + JS runtime effects” | “Nudo hit a case it cannot handle” |
Rule (Nudo display faces): unconstrained entry parameters display as any, never as unknown. CLI/check signatures follow this contract. This rule scopes Nudo's own display / CLI output only — it does not govern TypeScript declaration output.
TS projection (2026-11-06 ruling): Nudo's any means "any JS value, unconstrained", which corresponds to TypeScript's unknown (the top type; consumers must narrow), not TypeScript's any (which disables type checking). .d.ts output — like the zod / standard / guard validators — therefore projects both Nudo any and Nudo unknown as TS unknown. An unconstrained return in a .d.ts legitimately raises TS2571 until narrowed: that is a correct safety signal, not a false positive (see Bug 544).
Type Expressions in Directives
@nudo:case / @nudo:mock / @nudo:contract arguments are written in the constraint-expression grammar — the same builders as *.nudo.js templates:
| Expression | Meaning | Example |
|---|---|---|
number() / string() / boolean() | primitive domain | @nudo:case "symbolic" (number()) |
lit(v) | literal domain | lit(42) / lit("ada") / lit(true) |
union(…) | union of members | union(lit(1), lit(2)) |
shape({ … }) | object shape (fields recursive) | shape({ id: number().gt(0) }) |
array(…) | array element constraint | array(number()) |
any() | unconstrained domain (same as an unannotated entry param) | any() |
fn({ … }, …) | function relation | fn({ x: number().gt(0) }, number()) |
| builders | .gt/.ge/.lt/.le/.int/.min/.max/.length/.shift… | number().gt(0).int() |
| bare literals | parsed directly | 42, "abc", true, [1, 2], null, undefined, unknown, never |
Directive type expressions use the constraint builders above plus concrete literals. Inside @nudo:mock bodies write plain JavaScript values and closures — not builder calls as return payloads.
/**
* @nudo:case "concrete" (5, 3)
* @nudo:case "symbolic" (number(), number())
* @nudo:case "mixed" (lit(0), string())
*/
function combine(a, b) {
return a + b;
}
Design Principles
Nudo's type value system follows four core principles that govern how operations and inference behave.
1. Literal Preservation
When all inputs are literals, the output is also a literal. The engine computes the concrete result.
combine(5, 3) // → 8 #exact, not number
"ab" + "c" // → "abc" #exact
This keeps inferred types precise when enough information is available.
2. Widening on Abstraction
When any input is abstract (non-literal), the result widens to the appropriate domain — but Nudo preserves as much structure as possible.
1 + number // → number #path (displayed as the domain)
"xy" + string // → string #path (displayed as the domain)
string + string // → string (no structure to preserve)
When string concatenation involves at least one literal, Nudo tracks a template string internally — the known prefix/suffix is preserved, which is what makes ("user-" + x).startsWith("user-") fold to true #exact even for a symbolic x.
3. Lazy Union Distribution
Unions propagate as-is. An operation over a symbolic value stays symbolic — it is not eagerly expanded into a cross product of members. This avoids combinatorial explosion and preserves correlation:
function selfAdd(a) {
return a + a; // intension: (A1 + A1) — one symbolic variable, not A1 + A1'
}
selfAdd(1); // → 2 #exact (per call site)
selfAdd(2); // → 4 #exact
// Observed: 2 | 4 — correlation kept, never 1+1 | 1+2 | 2+1 | 2+2
With abstract arguments the result widens to the domain the algebra determines (2 + x with x: number | string → number | string; selfAdd(number) → number #widened) — member-wise expansion only happens when an operator or method must distinguish members.
4. Guard Narrowing (per call site)
Type guards fork branches only when the guard test is definitely true or false for the concrete argument of a call site. Each call@L… case is evaluated with that call's exact argument, so the matching branch runs and the other is eliminated:
function len(x) {
if (typeof x === "string") return x.length;
return -1;
}
len("abc"); // → 3 (string call takes the branch)
len(5); // → -1 (number call falls through)
With abstract arguments (number(), union(...)), the condition cannot be decided — both branches run with the same value and their results join. There is no intersection/subtraction of abstract unions. Verified patterns and current limits: Control Flow Narrowing.
Next
- Abstract Interpretation — how Abs values are computed
- Control Flow Narrowing — branch elimination on concrete call sites
- Directives — type expressions in
@nudo:annotations - Concept layers — Observation / Contracts / Advanced