Skip to main content

Introduction

Nudo exists for one outcome: see variables close to how they look at runtime, right in the source.

When reading code, one usually sees only broad type names (number, string), often with another layer of annotations. Nudo executes JavaScript on abstract values so each variable carries what it will actually compute — literals, shapes, constraints — surfaced next to the source as signatures, IDE inlays, and call-site evidence.

engine-verifiedRun in Playground
// calc.js
export function scale(x) {
return x + 1;
}

scale(5);
engine-verifiedRun in Playground
// calc.nudo.js — explicit contract (obligation)
import { number, fn } from "@nudojs/core";
export const scale = fn({ x: number().gt(0) }, number());

In the IDE, intermediates show a runtime-adjacent form per line, not a single type name:

scale(x) x: number · x > 0 // from contract or call sites
return x + 1 term (x + 1) · > 1 // derivation, not "number"
scale(5) => 6 #exact // call site is runtime truth
scale(0) ⊭ x > 0 // actual 0 · expected x > 0

nudo check provides the same observation face on the command line (signatures print even on success). When obligations are needed, declare them as sidecar contracts (*.nudo.js / @nudo:contract); violations report values and predicates, not type names. For per-call-site scenario debugging, nudo test is a separate case reporter, not the gate.

signatures
scale(x: number) => number

issues
[ERROR L7 scale] scale[x]: argument ⊭ precondition (nudo:constraint-violated)
actual: 0 #exact
expected: x > 0

Open in the Playground.

Product face: Observation (Day 0) = nudo check (signatures and diagnostics). Contracts (Day 1) = nudo contract + nudo check (explicit contracts). Ecosystem = nudo export (one-way Abs projections to .d.ts / schemas). Observation lives in check signatures and IDE hover — there is no separate observation verb. nudo test is an optional debug case reporter.

How this is achieved: execution, not annotations​

The goal is runtime-adjacent variables in the source. The method is executing code on abstract values (Abs):

  1. Execution produces facts. The engine evaluates on symbolic values and records each intermediate’s shape, value identity, and constraints — not inferred from annotations.
  2. Call sites are evidence. scale(5) => 6 comes from an actual call path, not a comment.
  3. Constraints participate in algebra. x ≥ 0 implies (x + 1) ≥ 1 (strict bounds are ulp-adjusted to stay sound under IEEE rounding), so inlays show relations that can be reasoned about, not only type names.
  4. Annotations are never required. Sources stay plain .js; contracts are JS modules.

Deeper: Abstract interpretation · Abs.

How to use these docs​

You areStart here
JS engineer evaluating a type/check gateMental model → Quick Start → nudo check
TypeScript userNudo vs TypeScript → Migrate from TS
Existing JS packageMigrating existing JS → Contracts
Automated workflow / platformRecipes → Diagnostics → Error faces
AI coding agent / toolingAgents → Agent integration → API · agent

Non-goals: Nudo is not a TypeScript compiler; it does not invent required slots from body AST scans; @nudo:case is debug-only and never the contract product. See Limits.

Observation vs Contracts​

LayerWhat you writeWhat you get
Observation (Day 0)Plain JS + call sitescheck signatures and L2 entry may-throw diagnostics
Contracts (Day 1)*.nudo.js / @nudo:contractL1 obligations (actual ⊭ expected)
Ecosystemnothing extraexport projections: dts / guard / schema
AdvancedAbs algebra, envs, mocksString/number algebra, HOFs, module graphs

Observation → Contracts → Ecosystem

Obligation increases; any is unconstrained, unknown is inference failure.

Relation to declared types​

TypeScriptNudo
Variable presentationDeclared type namesRuntime-adjacent values / shapes / constraints
ContractsType language + assignabilitySidecar builders + L2 entry throws
PrecisionOften widens to string / numberCan keep literals, template structure, loop sums
Source of truthSource annotationsAbs from execution; projections are lossy and one-way

Comparison: Nudo vs TypeScript. Limits: what Nudo does not claim.

Next​