Repository navigation
feat(ir): introduce a minimal target-neutral expression and control IR with source spans #194
Description
Audited on master at 5630d74ec9cd912d4e2f325349f1943cbc15bcc6. This is a scoped implementation item under #147, based on the typed control/dataflow/effect audit. Proposed syntax below is illustrative unless explicitly marked as a current reproducer.
Problem and current evidence
The existing semantic document from #88 is useful, but there is no checked IR between the surface AST and emitters. nlsc/pipeline.py:132–181 validates contract fields/dependency declarations; nlsc/emitter.py:635–696 and nlsc/emitter_typescript.py:47–121 independently reinterpret expression strings.
Two reproduced failures show why this boundary matters:
[identity](max(1, 2)) -> resulttruncates a closing parenthesis in Python's ANLU-call regex and fails output validation.RETURNS: "True and False"produces the unchanged string in Python but"true && false"in TypeScript. The corrupted TypeScript passestsc --strict --noEmit.
Minimum deliverable
Create a small IR schema and deterministic lowering pass, not the entire proposed universal ontology:
- Values: literal, local reference, field/index access, record/list construction, unary/binary operation, and resolved-call representation.
- Statements/regions: bind, discarded expression, return, guard/raise, sequence, branch, and an explicit loop-region representation.
- Contracts: target-neutral type references and slots for effects/failures/state contracts populated by subsequent passes.
- Identity: stable node IDs and source spans for both the operation and its contributing syntax.
Implementation hints
- Add
nlsc/ir.pyandnlsc/lowering.py; retainschema.pyas the surface AST during migration. - Distinguish unchecked lowering output from a checked module that is eligible for emission. Do not let an unfilled type/effect field silently mean a proof of validity or purity.
- Parse expressions once with a real token/precedence parser or a documented deterministic subset adapter. Fully consume the input, support nested arguments, and preserve literal tokens exactly.
- Normalize localized keywords only outside literals. Resolve ANLU syntax structurally rather than replacing bracketed substrings.
- Keep human prose as attached narrative metadata. The same source should produce identical canonical IR regardless of target.
- Give both parser paths one lowering contract and retain the established regex fallback; do not reintroduce dual semantic implementations.
Acceptance criteria
- A canonical serialization and small IR schema document exist, with a deliberate extension/version policy.
- Nested calls and quoted operator/keyword text lower correctly and consume all tokens.
- Unsupported executable constructs fail with a precise diagnostic rather than becoming raw target source or placeholders.
- The same source produces the same target-neutral IR for Python/TypeScript.
- Source spans survive lowering and identify the original LOGIC step in diagnostics.
- Backend-independent tests inspect meaning, evaluation order, and serialization.
Scope: the IR boundary/schema and expression lowering. Separate items implement type checking, structured control checks, effect/failure analysis, and emitter migration. Relates to #143/#144/#147; it does not reopen or duplicate #88's documentation work.
Implementation ordering
Can begin immediately; integrate with the checked IR work under #147. Add the regression fixtures before implementation.
Activity