functionalscript 0.46.0 → 0.47.0

package/fjs/path/proof.f.mjs

@@ -1,4 +1,4 @@
-import { concat, isProperPrefix, join, normalize, relativize, toPosix } from "./module.f.mjs"
+import { concat, escapes, isProperPrefix, join, normalize, parse, relativize, root, toPosix } from "./module.f.mjs"
 import { assertEq } from '../asserts/module.f.mjs'
 
 const normalizeTest = [
@@ -18,6 +18,193 @@ const normalizeTest = [
         const norm = normalize("../../dir/../file.json")
         assertEq(norm, "../../file.json")
     },
+    // A root survives normalization: it is not a segment, so it is not one of
+    // the empty ones the fold drops.
+    () => {
+        const norm = normalize("/a/b")
+        assertEq(norm, "/a/b")
+    },
+    () => {
+        const norm = normalize("//srv/share")
+        assertEq(norm, "//srv/share")
+    },
+    () => {
+        const norm = normalize("/")
+        assertEq(norm, "/")
+    },
+    // `..` has no parent of the root to name, so it is dropped — while the
+    // same input without a root keeps it.
+    () => {
+        const norm = normalize("/a/../..")
+        assertEq(norm, "/")
+    },
+    () => {
+        const norm = normalize("a/../..")
+        assertEq(norm, "..")
+    },
+    // A drive letter is an ordinary segment and needs no case of its own.
+    () => {
+        const norm = normalize("C:/a/b")
+        assertEq(norm, "C:/a/b")
+    },
+    () => {
+        const norm = normalize("C:\\a\\b")
+        assertEq(norm, "C:/a/b")
+    },
+    // An *interior* empty segment is still noise: only the leading one is a root.
+    () => {
+        const norm = normalize("a//b")
+        assertEq(norm, "a/b")
+    },
+    () => {
+        const norm = normalize("")
+        assertEq(norm, "")
+    },
+]
+
+const escapesTest = [
+    // A `..` that cancels a real segment does not escape; one with nothing
+    // left to cancel does. `parse` cannot answer this — it folds with the root
+    // in place, which is exactly what removes the escaping `..`.
+    () => {
+        assertEq(escapes("/a/../b"), false)
+    },
+    () => {
+        assertEq(escapes("/../b"), true)
+    },
+    () => {
+        assertEq(escapes("a/../../b"), true)
+    },
+    () => {
+        assertEq(escapes("a/b/../c"), false)
+    },
+    // Taking the root off is not the same as dropping one leading `/`: these
+    // remainders read as rooted again, and a second fold would clamp the very
+    // `..` being looked for.
+    () => {
+        assertEq(escapes("///../secret"), true)
+    },
+    () => {
+        assertEq(escapes("/C:/../../secret"), true)
+    },
+    () => {
+        assertEq(escapes("//../secret"), true)
+    },
+    () => {
+        assertEq(escapes("C:/../secret"), true)
+    },
+    () => {
+        assertEq(escapes(""), false)
+    },
+]
+
+const rootTest = [
+    () => {
+        const r = root("a/b")
+        assertEq(r, "")
+    },
+    () => {
+        const r = root("/a/b")
+        assertEq(r, "/")
+    },
+    () => {
+        const r = root("//srv/share")
+        assertEq(r, "//")
+    },
+    // Three or more leading slashes are an ordinary root followed by empty
+    // segments, which is what POSIX requires; exactly two are the UNC case.
+    () => {
+        const r = root("///a")
+        assertEq(r, "/")
+    },
+    () => {
+        const norm = normalize("///a")
+        assertEq(norm, "/a")
+    },
+    // Windows spells the UNC root with backslashes.
+    () => {
+        const r = root("\\\\srv\\share")
+        assertEq(r, "//")
+    },
+    // A Windows drive is a root, so `..` cannot climb off it — `C:\\..` is
+    // `C:\\` on Windows, not the parent of the drive.
+    () => {
+        const r = root("C:/a")
+        assertEq(r, "C:/")
+    },
+    () => {
+        const r = root("c:/a")
+        assertEq(r, "c:/")
+    },
+    () => {
+        const norm = normalize("C:/..")
+        assertEq(norm, "C:/")
+    },
+    () => {
+        const norm = normalize("C:/a/../../..")
+        assertEq(norm, "C:/")
+    },
+    () => {
+        const norm = normalize("C:/")
+        assertEq(norm, "C:/")
+    },
+    // Only the absolute spelling roots. A bare `C:` and the drive-relative
+    // `C:foo` — the current directory *on* drive C — stay ordinary segments,
+    // and a prefix that is not a single letter is not a drive at all.
+    () => {
+        const r = root("C:")
+        assertEq(r, "")
+    },
+    () => {
+        const r = root("C:a/b")
+        assertEq(r, "")
+    },
+    () => {
+        const r = root("1:/x")
+        assertEq(r, "")
+    },
+    () => {
+        const r = root("ab:/x")
+        assertEq(r, "")
+    },
+    // The UNC root stops at `//`: `server/share` are ordinary segments, so a
+    // `..` can still climb past a share. Parsing them into the root would let
+    // a `../` fold into it, which is what a root must never allow.
+    () => {
+        const c = concat("//srv/share")("../..")
+        assertEq(c, "//")
+    },
+    () => {
+        const p = parse("//a/b")
+        assertEq(join(...p), "a/b")
+    },
+]
+
+const parseTest = [
+    // `parse` answers with segments only, so an absolute and a relative path
+    // that name the same segments are indistinguishable through it. `root`
+    // is what tells them apart.
+    () => {
+        const p = parse("/a/b")
+        assertEq(join(...p), "a/b")
+    },
+    () => {
+        const p = parse("a/b")
+        assertEq(join(...p), "a/b")
+    },
+    // The root still reaches the fold: a `..` that would escape it is dropped.
+    () => {
+        const p = parse("/..")
+        assertEq(p.length, 0)
+    },
+    () => {
+        const p = parse("..")
+        assertEq(join(...p), "..")
+    },
+    () => {
+        const p = parse("../..")
+        assertEq(join(...p), "../..")
+    },
 ]
 
 const concatTest = [
@@ -33,6 +220,115 @@ const concatTest = [
         const c = concat("a/../b/..")("c")
         assertEq(c, "c")
     },
+    // The root comes from `a`, so `concat` no longer turns an absolute path
+    // into a relative one. This is the shape `fjs compile` resolves imports
+    // with: `concat(concat(path)('..'))(importPath)`.
+    () => {
+        const c = concat("/a/b/m.f.js")("..")
+        assertEq(c, "/a/b")
+    },
+    () => {
+        const c = concat("//srv/share/m.f.js")("..")
+        assertEq(c, "//srv/share")
+    },
+    () => {
+        const c = concat("/a/b")("../c")
+        assertEq(c, "/a/c")
+    },
+    () => {
+        const c = concat("/")("y")
+        assertEq(c, "/y")
+    },
+    () => {
+        const c = concat("/a")("../..")
+        assertEq(c, "/")
+    },
+    () => {
+        const c = concat("C:/a/b/m.f.js")("..")
+        assertEq(c, "C:/a/b")
+    },
+    () => {
+        const c = concat(concat("C:/a/m.f.js")(".."))("../../lib.f.js")
+        assertEq(c, "C:/lib.f.js")
+    },
+    // A bare drive is not a root, and `concat` does not make it one: joined
+    // with a separator, `C:` and `dir` would be the drive root `C:/dir`
+    // instead of the drive-relative `C:dir` — a different place on the disk.
+    () => {
+        const c = concat("C:")("dir")
+        assertEq(c, "C:dir")
+    },
+    () => {
+        const r = root(concat("C:")("dir"))
+        assertEq(r, "")
+    },
+    // The drive-absolute spelling is still reachable, and still a root.
+    () => {
+        const c = concat("C:/")("dir")
+        assertEq(c, "C:/dir")
+    },
+    () => {
+        const r = root(concat("C:/")("dir"))
+        assertEq(r, "C:/")
+    },
+    // Only a real bare drive skips the separator: the letter's case does not
+    // matter, a non-letter is not a drive, and `C:foo` is longer than a bare
+    // drive — reading it as one would join it to `C:foox`.
+    () => {
+        const c = concat("ab:")("dir")
+        assertEq(c, "ab:/dir")
+    },
+    () => {
+        const c = concat("c:")("dir")
+        assertEq(c, "c:dir")
+    },
+    () => {
+        const c = concat("1:")("dir")
+        assertEq(c, "1:/dir")
+    },
+    () => {
+        const c = concat("C:foo")("x")
+        assertEq(c, "C:foo/x")
+    },
+    () => {
+        const c = concat("C:")("/abs")
+        assertEq(c, "/abs")
+    },
+    // The left side is folded before its root is read, so every spelling of a
+    // bare drive is one — testing the unfolded text caught only the literal.
+    () => {
+        const c = concat("./C:")("dir")
+        assertEq(c, "C:dir")
+    },
+    () => {
+        const c = concat("x/../C:")("dir")
+        assertEq(c, "C:dir")
+    },
+    // Whatever `a` spells, appending a relative `b` leaves its root alone.
+    () => {
+        ["C:", "./C:", "x/../C:", "C:/", "./a", "/a", "//a", "", "."].forEach(a =>
+            assertEq(root(concat(a)("dir")), root(normalize(a)), a))
+    },
+    // An absolute `b` names a path on its own, so it replaces `a` rather than
+    // being appended to it.
+    () => {
+        const c = concat("a")("/abs/x")
+        assertEq(c, "/abs/x")
+    },
+    () => {
+        const c = concat("/a/b")("//srv/share")
+        assertEq(c, "//srv/share")
+    },
+    // The separator `concat` inserts is not a root: with an empty `a`, a
+    // leading `..` in `b` still has nothing to escape.
+    () => {
+        const c = concat("")("../lib.f.js")
+        assertEq(c, "../lib.f.js")
+    },
+    () => {
+        const c = concat("")("./lib.f.js")
+        assertEq(c, "lib.f.js")
+    },
 ]
 
 const joinTest = [
@@ -122,4 +418,4 @@ const isProperPrefixTest = [
     },
 ]
 
