docs: 38 sentences in the front doors and references, and 6 changelog fragments, contradict the runtime on phase2-numbers

Ouverte
#2,466 3 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
3/5
Temps estimé
1-2 jours
Accessibilité débutants
55/100
Type d'issue
Documentation
Clarté
Plutôt claire
Activité
Active
Stack technique
c
Domaine
documentation

Piste de recherche

Start with the listed documentation locations and compare each sentence with the cited decision records, tests, and corrected wording; the issue continues beyond the visible excerpt, so review the full checklist before editing. Run the provided eigenscript examples to confirm the documented behavior. Done when every listed contradiction in the full issue is corrected and the examples agree with the updated documentation.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

area:docs kind:docs-drift

Running the documents and the changelog fragments of phase2-numbers (tip f9f3e49b) against a release build of that tree found
sentences the runtime contradicts. For each one below, a decision record or a test in the tree says the runtime is right, so the
document is the thing to change. Each item gives the place, the sentence, the corrected sentence (checked by running it), and a
one-line program that shows the behaviour (eigenscript -e $'...', default environment unless an EIGS_STRICT value is given).

Refs #1758, #1776.

Front doors and references

  • Float zero divisors. README.md:290-291, docs/llms.txt:394-395, docs/COMPARISON.md:68-69
    • Now: "Zero divisors raise value for int, float and mixed operands."
    • Corrected (the wording docs/SPEC.md:280-281 already has): "Zero divisors raise value for int // and %; float forms follow IEEE arithmetic."
    • Record: docs/design/phase2-numbers.md §7 N11; tests/phase2/MAP.md rows N4.float-mod-zero-nan, N4.float-floordiv-zero-raises (-> inf, nan, inf, -inf).
    • Shows it: eigenscript -e 'print of [7.0 // 0, 7.0 % 0, 7 // 0.0]' prints [inf, nan, inf].
  • Integer-list tensor results. README.md:1036-1037, docs/llms.txt:950-951, docs/SPEC.md:3086-3087, docs/COMPARISON.md:1079-1080
    • Now: "gather keeps the selected list cell's int/float kind; buffer elements and numeric tensor calculations are floats."
    • Corrected: "gather keeps the selected list cell's int/float kind, and add, subtract, multiply, negative and all-int sum keep ints on all-int lists; buffer elements and other numeric tensor calculations are floats."
    • Record: the design's builtin table, add row ("scalar arm mirrors +"); tests/phase2/builtins/builtins/add.branch line 4; docs/BUILTINS.md:601-602.
    • Shows it: eigenscript -e 'print of [num_type of (add of [[1, 2], [3, 4]])[0], num_type of (divide of [[4, 2], [2, 2]])[0]]' prints ["int", "float"].
  • Byte converters. docs/llms.txt:370-371, docs/SPEC.md:2827-2828, docs/COMPARISON.md:523-524 (they disagree with docs/BUILTINS.md:1501, which is right)
    • Now: "write_bytes requires exact bytes in 0..255 (N5/Q1); other byte converters retain truncation and wrapping at this stage" (SPEC: "the remaining byte converters ...").
    • Corrected, docs/llms.txt: "write_bytes, str_from_bytes, f64_from_bytes, inflate and buf_from_pcm16le require exact bytes in 0..255 (N5/Q1); raw copies, serialization and buffer-only work areas preserve representation." docs/SPEC.md and docs/COMPARISON.md: "write_bytes, str_from_bytes, f64_from_bytes, inflate and buf_from_pcm16le require exact bytes in 0..255 (N5/Q1)."
    • Record: tests/phase2/builtins/builtins/str_from_bytes.branch, inflate.branch; MAP row N5.pcm16-byte-raises.
    • Shows it: eigenscript -e $'try:\n print of (str_from_bytes of ([256]))\ncatch e:\n print of e.kind' prints value (65.5 and -1 likewise).
  • Buffer reductions. docs/llms.txt:553-555, docs/COMPARISON.md:506-507 (they disagree with docs/BUILTINS.md:606, which is right)
    • Now: "... takes either container and returns a buffer iff every tensor operand was one." / "... and hand back a buffer when every operand was one."
    • Corrected, docs/llms.txt: "... takes either container and returns a buffer iff every tensor operand was one; sum/mean/norm return a number." docs/COMPARISON.md: "... accept either, and hand back a buffer when every operand was one; sum, mean and norm return a number."
    • Record: tests/test_tensor_buffer_inputs.eigs:98-100.
    • Shows it: eigenscript -e $'b is buf_from_list of [1, 2]\nprint of [type of (sum of b), type of (mean of b), type of (norm of b)]' prints ["num", "num", "num"].
  • shape of a buffer. README.md:485-486, docs/SPEC.md:2881-2884 (they disagree with docs/BUILTINS.md:607, which is right)
    • Now: "... and returns a buffer when every tensor operand was one." (README); SPEC lists shape among the builtins that return a buffer.
    • Corrected, README.md: "... and returns a buffer when every tensor operand was one; shape returns a list." docs/SPEC.md: drop "shape," from the list and end the sentence "...; shape accepts a buffer and always returns a list."
    • Record: tests/test_tensor_buffer_inputs.eigs:105, :148.
    • Shows it: eigenscript -e 'print of (type of (shape of (buffer of 3)))' prints list.
  • Buffers and text builders sent through a channel are copied. docs/BUILTINS.md:1439-1441 (disagrees with docs/llms.txt:575, which is right)
    • Now: "The exceptions are handle-like values — buffer, text_builder, fn, and builtin — which remain shared by reference across a send; do not mutate those concurrently from sender and receiver."
    • Corrected: "Buffers and text builders are copied too (#1148/#1153); only handles are shared, and docs/CONCURRENCY.md lists them."
    • Record: tests/test_transfer_copy.eigs (#1148/#1153); docs/CONCURRENCY.md:33-35.
    • Shows it: eigenscript -e $'c is channel of 1\nb is buf_from_list of ([1])\nsend of [c, b]\nb[0] is 99\nprint of (recv of c)[0]' prints 1.0.
  • sqrt of a negative number. docs/BUILTINS.md:647
    • Now: "Element-wise square root; negative input returns 0"
    • Corrected: "Element-wise square root; negative input returns NaN and sets math_flags.invalid (EIGS_STRICT=1 raises value)"
    • Record: MAP row N11.sqrt-neg-nan.
    • Shows it: eigenscript -e 'print of (sqrt of -1)' prints nan.
  • contains on a non-string. docs/BUILTINS.md:125
    • Now: "true if haystack contains needle, else false (non-string operands are false, never a spurious match)"
    • Corrected: "true if haystack contains needle, else false; a non-string operand raises type_mismatch unless EIGS_STRICT=0, where it is false (never a spurious match)"
    • Record: changes/fixed/2439-argument-guards-raise-by-default.md; tests/strict_guard_release_messages.tsv row 11; the guard-default half of tools/strict_differential.sh.
    • Shows it: eigenscript -e $'try:\n print of (contains of [1, "x"])\ncatch e:\n print of e.kind' prints type_mismatch; with EIGS_STRICT=0, eigenscript -e 'print of (contains of [1, "x"])' prints false.
  • is_file on a non-string. docs/BUILTINS.md:480
    • Now: "false for a directory, a device/fifo/socket, a missing path, or a non-string."
    • Corrected: "false for a directory, a device/fifo/socket or a missing path; a non-string raises type_mismatch unless EIGS_STRICT=0, where it is false."
    • Record: as above, tests/strict_guard_release_messages.tsv row 64; tests/suite_program_env.txt runs test_file_rename.eigs (whose is_file of 42 is false) under EIGS_STRICT=0.
    • Shows it: eigenscript -e $'try:\n print of (is_file of 3)\ncatch e:\n print of e.kind' prints type_mismatch.
  • sum/mean error positions. docs/BUILTINS.md:671 (mean), docs/BUILTINS.md:672 (sum)
    • Now: "A non-number list element raises an error naming its zero-based flattened index and type; a non-number in the argument-list form raises naming its 1-based argument position (#1649/#2112)."
    • Corrected: "A non-number element raises an error naming its zero-based flattened index and type, in either call form; a bool directly in the top-level list raises naming its 1-based position instead (sum: argument 2 is a bool, which sum does not take there) (#1649/#2112)." (mean: in the mean row.)
    • Record: tests/test_aggregate_non_numbers_1649.eigs:9-11 pins sum of [10, "bad", 20] (an argument list) to "sum: element 1 is str"; the bool rule is #1637's (CHANGELOG, "A distinct bool type").
    • Shows it: eigenscript -e $'try:\n sum of [1, "bad"]\ncatch e:\n print of e.message' prints sum: element 1 is str (expected a number); with true in place of "bad" it prints sum: argument 2 is a bool, which sum does not take there.
  • Audio generator sample counts round. docs/BUILTINS.md:1492-1493 (disagrees with README.md:68, which is right)
    • Now: "Their validated counts still truncate: at 44100 Hz, 0.00101 seconds produces 44 samples. The sample count rounding change is staged for R2.6 (RULINGS B5)."
    • Corrected: "Their validated counts round half away from zero: at 44100 Hz, 0.00101 seconds produces 45 samples." and remove the second sentence (R2.6 has landed).
    • Record: tests/phase2/builtins/BAR.md, "R2.6 row list (ruling B5)": "45 after R2.6".
    • Shows it: eigenscript -e 'print of (len of (audio_sine of [440, 0.00101, 1]))' prints 45.
  • report at a NaN. docs/SPEC.md:2079-2080
    • Now: "... it either names a band whose predicate is true, or — when a full window matches none of them — returns moving."
    • Corrected: "... or — when a full window matches none of them — returns moving; a NaN current value returns undefined."
    • Record: the design's O2 definition alignments ("NaN current value: every predicate is false, and report is "undefined""); MAP row O2.nan-report-undefined.
    • Shows it: eigenscript -e $'x is 1\nfor i in range of 12:\n x is f64_from_bits of 9221120237041090560\nprint of (report of x)' prints undefined.
  • Tracking inside unobserved:. docs/SYNTAX.md:726-729 (disagrees with docs/SPEC.md:1957, which is right)
    • Now: "Observer tracking is skipped. Entropy / dH / obs_age on touched values stay frozen at whatever the last observed write left them. Interrogatives (why is game.px, how is game.px) will return stale answers until the next observed assignment."
    • Corrected: "Entropy tracking is skipped. Entropy / dH / obs_age on touched values stay frozen at whatever the last observed write left them; numeric assignments still update the value trajectory, so when, where, why and how of a number stay current."
    • Record: CHANGELOG #1049 ("Elision now suppresses the verdict, not the sample").
    • Shows it: eigenscript -e $'x is 3\nunobserved:\n x is 4\n print of [when is x, why is x]' prints [2, 1], the same as without the block.
  • Predicates inside unobserved: raise. docs/SYNTAX.md:730-731
    • Now: "The last-observer pointer is not updated. Predicates in scope continue to report whatever was last observed outside the block."
    • Corrected: "Observer predicates raise. A predicate asked inside the block, or in a function called from it, raises value (#871)."
    • Record: CHANGELOG #871 ("An observer predicate inside unobserved: raises instead of answering false forever").
    • Shows it: eigenscript -e $'x is 3\nunobserved:\n x is 4\n try:\n print of (converged of x)\n catch e:\n print of e.kind' prints value.
  • A one-element literal list passes its element. docs/SPEC.md:3002-3003, docs/SYNTAX.md:759-760
    • Now: "a literal list argument with 2+ elements spreads into parameters; a 1-element literal list does not; a list passed via a variable never spreads." / "f of [x] (a one-element list) binds the whole list to the first parameter — it does not spread."
    • Corrected, docs/SPEC.md: "a literal list argument is an argument list at every count: 2+ elements spread into parameters and a 1-element literal list passes its element; a list passed via a variable never spreads." docs/SYNTAX.md: "The one-element spread trap: f of [x] (a one-element list) passes x, not the list — write f of ([x]) to pass the list whole."
    • Record: tests/test_call_semantics.eigs:209-216 (#405).
    • Shows it: eigenscript -e $'define two(a, b) as:\n return [a, b]\nprint of (two of [3])' prints [3, null].
  • A caught runtime error is a dict. docs/SYNTAX.md:276-277 (disagrees with docs/llms.txt:697, which is right)
    • Now: "runtime errors bind their message string; a thrown value binds unchanged, so errors can carry data:"
    • Corrected: "runtime errors bind a dict with kind, message, line and file; a thrown value binds unchanged, so errors can carry data:"
    • Shows it: eigenscript -e $'try:\n x is 1 // 0\ncatch e:\n print of (keys of e)' prints ["kind", "message", "line", "file"].
  • Import order is project-first. docs/SYNTAX.md:477-478
    • Now: "It resolves lib/name.eigs (the standard library) first, then name.eigs relative to your script."
    • Corrected: "It resolves name.eigs relative to your script first, then lib/name.eigs (the standard library), and warns when both exist."
    • Record: CHANGELOG #821 ("import resolution is project-first, and a stdlib collision warns").
    • Shows it: a script beside a math.eigs holding marker is "project module" runs import math then print of math.marker and prints project module, with the shadowing warning on stderr.
  • prev and at bind with plain is. docs/llms.txt:183-186 (disagrees with docs/SYNTAX.md:658-660, which is right)
    • Now: "usable as params/loop-vars/catch-names, but you can NEVER bind one with plain is — what is e parses as the interrogative form, ..."
    • Corrected: "usable as params/loop-vars/catch-names, and prev is 3/at is 4 are ordinary assignments, but you can NEVER bind a question word with plain is — what is e parses as the interrogative form, ..."
    • Record: tests/test_soft_keyword_idents.eigs:8,10.
    • Shows it: eigenscript -e $'prev is 3\nat is 4\nprint of [prev, at]' prints [3, 4].
  • false is falsy; comparisons give bools. docs/SPEC.md:3016-3017, docs/LANGUAGE_CONTRACT.md:249-250
    • Now: "Truthiness: 0, null, "", [], {} are falsy; everything else is truthy. Comparisons yield 1/0." / "Falsy values are 0, "", [], {}, and null. Everything else is truthy (including functions)."
    • Corrected, docs/SPEC.md: "Truthiness: 0, false, null, "", [], {} are falsy; everything else is truthy. Comparisons yield true/false (type bool)." docs/LANGUAGE_CONTRACT.md: "Falsy values are 0, false, "", [], {}, and null. Everything else is truthy (including functions)."
    • Record: CHANGELOG #1637 ("A distinct bool type ... Truthiness is unchanged (false is falsy, true truthy)").
    • Shows it: eigenscript -e 'print of [1 < 2, type of (1 < 2), not false]' prints [true, "bool", true].
  • task_alive returns a bool. docs/SPEC.md:2509-2510
    • Now: "task_alive of id is 1 until the task finishes."
    • Corrected: "task_alive of id is true until the task finishes."
    • Shows it: eigenscript -e $'define w as:\n task_yield of null\nid is task_spawn of [w, 0]\nprint of (task_alive of id)' prints true.
  • Runtime type count. docs/COMPARISON.md:42
    • Now: "everything is one of eight runtime types"
    • Corrected: "everything is one of a fixed set of runtime types that type of names" (no count; there are ten labels today, bool and text_builder included). Also add "bool" to the type row, docs/BUILTINS.md:68, which omits it.
    • Shows it: eigenscript -e 'print of (type of false)' prints bool.
  • str_from_bytes of [n]. docs/BUILTINS.md:336
    • Now: "(chr of n == str_from_bytes of [n] for 1–255)"
    • Corrected: "(chr of n == str_from_bytes of ([n]) for 1–255)"
    • Shows it: eigenscript -e 'print of [chr of 65, str_from_bytes of ([65])]' prints ["A", "A"]; str_from_bytes of [65] passes the number 65 and raises type_mismatch.
  • Division-derived index. docs/LANGUAGE_CONTRACT.md:468-470
    • Now: "Because / always yields a double, a division-derived index must be collapsed explicitly — a[floor of ((lo + hi) / 2)] — ..."
    • Corrected: "Because / always yields a double, a division-derived index that may be fractional must be collapsed explicitly — a[floor of ((lo + hi) / 2)] — ..." (the paragraph already says integer-valued doubles are accepted).
    • Shows it: eigenscript -e $'xs is [10, 20, 30]\nprint of xs[4 / 2]' prints 30.
  • Empty slice at the end. docs/LANGUAGE_CONTRACT.md:489-491
    • Now: "a[len:] and a[start:len] are legal and yield an empty slice"
    • Corrected: "a[len:] and a[len:len] are legal and yield an empty slice"
    • Shows it: eigenscript -e $'a is [1, 2, 3]\nprint of [a[1:len of a], a[len of a:len of a]]' prints [[2, 3], []].
  • JSON text equals str only for finite floats. docs/LANGUAGE_CONTRACT.md:182-185
    • Now: "... so a JSON round-trip returns the same double and json_encode of x equals str of x for every float (#875)."
    • Corrected: "... so a JSON round-trip returns the same double and json_encode of x equals str of x for every finite float; a non-finite float raises value (N13) (#875)."
    • Record: MAP row N13.json-refuses-inf.
    • Shows it: eigenscript -e $'try:\n print of (json_encode of (1e308 * 10))\ncatch e:\n print of [str of (1e308 * 10), e.kind]' prints ["inf", "value"].

Changelog fragments

A later round's fragment replaced these; the release notes assembled from both would say two things.

  • changes/added/1758-int64-flip.md: says "Trace tape format v7 preserves numeric kinds and refuses older tapes"; the format is 10 (src/trace.h, changes/added/1758-r25-ieee-tape-text.md). Corrected: - Integer literals now retain exact int64 values, with exact int/float comparisons and checked `+`, `-`, `*`, negation and `abs` that raise `value` on int64 overflow. `num_type` reports `"int"`, `"float"` or `null`; `type` continues to report `"num"` for either numeric kind, and trace tapes preserve numeric kinds (#1758) Shows it: eigenscript --trace t.tape prog.eigs writes a first line V 10 0.48.0.
  • changes/changed/1758-r16z-bridge.md (first entry): "embedding buffer reads return the exact stored double, including NaN payloads" was replaced by changes/breaking/1758-r24-bits-canonical-boundary.md and docs/EMBEDDING.md ("Stored non-finite buffer data"). Corrected: - Buffer indexing and iteration refuse stored non-finite elements in every strict mode. Buffer equality compares stored doubles with IEEE equality, without raises or math flags. The transitional numeric bridge and caller-less helpers are removed (R1.6z, #1758) Shows it: tests/phase2/embed_buffer_get_raw.c passes (checks=72 failures=0), reading payload 0x7ff8000000000042 back as 0x7ff8000000000000.
  • changes/changed/1758-r31-observer.md: its R31-1/R31-2 paragraphs ("never counts an oscillating window", "The harmonic tail still stalls before certification") were replaced by changes/fixed/1758-r315-stall-amplitude.md, changes/fixed/1758-r316-stall-step.md and changes/changed/2407-reveal-converged-stable.md. Corrected: keep the first paragraph only, ending ... Non-numeric entropy observation remains available (#1758). Shows it: eigenscript -e $'x is 1.0\nx is 1.0\nloop while not converged:\n x is 0.0 - x\nprint of [__loop_iterations__, __loop_exit__]' prints [104, "stalled"].
  • changes/fixed/1758-r312-runaway-contract.md: the stall-reader rule, "The additional same-binding HD1b/LE1b rows stall at 106; an isolated additive fixture stalls at 100" and the harmonic residual are replaced (as above; tests/test_halting_descent.eigs HD1b and tests/test_loop_exit.eigs LE1b pin 9 iterations, normal). Corrected: - Elided numeric samples inside `unobserved:` retain live value and running-best updates without writing line-qualified observer-history snapshots (RULING R31-2, #1758) Shows it: eigenscript -e $'x is 1000000.0\nx is 1000000.0\nloop while not converged:\n x is x + 200.0\nprint of [__loop_iterations__, __loop_exit__]' prints [9, "normal"].
  • changes/fixed/1758-r315-stall-amplitude.md: "Pin HD1b/LE1b at 100 stalled." is replaced by #2407 (the tests above). Corrected: - Restore the bare observer-loop stall exit for non-contracting oscillations whose peaks fall in both halves of the retained window (RULING R31-4/R31-5): current non-finite values count unconditionally, finite oscillations compare the magnitude envelopes of the retained window's halves, and contracting oscillations keep the convergence route (#1758) Shows it: the alternation program above stalls at 104; x is -0.999 * x from 1.0 exits normal, converged, after 14511.
  • changes/internal/1758-phase2-r16a-readers.md (internal, not assembled): the "opt-in bridge deprecation meter" went with the bridge (changes/changed/1758-r16z-bridge.md); neither EIGS_PHASE2_METER nor EIGS_R16_DEPRECATED is in src/, Makefile or tools/. Corrected: - Add the Phase 2 final numeric readers; builtin callers and behavior are unchanged (#1758)

Done when

  • Every checked place above carries its corrected sentence (or an equivalent the program next to it prints true for).
  • The six fragments read as given, or are merged into the later fragment that replaced them, so the assembled [Unreleased] section states each behaviour once.
  • Each "Shows it" program, run on the merged tree, prints what its item says.
  • tests/test_doc_examples.py (suite [89]/[90]) and tools/docs_claims_check.sh (suite [99za]) pass on the changed documents.

— Claude DevBox

Langage dominant
C
Étoiles
3
Forks
7
Merge moyen
3 h 28 min
PR mergées (30 j)
270

Préparer son environnement

Ouvrir dans Codespaces

Lance le conteneur de développement du projet dans votre navigateur, avec votre propre compte GitHub.

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de InauguralSystems/EigenScript

Toutes les issues de InauguralSystems/EigenScript

Issues similaires

Plus d'issues C

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.