@coreplane/switchboard 0.0.0 → 1.18.1

package/dist/assets/src/core/trace/streamSpans.ts

@@ -0,0 +1,163 @@
+/** Which spans reach a run's stream, and how the partition counts each one
+ *  (docs/reference/specs/tracing.md). Everything not named here is log-only by default.
+ *
+ *  Three classes:
+ *  - counted: the span's interval claims one of the four buckets;
+ *  - uncounted: structure only — its own time, minus its counted children, is
+ *    Switchboard overhead by design;
+ *  - background: concurrent, non-blocking work the claim pass ignores entirely.
+ *
+ *  Invariant (tested): every ancestor of a counted span that belongs to a
+ *  different bucket is uncounted, so the deepest counted node can always claim
+ *  an instant without a bucket fight. */
+
+export type Bucket = "getting_ready" | "thinking" | "tools" | "finishing_up";
+export type SpanClass = { kind: "counted"; bucket: Bucket } | { kind: "uncounted" } | { kind: "background" };
+
+/** Who owns the run: an agent run (the default) or a deterministic command run,
+ *  which changes where `run.command` and its grafts count. */
+export type RunOwner = "agent" | "command";
+
+/** The enumerated streamed names. Prefix families (`tool.`, `mcp.`, the two
+ *  graft prefixes) are matched separately. */
+export const STREAMED_SPANS = [
+  "request",
+  "slack.receive",
+  "dispatch.history",
+  "dispatch.admission",
+  "dispatch.ack_card",
+  "dispatch.gate.repo",
+  "dispatch.gate.pr_head",
+  "dispatch.workspace.attach",
+  "dispatch.gate.attached_head",
+  "dispatch.mcp_discovery",
+  "dispatch.compose",
+  "dispatch.channel_visibility",
+  "dispatch.repo_context",
+  "dispatch.memory_read",
+  "dispatch.refuse",
+  "dispatch.ship_preflight",
+  "dispatch.ledger_claim",
+  "run.agent",
+  "run.command",
+  "run.reading_diff",
+  "run.settle_reviewed_head",
+  "run.description_turn",
+  "run.observe_workspace",
+  "run.pr_post_step",
+  "run.reading_diff_join",
+  "run.pr_description_join",
+  "model.turn",
+  "ship.round",
+  "post.card_close",
+  "post.reply",
+] as const;
+
+export type StreamedSpanName = (typeof STREAMED_SPANS)[number];
+
+/** Streamed prefix families and the bucket each counts toward. `run.command.`
+ *  (the op-route grafts) follows `run.command`'s owner-dependent bucket. */
+export const STREAMED_PREFIXES = {
+  "tool.": "tools",
+  "mcp.": "tools",
+  "dispatch.workspace.attach.": "getting_ready",
+  "run.command.": "owner",
+} as const satisfies Record<string, Bucket | "owner">;
+
+const STREAMED_SET: ReadonlySet<string> = new Set(STREAMED_SPANS);
+
+export function isStreamed(name: string): boolean {
+  if (STREAMED_SET.has(name)) return true;
+  return Object.keys(STREAMED_PREFIXES).some((p) => name.startsWith(p));
+}
+
+const GETTING_READY: ReadonlySet<string> = new Set([
+  "slack.receive",
+  "dispatch.history",
+  "dispatch.admission",
+  "dispatch.ack_card",
+  "dispatch.gate.repo",
+  "dispatch.gate.pr_head",
+  "dispatch.workspace.attach",
+  "dispatch.gate.attached_head",
+  "dispatch.mcp_discovery",
+  "dispatch.compose",
+  "dispatch.channel_visibility",
+  "dispatch.repo_context",
+  "dispatch.memory_read",
+  "dispatch.refuse",
+  "dispatch.ship_preflight",
+  "dispatch.ledger_claim",
+]);
+const FINISHING_UP: ReadonlySet<string> = new Set([
+  "run.observe_workspace",
+  "run.pr_post_step",
+  "run.reading_diff_join",
+  "run.pr_description_join",
+]);
+const UNCOUNTED: ReadonlySet<string> = new Set([
+  "request",
+  "run.agent",
+  "ship.round",
+  "run.settle_reviewed_head",
+  "run.description_turn",
+  "post.card_close",
+  "post.reply",
+]);
+const BACKGROUND: ReadonlySet<string> = new Set(["run.reading_diff"]);
+
+/** The class of a streamed name under `owner`. A name that is not streamed has
+ *  no class (log-only spans never reach the partition). */
+export function classOf(name: string, owner: RunOwner): SpanClass | undefined {
+  if (BACKGROUND.has(name)) return { kind: "background" };
+  if (UNCOUNTED.has(name)) return { kind: "uncounted" };
+  if (name === "model.turn") return { kind: "counted", bucket: "thinking" };
+  if (name === "run.command" || name.startsWith("run.command.")) {
+    return { kind: "counted", bucket: owner === "command" ? "tools" : "getting_ready" };
+  }
+  if (GETTING_READY.has(name) || name.startsWith("dispatch.workspace.attach."))
+    return { kind: "counted", bucket: "getting_ready" };
+  if (FINISHING_UP.has(name)) return { kind: "counted", bucket: "finishing_up" };
+  if (name.startsWith("tool.") || name.startsWith("mcp.")) return { kind: "counted", bucket: "tools" };
+  return undefined;
+}
+
+/** The parents each streamed name may have (docs/reference/specs/tracing.md taxonomy) —
+ *  what the ancestor invariant is checked against. Prefix families are keyed by
+ *  their prefix. */
+export const PARENTS: Readonly<Record<string, readonly string[]>> = {
+  request: [],
+  "slack.receive": ["request"],
+  "dispatch.history": ["request"],
+  "dispatch.admission": ["request"],
+  "dispatch.ack_card": ["request"],
+  "dispatch.gate.repo": ["request"],
+  "dispatch.gate.pr_head": ["request"],
+  "dispatch.workspace.attach": ["request"],
+  "dispatch.gate.attached_head": ["request"],
+  "dispatch.mcp_discovery": ["request"],
+  "dispatch.compose": ["request"],
+  "dispatch.channel_visibility": ["request"],
+  "dispatch.repo_context": ["request"],
+  "dispatch.memory_read": ["request"],
+  "dispatch.refuse": ["request"],
+  "dispatch.ship_preflight": ["request"],
+  "dispatch.ledger_claim": ["request"],
+  "run.agent": ["request", "ship.round", "run.settle_reviewed_head", "run.description_turn"],
+  "run.command": ["request"],
+  "run.reading_diff": ["request"],
+  "run.settle_reviewed_head": ["request", "ship.round"],
+  "run.description_turn": ["request", "ship.round"],
+  "run.observe_workspace": ["request", "ship.round"],
+  "run.pr_post_step": ["request", "ship.round"],
+  "run.reading_diff_join": ["request", "ship.round"],
+  "run.pr_description_join": ["request", "ship.round"],
+  "model.turn": ["run.agent"],
+  "ship.round": ["request"],
+  "post.card_close": ["request"],
+  "post.reply": ["request"],
+  "tool.": ["run.agent"],
+  "mcp.": ["tool."],
+  "dispatch.workspace.attach.": ["dispatch.workspace.attach"],
+  "run.command.": ["run.command"],
+};

