Repository navigation
Core NLS Semantics (Target-Neutral IR) #88
Description
Description
Define the target-neutral semantic core that all emitters must preserve. This is the contract between meaning and implementation.
Currently NLS surface syntax maps directly to Python. For multi-target compilation to work, we need an intermediate representation that captures semantics without committing to any target language's idioms.
Spec Document: core-nls-semantics-spec.md
Scope
Expressions
- Literals (numbers, strings, booleans, none)
- Arithmetic and comparison operators
- Function calls
- Field access
- Collection literals (list, dict)
Statements
- Let-bindings (immutable by default)
- Conditionals (if/else as expressions)
- Pattern matching (future)
- Early return / guard failure
Type System
- Primitives:
number,string,boolean,none - Compound:
list of T,dict of K to V,optional T - User-defined:
@typestructs with fields - Type aliases
Error Model
- Guards produce typed errors (not bare exceptions)
- Choose: exceptions vs Result/Option — document which and why
Semantic Invariants
- What MUST behave identically across all targets
- What MAY differ (performance, idiom, runtime representation)
Acceptance Criteria
-
docs/core-semantics.mdspecifies all of the above - Each construct has a precise meaning independent of target
- Python emitter documented as "Core NLS → Python" mapping
- Test suite validates Core semantics (not just Python output)
Why This Matters
- Unblocks TypeScript emitter (feat: TypeScript target #20)
- Makes package registry meaningful — packages are semantic contracts
- Enables future targets (Rust, Go) without redesigning the language
- Makes NLS a platform, not a transpiler
Related Issues
- Blocks feat: TypeScript target #20 (TypeScript emitter)
- Blocks feat: ANLU package registry #27 (Package registry)
Activity
docs: add core NLS semantics specification
feat(tests): add semantic test suite for Core NLS semantics
feat(tests): add semantic test suite for Core NLS semantics