Skip to content

docs: record owner decisions in PRINCIPLES; contract bool==num exception #1671

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
InauguralPhysicist merged 1 commit into from
Oct 8, 2026
Merged

docs: record owner decisions in PRINCIPLES; contract bool==num exception #1671

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/LANGUAGE_CONTRACT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,14 +17,16 @@ is what forces you to notice the decisions you haven't made.

**Promise:** Structural for collections, by-value for scalars, by-identity
for functions. No cross-type coercion: operands of different types are
never equal (and it is never an error to compare them).
never equal (and it is never an error to compare them, except bool vs number, below).

- Numbers, strings, null: by value (`3 == 3.0`, `"a" == "a"`).
- Lists: equal iff same length and elementwise-equal (recursive).
- Dicts: equal iff same keys with equal values (order-independent).
- Buffers / text-builders: by contents.
- Functions, builtins: by identity.
- Mixed types: `"3" == 3` is `false`, never an error.
- The one exception: `bool` vs number raises at any depth, e.g. `true == 1` and `[true] == [1]` (#1637). A bool

@chatgpt-codex-connector chatgpt-codex-connector Bot Oct 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Document equality's short-circuit behavior

When an earlier element differs—for example, [0, true] == [1, 1]—values_equal_impl returns false before reaching the bool/number pair, as docs/SPEC.md already specifies. The unqualified claim that bool versus number “raises at any depth” therefore overstates the enforced contract; clarify that it raises only when the structural comparison reaches that pair.

Useful? React with 👍 / 👎.

is never numerically equal to anything, and the raise keeps `(pred of x) == 1` from silently going false.

**Status:** Enforced — `tests/test_equality.eigs`, `values_equal()` in
`eigenscript.c`.
Expand Down
16 changes: 16 additions & 0 deletions docs/PRINCIPLES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,15 @@ The rules every design decision is checked against. When a decision issue,
PR or review cites one, it cites it by name. A principle changes only by an
explicit decision recorded in an issue, never by drift.

## 0. One novel thing, deterministic replay, standard everywhere else

These are the owner's decisions; everything below elaborates them. EigenScript has **one novel thing: the
observer**, i.e. measurement as a language primitive. Its open questions are the signal (distance vs entropy)
and opt-in observation (#1667). **Deterministic replay** (the trace tape) is a product guarantee (principle 3).
**Everything else is standard**: where mature languages agree, EigenScript does what they do (principle 1).
Owner intent lives in this file, in `kind:decision` issues and in the language contract. A design found only in
the code is not owner intent (principle 8). (2026-10-07)

## 1. Best practice by default; depart only by measurement

For any question mature languages have already answered, their consensus is
Expand Down Expand Up @@ -71,3 +80,10 @@ carries no authority from seniority. When a design looks forced, ask
whether it is a law (language semantics, an external contract) or a
decision, and price the alternative. Gaps go upstream as issues; they are
not worked around silently. (See CLAUDE.md.)

## 9. It runs on a small machine

EigenScript, its toolchain and its suites must build and run on the reference dev box: 2 cores, 4 GB RAM. A
feature, default or test that only works on a bigger machine is a defect, not a hardware excuse. Heavy jobs may
run elsewhere (CI, cloud), but nothing may *require* more than the box to use the language. (2026-10-07)

Loading