-export const proof = { normalizeTest, concatTest, joinTest, relativizeTest, toPosixTest, isProperPrefixTest }
+export const proof = { normalizeTest, escapesTest, rootTest, parseTest, concatTest, joinTest, relativizeTest, toPosixTest, isProperPrefixTest }

package/fjs/protocol/json_rpc/module.f.d.mts

@@ -15,74 +15,79 @@
  * @module
  *
  * @import { Unknown } from '../../media/json/types.ts'
- * @import { Id, RpcError, Handlers, Response } from './types.ts'
+ * @import { Id, RpcError, Handlers, Response, SuccessResponse, ErrorResponse } from './types.ts'
  */
 import type { Unknown } from '../../media/json/types.ts';
-import type { RpcError, Handlers, Response } from './types.ts';
+import type { Id, RpcError, Handlers, Response } from './types.ts';
 export declare const jsonrpc: '2.0';
 /** Request/response identifier: a string, a number, or `null`. */
-export declare const _id: import("../../types/rtti/types.ts").Or<[import("../../types/rtti/types.ts")._Type0<"string">, import("../../types/rtti/types.ts")._Type0<"number">, null]>;
+export declare const _id: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, import("../../types/rtti/types.ts")._Type0<"number">, null]>;
 /**
  * A request or notification envelope. `id` present → request (a response is
  * expected); `id` absent → notification (no response). `params` is optional.
  *
+ * `open`, as every envelope in this module is: a bare struct is closed, and a
+ * peer implementing a later revision of the protocol may send members this one
+ * does not name — rejecting those outright is the opposite of what a wire
+ * format wants. Do not drop the wrapper.
+ *
  * https://www.jsonrpc.org/specification#request_object
  */
