functionalscript 0.44.0 → 0.46.0

package/fjs/media/json/tokenizer/proof.f.mjs

@@ -7,6 +7,7 @@ import { toArray } from '../../../types/list/module.f.mjs'
 import { stringifyAsTree } from '../../../djs/serializer/module.f.mjs'
 import { sort } from '../../../types/object/module.f.mjs'
 import { stringToList } from '../../../text/utf16/module.f.mjs'
+import { assertStructurallySame } from '../../../asserts/module.f.mjs'
 
 /** @type {(s: string) => readonly JsonToken[]} */
 const tokenizeString = s => toArray(tokenize(stringToList(s)))
@@ -109,11 +110,11 @@ export const proof = {
         },
         () => {
             const result = stringify(tokenizeString('0'))
-            if (result !== '[{"bf":[0n,0],"kind":"number","value":"0"},{"kind":"eof"}]') { throw result }
+            if (result !== '[{"kind":"number","value":"0"},{"kind":"eof"}]') { throw result }
         },
         () => {
             const result = stringify(tokenizeString('[0]'))
-            if (result !== '[{"kind":"["},{"bf":[0n,0],"kind":"number","value":"0"},{"kind":"]"},{"kind":"eof"}]') { throw result }
+            if (result !== '[{"kind":"["},{"kind":"number","value":"0"},{"kind":"]"},{"kind":"eof"}]') { throw result }
         },
         () => {
             const result = stringify(tokenizeString('00'))
@@ -125,23 +126,23 @@ export const proof = {
         },
         () => {
             const result = stringify(tokenizeString('123456789012345678901234567890'))
-            if (result !== '[{"bf":[123456789012345678901234567890n,0],"kind":"number","value":"123456789012345678901234567890"},{"kind":"eof"}]') { throw result }
+            if (result !== '[{"kind":"number","value":"123456789012345678901234567890"},{"kind":"eof"}]') { throw result }
         },
         () => {
             const result = stringify(tokenizeString('{90}'))
-            if (result !== '[{"kind":"{"},{"bf":[90n,0],"kind":"number","value":"90"},{"kind":"}"},{"kind":"eof"}]') { throw result }
+            if (result !== '[{"kind":"{"},{"kind":"number","value":"90"},{"kind":"}"},{"kind":"eof"}]') { throw result }
         },
         () => {
             const result = stringify(tokenizeString('1 2'))
-            if (result !== '[{"bf":[1n,0],"kind":"number","value":"1"},{"bf":[2n,0],"kind":"number","value":"2"},{"kind":"eof"}]') { throw result }
+            if (result !== '[{"kind":"number","value":"1"},{"kind":"number","value":"2"},{"kind":"eof"}]') { throw result }
         },
         () => {
             const result = stringify(tokenizeString('0. 2'))
-            if (result !== '[{"kind":"error","message":"invalid number"},{"bf":[2n,0],"kind":"number","value":"2"},{"kind":"eof"}]') { throw result }
+            if (result !== '[{"kind":"error","message":"invalid number"},{"kind":"number","value":"2"},{"kind":"eof"}]') { throw result }
         },
         () => {
             const result = stringify(tokenizeString('10-0'))
-            if (result !== '[{"bf":[10n,0],"kind":"number","value":"10"},{"bf":[0n,0],"kind":"number","value":"-0"},{"kind":"eof"}]') { throw result }
+            if (result !== '[{"kind":"number","value":"10"},{"kind":"number","value":"-0"},{"kind":"eof"}]') { throw result }
         },
         () => {
             const result = stringify(tokenizeString('9a:'))
@@ -149,7 +150,7 @@ export const proof = {
         },
         () => {
             const result = stringify(tokenizeString('-10'))
-            if (result !== '[{"bf":[-10n,0],"kind":"number","value":"-10"},{"kind":"eof"}]') { throw result }
+            if (result !== '[{"kind":"number","value":"-10"},{"kind":"eof"}]') { throw result }
         },
         () => {
             const result = stringify(tokenizeString('-'))
@@ -165,7 +166,7 @@ export const proof = {
         },
         () => {
             const result = stringify(tokenizeString('-0'))
-            if (result !== '[{"bf":[0n,0],"kind":"number","value":"-0"},{"kind":"eof"}]') { throw result }
+            if (result !== '[{"kind":"number","value":"-0"},{"kind":"eof"}]') { throw result }
         },
         () => {
             const result = stringify(tokenizeString('-00'))
@@ -173,15 +174,15 @@ export const proof = {
         },
         () => {
             const result = stringify(tokenizeString('-.123'))
-            if (result !== '[{"kind":"error","message":"invalid token"},{"kind":"error","message":"invalid token"},{"bf":[123n,0],"kind":"number","value":"123"},{"kind":"eof"}]') { throw result }
+            if (result !== '[{"kind":"error","message":"invalid token"},{"kind":"error","message":"invalid token"},{"kind":"number","value":"123"},{"kind":"eof"}]') { throw result }
         },
         () => {
             const result = stringify(tokenizeString('0.01'))
-            if (result !== '[{"bf":[1n,-2],"kind":"number","value":"0.01"},{"kind":"eof"}]') { throw result }
+            if (result !== '[{"kind":"number","value":"0.01"},{"kind":"eof"}]') { throw result }
         },
         () => {
             const result = stringify(tokenizeString('-0.9'))
-            if (result !== '[{"bf":[-9n,-1],"kind":"number","value":"-0.9"},{"kind":"eof"}]') { throw result }
+            if (result !== '[{"kind":"number","value":"-0.9"},{"kind":"eof"}]') { throw result }
         },
         () => {
             const result = stringify(tokenizeString('-0.'))
@@ -193,11 +194,11 @@ export const proof = {
         },
         () => {
             const result = stringify(tokenizeString('12.34'))
-            if (result !== '[{"bf":[1234n,-2],"kind":"number","value":"12.34"},{"kind":"eof"}]') { throw result }
+            if (result !== '[{"kind":"number","value":"12.34"},{"kind":"eof"}]') { throw result }
         },
         () => {
             const result = stringify(tokenizeString('-12.00'))
-            if (result !== '[{"bf":[-1200n,-2],"kind":"number","value":"-12.00"},{"kind":"eof"}]') { throw result }
+            if (result !== '[{"kind":"number","value":"-12.00"},{"kind":"eof"}]') { throw result }
         },
         () => {
             const result = stringify(tokenizeString('-12.'))
@@ -209,27 +210,27 @@ export const proof = {
         },
         () => {
             const result = stringify(tokenizeString('0e1'))
-            if (result !== '[{"bf":[0n,1],"kind":"number","value":"0e1"},{"kind":"eof"}]') { throw result }
+            if (result !== '[{"kind":"number","value":"0e1"},{"kind":"eof"}]') { throw result }
         },
         () => {
             const result = stringify(tokenizeString('0e+2'))
-            if (result !== '[{"bf":[0n,2],"kind":"number","value":"0e+2"},{"kind":"eof"}]') { throw result }
+            if (result !== '[{"kind":"number","value":"0e+2"},{"kind":"eof"}]') { throw result }
         },
         () => {
             const result = stringify(tokenizeString('0e-0'))
-            if (result !== '[{"bf":[0n,0],"kind":"number","value":"0e-0"},{"kind":"eof"}]') { throw result }
+            if (result !== '[{"kind":"number","value":"0e-0"},{"kind":"eof"}]') { throw result }
         },
         () => {
             const result = stringify(tokenizeString('12e0000'))
-            if (result !== '[{"bf":[12n,0],"kind":"number","value":"12e0000"},{"kind":"eof"}]') { throw result }
+            if (result !== '[{"kind":"number","value":"12e0000"},{"kind":"eof"}]') { throw result }
         },
         () => {
             const result = stringify(tokenizeString('-12e-0001'))
-            if (result !== '[{"bf":[-12n,-1],"kind":"number","value":"-12e-0001"},{"kind":"eof"}]') { throw result }
+            if (result !== '[{"kind":"number","value":"-12e-0001"},{"kind":"eof"}]') { throw result }
         },
         () => {
             const result = stringify(tokenizeString('-12.34e1234'))
-            if (result !== '[{"bf":[-1234n,1232],"kind":"number","value":"-12.34e1234"},{"kind":"eof"}]') { throw result }
+            if (result !== '[{"kind":"number","value":"-12.34e1234"},{"kind":"eof"}]') { throw result }
         },
         () => {
             const result = stringify(tokenizeString('0e'))
@@ -287,5 +288,45 @@ export const proof = {
             const result = stringify(tokenizeString('[null]'))
             if (result !== '[{"kind":"["},{"kind":"null"},{"kind":"]"},{"kind":"eof"}]') { throw result }
         },
-    ]
+    ],
+    // Losslessness starts at the tokenizer boundary: a syntactically valid
+    // JSON number reaches `NumberToken.value` as its exact lexeme. Nothing
+    // derived from it — a coefficient bigint, an exponent number — is built
+    // while scanning, so no valid input can fail to tokenize because such a
+    // derived value would exceed a runtime numeric limit.
+    //
+    // The runtime's own bigint limit (V8 rejects magnitudes above 2^30 bits,
+    // roughly 3.2e8 decimal digits) is not exercised here: the smallest input
+    // that reaches it is a JSON document of some hundreds of megabytes. These
+    // cases stay far below that while still being far above what `number` and
+    // `Number.MAX_SAFE_INTEGER` can hold.
+    lossless: {
+        // a coefficient with more digits than any JavaScript number can carry
+        oversizedCoefficient: () => {
+            const value = `1${'0'.repeat(100000)}1`
+            assertStructurallySame(
+                tokenizeString(value),
+                [{ kind: 'number', value }, { kind: 'eof' }])
+        },
+        // exponent text far beyond JavaScript-number precision: `Number` of it
+        // is `Infinity`, yet every digit still has to reach the token
+        unboundedExponent: () => {
+            const value = '1e999999999999999999999'
+            assertStructurallySame(
+                tokenizeString(value),
+                [{ kind: 'number', value }, { kind: 'eof' }])
+        },
+        negativeUnboundedExponent: () => {
+            const value = '-1.5e-999999999999999999999'
+            assertStructurallySame(
+                tokenizeString(value),
+                [{ kind: 'number', value }, { kind: 'eof' }])
+        },
+        negativeOversized: () => {
+            const value = `-1${'0'.repeat(100000)}1`
+            assertStructurallySame(
+                tokenizeString(value),
+                [{ kind: 'number', value }, { kind: 'eof' }])
+        },
+    },
 }

package/fjs/media/json/types.d.ts

@@ -1,12 +1,13 @@
 /**
  * TypeScript counterparts of the JSON data model: `Primitive`, `Unknown`,
- * `Object`, and `Array`.
+ * `Object`, and `Array`, plus the leaf-parameterized `Tree` they instantiate.
  *
  * `Unknown` is written by hand rather than derived, so that the recursion
  * reads directly, and is then pinned against the rtti schemas in the sibling
  * [`./rtti/module.f.mjs`](./rtti/module.f.mjs) with
  * `Assert<Equal<Unknown, Ts<typeof unknown>>>`. The pin is what keeps the two
- * descriptions of the same data model from drifting apart.
+ * descriptions of the same data model from drifting apart — and it holds the
+ * `Tree<Primitive>` spelling to the same data model the schemas describe.
  *
  * @module
  */
@@ -14,12 +15,37 @@ import type { Entry as ObjectEntry } from '../../types/object/types.ts';
 import type { Ts } from '../../types/rtti/ts/types.ts';
 import type { primitive } from './rtti/module.f.mjs';
 import type { List } from '../../types/list/types.ts';
-export type Primitive = Ts<typeof primitive>;
-export type Unknown = Object | Array | Primitive;
-export type Object = {
-    readonly [k in string]?: Unknown;
+/**
+ * A recursive JSON-shaped tree over a leaf type `P`: JSON's container
+ * structure with its primitive set left open.
+ *
+ * The parser and the serializer are written once against this shape and are
+ * instantiated per numeric policy — `Tree<Primitive>` is ordinary JSON,
+ * `Tree<ExtendedPrimitive>` (see
+ * [`./extended/types.ts`](./extended/types.ts)) adds `bigint` to the leaves.
+ *
+ * `TreeObject`'s index signature is **optional** on purpose: reading an
+ * arbitrary key off a JSON-shaped object yields `undefined` when the property
+ * is absent, and `undefined` is not a leaf of any of these trees. A required
+ * index signature would type every missing property as a value.
+ */
+export type Tree<P> = P | TreeObject<P> | TreeArray<P>;
+export type TreeObject<P> = {
+    readonly [k in string]?: Tree<P>;
 };
-export type Array = readonly Unknown[];
-export type Entry = ObjectEntry<Unknown>;
-export type _Entries = List<Entry>;
-export type _MapEntries = (entries: _Entries) => _Entries;
+export type TreeArray<P> = readonly Tree<P>[];
+export type Primitive = Ts<typeof primitive>;
+export type Unknown = Tree<Primitive>;
+export type Object = TreeObject<Primitive>;
+export type Array = TreeArray<Primitive>;
+export type TreeEntry<P> = ObjectEntry<Tree<P>>;
+export type TreeEntries<P> = List<TreeEntry<P>>;
+/**
+ * How a serializer orders an object's entries — `sort` for canonical output,
+ * `identity` to keep insertion order. It is a per-leaf-type alias only because
+ * the entries it reorders carry the tree's own leaves.
+ */
+export type TreeMapEntries<P> = (entries: TreeEntries<P>) => TreeEntries<P>;
+export type Entry = TreeEntry<Primitive>;
+export type _Entries = TreeEntries<Primitive>;
+export type _MapEntries = TreeMapEntries<Primitive>;

package/fjs/media/lock/module.f.d.mts

@@ -0,0 +1,100 @@
+/**
+ * `vnd.fjs.lock` — a lock map as a BLOB of its own, so several revisions can
+ * point at one agreed resolution instead of each carrying a copy.
+ *
+ * `vnd.fjs.revision`'s `lock` is an inline map, which keeps a revision
+ * interpretable in isolation but re-serializes the whole map into a new blob
+ * every time anything else about the revision changes — CAS deduplicates whole
+ * blobs, not fragments. This dialect is that map, alone: no `subject`,
+ * `parents`, `generation`, or `archived`, because it is a **value**, not a
+ * step. History for lock content, when someone wants it, is an ordinary
+ * revision whose `snapshot` is one of these blobs, so no second history
+ * mechanism appears and `revision` stays the only one.
+ *
+ * The `lock` schema and its semantic check are **imported** from
+ * `fjs/media/revision`, not restated: one recursive schema, one hash check,
+ * one canonical serialization, so a map means the same thing inline and shared
+ * and the two forms cannot drift (`proof.f.mjs` pins the bytes).
+ *
+ * Like its sibling, this module is the pure format only: the rtti schema, the
+ * `dialect` tag, and decode/validate. Whether a referenced blob exists, and
+ * what its bindings mean once fetched, stay a resolver's business.
+ *
+ * See `README.md` for the full spec.
+ *
+ * @module
+ *
+ * @import { Unknown } from '../json/types.ts'
+ * @import { Result } from '../../types/result/types.ts'
+ * @import { DialectEntry } from '../types.ts'
+ * @import { Lock, LockError } from './types.ts'
+ */
+import type { Unknown } from '../json/types.ts';
+import type { Result } from '../../types/result/types.ts';
+import type { DialectEntry } from '../types.ts';
+import type { Lock, LockError } from './types.ts';
+/**
+ * Format tag: names the dialect of this BLOB. The media type it is served
+ * with is derived mechanically: `application/` + `dialect` + `+json`.
+ */
+export declare const dialect: 'vnd.fjs.lock';
+/** The media type derived from {@link dialect}: `application/vnd.fjs.lock+json`. */
+export declare const mediaType: "application/vnd.fjs.lock+json";
+/**
+ * rtti schema for a `lock` BLOB: the dialect tag and the map, nothing else.
+ *
+ * `lock` is `fjs/media/revision`'s own schema, so the shared form admits
+ * exactly the maps the inline form does, to the same depth, with the same
+ * value domain.
+ *
+ * The field is **required** and may be `{}`: an absent map and an empty one
+ * would otherwise be two spellings of one blob, and a blob whose only purpose
+ * is to hold a map has nothing to say when it does not. It is also never a
+ * hash — a lock blob does not reference further lock blobs (see the README's
+ * [Composition](./README.md#composition)), so following a reference always
+ * terminates in one step.
+ */
+export declare const lockSchema: {
+    readonly dialect: "vnd.fjs.lock";
+    readonly lock: import("../revision/types.ts").LockSchema;
+};
+/** Serializes a lock blob canonically, recursively sorting every object's property names.
+ * @type {(lock: Lock) => string}
+ */
+export declare const encodeText: (lock: Lock) => string;
+/**
+ * Checks the semantic refinement the structural schema can't express on an
+ * already shape-valid lock blob: every direct value at every depth of the map
+ * must decode as a cbase32 hash. This is `fjs/media/revision`'s own
+ * `lockMapError`, so a map rejected inline is rejected here and vice versa.
+ *
+ * Exported separately from {@link validate} for callers holding an
+ * already-typed `Lock` — the same split, for the same reason, as the revision
+ * dialect's `checkReferences`.
+ *
+ * @type {(l: Lock) => Result<Lock, string>}
+ */
+export declare const checkReferences: (l: Lock) => Result<Lock, string>;
+/**
+ * Validates an already-parsed JSON value as a `lock` BLOB: structural (rtti)
+ * validation followed by the hash semantic check.
+ *
+ * @type {(value: Unknown) => Result<Lock, LockError>}
+ */
+export declare const validate: (value: Unknown) => Result<Lock, LockError>;
+/**
+ * Decodes `text` as a `lock` BLOB: JSON-parses it, then validates it per
+ * {@link validate}. Detection is semantic, not syntactic — any JSON that
+ * satisfies the schema is a lock blob, regardless of key order or whitespace.
+ *
+ * @type {(text: string) => Result<Lock, LockError>}
+ */
+export declare const decodeText: (text: string) => Result<Lock, LockError>;
+/**
+ * This dialect as a registry entry for `fjs/media`'s `detect`. It carries the
+ * semantic check too, so a blob is detected as `vnd.fjs.lock` exactly when
+ * {@link decodeText} would accept it.
+ *
+ * @type {DialectEntry}
+ */
+export declare const lockDialect: DialectEntry;

package/fjs/media/lock/module.f.mjs

@@ -0,0 +1,125 @@
+/**
+ * `vnd.fjs.lock` — a lock map as a BLOB of its own, so several revisions can
+ * point at one agreed resolution instead of each carrying a copy.
+ *
+ * `vnd.fjs.revision`'s `lock` is an inline map, which keeps a revision
+ * interpretable in isolation but re-serializes the whole map into a new blob
+ * every time anything else about the revision changes — CAS deduplicates whole
+ * blobs, not fragments. This dialect is that map, alone: no `subject`,
+ * `parents`, `generation`, or `archived`, because it is a **value**, not a
+ * step. History for lock content, when someone wants it, is an ordinary
+ * revision whose `snapshot` is one of these blobs, so no second history
+ * mechanism appears and `revision` stays the only one.
+ *
+ * The `lock` schema and its semantic check are **imported** from
+ * `fjs/media/revision`, not restated: one recursive schema, one hash check,
+ * one canonical serialization, so a map means the same thing inline and shared
+ * and the two forms cannot drift (`proof.f.mjs` pins the bytes).
+ *
+ * Like its sibling, this module is the pure format only: the rtti schema, the
+ * `dialect` tag, and decode/validate. Whether a referenced blob exists, and
+ * what its bindings mean once fetched, stay a resolver's business.
+ *
+ * See `README.md` for the full spec.
+ *
+ * @module
+ *
+ * @import { Unknown } from '../json/types.ts'
+ * @import { Result } from '../../types/result/types.ts'
+ * @import { DialectEntry } from '../types.ts'
+ * @import { Lock, LockError } from './types.ts'
+ */
+
+import { parse as rttiParse } from '../../types/rtti/parse/module.f.mjs'
+import { parse as parseJson, stringify } from '../json/module.f.mjs'
+import { error, ok, okThen } from '../../types/result/module.f.mjs'
+import { dialectEntry } from '../module.f.mjs'
+import { sort } from '../../types/object/module.f.mjs'
+import { lock, lockMapError } from '../revision/module.f.mjs'
+
+/**
+ * Format tag: names the dialect of this BLOB. The media type it is served
+ * with is derived mechanically: `application/` + `dialect` + `+json`.
+ */
+export const dialect = /** @type {const} */ ('vnd.fjs.lock')
+
+/** The media type derived from {@link dialect}: `application/vnd.fjs.lock+json`. */
+export const mediaType = /** @type {const} */ (`application/${dialect}+json`)
+
+/**
+ * rtti schema for a `lock` BLOB: the dialect tag and the map, nothing else.
+ *
+ * `lock` is `fjs/media/revision`'s own schema, so the shared form admits
+ * exactly the maps the inline form does, to the same depth, with the same
+ * value domain.
+ *
+ * The field is **required** and may be `{}`: an absent map and an empty one
+ * would otherwise be two spellings of one blob, and a blob whose only purpose
+ * is to hold a map has nothing to say when it does not. It is also never a
+ * hash — a lock blob does not reference further lock blobs (see the README's
+ * [Composition](./README.md#composition)), so following a reference always
+ * terminates in one step.
+ */
+export const lockSchema = /** @type {const} */ ({
+    dialect,
+    lock,
+})
+
+/** Serializes a lock blob canonically, recursively sorting every object's property names.
+ * @type {(lock: Lock) => string}
+ */
+export const encodeText = stringify(sort)
+
+/** Structural-only validator: checks the shape, not the hash semantics. */
+const validateShape = rttiParse(lockSchema)
+
+/**
+ * Checks the semantic refinement the structural schema can't express on an
+ * already shape-valid lock blob: every direct value at every depth of the map
+ * must decode as a cbase32 hash. This is `fjs/media/revision`'s own
+ * `lockMapError`, so a map rejected inline is rejected here and vice versa.
+ *
+ * Exported separately from {@link validate} for callers holding an
+ * already-typed `Lock` — the same split, for the same reason, as the revision
+ * dialect's `checkReferences`.
+ *
+ * @type {(l: Lock) => Result<Lock, string>}
+ */
+export const checkReferences = l => {
+    const message = lockMapError(l.lock)
+    return message === null ? ok(l) : error(message)
+}
+
+/**
+ * Validates an already-parsed JSON value as a `lock` BLOB: structural (rtti)
+ * validation followed by the hash semantic check.
+ *
+ * @type {(value: Unknown) => Result<Lock, LockError>}
+ */
+export const validate = value => okThen(checkReferences)(validateShape(value))
+
+/**
+ * Decodes `text` as a `lock` BLOB: JSON-parses it, then validates it per
+ * {@link validate}. Detection is semantic, not syntactic — any JSON that
+ * satisfies the schema is a lock blob, regardless of key order or whitespace.
+ *
+ * @type {(text: string) => Result<Lock, LockError>}
+ */
+export const decodeText = text => okThen(validate)(parseJson(text))
+
+/** {@link checkReferences} as the `boolean` refinement a {@link DialectEntry} takes.
+ * @type {(l: Lock) => boolean}
+ */
+const isValidLock = l => {
+    const [tag] = checkReferences(l)
+    return tag === 'ok'
+}
+
+/**
+ * This dialect as a registry entry for `fjs/media`'s `detect`. It carries the
+ * semantic check too, so a blob is detected as `vnd.fjs.lock` exactly when
+ * {@link decodeText} would accept it.
+ *
+ * @type {DialectEntry}
+ */
+export const lockDialect = dialectEntry(lockSchema, isValidLock)

package/fjs/media/lock/proof.f.d.mts

@@ -0,0 +1,33 @@
+/**
+ * @import { Object as JsonObject } from '../json/types.ts'
+ * @import { LockMap } from './types.ts'
+ */
+export declare const proof: {
+    dialectAndMediaType: () => void;
+    validate: {
+        flatMapAccepted: () => void;
+        emptyMapAccepted: () => void;
+        nestedMapAccepted: () => void;
+        missingLockRejected: () => void;
+        referenceLockRejected: () => void;
+        malformedMapRejected: () => void;
+        invalidHashRejected: () => void;
+        revisionFieldsIgnored: () => void;
+        revisionBlobRejected: () => void;
+    };
+    checkReferences: {
+        valid: () => void;
+        invalid: () => void;
+    };
+    decodeText: {
+        validJson: () => void;
+        keyOrderIndependent: () => void;
+        malformedJsonRejected: () => void;
+        ordinaryJsonRejected: () => void;
+    };
+    encodeText: {
+        recursivelySortsObjectsLexicographically: () => void;
+        equivalentOrdersConverge: () => void;
+    };
+    inlineAndSharedSerializeIdentically: () => void;
+};