functionalscript 0.44.0 → 0.45.0

package/fjs/bnf/module.f.mjs

@@ -31,12 +31,52 @@ const offset = 24
 
 const mask = (1 << offset) - 1
 
-const isValid = contains(0, mask)
+/**
+ * How many stored endpoint codes one 24-bit half holds: `2 ** 24`.
+ */
+const terminalSize = mask + 1
+
+/**
+ * The logical end-of-input symbol.
+ *
+ * `-1` is outside the non-negative physical-symbol domain, so no alphabet
+ * adapter can produce it and no ordinary symbol has to be reserved for it.
+ * Parser backends synthesize it exactly once, after the physical input.
+ */
+export const eofSymbol = -1
+
+/**
+ * The largest ordinary symbol, `2 ** 24 - 2`: the semantic domain is
+ * `[-1] | [0, 2 ** 24 - 2]`, exactly `2 ** 24` terminals, one per stored code.
+ */
+const maxSymbol = mask - 1
+
+const isValid = contains(eofSymbol, maxSymbol)
+
+/**
+ * Semantic terminal to its stored 24-bit endpoint code. Branchless: EOF wraps
+ * to `2 ** 24 - 1` (the top of the stored space) and every ordinary symbol
+ * keeps its own value as its code.
+ *
+ * @type {(value: number) => number}
+ */
+const encodeTerminal = value => (value + terminalSize) & mask
+
+/**
+ * The inverse of `encodeTerminal`, also branchless.
+ *
+ * Stored codes are an implementation representation, not semantic terminal
+ * ordering — `2 ** 24 - 1` is the largest code but the smallest terminal — so
+ * range operations that care about ordering must compare decoded values.
+ *
+ * @type {(value: number) => number}
+ */
+const decodeTerminal = value => ((value + 1) & mask) - 1
 
 /** @type {(a: number, b: number) => TerminalRange} */
 export const rangeEncode = (a, b) => {
     assert(isValid(a) && isValid(b) && a <= b)
-    return Number((BigInt(a) << BigInt(offset)) | BigInt(b))
+    return Number((BigInt(encodeTerminal(a)) << BigInt(offset)) | BigInt(encodeTerminal(b)))
 }
 
 /**
@@ -47,20 +87,21 @@ export const rangeEncode = (a, b) => {
 export const oneEncode = a => rangeEncode(a, a)
 
 /**
- * End-of-file marker: `mask`, the single largest value the 24-bit symbol
- * space can hold (the top of `fullRange`). Deliberately outside Unicode
- * (`unicodeRange` tops out at `0x10FFFF`) so it can never collide with a
- * real code point.
+ * End-of-file marker: the singleton range of {@link eofSymbol}. Deliberately
+ * outside the ordinary symbol domain — and so outside Unicode — so it can
+ * never collide with a real code point.
  *
  * @type {TerminalRange}
  */
-export const eof = oneEncode(mask)
+export const eof = oneEncode(eofSymbol)
 
 /**
- * Full 24-bit symbol range packed into a single {@link TerminalRange}.
+ * Every ordinary symbol packed into a single {@link TerminalRange}. EOF is not
+ * one of them, so complements over this range never include it.
+ *
  * @type {TerminalRange}
  */
-export const fullRange = 0x000000_FFFFFF
+export const fullRange = rangeEncode(0, maxSymbol)
 
 /**
  * Unicode scalar value range packed into a single {@link TerminalRange}.
@@ -74,12 +115,12 @@ export const unicodeRange = 0x000000_10FFFF
 export const unicodeMax = codePointListToString([0x10FFFF])
 
 /**
- * Decodes a packed range into `[start, end]` symbols.
+ * Decodes a packed range into `[start, end]` semantic symbols.
  *
  * @type {(r: number) => Tuple<2, number>}
  */
 export const rangeDecode = r =>
-    [Number(BigInt(r) >> BigInt(offset)), r & mask]
+    [decodeTerminal(Number(BigInt(r) >> BigInt(offset))), decodeTerminal(r & mask)]
 
 const mapOneEncode = map(oneEncode)
 

package/fjs/bnf/proof.f.d.mts