-export declare const request: {
+export declare const request: import("../../types/rtti/types.ts").Rest<{
     readonly jsonrpc: "2.0";
     readonly method: import("../../types/rtti/types.ts")._Type0<"string">;
     readonly params: import("../../types/rtti/types.ts").Or<readonly [() => readonly ['or', typeof import("../../media/json/rtti/module.f.mjs").primitive, typeof import("../../media/json/rtti/module.f.mjs").object, typeof import("../../media/json/rtti/module.f.mjs").array], undefined]>;
-    readonly id: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts").Or<[import("../../types/rtti/types.ts")._Type0<"string">, import("../../types/rtti/types.ts")._Type0<"number">, null]>, undefined]>;
-};
-/** The JSON-RPC error object. */
-export declare const error: {
+    readonly id: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, import("../../types/rtti/types.ts")._Type0<"number">, null]>, undefined]>;
+}, import("../../types/rtti/types.ts").Unknown>;
+/** The JSON-RPC error object — `open`, for the reason {@link request} gives. */
+export declare const error: import("../../types/rtti/types.ts").Rest<{
     readonly code: import("../../types/rtti/types.ts")._Type0<"number">;
     readonly message: import("../../types/rtti/types.ts")._Type0<"string">;
     readonly data: import("../../types/rtti/types.ts").Or<readonly [() => readonly ['or', typeof import("../../media/json/rtti/module.f.mjs").primitive, typeof import("../../media/json/rtti/module.f.mjs").object, typeof import("../../media/json/rtti/module.f.mjs").array], undefined]>;
-};
-export declare const successResponse: {
+}, import("../../types/rtti/types.ts").Unknown>;
+export declare const successResponse: import("../../types/rtti/types.ts").Rest<{
     readonly jsonrpc: "2.0";
     readonly result: () => readonly ['or', typeof import("../../media/json/rtti/module.f.mjs").primitive, typeof import("../../media/json/rtti/module.f.mjs").object, typeof import("../../media/json/rtti/module.f.mjs").array];
-    readonly id: import("../../types/rtti/types.ts").Or<[import("../../types/rtti/types.ts")._Type0<"string">, import("../../types/rtti/types.ts")._Type0<"number">, null]>;
-};
-export declare const errorResponse: {
+    readonly id: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, import("../../types/rtti/types.ts")._Type0<"number">, null]>;
+}, import("../../types/rtti/types.ts").Unknown>;
+export declare const errorResponse: import("../../types/rtti/types.ts").Rest<{
     readonly jsonrpc: "2.0";
-    readonly error: {
+    readonly error: import("../../types/rtti/types.ts").Rest<{
         readonly code: import("../../types/rtti/types.ts")._Type0<"number">;
         readonly message: import("../../types/rtti/types.ts")._Type0<"string">;
         readonly data: import("../../types/rtti/types.ts").Or<readonly [() => readonly ['or', typeof import("../../media/json/rtti/module.f.mjs").primitive, typeof import("../../media/json/rtti/module.f.mjs").object, typeof import("../../media/json/rtti/module.f.mjs").array], undefined]>;
-    };
-    readonly id: import("../../types/rtti/types.ts").Or<[import("../../types/rtti/types.ts")._Type0<"string">, import("../../types/rtti/types.ts")._Type0<"number">, null]>;
-};
+    }, import("../../types/rtti/types.ts").Unknown>;
+    readonly id: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, import("../../types/rtti/types.ts")._Type0<"number">, null]>;
+}, import("../../types/rtti/types.ts").Unknown>;
 /**
  * A response envelope: either a success (`result`) or an error (`error`).
  * Derived from the rtti schema via `Ts<>` — the same declaration is the
- * runtime decoder and the static type, with no drift. rtti structs are open
+ * runtime decoder and the static type, with no drift. Both arms say `open`
  * (extra keys allowed), so "result XOR error" is not enforced at runtime; in
  * practice the dispatcher only ever constructs one or the other.
  *
  * https://www.jsonrpc.org/specification#response_object
  */
