Define numeric diagnostics and acceptance evidence

Define numeric diagnostics and acceptance evidence

Label: wayfinder:grilling Type: grilling Status: ready-for-human Wayfinding state: resolved Assignee: Codex Blocked by: 07 Parent: Find the ASPL numeric type expansion specification

Question

Which diagnostics, bilingual examples, documentation changes, and focused acceptance checks make this numeric expansion precise enough to hand off for implementation?

Define the distinction between checking errors, ASPL traps, and recoverable parsing/conversion failures, with useful source locations and numeric type/range information. Select evidence for each width boundary, f32 rounding, full-range u64, mixed expressions, bitwise/shift edge cases, compact list storage and independent copies, numeric text round trips, and invalid bytecode. Cover direct execution, generated native programs, the online playground, and ASPL Console's existing workflow without requiring an exhaustive host matrix. Identify current examples and documentation that must change, preserve existing useful behavior, and confirm that every requirement has an acceptance obligation. Close or graduate the remaining in-scope fog before declaring the map complete; implementation and publication remain separate work.

Answer

Resolved with the user on 2026-09-19. ASPL 0.4.0 keeps numeric checking errors, runtime traps, recoverable numeric-text failures, bytecode load failures, and host or resource outcomes distinct. Their structured records preserve exact numeric types and full-width values before Arabic or English rendering. A focused development record traces every numeric requirement to acceptance evidence without turning this work into release certification.

The user explicitly requires a clean break. No production user depends on the current development implementation, so compatibility with ASPL 0.3.0, bytecode version 3, or the current numeric trap layout is not an objective.

Clean version boundary

ASPL 0.4.0 uses bytecode version 4 and browser-result wire version 3. Version 4 loaders reject every other bytecode version. Browser-result wire version 3 replaces version 2 where the expanded trap metadata changes the record. The implementation adds no old-bytecode reader, result-wire compatibility path, trap-reason alias, migration fixture, or dual representation.

The narrow invalid-f64-to-i64-conversion trap disappears. Version 4 uses the general invalid-numeric-conversion trap. Bitwise and shift fixtures that currently prove those tokens invalid become positive or edge-case fixtures under the new grammar. Historical release manifests and evidence stay unchanged as records of their own versions; they do not constrain the new development implementation.

Failure boundaries

The following categories do not substitute for one another:

An explicit checked numeric conversion is not recoverable. A well-typed conversion that cannot represent its reached value raises an ASPL trap. Only the parse_T numeric-text builtins return recoverable numeric failures.

Checking diagnostics

Numeric diagnostics retain the existing structured ASPL diagnostic contract: a stable reason, severity, typed arguments, a primary source span, ordered secondary spans, and bilingual rendering. Canonical numeric type arguments use i8, i16, i32, i64, u8, u16, u32, u64, f32, and f64 regardless of which source alias was written. Operators, reason keys, type names, classifications, bounds, and numeric values remain canonical ASCII technical fields in both catalogs. The renderer quotes and directionally isolates them and writes all digits as ASCII.

The numeric source reasons are:

• invalid-numeric-literal retains its existing identity and bilingual wording. Its spelling argument contains the complete invalid candidate.
• numeric-literal-out-of-range has two exact record shapes. An integer record carries spelling, type, minimum, and maximum, with exact inclusive decimal bounds able to represent the full u64 range. A floating record carries spelling, type, and the finite-overflow classification.
• type-mismatch continues to report different already-typed operands and every other exact-type boundary. Numeric contexts include binary operand, assignment, initializer, argument, return, record field, list element, indexed replacement, result payload, and explicit conversion.
• numeric-operator-not-supported is a new reason for a numeric type that does not provide the written operator. It carries operator and type. Examples include unary minus on an unsigned value, remainder on a floating value, and bitwise or shift operations on a floating value.

The fixed new or revised catalog text is:

A malformed or out-of-range literal uses the complete numeric candidate as its primary span. A directly applied unary minus joins the literal for range reporting, so a signed minimum or an out-of-range negative value points to the complete negative expression. An unsupported operator or mixed-type binary expression uses the operator token as primary and labels the operand expressions as ordered secondary spans with their canonical types. An invalid explicit-conversion operand uses the argument expression as primary and the target type token as secondary.

Source-stage recovery, ordering, duplicate removal, diagnostic caps, safe excerpts, and Arabic-default versus explicitly selected English behavior do not change.

Runtime traps and locations

The numeric trap reasons and ordered machine fields are:

