@gr8ful/spf 0.4.0 → 0.5.1

package/dist/test/git_helper.test.js

@@ -0,0 +1,59 @@
+import "./hermetic_git.js";
+/**
+ * `findRepoRoot()`'s contract is "never throws, always returns some root."
+ * `isRepoAt()` only proves `git rev-parse --git-dir` succeeds, which is also
+ * true inside a bare repo and inside a `.git/` directory itself — neither
+ * has a work tree, so the follow-up `--show-toplevel` call fails there even
+ * though `isRepoAt()` said yes. Regression coverage for that gap: before the
+ * fix, `findRepoRoot()` let that failure propagate as an uncaught throw,
+ * which — because `cli/index.ts` calls `paths.resolveAnchor()` outside its
+ * top-level try/catch — crashed every command (including `spf --version`)
+ * when run from a bare repo or from inside `.git/`.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { findRepoRoot } from "../core/git_helper.js";
+test("findRepoRoot falls back to cwd inside a bare repo (no work tree)", () => {
+    const dir = mkdtempSync(path.join(tmpdir(), "spf-bare-"));
+    try {
+        execFileSync("git", ["init", "--bare", dir], { stdio: "ignore" });
+        const root = findRepoRoot(dir);
+        assert.equal(root, path.resolve(dir));
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("findRepoRoot falls back to cwd inside a repo's .git directory", () => {
+    const dir = mkdtempSync(path.join(tmpdir(), "spf-dotgit-"));
+    try {
+        execFileSync("git", ["init"], { cwd: dir, stdio: "ignore" });
+        const gitDir = path.join(dir, ".git");
+        const root = findRepoRoot(gitDir);
+        assert.equal(root, path.resolve(gitDir));
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("findRepoRoot resolves the toplevel of an ordinary work tree", () => {
+    const dir = mkdtempSync(path.join(tmpdir(), "spf-worktree-"));
+    try {
+        execFileSync("git", ["init"], { cwd: dir, stdio: "ignore" });
+        const sub = path.join(dir, "nested");
+        execFileSync("node", ["-e", `require("fs").mkdirSync(${JSON.stringify(sub)})`]);
+        const root = findRepoRoot(sub);
+        // git may resolve symlinked tmpdirs (e.g. macOS /tmp -> /private/tmp) —
+        // compare against what git itself reports as the raw toplevel is what
+        // resolveAnchor ultimately does too, so lean on findRepoRoot from the
+        // repo root itself for a stable assertion.
+        assert.equal(root, findRepoRoot(dir));
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});

package/dist/test/hermetic_git.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/hermetic_git.js

@@ -0,0 +1,22 @@
+/**
+ * Import this FIRST in any test file that spawns `git`.
+ *
+ * When the suite runs inside a git hook (lefthook's `pre-push`), git exports
+ * GIT_DIR — and sometimes GIT_WORK_TREE/GIT_INDEX_FILE — into every child
+ * process, and those beat `cwd` for every git invocation. A test that does
+ * `git init` / `git remote add` / `git commit` in a scratch tmpdir then
+ * silently operates on the REAL repository being pushed. Observed damage
+ * before this guard existed: a stray empty "init" commit landed on the
+ * checked-out branch, and `git init` re-initialized the shared `.git`
+ * directory as BARE (git treats a target directory named `.git` as a bare
+ * repo), breaking `git status` in the main checkout until `core.bare` was
+ * flipped back.
+ *
+ * Deleting the variables at module load — each test file is its own
+ * `node --test` process — makes `cwd` authoritative again for the whole
+ * file, including git calls made by the code under test.
+ */
+for (const key of ["GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_PREFIX", "GIT_COMMON_DIR", "GIT_OBJECT_DIRECTORY"]) {
+    delete process.env[key];
+}
+export {};

package/dist/test/init_command.test.d.ts

@@ -1 +1,14 @@
-export {};
+/**
+ * Regression guard for `spf init`'s non-interactive paths — `--yes`,
+ * `--template <name>`, and (implicitly, since the test runner's stdin/stdout
+ * are never a TTY) plain `spf init` with no flags. All three must keep
+ * writing the exact same content they always have, byte for byte, and must
+ * never touch stdin — a scripted `spf init` in CI must not hang.
+ *
+ * The interactive interview itself is covered directly against `Asker`
+ * in `interview.test.ts`; `initCommand`'s interactive branch always calls
+ * the real `createAsker()` (backed by `node:readline` on `process.stdin`),
+ * which has nothing to read in a test process — exercising it here would
+ * just hang, so it isn't.
+ */
+import "./hermetic_git.js";