package/dist/assets/src/core/trace/traceparent.ts

@@ -0,0 +1,29 @@
+/** W3C Trace Context `traceparent` (version 00), strict: exactly
+ *  `00-<32 hex>-<16 hex>-<2 hex>`, lowercase, and neither id all zero. Used
+ *  only between our own Workers (docs/reference/specs/tracing.md: container edges ignore an
+ *  inbound header and mint their own; internal Workers adopt one only inside
+ *  their authenticated branch). */
+
+export interface TraceParent {
+  traceId: string;
+  parentId: string;
+  sampled: boolean;
+}
+
+const TRACEPARENT_RE = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+
+export function parseTraceparent(header: string | null | undefined): TraceParent | undefined {
+  if (typeof header !== "string") return undefined;
+  const m = TRACEPARENT_RE.exec(header.trim());
+  if (!m) return undefined;
+  const [, traceId, parentId, flags] = m;
+  if (/^0+$/.test(traceId) || /^0+$/.test(parentId)) return undefined;
+  return { traceId, parentId, sampled: (parseInt(flags, 16) & 1) === 1 };
+}
+
+export function formatTraceparent(traceId: string, spanId: string, sampled = true): string {
+  return `00-${traceId}-${spanId}-${sampled ? "01" : "00"}`;
+}
+
+/** The three context headers an edge strips or ignores. */
+export const TRACE_CONTEXT_HEADERS = ["traceparent", "tracestate", "baggage"] as const;

