functionalscript 0.46.0 → 0.47.0

package/fjs/protocol/mcp/proof.f.d.mts

@@ -1,5 +1,7 @@
 /**
  * @import { Unknown } from '../../media/json/types.ts'
+ * @import { Assert } from '../../asserts/types.ts'
+ * @import { Equal } from '../../types/ts/types.ts'
  * @import { Operation } from '../../effects/types.ts'
  * @import { Effect, NotImplemented } from '../../effects/types.ts'
  * @import { MemOperationMap } from '../../effects/mock/types.ts'
@@ -7,6 +9,7 @@
  * @import {
  *   ToolsListParams,
  *   ToolsCallParams,
+ *   ToolsCallResult,
  *   McpHandlers,
  *   McpConfig,
  *   McpSessionState,
@@ -48,6 +51,11 @@ export declare const proof: {
         methodDuringInitializingReturnsNotInitialized: () => void;
         invalidEnvelopeReturnsInvalidRequest: () => void;
     };
+    versionNegotiation: {
+        supportedRequestIsEchoed: () => void;
+        unsupportedRequestGetsLatestSupported: () => void;
+        oneVersionCounterProposesItsOnlyVersion: () => void;
+    };
     tools: {
         toolsListSucceeds: () => void;
         toolsListPassesCursorToHandler: () => void;
@@ -62,5 +70,10 @@ export declare const proof: {
     };
     registry: {
         toolsCallAbsentArgumentsDefaultsToEmptyObject: () => void;
+        inlineSchemaLiteralKeepsItsLiteralMembers: () => void;
+    };
+    toolResultStep: {
+        okIsRendered: () => void;
+        errorIsRenderedInBand: () => void;
     };
 };

package/fjs/protocol/mcp/proof.f.mjs

@@ -1,5 +1,7 @@
 /**
  * @import { Unknown } from '../../media/json/types.ts'
+ * @import { Assert } from '../../asserts/types.ts'
+ * @import { Equal } from '../../types/ts/types.ts'
  * @import { Operation } from '../../effects/types.ts'
  * @import { Effect, NotImplemented } from '../../effects/types.ts'
  * @import { MemOperationMap } from '../../effects/mock/types.ts'
@@ -7,6 +9,7 @@
  * @import {
  *   ToolsListParams,
  *   ToolsCallParams,
+ *   ToolsCallResult,
  *   McpHandlers,
  *   McpConfig,
  *   McpSessionState,
@@ -15,13 +18,15 @@
 
 import { assert, assertEq } from '../../asserts/module.f.mjs'
 import { runPure } from '../../effects/module.f.mjs'
-import { history, historyStep, mapStep, pureOk, step } from '../../effects/module.f.mjs'
+import { history, historyStep, mapStep, pureError, pureOk, step } from '../../effects/module.f.mjs'
 import { error, ok, unwrap as unwrapResult } from '../../types/result/module.f.mjs'
 import { run } from '../../effects/mock/module.f.mjs'
 import { internalError } from '../json_rpc/module.f.mjs'
+import { string } from '../../types/rtti/module.f.mjs'
 import { asBase, asNominal, create, read } from '../../effects/memory/module.f.mjs'
 import {
     uninitializedState, mcpStep, notInitialized, fromRegistry, toolEntry, okResult,
+    toolResultStep,
 } from './module.f.mjs'
 
 // ── Memory mock ────────────────────────────────────────────────────────────────
@@ -55,11 +60,16 @@ const mock = {
 const config = {
     serverInfo: { name: 'test-server', version: '0.1.0' },
     capabilities: { tools: {} },
-    protocolVersion: '2024-11-05',
+    protocolVersions: ['2024-11-05'],
 }
 
 const configNoTools = { ...config, capabilities: {} }
 
+// A server speaking two revisions, latest first — the case a single
+// `protocolVersion` string could not describe.
+/** @type {McpConfig} */
+const configTwoVersions = { ...config, protocolVersions: ['2025-06-18', '2024-11-05'] }
+
 /** @typedef {never} _Op */
 /** @type {McpHandlers<_Op>} */
 const handlers = {
@@ -208,16 +218,39 @@ const firstText = resp => {
     return text
 }
 
+// ── `toolResultStep` renderers ────────────────────────────────────────────────
+
+// Shared by both branches so each renderer is written once and reached once:
+// the `ok` test exercises `dashes`, the `error` test `errorText`.
+
+/** @type {(xs: readonly string[]) => string} */
+const dashes = xs => xs.join('-')
+
+/** @type {(e: string) => string} */
+const errorText = e => `failed: ${e}`
+
+/** The `text` of the first content item of a `ToolsCallResult`. */
+/** @type {(r: ToolsCallResult) => string} */
+const textOf = r => {
+    const [item] = r.content
+    assert(item.type === 'text', item)
+    return item.text
+}
+
 // ── Test messages ─────────────────────────────────────────────────────────────
 
-const initMsg = { jsonrpc: '2.0', method: 'initialize', id: 1,
-    params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'client', version: '0.0.1' } } }
+/** An `initialize` request asking for `protocolVersion`. */
+/** @type {(protocolVersion: string) => Unknown} */
+const initMsgFor = protocolVersion => ({ jsonrpc: '2.0', method: 'initialize', id: 1,
+    params: { protocolVersion, capabilities: {}, clientInfo: { name: 'client', version: '0.0.1' } } })
+
+const initMsg = initMsgFor('2024-11-05')
 
 const initNotif = { jsonrpc: '2.0', method: 'notifications/initialized' }
 
 /** A memory handler that answers as a runner with no such operation. */
 const memNotImplemented = () => (/** @type {_MemoryState} */ state) =>
