Skip to main content

Mental model

This page answers only: how Nudo sees and computes your JavaScript. The command surface lives in the CLI guide; migrating off tsc is linked at the end.

The one-sentence model​

Nudo executes your JavaScript on abstract values so variables carry runtime-adjacent values, shapes, and constraints — and reports what the code actually computes — then validates the contracts you accept. Sources stay plain .js.

You writeNudo does
Plain .js + call sitesExecutes and observes: signatures, intermediates, call-site truth
Optional *.nudo.js / @nudo:contractValidates obligations (actual ⊭ expected)
Nothing extraStill diagnoses export may-throw (L2)

There is no second type language. Contracts are ordinary JS modules with builders like number().gt(0).

Two layers: observation and contracts​

LayerWhat you readSource
Observationruntime-adjacent values / shapes / constraintsexecution facts (call sites, paths)
Contractsconditions that must hold; violations give actual / expecteddeclarations you accept (sidecar / @nudo:contract)

Observation is not commentary; contracts are not type annotations.

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

scale(5);
scale(0); // violates the sidecar precondition below
engine-verifiedRun in Playground
import { number, fn } from "@nudojs/core";
export const scale = fn({ x: number().gt(0) }, number());
signatures
scale(x: number) => number

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

The evidence from scale(5) keeps the entry from staying bare any; the contract turns x > 0 into a checkable obligation. if is not a contract — obligations come only from declarations you accept.

Why variables look runtime-adjacent​

Because they are computable Abs (shape × term × pred × conf), not type names:

ComponentWhat you see on the product faceMeaning
shapeshape in the signatureprim / obj / arr / fn / sum / …
termvalue identitylit (42), var (symbolic A1), app (x+1)
predthe expected: lineconstraints (x > 0); participate in algebra (x>0 ⇒ x+1>1)
conf#exact / #pathabstraction precision

Call sites are evidence: more real calls → signatures closer to runtime. nudo test shows per-call witnesses; @nudo:case is debug-only and never creates contract obligations.

Deeper: Abs · Abstract interpretation · nudo check --abs.

Four model rules​

  1. Call sites are evidence. More real calls → signatures closer to runtime.
  2. any ≠ unknown. any = unconstrained entry (you may refine it). unknown = inference failed (engine debt).
  3. Contracts are obligations, not annotations. Constraints participate in algebra — they are not intent written in comments.
  4. Projections are not the source of truth. .d.ts / schemas are lossy views of Abs; Abs from execution is the truth.

What you can ignore for now​

Next​