package/dist/assets/src/core/trace/tracer.ts

@@ -0,0 +1,247 @@
+/** The one production `Tracer` (docs/reference/specs/tracing.md).
+ *
+ *  Pinned semantics, each with a test:
+ *  - `span(fn)` invokes `fn` synchronously and ends the child in `finally`:
+ *    `ok` on return, `error` and rethrow on throw;
+ *  - `end()` is idempotent; `startedAt` may backdate a span created after the
+ *    fact; a child started after its parent ended is a late child, recorded
+ *    with true times (the stream sink is what refuses it);
+ *  - a throwing sink never reaches traced code;
+ *  - names are sanitized to `[a-z0-9_.-]`, 64 chars, with the MCP bridge's
+ *    hash-suffix rule for a cut name;
+ *  - a failure with a classification records kind and code and no message; an
+ *    unclassified one records its message redacted and capped at 200. */
+import { redactAndCap } from "../redact.js";
+import type { SpanAttrs } from "./attrs.js";
+import { classificationOf } from "./classify.js";
+import { identityContext } from "./context.js";
+import { newSpanId, newTraceId } from "./ids.js";
+import type {
+  Clock,
+  RootOptions,
+  Span,
+  SpanContext,
+  SpanOptions,
+  SpanRecord,
+  SpanSink,
+  SpanStatus,
+  Tracer,
+  ErrorKind,
+  GraftOptions,
+} from "./types.js";
+
+export const SPAN_NAME_MAX = 64;
+export const ERROR_MESSAGE_CAP = 200;
+
+/** Lowercase `[a-z0-9_.-]`, at most 64 chars. A longer name keeps its head and
+ *  ends in `-<8 hex>` of the full name, so two long names never collide into
+ *  one (the same rule the MCP bridge applies to tool names). */
+export function sanitizeSpanName(raw: string): string {
+  const clean =
+    raw
+      .toLowerCase()
+      .replace(/[^a-z0-9_.-]+/g, "_")
+      .replace(/^[_.-]+|[_.-]+$/g, "") || "span";
+  if (clean.length <= SPAN_NAME_MAX) return clean;
+  return `${clean.slice(0, SPAN_NAME_MAX - 9)}-${fnv1a(raw)}`;
+}
+
+function fnv1a(s: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h.toString(16).padStart(8, "0");
+}
+
+export interface TracerOptions {
+  clock: Clock;
+  context?: SpanContext;
+  /** Where a sink's own failure is reported; never rethrown into traced code. */
+  warn?: (message: string) => void;
+}
+
+export function createTracer(opts: TracerOptions): Tracer {
+  const context = opts.context ?? identityContext;
+  const warn = opts.warn ?? ((m: string) => console.warn(m));
+  const shared: Shared = { clock: opts.clock, context, warn };
+  return {
+    clock: opts.clock,
+    start(name, root: RootOptions) {
+      const span = new SpanImpl(shared, {
+        traceId: root.parent?.traceId ?? newTraceId(),
+        parentId: root.parent?.parentId,
+        adopted: root.parent !== undefined,
+        name,
+        sinks: root.sinks,
+        startedAt: root.startedAt,
+        attrs: root.attrs,
+      });
+      span.emitStart();
+      return span;
+    },
+  };
+}
+
+interface Shared {
+  clock: Clock;
+  context: SpanContext;
+  warn: (message: string) => void;
+}
+
+interface SpanInit {
+  traceId: string;
+  parentId: string | undefined;
+  /** A root continuing a remote trace (see `SpanRecord.adopted`); children never are. */
+  adopted?: boolean;
+  name: string;
+  sinks: SpanSink[];
+  startedAt: number | undefined;
+  attrs: SpanAttrs | undefined;
+}
+
+class SpanImpl implements Span {
+  readonly id = newSpanId();
+  readonly traceId: string;
+  readonly name: string;
+  readonly parentId: string | undefined;
+  ended = false;
+  private readonly sinks: SpanSink[];
+  private readonly rec: SpanRecord;
+
+  constructor(
+    private readonly shared: Shared,
+    init: SpanInit,
+  ) {
+    this.traceId = init.traceId;
+    this.parentId = init.parentId;
+    this.name = sanitizeSpanName(init.name);
+    this.sinks = init.sinks;
+    this.rec = {
+      traceId: this.traceId,
+      spanId: this.id,
+      ...(init.parentId ? { parentSpanId: init.parentId } : {}),
+      ...(init.adopted ? { adopted: true as const } : {}),
+      name: this.name,
+      startedAt: init.startedAt ?? shared.clock(),
+      attrs: { ...(init.attrs ?? {}) },
+    };
+  }
+
+  emitStart(): void {
+    for (const s of this.sinks) {
+      try {
+        s.onStart?.(this.record());
+      } catch (err) {
+        this.shared.warn(
+          `[trace] sink onStart threw for ${this.name}: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+  }
+
+  async span<T>(name: string, fn: (span: Span) => Promise<T> | T, opts?: SpanOptions): Promise<T> {
+    const child = this.start(name, opts);
+    try {
+      // `fn` is invoked synchronously here (the async wrapper only defers what
+      // follows the first await inside `fn`), so a caller's ordering holds.
+      const result = await this.shared.context.run(child, () => fn(child));
+      child.end("ok");
+      return result;
+    } catch (err) {
+      child.fail(err);
+      child.end("error");
+      throw err;
+    }
+  }
+
+  start(name: string, opts?: SpanOptions): Span {
+    const child = new SpanImpl(this.shared, {
+      traceId: this.traceId,
+      parentId: this.id,
+      name,
+      sinks: this.sinks,
+      startedAt: opts?.startedAt,
+      attrs: opts?.attrs,
+    });
+    child.emitStart();
+    return child;
+  }
+
+  graft(name: string, opts: GraftOptions): SpanRecord {
+    const child = new SpanImpl(this.shared, {
+      traceId: this.traceId,
+      parentId: this.id,
+      name,
+      sinks: this.sinks,
+      startedAt: opts.startedAt,
+      attrs: opts.attrs,
+    });
+    child.emitStart();
+    child.endAt(Math.max(opts.startedAt, opts.endedAt), opts.status ?? "ok", opts.errorKind, opts.errorCode);
+    return child.record();
+  }
+
+  /** `end` with the end stamp supplied (a graft); the same idempotence and sinks. */
+  private endAt(endedAt: number, status: SpanStatus, errorKind?: ErrorKind, errorCode?: string): void {
+    if (this.ended) return;
+    this.ended = true;
+    this.rec.endedAt = endedAt;
+    this.rec.durationMs = Math.max(0, endedAt - this.rec.startedAt);
+    this.rec.status = status;
+    if (errorKind !== undefined) {
+      this.rec.errorKind = errorKind;
+      if (errorCode !== undefined) this.rec.errorCode = errorCode;
+    }
+    for (const s of this.sinks) {
+      try {
+        s.onEnd(this.record());
+      } catch (err) {
+        this.shared.warn(
+          `[trace] sink onEnd threw for ${this.name}: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+  }
+
+  end(status?: SpanStatus, attrs?: SpanAttrs): void {
+    if (this.ended) return;
+    this.ended = true;
+    if (attrs) this.setAttrs(attrs);
+    const endedAt = this.shared.clock();
+    this.rec.endedAt = endedAt;
+    this.rec.durationMs = Math.max(0, endedAt - this.rec.startedAt);
+    this.rec.status = status ?? this.rec.status ?? "ok";
+    for (const s of this.sinks) {
+      try {
+        s.onEnd(this.record());
+      } catch (err) {
+        this.shared.warn(
+          `[trace] sink onEnd threw for ${this.name}: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+  }
+
+  fail(err: unknown): void {
+    this.rec.status = "error";
+    const c = classificationOf(err);
+    if (c) {
+      this.rec.errorKind = c.kind;
+      if (c.code !== undefined) this.rec.errorCode = c.code;
+      delete this.rec.errorMessage;
+      return;
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    this.rec.errorMessage = redactAndCap(message, ERROR_MESSAGE_CAP);
+  }
+
+  setAttrs(attrs: SpanAttrs): void {
+    (this.rec as { attrs: SpanAttrs }).attrs = { ...this.rec.attrs, ...attrs };
+  }
+
+  record(): SpanRecord {
+    return { ...this.rec, attrs: { ...this.rec.attrs } };
+  }
+}

package/dist/assets/src/core/trace/types.ts

@@ -0,0 +1,125 @@
+/** The one measurement primitive (docs/reference/specs/tracing.md).
+ *
+ *  A span is one unit of work with a start, an end, a name and a parent. A root
+ *  has no parent; one root per message. Every awaited step Switchboard takes
+ *  runs inside `span(fn)` (Execute Around Method), so the timeline of a run is a
+ *  side effect of the code's shape, never a second bookkeeping.
+ *
+ *  Node-free, no I/O: the Workers import this by relative path. */
+import type { SpanAttrs } from "./attrs.js";
+
+/** The only way production code reads the time: injected, never `Date.now()`
+ *  (docs/reference/specs/tracing.md, the clock ratchet). */
+export type Clock = () => number;
+
+export type SpanStatus = "ok" | "error";
+
+/** Our classification of a failure. The peer's own discriminator, where one
+ *  exists, rides beside it as `errorCode`; free text never does for a span whose
+ *  error came from a remote body (see `classify.ts`). */
+export type ErrorKind = "timeout" | "transport" | "http" | "refused" | "infra" | "other";
+
+export interface SpanRecord {
+  traceId: string;
+  spanId: string;
+  parentSpanId?: string;
+  /** The parent belongs to another process: this span is a root of its own
+   *  process that continues a remote trace — a Worker's root adopting the
+   *  bot's `traceparent` (docs/reference/specs/tracing.md item 22). The log sink prints
+   *  it as a root; it never travels on a run stream. */
+  adopted?: true;
+  name: string;
+  startedAt: number;
+  endedAt?: number;
+  durationMs?: number;
+  status?: SpanStatus;
+  errorKind?: ErrorKind;
+  errorCode?: string;
+  /** Redacted and capped; absent whenever the error carries a classification. */
+  errorMessage?: string;
+  attrs: SpanAttrs;
+}
+
+/** Observer of span starts and ends (Observer). Sinks are attached to a root
+ *  and inherited by its whole subtree; a throwing sink never reaches traced
+ *  code. */
+export interface SpanSink {
+  onStart?(span: SpanRecord): void;
+  onEnd(span: SpanRecord): void;
+}
+
+/** The seam the no-gaps test enters through (Strategy): production is the
+ *  identity, so the primitive stays free of `node:async_hooks`; the test wraps
+ *  `fn` in an `AsyncLocalStorage.run`, so a bare await outside any `span(fn)`
+ *  records no current span. */
+export interface SpanContext {
+  run<T>(span: Span, fn: () => T): T;
+}
+
+export interface SpanOptions {
+  attrs?: SpanAttrs;
+  /** Backdate a span created after the fact (a grafted step, a late measure). */
+  startedAt?: number;
+}
+
+/** The one trailing argument a client method takes to join a trace: the
+ *  caller's span, under which the client's outbound call becomes an
+ *  `http.client` span (docs/reference/specs/tracing.md item 24). Absent, the call is the
+ *  plain fetch it was. */
+export interface TraceOptions {
+  span?: Span;
+}
+
+export interface Span {
+  readonly id: string;
+  readonly traceId: string;
+  readonly name: string;
+  readonly parentId: string | undefined;
+  readonly ended: boolean;
+  /** Execute Around Method: start a child, run `fn` inside it (invoked
+   *  synchronously), end it when `fn` settles — `ok` on return, `error` (and
+   *  rethrow) on throw. The one way to time an awaited step. */
+  span<T>(name: string, fn: (span: Span) => Promise<T> | T, opts?: SpanOptions): Promise<T>;
+  /** A handle: a child kept across a suspension point and ended explicitly.
+   *  The root is the only handle in the request path. */
+  start(name: string, opts?: SpanOptions): Span;
+  /** A child recorded after the fact with BOTH stamps supplied — a step another
+   *  process measured (a resident's attach steps), rebased and clipped by the
+   *  caller: its start and end reach the sinks at once, in the given order,
+   *  never entering the context. */
+  graft(name: string, opts: GraftOptions): SpanRecord;
+  /** Idempotent. */
+  end(status?: SpanStatus, attrs?: SpanAttrs): void;
+  /** Record the failure's classification (or its redacted message) without
+   *  ending the span. */
+  fail(err: unknown): void;
+  setAttrs(attrs: SpanAttrs): void;
+  record(): SpanRecord;
+}
+
+export interface GraftOptions {
+  startedAt: number;
+  endedAt: number;
+  status?: SpanStatus;
+  attrs?: SpanAttrs;
+  /** An error's classification, when the measuring process named one; a graft never carries a message. */
+  errorKind?: ErrorKind;
+  errorCode?: string;
+}
+
+export interface RootOptions {
+  sinks: SpanSink[];
+  startedAt?: number;
+  attrs?: SpanAttrs;
+  /** A remote parent to adopt — a Worker's authenticated branch reading the
+   *  bot's `traceparent` (docs/reference/specs/tracing.md item 22): the root joins that
+   *  trace as a child of that span instead of minting its own. */
+  parent?: { traceId: string; parentId: string };
+}
+
+/** The one production implementation is `createTracer`; the seams with two
+ *  implementations are `SpanSink`, `Clock` and `SpanContext`. */
+export interface Tracer {
+  start(name: string, opts: RootOptions): Span;
+  readonly clock: Clock;
+}

package/dist/assets/src/core/trace/workerTrace.ts

@@ -0,0 +1,97 @@
+import type { SpanAttrs } from "./attrs.js";
+import { createLogSink } from "./sinks.js";
+import { formatTraceparent, parseTraceparent, TRACE_CONTEXT_HEADERS } from "./traceparent.js";
+import type { Span, SpanSink, Tracer } from "./types.js";
+
+// The Workers' side of trace context (docs/reference/specs/tracing.md item 22), shared by
+// the shim, the state Worker, the resident and the sandbox — pure functions
+// over the platform's Request/Headers, no I/O. The public edge (the shim)
+// strips whatever context a caller sent and mints its own root; an internal
+// Worker adopts the bot's `traceparent` only after its bearer checked out; a
+// route attr is always a word from a closed table, never the path a caller
+// typed; and an unauthenticated refusal leaves no line at all.
+
+export interface RemoteParent {
+  traceId: string;
+  parentId: string;
+}
+
+/** The parent a `traceparent` header names, or nothing for an absent or malformed one. */
+export function adoptedParent(header: string | null | undefined): RemoteParent | undefined {
+  const tp = parseTraceparent(header);
+  return tp ? { traceId: tp.traceId, parentId: tp.parentId } : undefined;
+}
+
+/** The request without any inbound trace context — what the public edge forwards. */
+export function stripTraceContext(request: Request): Request {
+  const headers = new Headers(request.headers);
+  for (const name of TRACE_CONTEXT_HEADERS) headers.delete(name);
+  return new Request(request, { headers });
+}
+
+/** The request carrying `span` as its trace context — what a Worker sends onward. */
+export function withTraceContext(request: Request, span: Span): Request {
+  const headers = new Headers(request.headers);
+  headers.set("traceparent", formatTraceparent(span.traceId, span.id));
+  return new Request(request, { headers });
+}
+
+/** The shim's closed route table: the word a `bot-shim.fetch` root carries for
+ *  a path. `undefined` means no root at all — a static asset, the favicon, or
+ *  the live view's SSE stream (one long-lived request per open dashboard). */
+export function shimRoute(pathname: string): string | undefined {
+  if (/\.(js|mjs|css|map|ico|svg|png|jpe?g|webp|woff2?|txt)$/i.test(pathname) || pathname.startsWith("/assets/")) {
+    return undefined;
+  }
+  if (/^\/runs\/[^/]+\/events$/.test(pathname)) return undefined;
+  if (pathname === "/healthz") return "healthz";
+  if (pathname === "/ingress") return "ingress";
+  if (pathname === "/mcp" || pathname.startsWith("/mcp/")) return "mcp";
+  if (pathname === "/runs" || pathname.startsWith("/runs/")) return "runs";
+  if (pathname === "/residents" || pathname.startsWith("/residents/")) return "residents";
+  if (pathname === "/costs" || pathname.startsWith("/costs/")) return "costs";
+  if (pathname.startsWith("/api/")) return "api";
+  if (pathname.startsWith("/admin/")) return "admin";
+  if (pathname === "/docs" || pathname.startsWith("/docs/")) return "docs";
+  if (pathname === "/" || pathname === "/index.html") return "page";
+  return "other";
+}
+
+/** A sink that drops the records an unauthenticated refusal would leave: a
+ *  root that ended with HTTP 401 or 403 is never written. */
+export function refusalFilter(sink: SpanSink): SpanSink {
+  const refused = (status: unknown) => status === 401 || status === 403;
+  return {
+    ...(sink.onStart ? { onStart: (rec) => sink.onStart!(rec) } : {}),
+    onEnd: (rec) => {
+      if (refused(rec.attrs.httpStatus)) return;
+      sink.onEnd(rec);
+    },
+  };
+}
+
+/** A Worker's span log: `slow` (the root always, a child when it took a second
+ *  or more), refusals filtered, one JSON line per record through `write`. */
+export function workerLogSink(write: (line: string) => void): SpanSink {
+  return refusalFilter(createLogSink({ level: "slow", write }));
+}
+
+export interface AdoptedRootOptions {
+  sinks: SpanSink[];
+  /** The inbound `traceparent`, read only after the request authenticated. */
+  traceparent?: string | null;
+  startedAt?: number;
+  attrs?: SpanAttrs;
+}
+
+/** A Worker's root for one authenticated request: joins the caller's trace when
+ *  `traceparent` parses, else starts its own. */
+export function startAdoptedRoot(tracer: Tracer, name: string, opts: AdoptedRootOptions): Span {
+  const parent = adoptedParent(opts.traceparent);
+  return tracer.start(name, {
+    sinks: opts.sinks,
+    ...(opts.startedAt !== undefined ? { startedAt: opts.startedAt } : {}),
+    ...(opts.attrs ? { attrs: opts.attrs } : {}),
+    ...(parent ? { parent } : {}),
+  });
+}