EB Language Specification
=========================

A domain-specific language for Monte Carlo simulation and stochastic
modeling. One language expresses periodic, event, and agent models, and
the compiler reduces all three to a single event-segment kernel.

This specification is self-contained. It supersedes the specification in
``~/proj/eichenbank-claude/spec``, which is frozen as reference — see
:doc:`eb-provenance`.


What is normative
-----------------

===========================  =========================================
``eb.ebnf``                  Grammar, keyword list, intrinsic list.
                             The source of truth for syntax.
:doc:`eb-semantics`          The numbered rules. The source of truth
                             for behavior.
:doc:`eb-constraints`        Normative, but derived: it restates the
                             rules per execution unit and adds none.
:doc:`eb-errors`             Normative message text. The catalog is
                             generated from ``tests/suite``.
:doc:`eb-usage`              The command-line interface.
:doc:`eb-rationale`          **Non-normative.** Why the rules are what
                             they are, including decisions since
                             reversed.
:doc:`eb-provenance`         **Non-normative.** What changed from the
                             eichenbank-claude spec, and why.
===========================  =========================================

Where this specification and ``spec/eb.ebnf`` disagree with any older
document, these win. The executable suite in ``tests/suite`` pins the
behavior, and ``./mk spec`` checks that every rule cited by a test or by
a source comment actually exists here.


Reading order
-------------

For the language itself, read the grammar, then :doc:`eb-semantics`. For
"can I do this here?", :doc:`eb-constraints` answers faster. For a
specific diagnostic, :doc:`eb-errors`.

.. toctree::
   :maxdepth: 2

   eb-grammar
   eb-semantics
   eb-constraints
   eb-errors
   eb-usage
   eb-rationale
   eb-provenance


Implementation status
---------------------

The specification leads the implementation in places. Every such place
carries a **NOT YET IMPLEMENTED** admonition in the text; they are
collected here.

===============================  ======================================
``:capacity(r, n)``              RC-60 and RC-70 are specified; the
                                 intrinsic is not implemented.
Modules (MOD-i)                  ``import``, ``export``, ``as`` are
                                 reserved words the compiler rejects.
``sm`` samplers                  Reserved. Per-sampler PRNG streams
                                 keyed (simseed, sampler, run).
``eb repl``                      Reserved; reports "not yet
                                 implemented".
Native and GPU emitters          ``--format native`` and ``--target``
                                 are reserved. ``--format ebc`` and the
                                 VM are the supported path.
``-O0`` .. ``-O3``               Parsed and ignored; all four produce
                                 identical output.
Non-integer ``pi`` periods       Rejected. See the OPEN ISSUE under
                                 PI-15.
===============================  ======================================

``:capacity`` is the one entry where the specification was changed ahead
of the compiler by decision rather than by backlog: RC-60 and RC-70 are
settled, and the test suite has nothing to say about them yet. The rest
are ordinary "not built".

Explicit ``release`` was in this position and no longer is — the compiler
implements CLAIM-10 through CLAIM-70, and ``tests/suite`` covers crossing
lifetimes, reuse through the scan, reclamation at agent termination, and
the two runtime errors.