-    /** @type {const} */ ([state, error(/** @type {const} */ (['notImplemented', 'memRead']))])
+    /** @type {const} */ ([state, error(['notImplemented', 'memRead'])])
 
 // Runs one step against a memory mock with `overrides` applied, from a session
 // slot created before them so the slot itself always exists.
@@ -376,6 +409,35 @@ export const proof = {
         },
     },
 
+    // Version negotiation, per the lifecycle spec: answer with the requested
+    // revision when the server speaks it, and with the latest one it does speak
+    // otherwise. The counter-proposal is a success frame, so what distinguishes
+    // the two branches is the answered version, never the session state.
+    versionNegotiation: {
+        supportedRequestIsEchoed: () => {
+            // `2024-11-05` is supported but not the latest — the case a
+            // single-string config had to counter-propose out of.
+            const [resp] = step1(configTwoVersions)(initMsgFor('2024-11-05'))
+            assertEq(protocolVersion(resp), '2024-11-05')
+        },
+
+        unsupportedRequestGetsLatestSupported: () => {
+            const [resp, newState] = step1(configTwoVersions)(initMsgFor('2030-01-01'))
+            assertEq(protocolVersion(resp), '2025-06-18')
+            assert(newState[0] === 'initializing')
+        },
+
+        // A one-element list answers exactly as the `protocolVersion` string
+        // field did: its only revision, whichever branch is taken. The echo
+        // half is `lifecycle.initializeReturnsResult`, which asks `config` for
+        // the one version it has; this is the counter-proposal half.
+        oneVersionCounterProposesItsOnlyVersion: () => {
+            const [resp, newState] = step1(config)(initMsgFor('2030-01-01'))
+            assertEq(protocolVersion(resp), '2024-11-05')
+            assert(newState[0] === 'initializing')
+        },
+    },
+
     tools: {
         toolsListSucceeds: () => {
             const msg = { jsonrpc: '2.0', method: 'tools/list', id: 5 }
@@ -453,8 +515,7 @@ export const proof = {
         // validating it against the empty-object schema below would fail and
         // this would observe an error result instead of `ok`.
         toolsCallAbsentArgumentsDefaultsToEmptyObject: () => {
-            const echoArgs = /** @type {const} */ ({})
-            const entry = toolEntry('echo', 'echoes', echoArgs,
+            const entry = toolEntry('echo', 'echoes', {},
                 () => pureOk(okResult('ok')))
             const handlers = fromRegistry([entry])
             const [r] = runPure(handlers.toolsCall({ name: 'echo' }))
@@ -463,5 +524,44 @@ export const proof = {
             assert(item.type === 'text', item)
             assertEq(item.text, 'ok')
         },
+        // The type guarantee `./README.md` documents: an inline schema literal
+        // reaches the handler as `Ts<T>`, with no cast on either side. That
+        // rests on `toolEntry`'s `const` type parameter — without it `kind`
+        // widens to `string` and the assertion below fails, which is the only
+        // place that would notice.
+        inlineSchemaLiteralKeepsItsLiteralMembers: () => {
+            const entry = toolEntry('tag', 'tags', { kind: 'add', name: string },
+                ({ kind, name }) => {
+                    /** @typedef {Assert<Equal<typeof kind, 'add'>>} _ConstParameter */
+                    return pureOk(okResult(`${kind}:${name}`))
+                })
+            const handlers = fromRegistry([entry])
+            const [r] = runPure(handlers.toolsCall(
+                { name: 'tag', arguments: { kind: 'add', name: 'x' } }))
+            assert(r !== undefined && r[0] === 'ok', r)
+            const [item] = r[1].content
+            assert(item.type === 'text', item)
+            assertEq(item.text, 'add:x')
+        },
+    },
+
+    // `toolResultStep` picks between `okResult` and `errorResult`, so both
+    // branches are the whole of it — and the error branch is the one that
+    // proves the failure stays in-band (`isError`) instead of escaping as a
+    // transport error, which the `never` error channel is the type-level claim
+    // of.
+    toolResultStep: {
+        okIsRendered: () => {
+            const [r] = runPure(toolResultStep(pureOk(['a', 'b']), dashes, errorText))
+            assert(r !== undefined && r[0] === 'ok', r)
+            assertEq(r[1].isError, undefined)
+            assertEq(textOf(r[1]), 'a-b')
+        },
+        errorIsRenderedInBand: () => {
+            const [r] = runPure(toolResultStep(pureError('gone'), dashes, errorText))
+            assert(r !== undefined && r[0] === 'ok', r)
+            assertEq(r[1].isError, true)
+            assertEq(textOf(r[1]), 'failed: gone')
+        },
     },
 }

package/fjs/protocol/mcp/stdio/module.f.mjs

@@ -41,19 +41,18 @@ import { ioError, readLine, write } from '../../../effects/node/module.f.mjs'
 import { tryUtf8 } from '../../../text/module.f.mjs'
 import { parse, stringify } from '../../../media/json/module.f.mjs'
 import { sort } from '../../../types/object/module.f.mjs'
-import { internalError, jsonrpc, parseError } from '../../json_rpc/module.f.mjs'
+import { errorResponseOf, internalError, parseError } from '../../json_rpc/module.f.mjs'
 import { error } from '../../../types/result/module.f.mjs'
 
 const stringifyJson = stringify(sort)
 
 /** The parse-error response (`-32700`, `id: null`) for a malformed input line. */
-/** @type {Response} */
-const parseErrorResponse = { jsonrpc, error: parseError, id: null }
+const parseErrorResponse = errorResponseOf(null)(parseError)
 
 /** An internal-error response (`-32603`) carrying `id`.
  * @type {(id: Response['id']) => Response}
  */
-const internalErrorResponse = id => ({ jsonrpc, error: internalError, id })
+const internalErrorResponse = id => errorResponseOf(id)(internalError)
 
 /** Encodes a response as a newline-terminated UTF-8 line and writes it to `stdout`.
  * @type {(resp: Response) => Effect<Write, void, IoChannel>}

package/fjs/protocol/mcp/stdio/proof.f.mjs

@@ -79,7 +79,7 @@ export const proof = {
     // `eofImmediately` above pins it as the clean shutdown it should be.
     readFailurePropagates: () => {
         const runner = mockRun(/** @type {Parameters<typeof mockRun<Read | Write, undefined>>[0]} */ ({
-            read: () => (/** @type {undefined} */ s) => [s, error(/** @type {const} */ (['notImplemented', 'read']))],
+            read: () => (/** @type {undefined} */ s) => [s, error(['notImplemented', 'read'])],
             write: () => (/** @type {undefined} */ s) => [s, ok(undefined)],
         }))
         const [, result] = runner(undefined)(stdioTransport(echoStep))
@@ -95,7 +95,7 @@ export const proof = {
         const runner = mockRun(/** @type {Parameters<typeof mockRun<Read | Write, readonly number[]>>[0]} */ ({
             read: () => (/** @type {readonly number[]} */ s) =>
                 s.length === 0
-                    ? [s, error(/** @type {const} */ (['notImplemented', 'read']))]
+                    ? [s, error(['notImplemented', 'read'])]
                     : [s.slice(1), ok(s[0])],
             write: () => (/** @type {readonly number[]} */ s) => [s, ok(undefined)],
         }))

package/fjs/protocol/mcp/types.d.ts

@@ -48,7 +48,7 @@ export type ToolEntry<O extends Operation> = {
  * **`never` is a claim, not an absence.** The handler behind this does perform
  * effects and they can fail — a session-state read is dispatched by a runner
  * that may decline it. It says `never` because it has *absorbed* those: a
- * request's failure becomes `_errResponse(id)(internalError)` and a
+ * request's failure becomes `errorResponseOf(id)(internalError)` and a
  * notification's is dropped, there being no frame to put it in. Spelling that
  * as `Effect<…, never>` puts the decision in the type where a reader can
  * disagree with it, which an opaque payload could not.
@@ -62,9 +62,21 @@ export type Initializing = readonly ['initializing'];
 export type InitializedState = true;
 /** The three phases of an MCP session. */
 export type McpSessionState = Uninitialized | Initializing | readonly ['initialized', InitializedState];
+/**
+ * The protocol revisions a server supports, **latest first** and non-empty by
+ * construction — the tuple's head is what an unsupported request is answered
+ * with, so "the server supports nothing" is not a state that can be reached.
+ */
+export type ProtocolVersions = readonly [string, ...readonly string[]];
 /** Static configuration supplied by the server implementer. */
 export type McpConfig = {
     readonly serverInfo: Implementation;
     readonly capabilities: ServerCapabilities;
-    readonly protocolVersion: string;
+    /**
+     * Every revision this server speaks, latest first. `initialize` answers
+     * with the client's requested version when it is in this list and with the
+     * head — the latest supported one — otherwise, which is the counter-proposal
+     * the lifecycle spec prescribes.
+     */
+    readonly protocolVersions: ProtocolVersions;
 };

package/fjs/text/utf8/module.f.mjs

@@ -19,6 +19,7 @@ import {
     isValidCodePoint,
 } from '../code_point/module.f.mjs'
 import { msb, u8List, length } from '../../types/bit_vec/module.f.mjs'
+import { contains } from '../../types/range/module.f.mjs'
 import { codePointListToString } from '../utf16/module.f.mjs'
 
 /**
@@ -43,6 +44,31 @@ const lead3Mask = 0b0000_1111
 const lead4Tag = 0b1111_0000
 const lead4Mask = 0b0000_0111
 
+const isInU8Range = contains(0x00, 0xff)
+
+/**
+ * Whether `i` is a byte this decoder can be handed.
+ *
+ * `U8` is just `number`, so neither half is redundant. The dispatch below
+ * partitions only the *integers* in `0x00`–`0xff` — below `contTag`, a
+ * continuation, or one of the leads, with no gap — so a fraction falls between
+ * two of those and would be misclassified rather than rejected: emitted as a
+ * code point when it is below `contTag`, tagged with a fractional payload when
+ * it is not. Worse where the payload arithmetic reaches it, since the bitwise
+ * operators truncate silently: a fractional continuation byte would decode to
+ * the very code point its integer part spells, reporting nothing.
+ *
+ * The range half is not carrying `NaN` — `contains` is written positively, so
+ * `isInU8Range(NaN)` is already `false`. `Number.isInteger`'s own job here is
+ * the *in-range* fraction, which no bound can reach.
+ *
+ * This mirrors `u16` in `../utf16/module.f.mjs`, which carries the same check
+ * for the same reason; the two differ only in their bounds.
+ *
+ * @type {(i: number) => boolean}
+ */
+const u8 = i => Number.isInteger(i) && isInU8Range(i)
+
 /**
  * Encodes the low six bits of `x` as a UTF-8 continuation byte.
  *
@@ -199,7 +225,7 @@ export const utf8StateToError = state => {
  * @type {StateScan<number, Utf8State, readonly I32[]>}
  */
 export const utf8ByteToCodePointOp = (byte, state) => {
-    if (byte < 0x00 || byte > 0xff) {
+    if (!u8(byte)) {
         return [[errorMask], state]
     }
     if (state === null) return restart([])(byte)

package/fjs/text/utf8/proof.f.mjs

@@ -82,6 +82,43 @@ export const proof = {
         () => {
             const result = stringify(utf8ByteToCodePointOp(0x80, [0xf8, 0x80]))
             assertEq(result, '[[-2147483136,-2147483520],null]')
+        },
+        // `U8` is just `number`, so a non-integer in [0x00, 0xff] is a
+        // possible (if malformed) input. The dispatch partitions only the
+        // integers in that range, so a fraction has to be rejected here rather
+        // than misclassified: below `contTag` it would otherwise be emitted as
+        // a code point, and above it tagged with a fractional payload.
+        () => {
+            const result = stringify(toArray(toCodePointList([1.5])))
+            assertEq(result, '[2147483648]')
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([200.5])))
+            assertEq(result, '[2147483648]')
+        },
+        // `NaN` is flagged either way — the old guard let it past and the
+        // payload arithmetic tagged it anyway, as `errorMask | 0`. Pinned for
+        // the spelling: rejecting it up front gives the canonical `errorMask`
+        // rather than its `| 0` form.
+        () => {
+            const result = stringify(toArray(toCodePointList([NaN])))
+            assertEq(result, '[2147483648]')
+        },
+        // A fractional continuation byte is the case that hides: the bitwise
+        // payload arithmetic truncates it, so `C3 A9.5` decoded as U+00E9 —
+        // the same character `C3 A9` spells — with nothing reported. It is now
+        // invalid on its own, and the pending lead is flagged incomplete.
+        () => {
+            const result = stringify(toArray(toCodePointList([0xc3, 0xa9])))
+            assertEq(result, '[233]')
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([0xc3, 169.5])))
+            assertEq(result, '[2147483648,-2147483453]')
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([0xf0, 0x90, 128.5])))
+            assertEq(result, '[2147483648,-2147483120]')
         }
     ],
     fromCodePointList: [

package/fjs/types/array/module.f.mjs

@@ -6,7 +6,7 @@
  * @import { Tuple } from './types.ts'
  */
 
-import { fromUndefined, map } from '../nullable/module.f.mjs'
+import { fromUndefined } from '../nullable/module.f.mjs'
 
 /**
  * @type {(value: unknown) => value is readonly unknown[]}
@@ -61,6 +61,11 @@ export const last = a => at(a.length - 1)(a)
  * through `fromUndefined`, so it reads a *stored* `null` or `undefined`
  * element as absence. `[null]` is not empty, but `first` says it is.
  *
+ * For the same reason `splitFirst`/`splitLast` take their element by index
+ * rather than projecting `first`/`last` through `nullable`'s `map`: their
+ * result tells "present and nullish" apart from "empty" — `[null, []]` is not
+ * `null` — where `at`/`first`/`last`, answering `T | null`, cannot.
+ *
  * @type {<T, R>(f: (a: readonly T[]) => R) => (a: readonly T[]) => R | null}
  */
 const onNonEmpty = f => a => a.length === 0 ? null : f(a)
@@ -70,24 +75,26 @@ const onNonEmpty = f => a => a.length === 0 ? null : f(a)
  */
 export const tail = onNonEmpty(uncheckTail)
 
+/**
+ * @type {<T>(a: readonly T[]) => readonly [T, readonly T[]]}
+ */
+const uncheckSplitFirst = a => [a[0], uncheckTail(a)]
+
 /**
  * @type {<T>(a: readonly T[]) => readonly [T, readonly T[]] | null}
  */
-export const splitFirst = a => {
-    /** @typedef {(typeof a)[0]} T */
-    const split = (/** @type {T} */first) =>
-        /** @type {const} */([first, uncheckTail(a)])
-    return map(split)(first(a))
-}
+export const splitFirst = onNonEmpty(uncheckSplitFirst)
 
 /** @type {<T>(a: readonly T[]) => readonly T[] | null} */
 export const head = onNonEmpty(uncheckHead)
 
+/**
+ * @type {<T>(a: readonly T[]) => readonly [readonly T[], T]}
+ */
+const uncheckSplitLast = a => [uncheckHead(a), a[a.length - 1]]
+
 /** @type {<T>(a: readonly T[]) => readonly [readonly T[], T] | null} */
-export const splitLast = a => {
-    const lastA = last(a)
-    return lastA === null ? null : [uncheckHead(a), lastA]
-}
+export const splitLast = onNonEmpty(uncheckSplitLast)
 
 /**
  * An empty immutable array.

package/fjs/types/array/proof.f.mjs

@@ -1,7 +1,7 @@
 import { at, first, last, head, tail, splitFirst, splitLast, empty } from './module.f.mjs'
 import { stringify as jsonStringify } from '../../media/json/module.f.mjs'
 import { sort } from '../object/module.f.mjs'
-import { assertEq, assertNotNullish } from '../../asserts/module.f.mjs'
+import { assertEq, assertNotNullish, assertStructurallySame } from '../../asserts/module.f.mjs'
 
 const stringify = jsonStringify(sort)
 
@@ -74,6 +74,20 @@ export const proof = {
             const result = splitFirst([])
             assertEq(result, null)
         },
+        // A stored nullish element is an element: `[null]` has a first one,
+        // even though `first([null])` cannot say so.
+        () => {
+            const result = splitFirst([null])
+            assertStructurallySame(result, [null, []])
+        },
+        () => {
+            const result = splitFirst([undefined])
+            assertStructurallySame(result, [undefined, []])
+        },
+        () => {
+            const result = splitFirst([undefined, 20, 300])
+            assertStructurallySame(result, [undefined, [20, 300]])
+        },
     ],
     splitLast: [
         () => {
@@ -84,6 +98,18 @@ export const proof = {
         () => {
             const result = splitLast([])
             assertEq(result, null)
+        },
+        () => {
+            const result = splitLast([null])
+            assertStructurallySame(result, [[], null])
+        },
+        () => {
+            const result = splitLast([undefined])
+            assertStructurallySame(result, [[], undefined])
+        },
+        () => {
+            const result = splitLast([1, 20, undefined])
+            assertStructurallySame(result, [[1, 20], undefined])
         }
     ],
     empty: () => {

package/fjs/types/bigfloat/module.f.d.mts

@@ -3,12 +3,28 @@
  *
  * @module
  *
- * @import { BigFloat } from './types.ts'
+ * @import { BigFloat, Format } from './types.ts'
+ * @import { Nullable } from '../nullable/types.ts'
  */
-import type { BigFloat } from './types.ts';
+import type { BigFloat, Format } from './types.ts';
+import type { Nullable } from '../nullable/types.ts';
 export type _BigFloatWithRemainder = readonly [BigFloat, bigint];
 /** @type {(_: BigFloat) => (mul: bigint) => BigFloat} */
 export declare const multiply: (_: BigFloat) => (mul: bigint) => BigFloat;
+/**
+ * IEEE-754 binary64 — the format of a JavaScript `number`.
+ *
+ * Both exponents are *ulp* exponents, the same units a `BigFloat`'s own
+ * exponent is in: `minExp` is the exponent of the smallest subnormal
+ * (`2^-1074`), not the smallest normal's `-1022`, and `maxExp` is the exponent
+ * the largest finite value carries once its mantissa fills `precision` bits
+ * (`(2^53 - 1) * 2^971`). The two conventions differ by the precision, and a
+ * `Format` that mixes them is off by exactly that much, so this one never
+ * leaves `BigFloat`'s units.
+ *
+ * @type {Format}
+ */
+export declare const binary64: Format;
 /**
  * Converts a decimal big-float `m * 10^e` into the nearest binary big-float,
  * rounding ties to even.
@@ -18,17 +34,40 @@ export declare const multiply: (_: BigFloat) => (mul: bigint) => BigFloat;
  * even when rounding carries out of the top bit.
  *
  * The **exponent is unbounded**: this is the correctly-rounded 53-bit value,
- * not a `number`. Nothing here knows binary64's exponent range, so a result
- * is neither turned into an infinity when it is too large for a `double` nor
- * cut down to the fewer-than-53 bits a subnormal actually carries. A consumer
- * that rounds one of these results onto the subnormal grid therefore rounds
- * twice and can land an ulp away from the correctly-rounded `double`: reaching
- * the subnormal range needs a single rounding to a precision chosen from the
- * target exponent, which this function does not offer yet.
+ * not a `number`. A result too large for a `double` is not turned into an
+ * infinity, and one below the normal range keeps all 53 bits instead of the
+ * fewer a subnormal carries. That is the honest answer when the target is not
+ * a `double` — and the wrong starting point when it is, because rounding one
+ * of these results onto the subnormal grid rounds twice and can land an ulp
+ * away from the correctly-rounded `double`. Use {@link tryDecToFormat} with
+ * {@link binary64} for that; it rounds once.
  *
  * @type {(dec: BigFloat) => BigFloat}
  */
 export declare const decToBin: (dec: BigFloat) => BigFloat;
+/**
+ * Converts a decimal big-float `m * 10^e` into the nearest value of `format`,
+ * rounding ties to even, or `null` when the magnitude is too large for the
+ * format to hold — the caller decides what an overflow becomes, since
+ * `BigFloat` has no encoding for an infinity.
+ *
+ * The result is a multiple of `2^format.minExp` carrying **at most**
+ * `format.precision` significant bits: exactly that many above the format's
+ * normal range, fewer below it, and `[0n, 0]` when the value rounds away
+ * entirely. Underflow to zero is not a separate signal, because `[0n, 0]` is
+ * the correctly-rounded answer rather than a failure to produce one.
+ *
+ * The rounding happens **once**, on the exact decimal, which is the whole
+ * point of taking the format rather than post-processing {@link decToBin}. The
+ * grid it rounds onto is `2^max(minExp, e + 1)`, where `e + 1` is the exponent
+ * a full-precision result would carry: full precision above the normal range's
+ * floor, shrinking by a bit per binade below it, down to none at all. Rounding
+ * to `precision` bits first and onto that grid afterwards is two roundings,
+ * and the first can manufacture a midpoint the true value only approached.
+ *
+ * @type {(format: Format) => (dec: BigFloat) => Nullable<BigFloat>}
+ */
+export declare const tryDecToFormat: (format: Format) => (dec: BigFloat) => Nullable<BigFloat>;
 export declare const proof: {
     normalizeMantissaZero: () => void;
 };