-export declare const response: import("../../types/rtti/types.ts").Or<[{
+export declare const response: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts").Rest<{
     readonly jsonrpc: "2.0";
     readonly result: () => readonly ['or', typeof import("../../media/json/rtti/module.f.mjs").primitive, typeof import("../../media/json/rtti/module.f.mjs").object, typeof import("../../media/json/rtti/module.f.mjs").array];
-    readonly id: import("../../types/rtti/types.ts").Or<[import("../../types/rtti/types.ts")._Type0<"string">, import("../../types/rtti/types.ts")._Type0<"number">, null]>;
-}, {
+    readonly id: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, import("../../types/rtti/types.ts")._Type0<"number">, null]>;
+}, import("../../types/rtti/types.ts").Unknown>, import("../../types/rtti/types.ts").Rest<{
     readonly jsonrpc: "2.0";
-    readonly error: {
+    readonly error: import("../../types/rtti/types.ts").Rest<{
         readonly code: import("../../types/rtti/types.ts")._Type0<"number">;
         readonly message: import("../../types/rtti/types.ts")._Type0<"string">;
         readonly data: import("../../types/rtti/types.ts").Or<readonly [() => readonly ['or', typeof import("../../media/json/rtti/module.f.mjs").primitive, typeof import("../../media/json/rtti/module.f.mjs").object, typeof import("../../media/json/rtti/module.f.mjs").array], undefined]>;
-    };
-    readonly id: import("../../types/rtti/types.ts").Or<[import("../../types/rtti/types.ts")._Type0<"string">, import("../../types/rtti/types.ts")._Type0<"number">, null]>;
-}]>;
+    }, import("../../types/rtti/types.ts").Unknown>;
+    readonly id: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, import("../../types/rtti/types.ts")._Type0<"number">, null]>;
+}, import("../../types/rtti/types.ts").Unknown>]>;
 /** Decodes an untrusted value as a JSON-RPC request / notification. */
