WIP-0005: Wheeler source language profile

Summary

Wheeler is a class-based language with familiar syntax and explicit rules for reversible and quantum work. Classes, fields, methods, calls, assignments, assertions, and blocks look Java-like. Wheeler does not claim Java source or binary compatibility.

The language adds computation-domain class modifiers, rev and coherent rev methods, unitary methods, affine qreg fields, reverse, preparation, measurement, and target-aware execution.

Implementation advances through small profiles that work end to end. The parser does not accept broad Java syntax and store unsupported placeholder nodes. Unsupported Java or quantum features produce clear source errors. Each accepted declaration lowers to the same Wheeler typed IR. WIP-0001 covers classical inverse, log, and barrier behavior. WIP-0002 covers affine quantum resources and adjoints. Measurement and host work stay visible as effect edges.

When a new parser path replaces an old one, the compiler removes the old path. Familiar syntax must not hide Java semantics underneath.

Motivation

Wheeler should feel like a practical next step for Java programmers working with reversible and quantum systems. Its first executable compiler used a temporary line-based declaration format to test bytecode. That format helped validate the VM, but it did not meet the language's goals or match the examples.

Copying all of Java's grammar before Wheeler can implement the meaning would repeat the old placeholder compiler. Wheeler instead needs a focused Java-shaped subset. Every accepted construct must have parsing, diagnostics, lowering, verification, execution, and example coverage.

That subset must grow toward the WIP-0007 bootstrap profile. The compiler itself is a Wheeler acceptance program, not a permanent Java-based service.

Use cases

Classical reversible class

classical class Counter {
  state long count = 0;

  rev void increment() {
    count += 1;
  }

  entry void main() {
    increment();
    increment();
    assert(count == 2);
    reverse {
      increment();
      increment();
    }

    assert(count == 0);
  }
}

Quantum class

quantum class Bell {
  state long measured = 0;
  qreg q = new qreg(2);

  unitary void prepareBell() {
    H(q[0]);
    CNOT(q[0], q[1]);
  }

  entry void main() {
    prepare(q, 0);
    prepareBell();
    measured = measure(q);
  }
}

Coherent lift

A coherent rev method is callable normally from classical code and may be referenced from a quantum register with q.apply(method). The compiler verifies that the body belongs to the exact finite coherent subset before producing a lifted operation.

Goals

• Make valid Wheeler source visually and structurally familiar to Java programmers.
• Preserve explicit classical, quantum, and hybrid class intent.
• Provide Java-shaped fields, methods, calls, assignments, assertions, and reverse blocks.
• Keep preparation and measurement explicit and readable.
• Give every accepted construct complete parser-to-runtime coverage.
• Produce line-numbered diagnostics for unsupported syntax and semantic violations.
• Migrate every checked-in example to the accepted profile.
• Grow typed locals, control flow, aggregate values, modules, and effects far enough to express the Wheeler compiler.
• Avoid permanent compatibility with the temporary declaration syntax or Java stage-0 internals.

Non-goals

• Accept all Java syntax, libraries, reflection, exceptions, threads, generics, or object allocation immediately.
• Treat Java bytecode as Wheeler bytecode.
• Hide measurement behind an ordinary cast or field read.
• Infer coherent eligibility from provider behavior.
• Preserve syntax that was never part of a released Wheeler version.

Terms and semantic model

classical class, quantum class, and hybrid class select the program domain and available declarations. They do not erase WIP-0002 effects.

A state long field is classical mutable state in the first bytecode format. A qreg field is an affine logical quantum resource. Ordinary Java-like local variables, parameters, object fields, and richer exact types are added only with bytecode and ownership support.

A rev method has a compiler-validated inverse body. A coherent rev method also satisfies WIP-0002 coherent eligibility. A unitary method lowers to quantum region IR and receives a generated adjoint. WIP-0031 carries those distinctions into callable values and effect-polymorphic APIs. It does not merge them into a universal function type.