@@ -9,6 +9,8 @@ export declare const proof: {
         rangeEncodeInvalid: (() => void)[];
         rangeInvalid: (() => void)[];
     };
+    terminal: (() => void)[];
+    complement: (() => void)[];
     str: (() => void)[];
     set: () => void;
     commaJoin0Plus: () => void;

package/fjs/bnf/proof.f.mjs

@@ -4,8 +4,18 @@
  * @import { Rule } from './types.ts'
  */
 
-import { assert, assertEq } from '../asserts/module.f.mjs'
 import {
+    assert,
+    assertEq,
+    assertStructurallySame,
+} from '../asserts/module.f.mjs'
+import {
+    eof,
+    eofSymbol,
+    fullRange,
+    not,
+    notSet,
+    rangeDecode,
     rangeEncode,
     str,
     set,
@@ -15,8 +25,14 @@ import {
     oneEncode,
     repeat1Plus,
 } from './module.f.mjs'
+import { definedValues } from '../types/object/module.f.mjs'
 import { classic, deterministic } from './testlib.f.mjs'
 
+// The last ordinary symbol, `2 ** 24 - 2`. Written out because the range codec
+// is what these tests check: deriving it from the codec would move both sides
+// of every assertion together.
+const maxSymbol = 0xFFFFFE
+
 export const proof = {
     test: () => {
         classic()
@@ -24,8 +40,14 @@ export const proof = {
     },
     throw: {
         rangeEncodeInvalid: [
-            () => { rangeEncode(-1, 0) },
-            () => { rangeEncode(0, -1) },
+            // one below `eofSymbol`, the smallest semantic terminal
+            () => { rangeEncode(-2, 0) },
+            () => { rangeEncode(0, -2) },
+            // one above the largest ordinary symbol: `2 ** 24 - 1` is EOF's
+            // stored code, not a terminal of its own
+            () => { rangeEncode(0, maxSymbol + 1) },
+            // semantic ordering, so EOF is below every ordinary symbol
+            () => { rangeEncode(0, eofSymbol) },
             () => { rangeEncode(5, 3) },
         ],
         rangeInvalid: [
@@ -33,6 +55,60 @@ export const proof = {
             () => { range('abc') },
         ],
     },
+    terminal: [
+        () => {
+            // EOF is the singleton `[-1, -1]` and keeps the stored code
+            // `2 ** 24 - 1` at both endpoints.
+            assertEq(eof, 0xFFFFFF_FFFFFF)
+            const [a, b] = rangeDecode(eof)
+            assertEq(a, eofSymbol)
+            assertEq(b, eofSymbol)
+        },
+        () => {
+            // `fullRange` holds the ordinary symbols only.
+            const [a, b] = rangeDecode(fullRange)
+            assertEq(a, 0)
+            assertEq(b, maxSymbol)
+        },
+        () => {
+            // Round trips over the whole semantic domain: EOF, the ordinary
+            // minimum, an ordinary symbol, and the ordinary maximum.
+            for (const v of [eofSymbol, 0, 0x10FFFF, maxSymbol]) {
+                const [a, b] = rangeDecode(oneEncode(v))
+                assertEq(a, v)
+                assertEq(b, v)
+            }
+        },
+        () => {
+            // Ordinary symbols keep their own value as their stored code, so a
+            // packed literal still reads as its endpoints.
+            assertEq(oneEncode(0x20), 0x000020_000020)
+            const [a, b] = rangeDecode(0x000030_000039)
+            assertEq(a, 0x30)
+            assertEq(b, 0x39)
+        },
+        () => {
+            // A range may span EOF and ordinary symbols; the endpoints are
+            // ordered semantically, not by stored code.
+            const [a, b] = rangeDecode(rangeEncode(eofSymbol, maxSymbol))
+            assertEq(a, eofSymbol)
+            assertEq(b, maxSymbol)
+        },
+    ],
+    complement: [
+        () => {
+            // The complement of nothing over `fullRange` is `fullRange`: EOF is
+            // not an ordinary symbol, so no complement can produce it.
+            const r = definedValues(not({}))
+            assertEq(r.length, 1)
+            assertEq(r[0], fullRange)
+        },
+        () => {
+            const r = definedValues(notSet('a'))
+            const decoded = r.map(rangeDecode)
+            assertStructurallySame(decoded, [[0, 0x60], [0x62, maxSymbol]])
+        },
+    ],
     str: [
         () => {
             const result = str('a')

package/fjs/bnf/token_symbol/module.f.d.mts

@@ -4,7 +4,8 @@
  * A parser built on top of a tokenizer consumes one input symbol per token, so
  * multi-character operators (`>>>=`) and keywords (`instanceof`) each need a
  * symbol of their own. Names are registered as one fixed alphabet and get a
- * symbol from their position in it, above the Unicode range and below `eof`.
+ * symbol from their position in it, above the Unicode range and up to the last
+ * ordinary symbol.
  *
  * See `./types.ts` for the `Encoding<T>` type-level API.
  *
@@ -14,8 +15,8 @@
  */
 import type { Encoding } from './types.ts';
 /**
- * How many names one encoding holds: every symbol from {@link start} up to but
- * not including `eof` (`0xFFFFFF`, the top of the 24-bit symbol space).
+ * How many names one encoding holds: every symbol from {@link start} up to and
+ * including the last ordinary symbol (`0xFFFFFE`, the top of `fullRange`).
  *
  * @type {number}
  */

package/fjs/bnf/token_symbol/module.f.mjs

@@ -4,7 +4,8 @@
  * A parser built on top of a tokenizer consumes one input symbol per token, so
  * multi-character operators (`>>>=`) and keywords (`instanceof`) each need a
  * symbol of their own. Names are registered as one fixed alphabet and get a
- * symbol from their position in it, above the Unicode range and below `eof`.
+ * symbol from their position in it, above the Unicode range and up to the last
+ * ordinary symbol.
  *
  * See `./types.ts` for the `Encoding<T>` type-level API.
  *
@@ -15,11 +16,11 @@
 
 import { assert } from '../../asserts/module.f.mjs'
 import { fromUndefined } from '../../types/nullable/module.f.mjs'
-import { eof, rangeDecode, unicodeRange } from '../module.f.mjs'
+import { fullRange, rangeDecode, unicodeRange } from '../module.f.mjs'
 
 const [, unicodeLast] = rangeDecode(unicodeRange)
 
-const [eofSymbol] = rangeDecode(eof)
+const [, lastOrdinary] = rangeDecode(fullRange)
 
 /**
  * The symbol of the first registered name: `0x110000`, one past the last
@@ -29,12 +30,12 @@ const [eofSymbol] = rangeDecode(eof)
 const start = unicodeLast + 1
 
 /**
- * How many names one encoding holds: every symbol from {@link start} up to but
- * not including `eof` (`0xFFFFFF`, the top of the 24-bit symbol space).
+ * How many names one encoding holds: every symbol from {@link start} up to and
+ * including the last ordinary symbol (`0xFFFFFE`, the top of `fullRange`).
  *
  * @type {number}
  */
-export const capacity = eofSymbol - start
+export const capacity = lastOrdinary - start + 1
 
 /**
  * Builds an encoding over the complete list of token names.

package/fjs/bnf/token_symbol/proof.f.mjs

@@ -1,4 +1,5 @@
 import { assertEq } from '../../asserts/module.f.mjs'
+import { eofSymbol } from '../module.f.mjs'
 import { capacity, encoding } from './module.f.mjs'
 
 const names = /** @type {const} */ (['>>', '>>>=', 'instanceof'])
@@ -17,10 +18,12 @@ export const proof = {
         },
         () => {
             const { decode } = encoding(names)
-            // past the end of the alphabet, a code point, and `eof`
+            // past the end of the alphabet, a code point, the last ordinary
+            // symbol, and `eof`
             assertEq(decode(0x110003), null)
             assertEq(decode(0x10FFFF), null)
-            assertEq(decode(0xFFFFFF), null)
+            assertEq(decode(0xFFFFFE), null)
+            assertEq(decode(eofSymbol), null)
         },
     ],
     roundTrip: () => {

package/fjs/bnf/token_symbol/types.d.ts

@@ -20,8 +20,8 @@ export type Encoding<T extends string> = {
     readonly encode: (name: T) => number;
     /**
      * The name a symbol stands for, or `null` when the symbol belongs to no
-     * registered name — a code point, `eof`, or a symbol past the end of the
-     * alphabet.
+     * registered name — a code point, the `eof` symbol, or a symbol past the
+     * end of the alphabet.
      */
     readonly decode: (symbol: number) => Nullable<T>;
 };

package/fjs/bnf/types.d.ts

@@ -5,11 +5,18 @@
  */
 import type { StringMap } from '../types/object/types.ts';
 /**
- * A range of symbols. Two 24-bit numbers are stored in one JS number (48 bits).
+ * A range of symbols. Two 24-bit endpoint codes are stored in one JS number
+ * (48 bits).
  *
  * For example: 0xBBBBBB_EEEEEE
- * - 0xBBBBBB is the first symbol (24 bits)
- * - 0xEEEEEE is the last symbol (24 bits)
+ * - 0xBBBBBB is the first endpoint's stored code (24 bits)
+ * - 0xEEEEEE is the last endpoint's stored code (24 bits)
+ *
+ * A stored code is not the semantic terminal value: the semantic domain is
+ * `[-1] | [0, 2 ** 24 - 2]` — EOF plus every ordinary symbol — and EOF's code
+ * is `0xFFFFFF`, the top of the stored space. `rangeEncode` / `rangeDecode` in
+ * `./module.f.mjs` convert between the two, and everything that compares
+ * terminals compares decoded values.
  *
  * 24 bits per half, not 26 (the most `float64`'s 52-bit safe-integer mantissa
  * could fit two of): 24 is divisible by 4, so each half is exactly 6 hex

package/fjs/cas/cli/proof.f.d.mts

@@ -1,4 +1,6 @@
-/** @import { NodeProgramOptions } from '../../effects/node/types.ts' */
+/**
+ * @import { NodeProgramOptions } from '../../effects/node/types.ts'
+ */
 export declare const proof: {
     mainAdd: () => void;
     mainAddGetBig: () => void;

package/fjs/cas/cli/proof.f.mjs

@@ -1,4 +1,6 @@
-/** @import { NodeProgramOptions } from '../../effects/node/types.ts' */
+/**
+ * @import { NodeProgramOptions } from '../../effects/node/types.ts'
+ */
 
 import { commands } from './module.f.mjs'
 import { computeSync, sha256 } from '../../crypto/sha2/module.f.mjs'

package/fjs/cas/evo/module.f.d.mts

@@ -111,19 +111,13 @@ export declare const syncRevision: (cacheKey: Key<Cache>) => (hash: Vec) => (val
 /**
  * Adds a new revision to `cas` and folds it into the cache at `cacheKey`.
  *
- * Steps: resolve and validate every parent ({@link resolveParents}), resolve
- * `subject` from them ({@link resolveSubject}) and check every parent
- * actually belongs to it ({@link validateParentSubjects}), resolve `snapshot`
- * ({@link resolveSnapshot}) and compute `generation`
- * ({@link computeGeneration}), assemble a `Revision` and check its hash /
- * generation semantics (`fjs/media/revision` `checkReferences` — the same rule
- * a reader applies; the shape itself is already guaranteed by this function's
- * own field types), encode and write it to `cas`, then fold the new revision
- * into the cache. Every failure — an invalid or missing parent, a
- * cross-subject parent, an unresolvable subject or snapshot, an invalid
- * revision, a blob too large to encode, or a store write failure — is
- * reported as `error(message)` rather than thrown, so a caller (e.g. an MCP
- * tool handler) can surface it without a `throw`/`catch`.
+ * Steps: resolve and validate every parent ({@link resolveParents}), derive
+ * the revision to store from them ({@link buildRevision}), then encode it,
+ * write it to `cas`, and fold it into the cache. Every failure — an invalid
+ * or missing parent, a cross-subject parent, an unresolvable subject or
+ * snapshot, an invalid revision, a blob too large to encode, or a store write
+ * failure — is reported as `error(message)` rather than thrown, so a caller
+ * (e.g. an MCP tool handler) can surface it without a `throw`/`catch`.
  *
  * `input.generation` is ignored: it exists on {@link RevisionData} only so a
  * value read back by {@link readRevision} round-trips into `add` unchanged,