@needmoretruth/nmts-cli 0.35.0 → 0.36.2

package/dist/download-sink.js

@@ -12,202 +12,9 @@
 // ⛔ A SINK MUST NOT KEEP THE ARRAY IT IS HANDED. The caller zeroes each run of plaintext as soon
 //    as `write` resolves, so a sink that stored the reference would hold a buffer full of zeroes
 //    and write them out. Copy, or finish with the bytes before resolving.
-import { randomBytes } from "node:crypto";
-import { createWriteStream, existsSync } from "node:fs";
-import { rename, rm } from "node:fs/promises";
-import { basename, dirname, join } from "node:path";
-import { NmtsError } from "./errors.js";
-import { handOver } from "./stdout.js";
-/** The one refusal text for a destination that is already occupied. Shared by every command. */
-function alreadyThere(destination) {
-    return new NmtsError(`${destination} already exists.`, {
-        exitCode: 4,
-        nextStep: "Nothing was written. Pass --out to choose another name, or --force to replace it.",
-    });
-}
-/**
- * Write to a file, through a temporary name beside it, renamed into place only when the whole
- * file has been proved.
- *
- * ⛔ THE TEMPORARY FILE IS IN THE SAME DIRECTORY AS THE DESTINATION, not in a system temporary
- *    directory, and that is the whole mechanism: `rename` is atomic only within one filesystem,
- *    and only an atomic rename guarantees that a reader either sees nothing under the real name or
- *    sees the finished file. A temporary directory can be — and on the machines this runs on
- *    usually is — a different filesystem, where the same call becomes copy-then-delete and a
- *    reader can catch the copy half done.
- *
- * ⛔ IT IS CREATED 0600 AND THE RENAME KEEPS THAT. The file is somebody's plaintext; it must not
- *    be readable by other accounts on the machine for the seconds it takes to download, any more
- *    than it may be afterwards.
- */
-export function fileSink(destination, options) {
-    // ⛔ Asked BEFORE the download rather than at the end, which is where the old code found out.
-    //    Fetching a file to discover it had nowhere to go spent somebody's time and the storage
-    //    network's bandwidth for a refusal that was knowable up front.
-    if (!options.force && existsSync(destination))
-        throw alreadyThere(destination);
-    const temporary = join(dirname(destination), `.${basename(destination)}.nmts-${randomBytes(6).toString("hex")}.part`);
-    let stream = null;
-    let failure = null;
-    let renamed = false;
-    // ⚠ Created on the first write rather than up front: a download that fails before it produces a
-    //   byte — a wrong key, a part on a network this build cannot read — then leaves no file at all,
-    //   not even one that appears and disappears.
-    const opened = () => {
-        if (stream !== null)
-            return stream;
-        const fresh = createWriteStream(temporary, { flags: "wx", mode: 0o600 });
-        // ⛔ An 'error' with no listener is thrown out of the event loop and kills the process, which
-        //    would turn "the disk is full" into a crash with no next step. Kept, and reported by the
-        //    next call that can report it.
-        fresh.on("error", (error) => {
-            failure = error;
-        });
-        stream = fresh;
-        return fresh;
-    };
-    const closed = async () => {
-        const open = stream;
-        if (open === null)
-            return;
-        stream = null;
-        // ⚠ Waits for 'close', not 'finish': a stream that failed to open never finishes, and waiting
-        //   for the wrong event there is a hang rather than an error.
-        await new Promise((resolve) => {
-            if (open.closed) {
-                resolve();
-                return;
-            }
-            open.once("close", () => resolve());
-            open.end();
-        });
-    };
-    const abandon = async () => {
-        if (renamed)
-            return;
-        try {
-            await closed();
-        }
-        catch {
-            // Nothing to do about it: the file below is going away either way.
-        }
-        await rm(temporary, { force: true }).catch(() => undefined);
-    };
-    return {
-        // Nothing to refuse: what a disk cannot take, the write itself reports, and the temporary
-        // file means a disk that fills up leaves no file under the name somebody asked for.
-        expect: () => undefined,
-        write: async (bytes) => {
-            const target = opened();
-            await new Promise((resolve, reject) => {
-                const known = failure;
-                if (known !== null) {
-                    reject(known);
-                    return;
-                }
-                target.write(bytes, (error) => {
-                    if (error === undefined || error === null)
-                        resolve();
-                    else
-                        reject(error);
-                });
-            });
-        },
-        commit: async () => {
-            // A file of zero bytes is still a file, so the stream is opened even if nothing was written.
-            opened();
-            await closed();
-            const known = failure;
-            if (known !== null) {
-                await abandon();
-                throw new NmtsError(`${destination} could not be written: ${known.message}`, {
-                    exitCode: 1,
-                    nextStep: "Nothing was left under that name. The download itself was fine — this is the disk.",
-                });
-            }
-            // ⛔ Asked a second time, as late as possible. The first check was before the download; a
-            //    file that appeared in the meantime is somebody else's, and rename would silently
-            //    replace it. The window is now the width of one system call rather than a download.
-            if (!options.force && existsSync(destination)) {
-                await abandon();
-                throw alreadyThere(destination);
-            }
-            await rename(temporary, destination);
-            renamed = true;
-            return true;
-        },
-        abandon,
-    };
-}
-/**
- * How much plaintext `--out -` will hold before it hands anything over. One part's worth.
- *
- * ⛔ NOT AN ARBITRARY NUMBER: it is the upload path's default part size, which is the most memory
- *    this tool has ever asked for. Keeping the stdout ceiling there means the whole tool's bound
- *    is one part plus one chunk whichever direction the bytes are going.
- */
-export const STDOUT_HOLD_LIMIT = 64 * 2 ** 20;
-/**
- * Hand the whole file to whatever is reading stdout — after it has been proved, not during.
- *
- * ⛔ THERE IS NO RENAME ON A PIPE, so the trick the file path uses is not available: a byte handed
- *    to a reader cannot be taken back, and a reader that has already consumed half a file cannot
- *    be told afterwards that the half was wrong. An exit code does not fix that — `nmts get x
- *    --out - > y` leaves the truncated bytes in `y` whatever the exit code says, and an agent
- *    reading a pipe usually acts on what it read. So this branch keeps the ORIGINAL guarantee
- *    rather than the original size: the file is held, checked, and only then handed over, exactly
- *    as before streaming existed.
- *
- * ⛔ WHICH MEANS IT HAS TO REFUSE SOMEWHERE, AND IT REFUSES OUT LOUD AND EARLY. Above the ceiling
- *    the answer is a refusal naming `--out <name>`, which streams and is checked before the file
- *    appears — not a silent trade of the guarantee for the size, and not the out-of-memory crash
- *    that this used to be. `put` already refuses this way rather than discovering a limit halfway.
- *
- * ⚠ Every protection this branch already had is still here and still applies to the whole file:
- *   bytes a terminal would act on are refused (`readableOnATerminal`), a reader that closed the
- *   pipe first is an ordinary end and not a failure, and any other write failure throws.
- */
-export function stdoutSink(to, limit = STDOUT_HOLD_LIMIT) {
-    const held = [];
-    let total = 0;
-    const tooLarge = (size) => new NmtsError(`This file is ${size} bytes, and \`--out -\` hands over at most ${limit}.`, {
-        exitCode: 4,
-        nextStep: "Nothing was written and nothing was sent. A pipe cannot be taken back, so this mode " +
-            "proves the whole file before it sends a byte, which means holding it. Use `--out <name>` " +
-            "— that writes any size, and the file only appears under that name once it has been checked.",
-    });
-    const forget = () => {
-        for (const run of held)
-            run.fill(0);
-        held.length = 0;
-    };
-    return {
-        expect: (size) => {
-            if (size > limit)
-                throw tooLarge(size);
-        },
-        write: async (bytes) => {
-            // ⚠ Copied, because the caller zeroes what it handed over as soon as this resolves.
-            total += bytes.length;
-            if (total > limit) {
-                forget();
-                throw tooLarge(total);
-            }
-            held.push(new Uint8Array(bytes));
-        },
-        commit: async () => {
-            const whole = new Uint8Array(total);
-            let at = 0;
-            for (const run of held) {
-                whole.set(run, at);
-                at += run.length;
-            }
-            forget();
-            // ⚠ NOT zeroed afterwards, deliberately: `ByteDestination` promises only that the bytes have
-            //   been handed over, and a destination is entitled to keep the array it was given — the
-            //   tests use one that does. Wiping it here would hand a reader a buffer of zeroes.
-            return await handOver(whole, to);
-        },
-        abandon: async () => forget(),
-    };
-}
+//
+// ⛔ ONLY THE SHAPE IS HERE. The two destinations this tool ships — a file on a disk, and whatever
+//    is reading its stdout — are both Node's, and they live in `download-sink-node.ts`. What is
+//    left is the contract, which is what a caller in a browser implements to hand a download to a
+//    `Blob`, an element or a stream of its own.
+export {};