integer-overflow:
type=<type> operation=<operation> operand-count=<count> operands=[<value>...]

integer-zero-divisor:
type=<type> operation=<divide|remainder> dividend=<value>

invalid-shift-count:
left-type=<type> count-type=<type> count=<value> width=<bits>

invalid-numeric-conversion:
source-type=<type> target-type=<type> classification=<classification>
source-value=<exact integer>

For a floating conversion source, source-bits replaces source-value. It uses exactly eight lowercase hexadecimal digits for f32 and sixteen for f64, after a 0x prefix. Integer fields retain exact signed or unsigned mathematical values. They never pass through a signed representation that changes a u64 value. Conversion classifications are below-range, above-range, nan, positive-infinity, and negative-infinity.

The renderer retains the localized Arabic or English trap shell, while reason keys, field names, operations, canonical types, classifications, decimal values, and hexadecimal bits remain the same technical text in either language. Browser-result wire version 3 carries raw 64-bit words plus type and signedness metadata. JavaScript reconstructs them with BigInt; it never converts a diagnostic integer through Number.

Direct CLI execution and the online playground map a reached numeric trap to the complete responsible expression, with the existing bounded call trace. Generated native programs retain the function name and function-relative instruction index because their bytecode contains no source map. A source map remains out of serialized bytecode and the generated executable.

Recoverable numeric-text failures

Each parse_T builtin retains the existing result[T] shape. A malformed complete spelling returns code invalid-number; a grammatically valid value outside the target range returns number-out-of-range. The failure is an ordinary value, so it has no source span, trace, or diagnostic record. Arabic and English aliases return identical values.

Messages are deterministic ASCII across hosts and aliases:

• malformed text uses invalid number for T, such as invalid number for u8;
• an integer range failure uses number out of range for T (MIN through MAX), with exact decimal bounds; and
• a floating range failure uses finite number out of range for T.

Programs branch on the stable code rather than the message. The result type and the selected parser identify the target even if a program discards the message.

Documentation and examples

The implementation updates the canonical authoring inputs browser/documentation-content.json and browser/documentation-examples.json, then regenerates the browser data and Arabic and English pages through the existing generators. Generated files are not edited as independent sources.

The reference material must update:

• the storable type inventory and all ten Arabic and English aliases;
• numeric literal grammar, inference, exact-type operators, conversions, and the absence of implicit conversion;
• arithmetic, bitwise, shift, floating, parsing, formatting, aggregate, and compact-list contracts;
• numeric diagnostic reasons, trap fields, recoverable parse codes, and the outcome distinctions above;
• ASPL 0.4.0, bytecode version 4, and browser-result wire version 3 where the development documentation exposes them; and
• the unchanged i64 boundaries for indexes, lengths, Unicode operations, start_main, and the existing foreign profiles.

Keep the existing sum and general diagnostic examples as simple baselines. Add numeric-types.ar.aspl, numeric-types.en.aspl, and an independently authored numeric-types.mixed.aspl. Together they demonstrate the paired type aliases, English and Arabic radix forms, full-range u64, direct f32 rounding, explicit conversion, bitwise operations, shifts, and independent list[u8] copies. Extend the existing parse-integer, parse-float, list, and list-mutation examples to cover a narrow type while retaining useful i64 and f64 coverage.

The Arabic and English reference text uses this contrast to teach the outcome boundary:

let byte: u8 = 256;           // checking error: numeric-literal-out-of-range
let converted = u8(256);      // valid source; traps if executed
let parsed = parse_u8("256"); // ordinary failed result: number-out-of-range

A contributor-only example corrupts version 4 bytecode and demonstrates load-failure / invalid-bytecode. The documentation also states that limits, cancellation, allocation failure, and host failure remain separate outcomes. It does not call any of these outcomes exceptions.

ASPL Console documentation continues to describe its CLI launch, selected file working directory, diagnostic-language selection, and separate standard streams. This effort updates development docs and generated local site output; it does not publish or deploy ASPL 0.4.0, alter release history, or claim a release.

Focused development acceptance record

Implementation creates conformance/numeric-focused-0.4.md. It is a development traceability record, not release evidence and not a replacement for the archived 0.1.1 manifest. Each normative rule in this map's decisions must link to at least one named obligation, exact fixture or generated table, oracle, and focused test target.

Shared semantic and storage matrix

Table-driven shared compiler, validator, VM, and resource checks cover:

