Repository navigation
research(backends): evaluate Osprey as an optional checked-IR target #209
Description
Question and scope
Could Osprey be an optional target for NLS's checked IR without changing NLS language semantics?
Osprey's shared frontend, operation checking, and handlers are useful references independently of this decision. This issue is a feasibility study with a go/no-go outcome, not a commitment to replace Python/TypeScript, adopt Osprey syntax, or implement a production backend.
Deliverables
- Write a version-pinned semantic compatibility matrix. For each item, record direct mapping, adapter required, or blocked, with source evidence and a small falsifiable example:
- Numeric representation, division/failure behavior, truthiness, structural equality, and strings.
- Structural records, list/reference mutation, field constraints, and NLS construction invariants.
- Calls, argument evaluation order, recursion, and supported callable/closure forms.
- NLS typed exceptions and error payloads versus Osprey's failure representations. Do not silently turn an NLS exception into a successful Result value.
- Required operations, observable resource effects, direct handlers, and optional single-shot resumption (feat(effects): add typed lexical handlers and injectable operation implementations #207/feat(control): enforce affine single-shot handler resumption #208).
- Foreign/literal implementations, exported entry points, resource cleanup, and target-specific runtime capabilities.
- Build a disposable emitter spike for the smallest agreed subset of shared checked NLS IR. Compare at least arithmetic, an ordinary ANLU call, a total branch, a record/list case, and a typed failure with the Python/TypeScript conformance oracle. Add a direct-handler fixture only when feat(effects): add typed lexical handlers and injectable operation implementations #207's contract is available.
- Capture actual compiler versions, commands, outputs/failures, toolchain requirements, and test results. Unsupported cases should be recorded as blocked rather than erased or replaced with placeholders.
- Produce an architecture decision stating whether to proceed, the exact supported subset, required runtime adapters, packaging/distribution and license obligations, and the conditions for revisiting a no-go. Open an implementation issue only if the evidence supports it.
Implementation hints
- Put any prototype behind an experimental capability boundary. NLS's semantics and IR remain authoritative; the backend must not parse LOGIC prose or change frontend meaning to suit Osprey.
- Reuse feat(backends): consume checked IR and enforce executable Python/TypeScript semantic conformance #202's normalized value/failure/event-trace harness. Compare equivalent typing contracts as well as observed output for one input.
- Test Osprey compilation/execution at a pinned release or commit. Do not infer support from the website's summary or from a grammar accepting a construct.
- Separate the host language target from the downstream platform: Osprey native, WASM, iOS, and Android do not necessarily accept the same control/runtime capabilities.
- Assess synchronous direct handlers independently from resumable handlers. A direct-handler prototype need not wait for full resumption.
- Do not make this spike, a new LLVM dependency, or an Osprey release a gate for the existing Python/TypeScript milestone.
Acceptance criteria
- Every matrix row has primary-source evidence and an executable probe or an explicit reason it cannot yet be probed.
- The prototype preserves the supported cases' values, normalized failures, and ordered effects; semantic differences are listed rather than hidden.
- Unsupported capabilities fail before misleading output, and the spike does not claim production backend support.
- A reproducible toolchain/setup description and a concrete go/no-go decision are committed for review.
- Any proposed production implementation is separately scoped with its own dependency and conformance requirements.
Ordering and references
Reference review can start now. The executable spike follows the necessary checked semantics in #195/#196/#198 and uses #202's harness; handler cases follow #207. #194 is complete. Existing Rust work remains in #24.
Current reference snapshot: 8792de9f6d159922141f9d191e4bc5d256fbb971.
- Shared frontend/canonical AST contract.
- Type implementation and effect contract.
- Target capability checks and their tests.
- Multiplicity implementation and unsupported forms.
Source inspection motivates this study; no Osprey backend or successful runtime comparison is claimed by this issue.
Activity
Merge pull request #244 from Mnehmos/docs/209-osprey-feasibility
Mnehmos commentedon Sep 12, 2026
Closing on the documented no-go, which this issue defines as a valid research outcome ("a feasibility study with a go/no-go decision… Open an implementation issue only if the evidence supports it").
What landed in
docs/design/issue-209-osprey-feasibility.md:8792de9f), one row per NLS semantic item with a direct / adapter / blocked verdict and a falsifiable probe expectation;tests/semanticrunner interface (deliverable 3 structured ahead of execution);Why no-go now: the executable spike the issue orders "follows the necessary checked semantics in #195/#196/#198" (#200/#207 also feed rows), and a third backend would add conformance cost for guarantees NLS's own checked pipeline plus the #202 harness already delivers. Revisit when those land and a concrete consumer needs Osprey emission; the matrix's probe rows are the slice-1 checklist.