-export declare const decodeRequest: import("../../types/rtti/parse/types.ts").Parse<{
+export declare const decodeRequest: import("../../types/rtti/parse/types.ts").Parse<import("../../types/rtti/types.ts").Rest<{
     readonly jsonrpc: "2.0";
     readonly method: import("../../types/rtti/types.ts")._Type0<"string">;
     readonly params: import("../../types/rtti/types.ts").Or<readonly [() => readonly ['or', typeof import("../../media/json/rtti/module.f.mjs").primitive, typeof import("../../media/json/rtti/module.f.mjs").object, typeof import("../../media/json/rtti/module.f.mjs").array], undefined]>;
-    readonly id: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts").Or<[import("../../types/rtti/types.ts")._Type0<"string">, import("../../types/rtti/types.ts")._Type0<"number">, null]>, undefined]>;
-}>;
+    readonly id: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, import("../../types/rtti/types.ts")._Type0<"number">, null]>, undefined]>;
+}, import("../../types/rtti/types.ts").Unknown>>;
 /**
  * Builds an `RpcError` with the given `code` and `message` (no `data`).
  * @type {(code: number) => (message: string) => RpcError}
@@ -113,6 +118,38 @@ export declare const internalError: import("../../types/rtti/ts/types.ts").Struc
     readonly message: import("../../types/rtti/types.ts")._Type0<"string">;
     readonly data: import("../../types/rtti/types.ts").Or<readonly [() => readonly ['or', typeof import("../../media/json/rtti/module.f.mjs").primitive, typeof import("../../media/json/rtti/module.f.mjs").object, typeof import("../../media/json/rtti/module.f.mjs").array], undefined]>;
 }>;
+/**
+ * The error half of the response envelope: `{ jsonrpc, error, id }`.
+ *
+ * Exported as one of a pair with {@link successResponseOf} — the `Response`
+ * schema, `jsonrpc`, `Id` and `RpcError` are all owned here, so the two shapes
+ * built from them are too. Every protocol layered on this module needs both
+ * (`fjs/protocol/mcp` and its stdio transport are the two consumers today),
+ * and a private constructor is what made each of them re-roll its own.
+ *
+ * It answers the `Response` union rather than {@link ErrorResponse}, the branch
+ * it always builds. That is deliberate: every consumer in the tree is a
+ * dispatcher answering either arm — `dispatch` here, `mcpStep` and the stdio
+ * transport in `fjs/protocol/mcp` — and `Handle` is defined in terms of the
+ * union, so the branch type would have to be widened again at each of them.
+ * {@link ErrorResponse} is exported for a caller that does want it.
+ *
+ * @type {(id: Id) => (error: RpcError) => Response}
+ */
+export declare const errorResponseOf: (id: Id) => (error: RpcError) => Response;
+/**
+ * The success half of the response envelope: `{ jsonrpc, result, id }`.
+ *
+ * The `…Of` suffix pairs with {@link errorResponseOf}, and both name the
+ * already-exported `successResponse` / `errorResponse` schemas they build a
+ * value of.
+ *
+ * It answers the union for the reason {@link errorResponseOf} does, and
+ * {@link SuccessResponse} names the branch for a caller that wants it.
+ *
+ * @type {(id: Id) => (result: Unknown) => Response}
+ */
+export declare const successResponseOf: (id: Id) => (result: Unknown) => Response;
 /**
  * Dispatches an already-parsed JSON-RPC value against `handlers`.
  *

package/fjs/protocol/json_rpc/module.f.mjs

@@ -15,11 +15,11 @@
  * @module
  *
  * @import { Unknown } from '../../media/json/types.ts'
- * @import { Id, RpcError, Handlers, Response } from './types.ts'
+ * @import { Id, RpcError, Handlers, Response, SuccessResponse, ErrorResponse } from './types.ts'
  */
 
 import { at } from '../../types/object/module.f.mjs'