WIP-0041 owns value-return semantics for reversible methods. void has no inhabitant, Done is the one-value generic completion type, and Slot<T> is explicit presence. A non-void reversible method elaborates to a caller-owned result slot. The surface may retain ordinary return expression; syntax, but no null-like literal or hidden history channel appears.

reverse method(); invokes one method inverse. A reverse { ... } block inverses supported calls in reverse lexical order. It is language-level inverse execution, not VM history rewind.

Ownership and boundaries

The source parser owns syntax and source locations. Semantic lowerers own name resolution, domain checking, inverse generation, coherent eligibility, quantum resource validation, and diagnostics. WIP-0001 and WIP-0002 remain authoritative for execution semantics.

Tools show source diagnostics and disassembly without exposing parser internals. Examples are executable acceptance programs, not speculative syntax catalogs.

Design

First complete profile

The first profile supports:

• one top-level computation-domain class.
• state long and qreg fields.
• signed long and boolean parameters and returns for ordinary classical methods. Zero-argument void entry, reversible, coherent, and unitary methods.
• rev, coherent rev, unitary, and entry methods.
• +=, -=, ^=, direct logged assignment, method calls, assertions, checkpoint, and commit.
• classical values and storage, including:
• signed long and boolean values.
• immutable nominal records and closed tagged variants with exhaustive match.
• fixed immutable arrays with checked indexing and nonescaping immutable slices.
• function-local affine region, words, bytes, utf8, and longmap storage.
• nonescaping immutable utf8 parameters and exclusive region, words, bytes, and longmap parameters.
• bounded allocation, checked mutation, strict UTF-8 validation and counting, and explicit drop.
• typed expressions that evaluate left to right, plus static calls.
• return, if/else, early return, bounded while, counted for, and break/continue in ordinary classical methods.
• direct inverse calls, reverse blocks, and finite inverse(function), adjoint(circuit), equivalent(left, right), and steps(function, bound) theorem declarations.
• H, X, Z, phase, controlled phase, CNOT, CZ, and swap gates.
• prepare, full-register computational-basis measurement, unitary call/adjoint, and coherent method reference.
• comments and conventional semicolons/indentation.

Each later profile must update this WIP or a successor with syntax, semantics, migration, and tests. Feature order is driven by executable examples and the WIP-0007 self-hosting compiler, not by copying the Java grammar.

Parsing strategy

The initial parser is a small source-located parser for the accepted profile, not a permissive Java parser followed by silent dropping of unsupported nodes. It rejects multiple declarations per line and unsupported nested control flow with an actionable diagnostic. When expressions and statements outgrow it, a token and grammar implementation can take its place without changing accepted source semantics.

Naming and dispatch

Names resolve statically within the class. An entry call to a unitary method becomes a quantum-region application. A call to a classical method becomes a classical invocation. reverse selects the corresponding inverse or adjoint. q.apply(method) selects coherent lifting and requires a coherent rev target.

Java relationship

Wheeler adopts Java familiarity, not Java source or binary compatibility. Constructs whose Java meaning conflicts with reversibility, affine ownership, or bounded execution require Wheeler-specific diagnostics and contracts.

Reversibility and history

Assignments lower according to WIP-0001 reversibility classes. +=, -=, and ^= have generated inverses in eligible methods. Direct assignment is logged and is rejected from methods requiring a generated inverse.

Reverse blocks only accept operations with a declared language-level inverse. External effects, measurement, and commit cannot hide in a reverse block.

Concurrency and determinism

The implemented profile has no Java threads, monitors, volatile fields, or asynchronous task syntax.

WIP-0039 owns future Task, TaskScope, spawn, join, and shared-atomic semantics. WIP-0040 owns source inverse for eligible task scopes. WIP-0032 retains sole ownership of IoScope, external requests, direct await, logical asynchrony, and required physical concurrency.

The language does not reuse Java Thread, synchronized, monitor, or volatile semantics. Final spelling lands only with parser, type, effect, verifier, VM, Tree-sitter, formatter, test, and reference coverage.

Quantum and proof implications

Quantum register references are affine semantic values even when field syntax resembles Java. Gate calls don't expose provider qubit objects. Measurement produces classical state through an explicit operation.

