@buritica/rootstock
v0.16.0
Published
Shared capabilities for Bun + Postgres knowledge systems: ingestion, chunking, embeddings, retrieval, judgments, and the goldens that prove extractions change nothing.
Readme
rootstock
Shared capabilities for Bun + Postgres knowledge systems: source adapters, ingestion, chunking, embeddings, retrieval and versioned judgments. Several systems graft onto one tested root.
Plain TypeScript with no build step. Bun runs the source directly.
Install
Pin an exact version from npm:
bun add --exact @buritica/rootstockThe office-document extractor needs its optional peers (jszip, mammoth,
unpdf); nothing else pulls them in. serve needs the MCP SDK server
(@modelcontextprotocol/server >=2.4.0 <3) and zod ^4.5.4; serve/auth
also needs better-auth, @better-auth/mcp and @better-auth/cimd, each
>=1.7.17 <1.8. All are optional peers, so the app's own copies are the ones
that load; serve itself never loads Better Auth. An optional peer that is
installed must still satisfy its range, even in an app that never imports
serve: a better-auth below 1.7.17 makes the package manager warn. @better-auth/mcp depends
on @better-auth/oauth-provider ^1.7.17, so that package and
@better-auth/core float with each lockfile: pin them in yours and name the
resolved versions when you bump.
Each capability is a subpath export:
import { runGoldenCli, type GoldenSuite } from "@buritica/rootstock/golden";Capabilities
| Subpath | Status | What it does |
|---|---|---|
| golden | v0.0.1 | Golden snapshots that prove a refactor or extraction changed nothing: canonical JSON, capture/check, a recording fetch, seeded vectors and throwaway Postgres |
| golden/bun-test | v0.0.1 | Registers golden suites as bun test cases |
| retrieval | v0.9.0 | Hybrid search pieces: bm25Query builds a top-K BM25 statement for a lakebase_bm25 index (the lakebase_text Postgres extension), with an optional candidate budget (a set local run first, since the index caps candidates before SQL limit), and reciprocalRankFusion merges ranked lists whose scores are not comparable. The database needs the extension and a lakebase_bm25 index built after the table is populated |
| runner | v0.15.0 | The pull runner (runPull: fetch outside the transaction, a batch transaction per batch with its cursor, quarantine, a quota breaker, a run record, a beforeSettle hook for work that needs the whole listing), plan mode (planPull) and the queue drain (drainQueue) |
| serve | v0.13.1 | An MCP server behind one handle(req): createMcpService runs auth, Host/Origin checks, body limits, the refusal and serving buckets and a deadline in front of the SDK's entry, with every response byte that differs between servers named in a profile; one registerTool seam checks scopes, charges the per-tool buckets, concurrency groups and turn budget, and records every call; installSeams does the same for a stdio server; liveness, cached readiness probes and a draining shutdown; serveSlice for config |
| serve/auth | v0.12.0 | defineAuth: one Better Auth instance as an MCP OAuth resource server (JWT, the MCP and CIMD plugins, magic link or Google sign-in, listed redirects, its rate limiter always on), the routes serve mounts, verify for the MCP path and assertStoreReady for startup |
| usage | v0.14.0 | What a tool call cost and who made it: postgresCallLog batches call records into a table you name (rootstock's migration creates rootstock.mcp_calls) without ever delaying a call and prunes it to the slice's callLog.retention (0.14.0), prometheusToolMetrics counts handler calls, createSpendCeiling keeps a daily per-caller total (tokens or dollars) and refuses past it, usageWiring binds pricing (the runs price table) and error classes into serve; usageSlice for config |
More arrive in phases. Phase 1 extractions must be byte-identical: each consumer adopts a module only where its goldens stay unchanged. Changes that can alter answers come later, one measured change at a time.
Goldens in a consumer repo
// goldens/suites.ts
import type { GoldenSuite } from "@buritica/rootstock/golden";
import { chunkText } from "../src/chunk.ts";
import fixture from "./fixtures/chunk/basic.json";
export const suites: GoldenSuite[] = [
{
capability: "chunk.split",
profile: "myrepo-v1",
cases: [{ id: "basic", input: fixture, run: () => chunkText(fixture.text) }],
},
];// goldens/capture.ts — `bun goldens/capture.ts capture|check`
import { runGoldenCli } from "@buritica/rootstock/golden";
import { suites } from "./suites.ts";
process.exit(await runGoldenCli(suites, { dir: "goldens/data", repo: "myrepo" }));// goldens/goldens.test.ts
import { registerGoldenTests } from "@buritica/rootstock/golden/bun-test";
import { suites } from "./suites.ts";
registerGoldenTests(suites, { dir: "goldens/data" });capture refuses to run when src/ differs from the merge-base with
origin/main, so goldens always record the unmodified behavior.
Operating the run lock, work queue and cursors
The lock and queue subpaths (0.6.0) add three tables in the rootstock
schema: run_locks, work_queue and cursors. The notes below are what an
operator needs before turning them on.
Grants
The migrations create the tables as the role that runs them. When the application connects as a different role, grant it:
USAGEon schemarootstock;SELECT,INSERT,UPDATEonrootstock.run_locks;SELECT,INSERT,UPDATE,DELETEonrootstock.work_queue;SELECT,INSERT,UPDATEonrootstock.cursors.
Without them the lock refuses UNFENCED (the fence cannot write its row) and
the queue and cursor calls fail with the driver's permission error.
Run record. The runs subpath (0.8.0) adds two more tables, runs and
quarantine, owned by the migrating role like the others. When the writers
connect as another role, grant it SELECT, INSERT, UPDATE, DELETE on
rootstock.runs and rootstock.quarantine (or on your own quarantine table,
when you pass one). 0.8.0 also adds two columns to work_queue,
version bigint NOT NULL DEFAULT 0 and claim_token uuid; a consumer that
passes its own queue table adds the same two columns, with the same types and
default, in its own additive migration applied before the 0.8.0 code serves.
Start that migration with SET lock_timeout = '5s';: the ALTER TABLE needs
an exclusive lock for a moment, and without a timeout it queues behind any
open reader of a busy queue table and stalls every queue statement behind it.
Existing table grants on work_queue cover the new columns. Altering
work_queue needs the migrating role to own it (creating tables needed
only CREATE on the schema): check SELECT tableowner FROM pg_tables WHERE
schemaname = 'rootstock' before the first 0.8.0 deploy. A role that only
reads run history (dashboards, freshness checks) needs SELECT on
rootstock.runs.
Rolling back
Rolling a consumer back to 0.5.x after 0.6.0 migrated its database leaves
applied migrations that release has no files for: migrate status reads the
database as ahead (so a drift monitor pages) and apply --manual refuses
until the consumer is on 0.6.0 again. A deploy's apply --deploy still goes
through. Fix forward with a release, not by reverting the migrations.
The same holds for any pre-0.8 release after 0.8.0 migrated a database: three
files read as ahead, apply --deploy goes through, status and apply
--manual stay red until the consumer is on 0.8.x again. A pre-0.8 image
ignores the new tables and columns (a claim token it leaves on a released row
is overwritten by the next 0.8 claim). Once 0.8.0 migrated a database, fix
forward on 0.8.x only: an older line can never ship a migration there.
Run lock
Use a direct endpoint. The lock client must be a dedicated connection to a direct (non-pooled) Postgres endpoint. Through a transaction pooler, the advisory lock and its fencing row can land on backends other runs share, so a lock can be shared or stranded and the lock cannot tell.
Bounded waits. Every statement the gate sends (the ownership probe and each recovery claim) is bounded by
probeStallSeconds. A probe that does not answer in time (a silently dropped socket, a stalled server) spends one ofmaxRecoveries:- The lock closes the stalled session (bounded by
endTimeoutSecondsplus one second), opens a fresh one, emitslock.session_replaced, and claims there. The keepalive stands down until the recovery ends. - If the claim reads the lock held and the fencing row still names this
run, the holder is most likely the run's own stalled backend: a
black-holed connection's backend lives as long as the server's TCP
keepalive allows. The lock ends it with
pg_terminate_backend, only whilepg_locksshows that backend (the pid the run last held the lock on) holding this name while the fencing row still names this run, and emitslock.stalled_backend_terminated. The lock role needs the privilege to end its own backends, which a role has by default; without it the lock emitslock.terminate_failedand only waits. Ifpg_locksshows another backend holding it, the recovery refuses at once and that backend is left alone. - The claim is retried every
wait.pollIntervalMs(at least 100 ms, and even withoutopts.wait) for up toprobeStallSecondsmore.
A recovery that fails or stalls makes the gate throw
UNVERIFIABLE, and every later gate rethrows it; when the run's own backend outlived the poll,lock.recovery_refusedcarries its pid asstalledPid. A gate call can now block for up to about sixprobeStallSecondsplusendTimeoutSeconds(probe, close, a claim and its retry, the terminate, the poll window and its last claim); 0.6.0 refused after one. A waited acquire bounds its try-lock and fence by what is left of the wait (never less thanprobeStallSeconds) and by its signal.release()bounds its unlock byendTimeoutSecondsand frees the in-process turn before closing, so a close that hangs never holds the next waiter (the database lock does, until that session ends).- The lock closes the stalled session (bounded by
Block mode (0.8.0).
wait: { mode: "block" }waits inpg_advisory_lockwithlock_timeoutset to what is left of the wait, andclient_connection_check_intervalset towait.block.checkIntervalMs, then restores both before fencing. An abort ends the waiting session withdestroy()(orclose()when the session has none), so the server drops the waiter instead of granting it later; a grant that races the abort is unlocked at once and refusedABANDONED. The connection check works only on a Linux server: elsewhere the server refuses it, the lock waits without it and emitslock.connection_check_unavailableonce per wait, and a waiter whose client vanished stays queued untillock_timeout. A role-levelstatement_timeoutshorter than the wait ends the wait as an error, notHELD. A session wrapper that spreads a shipped session and overrides onlycloseis skipped on abort: wrapdestroytoo. Block mode needs PostgreSQL 14 or later. On a server that refuses the connection check,lock.connection_check_unavailablefires on every block wait; that is expected there. An abort that lands while the session is still opening or setting up is honoured once that step returns (bounded byprobeStallSeconds), not at once. Over Bun.SQL the abort is prompt only on Bun 1.4.4 or later: before that,close({ timeout: 0 })waits for the waiting statement, so an aborted wait refusesABANDONEDonly whenlock_timeoutfires or the lock is granted (and then freed as the session closes). postgres.js is prompt on every supported Bun.openmust make a new client each call. It runs once for the acquire and once more for each stalled-probe recovery, which closes the session it replaces. Anopenthat wraps one shared client makes that recovery claim on a closed client, and the gate refusesUNVERIFIABLE.Events carry the raw driver error. The
errorfield of a lock event is the error the driver threw, unchanged. Some drivers put the server'shost:portin its message, so scrub it before shipping events somewhere that should not see it.
Work queue
- Events mean the statement succeeded, not that it committed. Called inside a caller's transaction, a queue call runs in a savepoint and emits its event when the statement returns. If the caller's transaction later rolls back, the event still fired for a change that never landed.
"contended"means retry.enqueuereturns"contended"when another writer held the row pastenqueueLockTimeoutMs. Nothing was written, so the caller retries (or drops the event knowingly).- A contended ack leaves the row claimed.
ack,failandextendClaim(0.8.0) wait at mostackLockTimeoutMsfor the row; past that they emitqueue.ack_contendedand rethrow the 55P03. The row stays claimed and is reclaimed when the claim expires, with an attempt charged. - Present the claim.
ack,failandextendClaimtake theclaimthe row came back with fromclaim; a stale holder whose row was reclaimed matches nothing and getsmissing.extendClaimanswering"changed"means new work arrived since the claim: the claim is still extended (0.11.0), so keep going, and the ack releases the row for its next run instead of deleting it.queue.claim_extendedcarrieschanged: boolean(0.11.0). Every writer of the table must run rootstock 0.8.0 or later, or new work never bumps the version and is not seen. - An enqueue on a dead key is parked. When the key is dead-lettered, the
enqueue coalesces into the dead row and reports
queue.enqueuedwithresult: "on_dead". Nothing claims it until someone callsretryDead, so alert on that event. - Alert on a missing
queue.drained. Everyclaimcall emitsqueue.drained, even when it claimed nothing. That event is the worker's liveness signal: its absence over a few drain intervals means the worker stopped. - Write cursors under the run lock.
setCursorhas no compare-and-set: two writers race and the last one wins. Hold the run lock for the source whose cursor you advance.
Run record
finishnever throws for the database. It returns{ written: true }when its row settled,why: "settled-elsewhere"when a later run under the same lock already settled it as interrupted, andwhy: "error"(with the driver'serror, andruns.record_failed) when the write failed. The work itself may have succeeded; only the record is lost, and the next run under the lock settles the row as interrupted. Alert onruns.record_failed.- Retries on a lost connection. When the settle fails with a
connection error (SQLSTATE class 08, 57P01–57P03, or a driver connection
error with no SQLSTATE),
finishretries it up to twice, each afterdeps.sleep(1000)(at once when nosleepis given). When a retry finds no running row, it reads the run's own row back: if the first attempt had committed before the connection dropped, the finish counts as written. Any other failure, or a third one, is the result: later calls return it and send nothing. - Events and results carry the raw driver error.
runs.record_failedandfinish'serrorare the driver's error, unchanged. Some drivers put the statement's parameters in it (the scope, the reason), and a check violation's detail can hold the whole row, so scrub it before shipping it somewhere that should not see run data. - Start the lock's keepalive for every run.
startRundoes not start it. A running row whose fencing row has not beaten forstaleHeartbeatSecondsreadsinterruptedinverdictFor, so a run withoutlock.startKeepalive()turns red once it outlives that bound. The config holdsstaleHeartbeatSecondsat no less than 6 × the lock'sprobeStallSeconds+endTimeoutSeconds+ 1 + 2 ×heartbeatSeconds(426 for 30 s beats, a 60 s stall and a 5 s end timeout), so a run that survives a stalled-probe recovery never reads red; the age is read on the database's clock.runs.lockTabledefaults to the lock slice's table. - Gate at least once every
staleHeartbeatSecondsin a long phase. The keepalive never recovers: after a stalled probe or a lost session it beats nothing until the nextensureExclusive()recovers the lock, so a phase that never calls it readsinterruptedonce it outlives the bound. Calling it per batch is enough. - Two kinds of
interrupted.verdictForreadsinterruptedboth for a settledinterruptedrow and for a row stillrunningwhose heartbeat went stale (itsatis the last beat). Looking for the second withstatus = 'interrupted'finds nothing: look at the job'srunningrows. A running row whose fencing row was taken by something that never callsstartRunhas no heartbeat to judge and is not counted; only the nextstartRununder that lock settles it. - A refused run records no buckets.
finish("refused")writes NULL buckets andreconciledeven afteraccount(); counters, tokens and cost are still recorded.
Pull runner and drain
@buritica/rootstock/runner (0.11.0) runs a pull source and drains a queue.
runPullfetches outside any transaction. Per batch it reads what is stored (existing), fetches what changed at mostfetchConcurrencyat a time, then opens one transaction for the batch's loads, quarantine rows, resolves and cursor. A fetch can take minutes without holding a backend idle in a transaction.- A killed run converges. The cursor moves with the batch that covers
it, so a run killed mid-batch leaves that batch uncommitted and the next
run lists it again. That needs
list(cursorOf(r))to return every ref afterr: when refs can share a cursor across a batch boundary,listmust be inclusive (equal cursors come back, already-stored ones are skipped as unchanged). - The lock is the caller's. Acquire it, start its keepalive, and release
it after
runPullreturns. The runner gates it before each batch, before each fetch, after the fetch pass, before each doc's writes and as the batch transaction's last step. A refusal settlesfailed(lost-lock) with the totals committed so far; inside the transaction it also rolls the batch back. - A quota trip stops after the ref that tripped it. With
quota, a doc counts one hit when its load throws whatisQuotarecognises, or when itstryRepointorloadcalledctx.quotaHit()(even if the load then threw something else, or the doc turned out unchanged). A load that resolves without calling it clears the count; other throws leave it. At the breaker's limit the batch commits through that ref, the cursor lands on it, and the run settlesfailed(quota), even when that ref was the listing's last. Nothing already paid for is rolled back. - Work that needs the listing to be over goes in
beforeSettle. Retracting what a source no longer lists can only run once the listing is done.beforeSettle(ctx)runs once, after every batch committed and the buckets balance, with the lock gated just before and the row stillrunning.await ctx.override(flag)(a brake the operator lifted) writes the flag to the running row at once (Run.recordOverride), so a run killed mid-hook still shows it once settledinterrupted: call it before the act the flag allows, and do not act if it rejects (the row is no longer running).ctx.count(name, n)andctx.meter(...)land on the row when it settles (counts,tokens); unlike a load's context, a bad call throws, and so does a count of the runner's ownfetchedorrepointed. - The hook is not called on a failed run. It is called on an empty
listing, and on an incremental run whose listing started from a cursor:
ctx.backfillflags a window, but only the source knows whether any other listing covered everything, so a hook that removes what was not listed checks that itself. - The hook fences its own writes. The gate before it does not cover
them: call
ctx.ensureExclusive()inside the hook's transaction, just before it commits. A refusal settles the runlost-lock, even when the hook caught it or never awaited it; any other throw settles itbefore-settleand is not rethrown. Either way the row'sphaseisbefore-settle, andrunner.before_settle_started/_finished(outcome, ms, the hook's error) bracket the hook. The hook bounds its own time (one that never resolves keeps the row running and the lock held), and the context refuses calls after the hook returns. - Meter from the load.
ctx.meterandctx.countforward to the run at once. A refusal fromrunsemitsrunner.settle_refusedand never fails the load. They are not undone when the batch rolls back. quarantinedcounts duplicates too. A repeat of an id already processed in the run counts as quarantined without a quarantine row, so the report'squarantinedcan exceed the rows written to the table.- A commit that may have landed reads as a rollback. If the connection
drops after COMMIT is sent, the runner reports
runner.batch_rolled_backand leaves the batch out of the totals; the next run lists from the stored cursor and skips what did land as unchanged. - Fold long exclusion lists. Each
excludedreason becomes a key of the run'sexcludedReasons, so a source with many reasons folds them before returning the listing. An empty reason, or one with a NUL, fails the run as alistfailure. - Events inside a batch can describe a rollback.
runs.quarantined,runs.resolvedandqueue.cursor_writtenfire inside the batch transaction; when the batch rolls back,runner.batch_rolled_backfollows. - Keep slow calls out of
load.loadruns inside the batch transaction, one doc at a time, so a model call there holds the backend idle in the transaction for as long as the batch's loads take. Do slow work infetchwhere you can, and sizebatchSizeto what the loads cost. Fetch errors never count toward the quota breaker: a source'sfetchhandles its own API's limits. - A killed run's row has no totals. The buckets, counters and tokens
reach the row only when the run settles. A run killed after some batches
committed reads
interruptedwith no buckets and no cost, though its rows, quarantine entries (tagged with itsrunId) and paid calls landed. - Check
recordedbefore trusting the row.runner.pull_finishedcarriesrecorded: false(and the reportfinish.written: false) when the settle could not write the run row. planPullwrites nothing. It lists, fetches and classifies each ref as the run would, batch by batch, and stops before load. A source withplanLoadgets the docs that would load inside a READ ONLY transaction, opened after the batch's fetches, that always rolls back.maxRefsplans only the first refs (truncated: true);cursor.wouldStoreis then the cursor after the planned refs, not what a full run would store.drainQueueholds one lock per source. It takes each source's lock without waiting (a refusalisHeldrecognises skips the source; any other propagates), claims a batch, and acks or fails each row, with one archival cap across the whole drain, a contention brake, an interrupt and a fatal stop. Rows left after a cap, an interrupt or a fatal error are failed with yourheldClasstext and an attempt charged. Rows left after a jam, and a row whose ack or fail was contended, stay claimed until the claim expires (leftClaimedcounts them). A throw fromrecord.startends the source as aqueuefailure, its claimed rows likewise left claimed. A lock whose teardown throws emitsdrain.release_failedand pages. Failing a held row charges it an attempt and its backoff, as a reclaim would, so a stop nearmaxAttemptscan dead-letter rows no handler saw.- A killed drain's record is settled by the next drain that claims rows.
record.startruns only after a claim returned rows, so an empty drain leaves an earlierrunningrow as it was.
Serving an MCP server
@buritica/rootstock/serve, serve/auth and usage (0.12.0) build an MCP
server over HTTP from parts an app wires together. Every tool, host and
address below is made up.
import { SQL } from "bun";
import {
createMcpService,
dbProbe,
defineToolScopes,
liveness,
readiness,
SERVE_HARDENING,
type ServeProfile,
type Limits,
type ServeSlice,
} from "@buritica/rootstock/serve";
import { checkAuthSecret, defineAuth } from "@buritica/rootstock/serve/auth";
import { postgresCallLog, type UsageSlice, usageWiring } from "@buritica/rootstock/usage";
import * as z from "zod/v4";
declare const sql: SQL; // the app's own client
declare const authPool: unknown; // the pg Pool (or drizzleAdapter) Better Auth reads
declare const PROFILE: ServeProfile; // every request-handling choice, spelled out
declare const s: ServeSlice; // config.serve: the numbers the config golden prints
declare const usage: UsageSlice & { callLog: NonNullable<UsageSlice["callLog"]> }; // config.usage
declare const withBusyText: (g: ServeSlice["limits"]["concurrency"]) => Limits["concurrency"];
declare const withExhaustedText: (t: ServeSlice["limits"]["turnBudget"]) => Limits["turnBudget"];
declare const sendMail: (to: string, url: string) => Promise<void>;
declare const loginPage: () => string;
declare const consentPage: (query: string) => string;
const clock = { now: () => Date.now(), monotonic: () => performance.now() };
const timers = {
set: (ms: number, fn: () => void) => {
const t = setTimeout(fn, ms);
return () => clearTimeout(t);
},
};
const log = (event: string, fields: Readonly<Record<string, unknown>>) =>
console.log(JSON.stringify({ event, ...fields }));
const toolScopes = defineToolScopes({
id: "notes",
tools: { echo: "mcp:tools" },
implies: { "mcp:tools": ["mcp:tools"] },
});
const auth = defineAuth({
baseURL: "https://notes.example.test",
baseUrlRule: "as-is",
secret: checkAuthSecret(process.env.AUTH_SECRET),
database: authPool,
signIn: {
kind: "magicLink",
allow: { kind: "invited" },
send: sendMail,
sendLimit: { max: 1, windowMs: 60_000, releaseOnFailure: true },
},
registration: { dcr: false },
clientPrivileges: "unset",
redirects: { kind: "listed", hosts: ["client.example.test"], loopback: "if-listed" },
extraScopes: [],
rateLimit: { window: 60, max: 100, rules: {} },
ipAddressHeaders: ["cf-connecting-ip"],
pages: { login: loginPage, consent: consentPage },
pageHeaders: {},
authHeaders: {},
assets: {},
clock,
timers,
log,
});
await auth.assertStoreReady();
// The numbers come from the slice (see "Config prints the numbers" below);
// the wording (`busy`, `exhausted`) stays here. Build `limits` once per
// process: limiter state is keyed on this object.
const profile: ServeProfile = {
...PROFILE,
id: s.id,
bodyLimit: s.bodyLimit,
deadlineMs: s.deadlineMs,
shutdown: s.shutdown,
};
const limits = {
...s.limits,
concurrency: withBusyText(s.limits.concurrency),
turnBudget: withExhaustedText(s.limits.turnBudget),
};
const callLog = postgresCallLog({
sql,
table: usage.callLog.table,
maxBuffered: usage.callLog.maxBuffered,
maxBatch: usage.callLog.maxBatch,
retention: usage.callLog.retention, // null keeps every row
clock,
log,
});
const service = createMcpService({
profile,
serverInfo: { name: "notes", version: "1.0.0" },
registerTools(server) {
server.registerTool(
"echo",
{ description: "Echo the text back", inputSchema: { text: z.string() } },
async ({ text }) => ({ content: [{ type: "text", text }] }),
);
},
auth,
toolScopes,
limits,
usage: usageWiring({
sinks: [callLog],
keepArgs: true,
keepOutput: false,
prices: null,
spend: null,
serverSha: process.env.GIT_SHA ?? null,
}),
hooks: {},
clock,
timers,
randomId: () => crypto.randomUUID(),
log,
});
const health = liveness({ fields: { status: "ok" }, headers: {} });
const ready = readiness({
sha: process.env.GIT_SHA ?? null,
db: dbProbe(sql),
probes: {},
headers: { "content-type": "application/json" },
timing: s.probes,
clock,
timers,
log,
});
const server = Bun.serve({
...SERVE_HARDENING,
idleTimeout: s.idleTimeout ?? SERVE_HARDENING.idleTimeout,
async fetch(req, srv) {
// HTTP/1.0 with no (or a bad) Host leaves a bare path in req.url: URL.parse
// answers null and handle refuses it, so such a probe gets no /health either.
const pathname = URL.parse(req.url)?.pathname;
if (pathname === "/health") return health();
if (pathname === "/ready") return ready();
const res = await service.handle(req, { remoteAddress: srv.requestIP(req)?.address });
return res ?? new Response("Not Found", { status: 404 });
},
});
process.on("SIGTERM", async () => {
await service.shutdown({
signal: "SIGTERM",
server: { stop: (force) => server.stop(force), pending: () => server.pendingRequests },
endPool: (s) => sql.close({ timeout: s }),
});
process.exit(0);
});The profile is the behavior.
ServeProfilespells out every choice that differs between servers: the SDK entry (JSON transport or the stateless handler), which non-POST methods authenticate first, body limits per caller kind, the deadline, Host/Origin rules and each refusal's exact bytes. Every field is required; nothing defaults.A tool's throw can stay on the server.
toolThrow: "generic"answers a handler's throw with{"error":"<tool> failed"}(isError: true), so a database driver's message (SQL, parameters) never reaches the client;"message"sends the error's message, as the SDK does. Either way the call record keeps the thrown error's message (and its class, as classified) for your sinks; with none,serve.tool_threw{tool, errorClass, message} logs it. Never rewritten: a result the handler returns, rootstock's own refusals (the spend ceiling's included), the SDK's output-validation error, and aProtocolErrorthe handler throws, whose message reaches the client as written (including one a proxy tool rethrows from an upstream MCP server). AnaroundCallhook sees the result the client gets. Added in 0.13.0 (required).A request with no usable URL is refused, not a 500. Bun hands
fetcha bare path when it cannot build an absolute URL: HTTP/1.0 with no Host, or a Host that does not parse (HTTP/1.1 without Host gets Bun's own 400). With ahostCheckit gets that check's refusal on every path and face, before any method answer (the 404 text, or the SDK's 403 for that Host, "Missing Host header" when there is none), and a throttledserve.host_refused(reasonunroutable); without one, the profile's 404 with the refusal bucket charged, even underpassUnknown. Parsereq.urlin your ownfetchwithURL.parse, nevernew URL, for the same reason.Limits are per process. Buckets, concurrency groups and turn budgets live in memory: N instances allow N times the rate. Build the
Limitsobject once; a fresh object per request starts every bucket full.Body limits sit under the listener's. A
bodyLimitabove the listener'smaxRequestBodySizeis never reached (Bun refuses first), and null means the listener's cap is the only one.A deadline needs the JSON transport.
deadlineMswithentry.kind: "handler"is refused atcreateMcpService; set it to null there.No
serve.startedline, no request id. The service logs no start line andserve.requestcarries no request id, because either would move a consumer's existing log goldens.hooks.requestFieldsadds fields of your own.handleanswersnullfor a path it does not own when the profile setspassUnknown; otherwise it answers the profile's 404. Mountlivenessandreadinesson your own routes, beforehandle.Every tool goes through one seam.
registerToolsgets anMcpServerwhoseregisterToolchecks the caller's scopes againsttoolScopes, charges the per-tool bucket, concurrency group and turn budget, and hands each call acurrentCall()handle (setResultIds,meter,assertWithinSpend) whose record reaches every sink once the call ends. A stdio server builds its ownMcpServerand callsinstallSeams.Auth routes are served for you. With
auth, the profile'sauthPrefixes(the well-known metadata and Better Auth's API,/jwksunmetered),/login,/consentand the assets go to the auth layer, andprofile.mcpPathrunsauth.verify.credentialsadmits static bearer tokens ahead of OAuth. Anode:httpserver that serves Better Auth itself (toNodeHandler(auth.instance)) wraps each response withauth.wrapNodeAuthResponseto get the same headers and 429 log. Better Auth's tables are the app's to migrate;assertStoreReadyrefuses to start on a store without them.The call log never slows a call.
postgresCallLogwrites in batches from one background writer; a full buffer drops and counts (usage.call_log_dropped).The call log prunes itself. Pass the usage slice's
callLog.retentionand aclocktopostgresCallLog: with{ keepDays }the same writer deletes rows older than that, a pass an hour, 1,000 rows a step and at most 20 steps a pass. Between two steps it writes every row buffered during the first, so a pass costs inserts one delete's wait and traffic cannot starve the pass; a burst larger thanmaxBufferedduring one delete still drops. A pass that stops at the cap with rows left makes the next one due a minute later, so turning retention on over a large table works the backlog off a pass a minute, never back to back (watch autovacuum that first day: freed space is reused, not returned to the OS). Processes pruning one table skip each other's locked rows.idle()drops a pending pass after its step in flight, so shutdown waits for one delete at most.usage.call_log_pruned{deleted, keepDays, steps, ms, more, stopped} logs each pass that deleted rows and the sink's first pass always, so a deploy shows retention is wired;usage.call_log_prune_failed{keepDays, deleted, steps, errorClass, failedPasses} logs a refused step, and the next pass waits the hour. Putpruned()andpruneFailures()on your metrics besidedropped()andfailedBatches(). A table you name needs a uniqueidand an index oncreated_at, or every step scans it. Added in 0.14.0 (required, breaking): setcallLog.retentionin the usage slice (nullkeeps 0.13's behavior, every row) and passretention(plusclockwhen it is not null) topostgresCallLog; a printed config gainsusage.callLog.retention.Alert on the table, not the process.
callLogRetentionStatus({ sql, table, retention })reads both ends ofcreated_atby the database clock and saysoverdueonce the oldest row was more thankeepDaysplusRETENTION_SLACK_DAYS(2, orslackDays) old when the newest row over an hour old was written. That lag sees every way pruning stops while rows still land (refused deletes, retention not wired, a sink that never prunes), where a process's counters see only their own failures, and a quiet week (no calls, so no pass) does not trip it, nor does the first call after one (its row waits an hour before it counts, and its pass runs first). A first backlog bigger than one pass reads overdue until it clears. When inserts fail too the lag freezes; alert on_failed_batches_totalfor that.renderCallLogMetrics({ prefix, table, counts: sink, status })renders the sink's four counters (<prefix>_call_log_dropped_total,_failed_batches_total,_prune_failures_total,_pruned_rows_total) and, with a status,<prefix>_call_log_retention_overdue(0 or 1),_retention_lag_seconds,_oldest_row_age_secondsand_keep_seconds. Alert onretention_overdue == 1, so the slack lives in one place. Read the status on every scrape beside the counters, not in a cached body; on a database error render withstatus: null, so the counters stay, and pair the rule withabsent(..._retention_overdue). A consumer without Prometheus runs the status from a scheduled check instead. Added in 0.16.0. Both rootstock migrations (mcp_calls,spend) are additive and run with rootstock's own (applyRootstockMigrationsormigrateCli).The spend ceiling is checked only where you ask.
createSpendCeilingcharges what each call meters; a tool callsassertWithinSpend()before it spends, and nothing else is ever refused. Two concurrent calls of one caller can both pass the check.Shutdown drains, forces, then flushes.
shutdownstops the listener and waits up todrainMsfor requests, then force-closes what is left (server.stop(true)and the SDK entry, each withinforceMs), then waits up toflushMsfor every sink'sidle(), the spend charger'sidle()(its writes in flight) and the auth layer's pending sends, then closes the pool withinpoolEndTimeoutS.Config prints the numbers.
defineRootstockConfigtakesserve(serveSlice: body limits, deadline, idle timeout, shutdown, limits and probe timing) andusage(usageSlice). They print in the config golden only when given, and bring built-in invariants:serve-deadline-idle(when both a deadline and an idle timeout are set),serve-probe-timeout, andusage-spend-prices(for a ceiling in dollars). The slices hold numbers only.createMcpServicenever reads a config: the app hands the slice's values to it, and nothing checks that the profile and limits it passes match the slice it printed. Pass them from the slice, not beside it:const s = config.serve!; // the slice your config golden prints const profile = { ...PROFILE, id: s.id, bodyLimit: s.bodyLimit, deadlineMs: s.deadlineMs, shutdown: s.shutdown }; const limits = { ...s.limits, concurrency: withBusyText(s.limits.concurrency), turnBudget: withExhaustedText(s.limits.turnBudget) }; Bun.serve({ ...SERVE_HARDENING, idleTimeout: s.idleTimeout ?? SERVE_HARDENING.idleTimeout, fetch }); readiness({ ...rest, timing: s.probes });withBusyTextandwithExhaustedTextstand for your own wording (busy,exhausted), which the slice does not hold. The slice refuses some values the runtime would take but that never work (a fractional bucket capacity, a probe timeout under 1 ms).
Rules
- Inject dependencies (SQL client,
fetch, clock, logger). Modules never readprocess.envand never open their own connections. - Test fixtures are synthetic. Consumer data never goes into this repo.
- The capability vocabulary in
src/golden/capabilities.tsis shared by every consumer. Adding an id is additive (a patch release while on 0.x); renaming or removing one is breaking.
License
MIT