-import { number, string, or, option } from '../../types/rtti/module.f.mjs'
+import { number, open, string, or, option } from '../../types/rtti/module.f.mjs'
 import { parse } from '../../types/rtti/parse/module.f.mjs'
 import { unknown } from '../../media/json/rtti/module.f.mjs'
 
@@ -32,29 +32,34 @@ export const _id = or(string, number, null)
  * A request or notification envelope. `id` present → request (a response is
  * expected); `id` absent → notification (no response). `params` is optional.
  *
+ * `open`, as every envelope in this module is: a bare struct is closed, and a
+ * peer implementing a later revision of the protocol may send members this one
+ * does not name — rejecting those outright is the opposite of what a wire
+ * format wants. Do not drop the wrapper.
+ *
  * https://www.jsonrpc.org/specification#request_object
  */
-export const request = /** @type {const} */ ({
+export const request = open(/** @type {const} */ ({
     jsonrpc,
     method: string,
     params: option(unknown),
     id: option(_id),
-})
+}))
 
-/** The JSON-RPC error object. */
-export const error = /** @type {const} */ ({
+/** The JSON-RPC error object — `open`, for the reason {@link request} gives. */
+export const error = open(/** @type {const} */ ({
     code: number,
     message: string,
     data: option(unknown),
-})
+}))
 
-export const successResponse = /** @type {const} */ ({ jsonrpc, result: unknown, id: _id })
-export const errorResponse = /** @type {const} */ ({ jsonrpc, error, id: _id })
+export const successResponse = open(/** @type {const} */ ({ jsonrpc, result: unknown, id: _id }))
+export const errorResponse = open(/** @type {const} */ ({ jsonrpc, error, id: _id }))
 
 /**
  * A response envelope: either a success (`result`) or an error (`error`).
  * Derived from the rtti schema via `Ts<>` — the same declaration is the
- * runtime decoder and the static type, with no drift. rtti structs are open
+ * runtime decoder and the static type, with no drift. Both arms say `open`
  * (extra keys allowed), so "result XOR error" is not enforced at runtime; in
  * practice the dispatcher only ever constructs one or the other.
  *
@@ -78,8 +83,39 @@ export const methodNotFound = rpcError(-32601)('Method not found')
 export const invalidParams = rpcError(-32602)('Invalid params')
 export const internalError = rpcError(-32603)('Internal error')
 
-/** @type {(id: Id) => (error: RpcError) => Response} */
-const errorResponseOf = id => error => ({ jsonrpc, error, id })
+/**
+ * The error half of the response envelope: `{ jsonrpc, error, id }`.
+ *
+ * Exported as one of a pair with {@link successResponseOf} — the `Response`
+ * schema, `jsonrpc`, `Id` and `RpcError` are all owned here, so the two shapes
+ * built from them are too. Every protocol layered on this module needs both
+ * (`fjs/protocol/mcp` and its stdio transport are the two consumers today),
+ * and a private constructor is what made each of them re-roll its own.
+ *
+ * It answers the `Response` union rather than {@link ErrorResponse}, the branch
+ * it always builds. That is deliberate: every consumer in the tree is a
+ * dispatcher answering either arm — `dispatch` here, `mcpStep` and the stdio
+ * transport in `fjs/protocol/mcp` — and `Handle` is defined in terms of the
+ * union, so the branch type would have to be widened again at each of them.
+ * {@link ErrorResponse} is exported for a caller that does want it.
+ *
+ * @type {(id: Id) => (error: RpcError) => Response}
+ */
+export const errorResponseOf = id => error => ({ jsonrpc, error, id })
+
+/**
+ * The success half of the response envelope: `{ jsonrpc, result, id }`.
+ *
+ * The `…Of` suffix pairs with {@link errorResponseOf}, and both name the
+ * already-exported `successResponse` / `errorResponse` schemas they build a
+ * value of.
+ *
+ * It answers the union for the reason {@link errorResponseOf} does, and
+ * {@link SuccessResponse} names the branch for a caller that wants it.
+ *
+ * @type {(id: Id) => (result: Unknown) => Response}
+ */
+export const successResponseOf = id => result => ({ jsonrpc, result, id })
 
 /**
  * Dispatches an already-parsed JSON-RPC value against `handlers`.
@@ -110,6 +146,6 @@ export const dispatch = handlers => value => {
     }
     const [t2, result] = handler(params)
     return t2 === 'ok'
-        ? { jsonrpc, result, id }
+        ? successResponseOf(id)(result)
         : errorResponseOf(id)(result)
 }

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

@@ -38,4 +38,8 @@ export declare const proof: {
         invalidRequest: () => void;
         notification: () => void;
     };
+    responseOf: {
+        success: () => void;
+        error: () => void;
+    };
 };

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

@@ -15,6 +15,9 @@ import {
     methodNotFound,
     invalidParams,
     internalError,
+    response,
+    errorResponseOf,
+    successResponseOf,
 } from './module.f.mjs'
 
 /** @type {(r: readonly [string, unknown]) => boolean} */