• every integer type at its minimum and maximum, one below and one above, with negative one included for every unsigned type;
• decimal, hexadecimal, binary, and representative Arabic-radix forms;
• arithmetic boundaries, zero divisors, and every signed minimum divided or remaindered by negative one;
• complement, AND, OR, XOR, and shifts by zero, width minus one, negative one, width, and width plus one;
• every integer source and target conversion pair at meaningful successful and failing boundaries;
• both floating widths at positive and negative zero, the smallest subnormal, the normal and subnormal boundary, finite extrema, infinities, canonical NaNs, and primitive-operation rounding points;
• direct decimal rounding of 1.0000000596046448 to binary32 bits 0x3f800001, contrasted with conversion through binary64 to 0x3f800000;
• every parse and format pair at integer extrema, floating finite round trips, negative zero, subnormals, infinities, canonical NaNs, malformed text, and finite overflow;
• exact types through bindings, calls, returns, records, lists, and successful results, with representative rejection of mixed already-typed values; and
• every compact numeric-list backing at empty, exact-capacity, spare-capacity, and one-growth states in native and WebAssembly test builds.

The compact-list accounting seam proves logical length, capacity, scalar-width element charge, and fixed charge directly. It also covers one shared copy before mutation, two independently charged compact backings afterward, nested numeric lists, records and results retaining a list, reclamation, old-plus-new peak charging, injected allocation failure, configured memory exhaustion, cancellation, and no partial mutation. A representative list[u8] source program supplies public integration evidence; total program memory and C structure sizes are not compactness oracles.

Bytecode rejection and runtime timing

Focused validator cases cover every rejection class rather than every possible corrupt byte sequence:

• bytecode version 3 and every non-version-4 input;
• a corrupted fixed numeric type identity or type descriptor;
• noncanonical or out-of-width signed and unsigned constants;
• noncanonical binary32 and binary64 NaNs;
• disagreement between a constant, load, register, or aggregate destination;
• illegal arithmetic, comparison, equality, bitwise, shift, and conversion types;
• noninteger shift counts and nonnumeric conversion endpoints;
• mismatched numeric parse or format operations;
• exact-type violations in calls, returns, records, lists, and results; and
• malformed full-range u64 transport.

A separate pair of cases proves that well-typed bytecode with a constant invalid shift count or failing numeric conversion loads successfully and traps only if execution reaches the instruction. No compatibility corpus, exhaustive malformed-input matrix, or long fuzz campaign is required.

Cross-path fixtures

The repeated public-path corpus stays small:

• numeric-success combines aliases, u64 maximum parsing and formatting, the direct f32 rounding discriminator, explicit conversion, bitwise operations, shifts, and independent list[u8] copies.
• numeric-range-check rejects an out-of-range contextual literal and checks the complete bilingual record and source span.
• numeric-mixed-check rejects two already-typed different numeric operands and checks the operator primary span and operand secondary spans.
• numeric-u64-overflow checks unsigned trap transport above both 2^63 - 1 and JavaScript's exact Number range.
• numeric-shift-trap uses a count equal to the left width.
• numeric-conversion-trap checks the general conversion reason and one exact classification.
• numeric-zero-divisor checks the enriched existing trap payload.

Direct CLI checks and the actual production WebAssembly worker run the success fixture, both checking failures, and all four trap fixtures. Generated native programs run the success fixture and all four traps, verifying unmapped function and instruction locations. The browser harness checks native and WebAssembly bytecode parity, structured records, source mapping, exact BigInt reconstruction, and the public playground presentation. These are representative path checks; the shared harness owns the complete type matrix.

ASPL Console runs one short, environment-supported smoke that selects and launches the numeric success example through its existing CLI workflow. It does not implement or retest numeric semantics inside Qt.

Completion policy

The shared focused suite, direct CLI, generated native programs, production WebAssembly worker and playground, documentation checks, site parity, and the focused 0.4 record must pass. One available headless browser is sufficient. The Qt Console smoke runs when its build and display environment are available; an unavailable check is recorded as unavailable and does not block the development handoff.

The final implementation report names ASPL 0.4.0 and bytecode version 4, lists the exact commands and focused checks that completed, and records any environment-dependent check that could not run. It never describes an unrun check as passed or a development build as published.

The full historical conformance suite, release evidence, clean-system matrix, publication, deployment, repeated browser matrix, compatibility testing, performance qualification, and multi-hour fuzzing remain outside this effort. The map has no remaining in-scope fog. Its resolved tickets and named decision pointers are the implementation-ready specification; no duplicate monolithic specification is required.