package/dist/download.js

@@ -26,7 +26,8 @@
 //    the engine's own buffer for the chunk it is assembling, and the one chunk of plaintext it
 //    hands back — 4 MiB each in NCF-3. A hundred-gigabyte file costs the same as a hundred-megabyte
 //    one. The exception is `--out -`, which is bounded by `STDOUT_HOLD_LIMIT` and refuses above it.
-import { createHash } from "node:crypto";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { fromBase64Url, utf8 } from "./bytes.js";
 import { request } from "./api.js";
 import { AAD, DERIVED, loadCrypto } from "./crypto.js";
 import { asParts, fetchPart, openPart } from "./download-part.js";
@@ -69,7 +70,7 @@ export async function fetchFile(input) {
     derived.fill(0);
     let dek;
     try {
-        dek = crypt.envelope_open(dataKey, new TextEncoder().encode(AAD.dekWrap), Buffer.from(input.dekWrapped, "base64url"));
+        dek = crypt.envelope_open(dataKey, utf8(AAD.dekWrap), fromBase64Url(input.dekWrapped));
     }
     catch {
         dataKey.fill(0);
@@ -80,7 +81,7 @@ export async function fetchFile(input) {
     let expected = null;
     if (input.contentHashCt !== undefined && input.contentHashCt !== "") {
         try {
-            expected = crypt.envelope_open(dataKey, new TextEncoder().encode(AAD.contentHash), Buffer.from(input.contentHashCt, "base64url"));
+            expected = crypt.envelope_open(dataKey, utf8(AAD.contentHash), fromBase64Url(input.contentHashCt));
         }
         catch {
             dataKey.fill(0);
@@ -115,7 +116,7 @@ export async function fetchFile(input) {
  *    sees the finished file or sees nothing under that name.
  */
 async function collect(crypt, ordered, dek, expected, size, chain, read, sink) {
-    const hasher = createHash("sha256");
+    const hasher = sha256.create();
     let remaining = size;
     try {
         // ⛔ Asked before a byte is fetched. A destination that cannot take a file this size says so

package/dist/engine-node.d.ts

@@ -0,0 +1,19 @@
+import { type CryptoGlue } from "./crypto-surface.ts";
+/**
+ * Where the engine's WebAssembly sits, in the three places an installation can put it.
+ *
+ * ⛔ FOUND RATHER THAN CONFIGURED. The package carries it in `vendor/`, a checkout runs from
+ *    `src/` with the same folder one level further up, and the repository's own web tree holds a
+ *    build of the same crate. A path in a setting would be a fourth answer nobody keeps right.
+ */
+export declare function engineDir(): string;
+/**
+ * Load the engine once per process.
+ *
+ * ⛔ NO TYPE ASSERTION. A dynamically imported module is `unknown`, and staying honest about that
+ *    matters here more than anywhere: a rebuild that renamed an export would otherwise become
+ *    "undefined is not a function" deep inside a derivation.
+ */
+export declare function loadEngine(): Promise<CryptoGlue>;
+/** For tests that need a fresh load. */
+export declare function forgetEngine(): void;

package/dist/engine-node.js

@@ -0,0 +1,77 @@
+// Finding and loading the engine on a machine with a disk.
+//
+// ⛔ NOTHING IS RE-IMPLEMENTED HERE. The bytes that derive an account's keys are the same
+//    WebAssembly the browser runs, built from the same Rust crate — this file only finds the build
+//    and hands it to the shape check every load passes.
+//
+// ⛔ SEPARATE FROM `host-node.ts` SO THAT REGISTERING A HOST COSTS NOTHING. `nmts --help` puts the
+//    host in place and never derives anything; loading this file, and the four `node:` modules it
+//    needs, on every run would be a fixed cost an agent pays thousands of times.
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { isCryptoGlue, missingExports } from "./crypto-surface.js";
+import { NmtsError } from "./errors.js";
+/**
+ * Where the engine's WebAssembly sits, in the three places an installation can put it.
+ *
+ * ⛔ FOUND RATHER THAN CONFIGURED. The package carries it in `vendor/`, a checkout runs from
+ *    `src/` with the same folder one level further up, and the repository's own web tree holds a
+ *    build of the same crate. A path in a setting would be a fourth answer nobody keeps right.
+ */
+export function engineDir() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        join(here, "..", "vendor", "nmts-crypto"),
+        join(here, "..", "..", "vendor", "nmts-crypto"),
+        join(here, "..", "..", "web", "vendor", "nmts-crypto"),
+    ];
+    for (const dir of candidates) {
+        if (existsSync(join(dir, "nmts_crypto_wasm_bg.wasm")))
+            return dir;
+    }
+    throw new NmtsError("The NMTS crypto engine is missing from this installation.", {
+        exitCode: 1,
+        nextStep: "Reinstall the package. Nothing can be encrypted or decrypted without it.",
+    });
+}
+let engine = null;
+/**
+ * Load the engine once per process.
+ *
+ * ⛔ NO TYPE ASSERTION. A dynamically imported module is `unknown`, and staying honest about that
+ *    matters here more than anywhere: a rebuild that renamed an export would otherwise become
+ *    "undefined is not a function" deep inside a derivation.
+ */
+export async function loadEngine() {
+    if (engine !== null)
+        return engine;
+    const dir = engineDir();
+    const module = await import(__rewriteRelativeImportExtension(pathToFileURL(join(dir, "nmts_crypto_wasm.js")).href));
+    if (typeof module !== "object" || module === null || !("default" in module)) {
+        throw new NmtsError("The NMTS crypto engine did not load (no initialiser).", { exitCode: 1 });
+    }
+    const init = Reflect.get(module, "default");
+    if (typeof init !== "function") {
+        throw new NmtsError("The NMTS crypto engine did not load (initialiser is not callable).", { exitCode: 1 });
+    }
+    await init({ module_or_path: await readFile(join(dir, "nmts_crypto_wasm_bg.wasm")) });
+    if (!isCryptoGlue(module)) {
+        throw new NmtsError(`The NMTS crypto engine is missing: ${missingExports(module).join(", ")}. This build does not match this tool.`, { exitCode: 1, nextStep: "Reinstall the package." });
+    }
+    engine = module;
+    return module;
+}
+/** For tests that need a fresh load. */
+export function forgetEngine() {
+    engine = null;
+}

package/dist/env-vars.d.ts

@@ -0,0 +1,20 @@
+/** Which NMTS server this run talks to. */
+export declare const SERVER_ENV_VAR = "NMTS_SERVER";
+/** Which storage network that server uses. */
+export declare const NETWORK_ENV_VAR = "NMTS_NETWORK";
+/**
+ * Point reads at somebody else's aggregator, or at a development stack.
+ *
+ * ⚠ It replaces the list rather than adding to it, and that is deliberate: a run should read from
+ *   where it was told to read, not from there AND the public hosts. Comma-separated for more
+ *   than one, tried in the order given.
+ */
+export declare const AGGREGATOR_ENV_VAR = "NMTS_AGGREGATOR";
+/**
+ * Push writes through somebody else's relay, or through a development stack.
+ *
+ * ⚠ ONE host, not a list. Unlike reads there is nothing to fail over to — see `RELAY_HOSTS`.
+ */
+export declare const RELAY_ENV_VAR = "NMTS_RELAY";
+/** Ask a different Sui JSON-RPC node the shard-count question. */
+export declare const SUI_RPC_ENV_VAR = "NMTS_SUI_RPC";

package/dist/env-vars.js

@@ -0,0 +1,27 @@
+// The names of the environment variables this tool reads.
+//
+// ⛔ NAMES ONLY, AND NO IMPORTS. `nmts --help` prints several of these, and a help text that had to
+//    load the module that USES a variable would drag that module's whole chain into every run —
+//    `check:cli-startup` measures exactly that, and it is the leak it has caught most often. The
+//    modules that read the variables re-export their own name from here, so every caller still
+//    finds it where it belongs and there is still only one spelling of each.
+/** Which NMTS server this run talks to. */
+export const SERVER_ENV_VAR = "NMTS_SERVER";
+/** Which storage network that server uses. */
+export const NETWORK_ENV_VAR = "NMTS_NETWORK";
+/**
+ * Point reads at somebody else's aggregator, or at a development stack.
+ *
+ * ⚠ It replaces the list rather than adding to it, and that is deliberate: a run should read from
+ *   where it was told to read, not from there AND the public hosts. Comma-separated for more
+ *   than one, tried in the order given.
+ */
+export const AGGREGATOR_ENV_VAR = "NMTS_AGGREGATOR";
+/**
+ * Push writes through somebody else's relay, or through a development stack.
+ *
+ * ⚠ ONE host, not a list. Unlike reads there is nothing to fail over to — see `RELAY_HOSTS`.
+ */
+export const RELAY_ENV_VAR = "NMTS_RELAY";
+/** Ask a different Sui JSON-RPC node the shard-count question. */
+export const SUI_RPC_ENV_VAR = "NMTS_SUI_RPC";

package/dist/gate.js

@@ -34,7 +34,7 @@ export async function unlocked(key, now) {
 }
 export async function gate(act, args, io = {}) {
     const a = ACTS[act];
-    const mode = currentMode();
+    const mode = await currentMode();
     const now = io.now ?? (() => new Date());
     if (a.tier === "none")
         return { ask: false, mode };

package/dist/help.js

@@ -10,10 +10,11 @@ import { AGENTS_DOC, BINARY_NAME, HOME_URL, PRODUCT_NAME, SOURCE_URL, VERSION }
 //    reading it here costs `nmts --help` nothing (`check:cli-startup`).
 import { ATTACH_LOG_TEXT, SUPPORT_LONG, supportHelpText } from "./support-copy.js";
 import { API_KEY_ENV_VAR, API_KEY_FILE_ENV_VAR, CODE_ENV_VAR, CODE_FILE_ENV_VAR, PASSPHRASE_ENV_VAR, } from "./credentials.js";
-import { NETWORK_ENV_VAR } from "./network.js";
+// ⛔ THE NAMES COME FROM THE MODULE THAT HAS NO IMPORTS, not from the modules that USE them. Those
+//    three reach the host register, and loading them to print a variable's name would put that
+//    chain in front of every `nmts --help` (`check:cli-startup`).
+import { AGGREGATOR_ENV_VAR, NETWORK_ENV_VAR, SERVER_ENV_VAR } from "./env-vars.js";
 import { LATEST_RELEASE_URL, NO_CHECK_ENV_VAR } from "./update-source.js";
-import { SERVER_ENV_VAR } from "./server.js";
-import { AGGREGATOR_ENV_VAR } from "./walrus.js";
 import { CHECK_DOES_NOT_PROVE, CHECK_PROVES, RECOVERY_TOOL_URL, wrapText, } from "./recovery-release.js";
 export function helpText(version) {
     return [
@@ -123,6 +124,9 @@ export function helpText(version) {
         `  privacy               The Privacy Policy in force`,
         `  mcp                   Serve this account's commands as tools, for an agent that speaks MCP`,
         `  s3                    Serve the drive to any S3 program, on this machine only`,
+        `  platform keygen       Make the key pair a business signs its Platform requests with — writes`,
+        `                        both halves to a file only you can read, prints only the public half`,
+        `  platform register     Where that public key is registered: a browser session, not this tool`,
         ``,
         `OPTIONS`,
         `  --server <url>        NMTS server (default ${SERVER_ENV_VAR} or the live one)`,
@@ -171,7 +175,8 @@ export function helpText(version) {
         `  --desc                Reverse whichever order is in effect (ls)`,
         `  --hidden              Include entries whose name begins with a dot (push)`,
         `  --out <path>          Where to write files (get, pull, mcp, listfile, recovery,`,
-        `                        recovery-list, kit, create, notices, terms, privacy). Default: here`,
+        `                        recovery-list, kit, create, notices, terms, privacy, platform`,
+        `                        keygen). Default: here`,
         `  --out -               Send a fetched file to stdout instead of writing it (get, listfile)`,
         `  --lang <en|ko>        Which language of a document (terms, privacy). Default: English`,
         `  --board               The message board's terms rather than the service's (terms)`,

package/dist/host-contract.d.ts

@@ -0,0 +1,7 @@
+import type { Host } from "./host.ts";
+/**
+ * Put a host's state through everything the package relies on, and say what it got wrong.
+ *
+ * An empty array is a pass.
+ */
+export declare function hostContract(host: Host): Promise<string[]>;

package/dist/host-contract.js

@@ -0,0 +1,95 @@
+// The one test both hosts sit: what "keeping state" has to mean, whoever is keeping it.
+//
+// ⛔ ONE FUNCTION, RUN FROM TWO TEST FILES. `test/host-node.test.ts` runs it over the Node host and
+//    the SDK's `test/host-browser.test.ts` runs it over the browser one. Two tests written
+//    separately would drift, and the way that drift shows up is a half-finished upload that
+//    resumes on a laptop and starts again in a browser — the same account, the same file, two
+//    answers.
+//
+// ⛔ IT REPORTS EVERY VIOLATION RATHER THAN THROWING AT THE FIRST. A host that is wrong is usually
+//    wrong about one thing; a list says which, and a caller that wanted an assertion gets one by
+//    asserting the list is empty.
+//
+// ⚠ IT WRITES. The keys all sit under `contract/`, which nothing else uses, and each one is
+//   removed before the function returns — including when a check above it failed.
+/** Where this check keeps its scratch. Nothing else in the package writes under it. */
+const AREA = "contract";
+function sample(length, seed) {
+    const out = new Uint8Array(length);
+    for (let i = 0; i < length; i += 1)
+        out[i] = (i * 31 + seed) & 0xff;
+    return out;
+}
+function same(left, right) {
+    if (left === undefined || left.length !== right.length)
+        return false;
+    for (let i = 0; i < left.length; i += 1)
+        if (left[i] !== right[i])
+            return false;
+    return true;
+}
+/**
+ * Put a host's state through everything the package relies on, and say what it got wrong.
+ *
+ * An empty array is a pass.
+ */
+export async function hostContract(host) {
+    const state = host.state;
+    const problems = [];
+    const one = `${AREA}/one`;
+    const two = `${AREA}/two`;
+    const big = `${AREA}/big`;
+    const say = (what) => void problems.push(what);
+    try {
+        // A key nothing has written is not an error and not empty bytes: it is nothing.
+        if ((await state.read(`${AREA}/never-written`)) !== undefined) {
+            say("read() of a key that was never written answered bytes instead of undefined");
+        }
+        const first = sample(64, 1);
+        await state.write(one, first);
+        if (!same(await state.read(one), first))
+            say("read() did not hand back the bytes write() was given");
+        // ⛔ THE SECOND WRITE REPLACES. A store that appended, or that kept the first value, would make
+        //    every record in the package grow a second version nobody reads.
+        const second = sample(96, 2);
+        await state.write(one, second);
+        if (!same(await state.read(one), second))
+            say("writing a key a second time did not replace what was there");
+        await state.write(two, sample(8, 3));
+        const listed = await state.keys(`${AREA}/`);
+        for (const key of [one, two]) {
+            if (!listed.includes(key))
+                say(`keys("${AREA}/") did not include ${key}`);
+        }
+        if (listed.includes(`${AREA}/never-written`))
+            say("keys() listed a key that was never written");
+        await state.remove(one);
+        if ((await state.read(one)) !== undefined)
+            say("remove() left the bytes readable");
+        if ((await state.keys(`${AREA}/`)).includes(one))
+            say("remove() left the key in keys()");
+        // Removing what is not there is how every caller here clears a record it may never have made.
+        await state.remove(one);
+        // ⛔ ONE MEBIBYTE, BECAUSE THAT IS WHAT AN UPLOAD KEEPS. A reservation holds a sealed part, and
+        //    a store that quietly truncated or refused at some smaller size would lose exactly the
+        //    records that let a large upload resume — and nothing else would notice.
+        const large = sample(1024 * 1024, 4);
+        await state.write(big, large);
+        if (!same(await state.read(big), large))
+            say("a 1 MiB value did not come back as it was written");
+    }
+    catch (error) {
+        say(`a call threw instead of answering: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        for (const key of [one, two, big]) {
+            try {
+                await state.remove(key);
+            }
+            catch {
+                // The store is somebody else's; a scratch key left behind is not this check's to report.
+            }
+        }
+    }
+    return problems;
+}

package/dist/host-node.d.ts

@@ -0,0 +1,27 @@
+import { type Host, type StateHost } from "./host.ts";
+/** Files under the person's own config directory, named by `placeOf`. */
+export declare function nodeState(): StateHost;
+/** Where a state key lands on this machine. For tests, and for messages that name a file. */
+export declare function statePath(key: string): string;
+/**
+ * Every `NMTS_*` variable this process is holding.
+ *
+ * ⛔ THE ONE PLACE THE WHOLE ENVIRONMENT IS READ. `redact.ts` needs the values to label them out of
+ *    a report, and a browser has none — so it is a host call rather than a `process.env` walk in a
+ *    module that has to run in both.
+ */
+export declare function nodeEnvEntries(): {
+    name: string;
+    value: string;
+}[];
+/** This machine, as the package's host. */
+export declare function nodeHost(): Host;
+/**
+ * Put this machine in the register: what the two Node doors — `index.ts` and the command's own
+ * entry point — call before anything that loads the engine, keeps state or reads the environment.
+ *
+ * ⛔ THE COMMAND LOADS THIS FILE LATE, not at the top of `main.ts`. The chain below reaches the
+ *    credentials module, and a fixed cost at the head of `nmts --help` is one an agent running
+ *    this tool in a loop pays thousands of times (`check:cli-startup`).
+ */
+export declare function registerNodeHost(): void;