@@ -102,4 +105,30 @@ export const proof = {
             assertEq(r, null)
         },
     },
+
+    // The two envelope constructors are public API, so they are proven
+    // directly rather than only through `dispatch`. Each result is parsed back
+    // with this module's own `response` schema, which is the fact worth
+    // pinning: the constructor and the schema describing the shape it builds
+    // cannot drift apart.
+    responseOf: {
+        success: () => {
+            const r = successResponseOf(1)('pong')
+            assertEq(r.jsonrpc, '2.0')
+            assert('result' in r && r.result === 'pong', r)
+            assertEq(r.id, 1)
+            assert(isOk(parse(response)(r)), r)
+        },
+        // A non-`null` id on purpose: an `id` forced to `null` is a mutation
+        // this case would not see if it asked for `null` to begin with, and a
+        // string exercises the other arm of `Id` besides. `errorResponseOf`'s
+        // `null` id is covered by `dispatch.invalidRequest`.
+        error: () => {
+            const r = errorResponseOf('abc')(parseError)
+            assertEq(r.jsonrpc, '2.0')
+            assert('error' in r && r.error.code === -32700, r)
+            assertEq(r.id, 'abc')
+            assert(isOk(parse(response)(r)), r)
+        },
+    },
 }

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

@@ -7,7 +7,7 @@
  */
 import type { Unknown } from '../../media/json/types.ts';
 import type { Result } from '../../types/result/types.ts';
-import type { _id, request, error as errorSchema, response } from './module.f.mjs';
+import type { _id, request, error as errorSchema, response, successResponse, errorResponse } from './module.f.mjs';
 import type { Ts } from '../../types/rtti/ts/types.ts';
 export type Id = Ts<typeof _id>;
 export type Request = Ts<typeof request>;
@@ -15,13 +15,23 @@ export type RpcError = Ts<typeof errorSchema>;
 /**
  * A response envelope: either a success (`result`) or an error (`error`).
  * Derived from the rtti schema via `Ts<>` — the same declaration is the
- * runtime decoder and the static type, with no drift. rtti structs are open
+ * runtime decoder and the static type, with no drift. Both arms say `open`
  * (extra keys allowed), so "result XOR error" is not enforced at runtime; in
  * practice the dispatcher only ever constructs one or the other.
  *
  * https://www.jsonrpc.org/specification#response_object
  */
 export type Response = Ts<typeof response>;
+/**
+ * The success branch of {@link Response}: `result` is present, `error` is not.
+ *
+ * `successResponseOf` answers the `Response` union, not this — every consumer
+ * in the tree is a dispatcher that returns either arm. Name this where a
+ * caller genuinely holds one branch and wants `.result` without an `in` check.
+ */
+export type SuccessResponse = Ts<typeof successResponse>;
+/** The error branch of {@link Response}, the mirror of {@link SuccessResponse}. */
+export type ErrorResponse = Ts<typeof errorResponse>;
 /** A method implementation: maps `params` to a result or an `RpcError`. */
 export type Handler = (params: Unknown | undefined) => Result<Unknown, RpcError>;
 /** A `method` name → `Handler` map. */