package/dist/test/init_command.test.js

@@ -11,13 +11,16 @@
  * which has nothing to read in a test process — exercising it here would
  * just hang, so it isn't.
  */
+import "./hermetic_git.js";
 import { test, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
 import { mkdtempSync, rmSync, readFileSync, existsSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { execFileSync } from "node:child_process";
-import { initCommand } from "../cli/commands/init.js";
+import { initCommand, EXAMPLE_CHAIN_YAML } from "../cli/commands/init.js";
+import { loadRepoChains } from "../chains/repo_chains.js";
+import { resolveAnchor } from "../core/paths.js";
 let dir;
 beforeEach(() => {
     dir = mkdtempSync(join(tmpdir(), "spf-init-test-"));
@@ -74,6 +77,56 @@ test("--no-skills skips the skill install", async () => {
     assert.equal(code, 0);
     assert.equal(existsSync(join(dir, ".claude", "skills", "spf")), false);
 });
+test("scaffolds .spf/chains/example.yaml, fully commented out (registers nothing)", async () => {
+    const code = await initCommand(["--cwd", dir, "--yes"]);
+    assert.equal(code, 0);
+    const examplePath = join(dir, ".spf", "chains", "example.yaml");
+    assert.ok(existsSync(examplePath), "spf init should scaffold .spf/chains/example.yaml");
+    const content = readFileSync(examplePath, "utf-8");
+    for (const line of content.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        assert.ok(line.startsWith("#"), `every non-blank line in the scaffolded example must be commented out: ${JSON.stringify(line)}`);
+    }
+});
+test("never adds .spf/chains to .gitignore — chain files must stay tracked for protected_files to cover them", async () => {
+    await initCommand(["--cwd", dir, "--yes"]);
+    const gitignore = readFileSync(join(dir, ".gitignore"), "utf-8");
+    assert.doesNotMatch(gitignore, /\.spf\/chains/);
+});
+test("the scaffolded example.yaml loads clean — zero chains, zero problems (it must not report a problem against spf's own scaffold)", async () => {
+    const code = await initCommand(["--cwd", dir, "--yes"]);
+    assert.equal(code, 0);
+    const anchor = resolveAnchor(dir);
+    const { chains, problems } = loadRepoChains(anchor);
+    assert.deepEqual(chains, []);
+    assert.deepEqual(problems, []);
+});
+test("EXAMPLE_CHAIN_YAML's commented-out template, uncommented verbatim, is a chain the loader accepts", async () => {
+    const lines = EXAMPLE_CHAIN_YAML.split("\n");
+    const startIdx = lines.findIndex((l) => l.startsWith("# name: example"));
+    assert.ok(startIdx !== -1, "expected a `# name: example` line to anchor the template block");
+    const uncommented = lines
+        .slice(startIdx)
+        .map((l) => l.replace(/^#\s?/, ""))
+        .join("\n");
+    const chainsDir = join(dir, ".spf", "chains");
+    execFileSync("mkdir", ["-p", chainsDir]);
+    const { writeFileSync } = await import("node:fs");
+    writeFileSync(join(chainsDir, "uncommented.yaml"), uncommented);
+    const anchor = resolveAnchor(dir);
+    const { chains, problems } = loadRepoChains(anchor);
+    assert.deepEqual(problems, [], `expected zero problems, got: ${JSON.stringify(problems)}`);
+    assert.equal(chains.length, 1);
+    assert.equal(chains[0]?.name, "example");
+});
+test("re-running spf init doesn't overwrite an already-scaffolded example.yaml", async () => {
+    await initCommand(["--cwd", dir, "--yes"]);
+    const examplePath = join(dir, ".spf", "chains", "example.yaml");
+    const before = readFileSync(examplePath, "utf-8");
+    await initCommand(["--cwd", dir, "--template", "ts-cc"]); // no --force
+    assert.equal(readFileSync(examplePath, "utf-8"), before);
+});
 test("re-running spf init doesn't re-copy an unchanged skill install (install-skill's own idempotency)", async () => {
     await initCommand(["--cwd", dir, "--yes"]);
     const manifestPath = join(dir, ".claude", "skills", "spf", ".spf-skill-version");

package/dist/test/interview.test.d.ts

@@ -1 +1,15 @@
-export {};
+/**
+ * `spf init`'s interactive interview (`cli/interview.ts`) — driven through
+ * the `Asker` seam with a scripted fake (`./fake_asker.ts`), never a real
+ * TTY. Covers the three things a wrong answer would actually break:
+ *   1. the pinned-roster trap (planner/reviewer/documenter overridden
+ *      whenever the backend switches to claude_code — see agent_cc.ts/
+ *      agents.ts's back-fill comment),
+ *   2. the generated config is a genuine override — validating it requires
+ *      merging with the packaged built-in roster first, exactly like
+ *      `spf doctor` does, never the raw document alone,
+ *   3. each `spf watch` combination collects exactly the credentials
+ *      `cli/commands/watch.ts`'s resolveIssueProvider/resolveCodeHostProvider
+ *      actually read — no more, no less.
+ */
+import "./hermetic_git.js";

package/dist/test/interview.test.js

@@ -12,6 +12,7 @@
  *      `cli/commands/watch.ts`'s resolveIssueProvider/resolveCodeHostProvider
  *      actually read — no more, no less.
  */
+import "./hermetic_git.js";
 import { test, before, after } from "node:test";
 import assert from "node:assert/strict";
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
@@ -107,6 +108,61 @@ test("flue + openrouter: no pinned-agent overrides needed, provider key collecte
     assert.equal(result.env.OPENROUTER_API_KEY, "sk-or-v1-test");
     assert.ok(!("watch" in config));
 });
+test("flue + ollama: keyless provider skips the API-key prompt, but still asks for OLLAMA_BASE_URL", async () => {
+    const ctx = gatherContext(dir, new Map());
+    const asker = createFakeAsker({
+        select: { "backend runs": "flue", Provider: "ollama" },
+        text: { "Model id": "llama3" }, // deliberately no "OLLAMA_BASE_URL" entry — the fake asker falls back to its default
+        confirm: {
+            'Add a "typecheck"': false,
+            'Add a "lint"': false,
+            'Add a "build"': false,
+            'Add a "test"': false,
+            "Enable spf watch": false,
+            "Configure advanced": false,
+            "Write .spf": true,
+        },
+        // Deliberately no `secret` entries: a keyless provider must never call
+        // asker.secret() at all — PROVIDER_ENV_KEYS.ollama is `[]`, so indexing
+        // [0] for a prompt label would be `undefined`, not skip the prompt.
+    });
+    const result = await runInterview(asker, ctx);
+    assert.ok(result);
+    const config = result.config;
+    assert.equal(config.defaults.coding_agent, "flue");
+    assert.equal(config.defaults.model, "ollama/llama3");
+    assert.deepEqual(result.env, { OLLAMA_BASE_URL: "http://localhost:11434/v1" }, "no API key, but the base URL prompt's default is written");
+    assert.deepEqual(result.envExampleKeys, ["OLLAMA_BASE_URL"], "OLLAMA_BASE_URL is the only key name to record for a keyless provider");
+    // Unlike the openrouter case above, ollama DOES need the pinned-roster
+    // fix: planner/reviewer/documenter pin their own fireworks/gemini/openai
+    // model strings in the packaged roster, which would otherwise always win
+    // over defaults.model and leave three agents needing keys this interview
+    // never asked for.
+    assert.deepEqual(config.agents, [
+        { name: "planner", model: "ollama/llama3" },
+        { name: "reviewer", model: "ollama/llama3" },
+        { name: "documenter", model: "ollama/llama3" },
+    ], "planner/reviewer/documenter are pinned to the chosen ollama model, same fix as the claude_code branch");
+});
+test("flue + ollama: a custom OLLAMA_BASE_URL answer is written verbatim", async () => {
+    const ctx = gatherContext(dir, new Map());
+    const asker = createFakeAsker({
+        select: { "backend runs": "flue", Provider: "ollama" },
+        text: { "Model id": "llama3", OLLAMA_BASE_URL: "http://gpu-box.local:11434/v1" },
+        confirm: {
+            'Add a "typecheck"': false,
+            'Add a "lint"': false,
+            'Add a "build"': false,
+            'Add a "test"': false,
+            "Enable spf watch": false,
+            "Configure advanced": false,
+            "Write .spf": true,
+        },
+    });
+    const result = await runInterview(asker, ctx);
+    assert.ok(result);
+    assert.equal(result.env.OLLAMA_BASE_URL, "http://gpu-box.local:11434/v1");
+});
 test("watch(jira/bitbucket): collects exactly JIRA_* + BITBUCKET_*, never GITHUB_TOKEN", async () => {
     const ctx = gatherContext(dir, new Map());
     const asker = createFakeAsker({
@@ -145,6 +201,77 @@ test("watch(jira/bitbucket): collects exactly JIRA_* + BITBUCKET_*, never GITHUB
     assert.equal(result.env.BITBUCKET_API_TOKEN, "bb-token");
     assert.equal(result.env.GITHUB_TOKEN, undefined, "neither provider needs GitHub — must not ask for or write GITHUB_TOKEN");
 });
+test("watch(github issues + bitbucket code): asks two repo questions and writes issue_repo separately from repo", async () => {
+    const ctx = gatherContext(dir, new Map());
+    const asker = createFakeAsker({
+        select: {
+            "backend runs": "claude_code",
+            "Model (Claude": "sonnet",
+            Authentication: "login",
+            "Issue tracker": "github",
+            "Code host": "bitbucket",
+            "Chain to run": "plan-build-test",
+        },
+        text: {
+            "Code repo, where PRs open (workspace/repo_slug)": "acme-workspace/widgets-code",
+            "Issue repo, where spf:ready issues live (owner/name)": "acme/widgets-issues",
+        },
+        confirm: {
+            'Add a "typecheck"': false,
+            'Add a "lint"': false,
+            'Add a "build"': false,
+            'Add a "test"': false,
+            "Enable spf watch": true,
+            "Also enable the refine lane": false,
+            "Configure advanced": false,
+            "Write .spf": true,
+        },
+        secret: { GITHUB_TOKEN: "ghp_x", BITBUCKET_API_TOKEN: "bb-token" },
+    });
+    const result = await runInterview(asker, ctx);
+    assert.ok(result);
+    const config = result.config;
+    assert.equal(config.watch.issue_provider, "github");
+    assert.equal(config.watch.code_host, "bitbucket");
+    assert.equal(config.watch.repo, "acme-workspace/widgets-code", "repo is the CODE HOST's repo");
+    assert.equal(config.watch.issue_repo, "acme/widgets-issues", "issue_repo overrides repo for the issue tracker side");
+    const configPath = mergedConfigPath();
+    const { stringify } = await import("yaml");
+    writeFileSync(configPath, stringify(config));
+    const cfg = loadConfig([BUILTIN_CONFIG_PATH, configPath]);
+    assert.equal(cfg.watch.repo, "acme-workspace/widgets-code");
+    assert.equal(cfg.watch.issue_repo, "acme/widgets-issues");
+});
+test("watch(github issues + github code): a single repo answers both, issue_repo stays unset", async () => {
+    const ctx = gatherContext(dir, new Map());
+    const asker = createFakeAsker({
+        select: {
+            "backend runs": "claude_code",
+            "Model (Claude": "sonnet",
+            Authentication: "login",
+            "Issue tracker": "github",
+            "Code host": "github",
+            "Chain to run": "plan-build-test",
+        },
+        text: { "Repo (owner/name)": "acme/widgets" },
+        confirm: {
+            'Add a "typecheck"': false,
+            'Add a "lint"': false,
+            'Add a "build"': false,
+            'Add a "test"': false,
+            "Enable spf watch": true,
+            "Also enable the refine lane": false,
+            "Configure advanced": false,
+            "Write .spf": true,
+        },
+        secret: { GITHUB_TOKEN: "ghp_x" },
+    });
+    const result = await runInterview(asker, ctx);
+    assert.ok(result);
+    const config = result.config;
+    assert.equal(config.watch.repo, "acme/widgets");
+    assert.equal(config.watch.issue_repo, undefined, "the single-repo case never writes issue_repo at all");
+});
 test("declining the final confirm returns null — nothing to write", async () => {
     const ctx = gatherContext(dir, new Map());
     const asker = createFakeAsker({ defaultConfirm: false }); // every confirm, including the final one, says no

package/dist/test/ollama_provider.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/ollama_provider.test.js

@@ -0,0 +1,103 @@
+/**
+ * Hermetic — never touches a live Ollama server. These exercise Flue's own
+ * in-process provider registry (via `@flue/runtime/internal`) plus this
+ * module's accumulation/idempotence logic, using synthetic model ids.
+ */
+import { test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { hasProvider, resetModelsForTests, resolveModel as flueResolveModel } from "@flue/runtime/internal";
+import { providerForTest, registerOllamaModel, resetOllamaRegistrationForTest, } from "../core/ollama_provider.js";
+// A minimal stand-in for pi-ai's `AuthContext` — our resolver ignores it
+// entirely (it has no ambient env/file lookups to do), but the `resolve()`
+// call site still needs something shaped right to pass.
+const fakeAuthContext = { env: async () => undefined, fileExists: async () => false };
+const ORIGINAL_BASE_URL = process.env.OLLAMA_BASE_URL;
+beforeEach(() => {
+    resetOllamaRegistrationForTest();
+    resetModelsForTests();
+    delete process.env.OLLAMA_BASE_URL;
+});
+afterEach(() => {
+    if (ORIGINAL_BASE_URL === undefined)
+        delete process.env.OLLAMA_BASE_URL;
+    else
+        process.env.OLLAMA_BASE_URL = ORIGINAL_BASE_URL;
+});
+test("registerOllamaModel: union accumulation — registering a second id doesn't orphan the first", async () => {
+    await registerOllamaModel("model-a");
+    await registerOllamaModel("model-b");
+    assert.equal(hasProvider("ollama"), true);
+    // `setProvider()` REPLACES the whole provider (models list included) on
+    // every call. If this module regressed from "re-register the full union"
+    // to "register just the newest id", model-a would throw "Unknown model
+    // ID … for provider \"ollama\"" here — exactly the failure the spike hit
+    // and the `registeredIds` Set exists to prevent.
+    const a = flueResolveModel("ollama/model-a");
+    const b = flueResolveModel("ollama/model-b");
+    assert.equal(a.id, "model-a");
+    assert.equal(b.id, "model-b");
+    const idsOnProvider = providerForTest()
+        .getModels()
+        .map((m) => m.id)
+        .sort();
+    assert.deepEqual(idsOnProvider, ["model-a", "model-b"], "the provider's own model list carries both ids, not just the latest");
+});
+test("registerOllamaModel: flue's registry resolves the SAME model object our provider registered — pins the pi-ai single-copy dedupe invariant", async () => {
+    // package.json pins @earendil-works/pi-ai to the exact version
+    // @flue/runtime depends on so npm dedupes to one physical copy — see that
+    // pin's own comment for why. If a future dependency bump ever re-splits
+    // that into two copies, `setProvider()`'s `Model`/`Provider` values would
+    // stop being instances flue's OWN copy of pi-ai recognizes, and
+    // `resolveModel()` would resolve to a DIFFERENT object than the one on
+    // our provider — same string id, wrong identity. Reference equality here
+    // is the one assertion that would actually catch that regression; a
+    // structural `deepEqual` would keep passing right through it.
+    await registerOllamaModel("model-a");
+    const resolved = flueResolveModel("ollama/model-a");
+    const onProvider = providerForTest().getModels().find((m) => m.id === "model-a");
+    assert.equal(resolved, onProvider, "flue's registry and our provider must hand back the identical object, not merely an equal one");
+});
+test("registerOllamaModel: idempotent for an already-registered id", async () => {
+    await registerOllamaModel("model-a");
+    const providerAfterFirst = providerForTest();
+    await registerOllamaModel("model-a");
+    assert.equal(providerForTest(), providerAfterFirst, "a repeat registration never calls setProvider again — same object identity");
+});
+test("registerOllamaModel: concurrent calls for the same new id both resolve to one registration, not a second no-op", async () => {
+    // Regression guard for committing to `registeredIds` before `setProvider`
+    // finishes: if the second call saw the id "already registered" before
+    // the first call's registration actually completed, it would resolve
+    // immediately with nothing registered yet, and a caller awaiting it could
+    // start dispatching before `setProvider()` ran.
+    const [a, b] = await Promise.all([registerOllamaModel("model-c"), registerOllamaModel("model-c")]);
+    assert.equal(a, undefined);
+    assert.equal(b, undefined);
+    const model = flueResolveModel("ollama/model-c");
+    assert.equal(model.id, "model-c");
+});
+test("registerOllamaModel: defaults to http://localhost:11434/v1 when OLLAMA_BASE_URL is unset", async () => {
+    await registerOllamaModel("model-a");
+    const model = flueResolveModel("ollama/model-a");
+    assert.equal(model.baseUrl, "http://localhost:11434/v1");
+    assert.equal(providerForTest().baseUrl, "http://localhost:11434/v1");
+});
+test("registerOllamaModel: OLLAMA_BASE_URL override is respected", async () => {
+    process.env.OLLAMA_BASE_URL = "http://example-ollama-host:9999/v1";
+    await registerOllamaModel("model-a");
+    const model = flueResolveModel("ollama/model-a");
+    assert.equal(model.baseUrl, "http://example-ollama-host:9999/v1");
+    assert.equal(providerForTest().baseUrl, "http://example-ollama-host:9999/v1");
+});
+test("registerOllamaModel: registered models carry contextWindow 0 (disables threshold compaction)", async () => {
+    await registerOllamaModel("model-a");
+    const model = flueResolveModel("ollama/model-a");
+    assert.equal(model.contextWindow, 0);
+});
+test("registerOllamaModel: auth.apiKey resolves a truthy dummy key, never the upstream 'No API key' failure", async () => {
+    await registerOllamaModel("model-a");
+    const apiKeyAuth = providerForTest().auth.apiKey;
+    assert.ok(apiKeyAuth, "auth.apiKey must be present — pi-ai requires at least one of apiKey/oauth even for a keyless provider");
+    const resolved = await apiKeyAuth.resolve({ ctx: fakeAuthContext, credential: undefined });
+    assert.ok(resolved, "resolve() must report the provider as configured, not 'unconfigured'");
+    assert.ok(typeof resolved.auth.apiKey === "string" && resolved.auth.apiKey.length > 0, "the resolved apiKey must be a non-empty string — a falsy one is exactly what pi-ai's getClientApiKey() throws on at dispatch");
+});

package/dist/test/otel.test.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The OTLP span exporter. Six things are pinned here, and every one of them is
+ * a thing a "simplification" would quietly break:
+ *
+ *  1. ID derivation — deterministic, right length, lowercase hex, never zero.
+ *  2. `traceparent` parsing — strict W3C, and GARBAGE IS SILENT (a malformed CI
+ *     variable must degrade to "own root", never throw, never half-parse).
+ *  3. THE ALLOWLIST — a synthetic EventRecord whose payload carries a marker
+ *     string, asserted absent from the literal JSON body the exporter would
+ *     POST. This is the exfiltration test: `EventRecord.payload` holds tool
+ *     args, result snippets, and the repo's own source. If someone adds a
+ *     `stringValue` read from a payload, this test is what says no.
+ *  4. The queue bound — 3000 spans pushed synchronously stay <= the bound, with
+ *     the overflow counted (drop-OLDEST, so the newest spans survive).
+ *  5. The wire shape — against an in-process `node:http` receiver, not a fetch
+ *     mock, so the assertions are on real bytes: resourceSpans -> scopeSpans ->
+ *     spans nesting, hex ids, AnyValue-wrapped attributes, and nanosecond
+ *     timestamps AS STRINGS (a JSON number loses precision past 2^53).
+ *  6. Failure isolation — an endpoint that 500s or does not exist must resolve
+ *     quietly, because export is never allowed to fail a run.
+ *
+ * Hermetic: every exporter is constructed with an explicit `env` (so the
+ * developer's own TRACEPARENT cannot leak in) and every network case talks to a
+ * loopback server on an ephemeral port.
+ */
+export {};