The initial WIP-0011 slice resolves generated-inverse, generated-adjoint, finite circuit-equivalence, and straight-line step-bound theorem declarations and emits canonical certificates checked by the finite kernel. Contracts, general propositions and terms, structured proof blocks, experiments, circuit/resource rules, and package proof APIs remain.

Bytecode, persistence, and compatibility

Source syntax does not appear in canonical bytecode except through names and optional debug maps. Temporary pre-WIP source files have no compatibility guarantee and are migrated in place. .wbc compatibility remains governed by WIP-0001 and WIP-0002.

Safety, limits, and failures

The parser bounds source bytes, lines, declarations, methods, statements, registers, gates, and nesting. Diagnostics include line numbers and never produce partial artifacts. Unsupported syntax fails closed.

Migration and deletion

1. Replace the temporary wheeler 1 declaration syntax with Wheeler classes.
2. Migrate Counter, QFT, and the coherent-oracle fixture first.
3. Add complete constructs only as the remaining examples require them.
4. Delete temporary parser branches and documentation in the same changes.
5. Keep all examples compiling in CI after each profile expansion.

Progress

• [x] Wheeler class, field, and method declarations parse.
• [x] Classical state and compile-time signed or Boolean constants lower to WIP-0001 major version 1 typed frames. The same path handles records, variants, finite enums, arrays, and nonescaping slices. It also handles affine region storage, signed maps, bounded control flow, exhaustive selection, checked indexing, and reverse blocks.
• [x] Unitary methods and quantum entry operations lower to WIP-0002.
• [x] Coherent method references execute on classical and simulated quantum data.
• [x] Counter, QFT, and coherent-oracle examples use only the Wheeler source profile.
• [x] Temporary source syntax and documentation are deleted.
• [ ] Deterministic classical modules enforce exact declarations, sorted imports, public visibility, dependency-first linking, closed DAG inputs, manifest-bound source sets, and locked direct-package visibility. Public immutable records/closed variants link, importers exhaustively match variants, and fixed signed/Boolean array fields cross module boundaries. WIP-0028 owns cross-function ownership and region loans, WIP-0029 owns constrained generic values, WIP-0030 owns coherent class evidence, and WIP-0031 owns typed callable/effect polymorphism. Exported state/proofs/circuits, package aliases/re-export, and complete qualified nominal APIs remain.

Testing and acceptance

• [x] Parser and executable-example tests cover every accepted declaration and statement.
• [x] Negative tests cover unsupported Java syntax, malformed blocks, unresolved names, illegal inverse calls, invalid module visibility/graphs, and invalid quantum references.
• [x] Source diagnostics identify stable line numbers and lexical columns.
• [x] Counter compiles and executes forward and inverse.
• [x] QFT followed by its generated adjoint restores the input state.
• [x] One coherent rev method gives matching classical and quantum basis behavior.
• [x] Every checked-in .w file compiles and executes in CI.
• [x] Current language reference contains no temporary declaration syntax.

Alternatives

Keep the line-oriented DSL

Rejected. It is useful as an internal assembly shape but does not provide the intended class-based ergonomics.

Restore the broad ANTLR grammar immediately

Rejected. The removed grammar accepted far more syntax than the AST, verifier, or runtime could execute. Grammar breadth follows semantic implementation.

Use Java annotations only

Rejected. Reversibility, affine quantum resources, reverse blocks, and measurement are core language semantics. They need direct, readable syntax.

Open questions

• Which exact local-variable, parameter, and aggregate profile is the smallest complete WIP-0007 bootstrap subset (owner: language and compiler maintainers. Decision point: before the BinaryTree migration)?
• Should coherent invocation eventually use ordinary overload resolution on coherent value types, method references, or both (owner: language and quantum maintainers. Decision point: before parameters are added)?

References

• WIP-0039
• WIP-0040

• WIP-0001
• WIP-0002
• WIP-0007
• WIP-0010
• WIP-0011
• WIP-0012
• WIP-0017
• WIP-0028
• WIP-0029
• WIP-0030
• WIP-0031
• WIP-0032
• Language profile