@phosphorco/bb-thread-metrics 0.0.0-stage → 0.1.0

package/CONTRACT.md

@@ -0,0 +1,318 @@
+# Thread metrics wire v1 (@phosphorco/bb-thread-metrics 0.1.0)
+
+| Supplier owns | Package owns | Host owns |
+| --- | --- | --- |
+| Ledger, edge index, pricing data, observation/retention, source coverage and revisions | Bounded DTOs, dual-edge closure, dollar percentile/heat, fixed RPC, injected adapters and conformance | Discovery triggers, demand batching, caching, navigation, thread panel rendering and recovery |
+
+The package is pure data and transport, without storage, collectors, pricing seeds,
+React, polling or lifecycle scheduling. Root uses Zod and the seed-free algebra
+`/vector` entry. `/bb` accepts injected SDK objects; `/testing` exercises real
+registered handlers on the SDK fake host.
+
+## API sketch (cross-lane alignment)
+
+- `familyClosure(edges, roots, policy?)`: union of parent and lifecycle-owner
+  links, reflexive, cycle/diamond safe, hidden always included, archived default
+  true, deleted excluded. Explicit input/member/depth caps and coverage reasons.
+- `dollarPercentiles(population)`: per-window host-wide active dollar
+  population (finite positive amounts only); ties use strict-lower-count / (N-1).
+  Singleton and all-equal populations rank 0; no median mark. Zero, unknown and
+  inactive get null. `heat(ranks)` gates m20/on-fire, h24/hot, d7/heavy at >=0.9.
+- `threadMetricsDescribe({})`: `{protocol:'bb-thread-metrics',versions:[1],
+  capabilities:{summary:true,series:boolean,detail:boolean}}`. Negotiate envelope
+  before decoding v1 capabilities; unknown output fields tolerated.
+- `threadMetricsReadV1({threadIds,scope,includeArchived?,knownRevisions?,
+  series?:{activeThreadId,maxPoints}})` <=200 unique IDs. A single active ID may
+  request last-24h buckets, <=288. Summary rows never contain descendant records.
+- `threadMetricsDetailV1({threadId,scope,includeArchived?,axis,window,cursor?,limit?})`
+  is optional, explicitly on demand. Axis `model|time`; bounded rows,
+  optional nextCursor, total and coverage metadata. No summary fanout.
+
+Every summary row has threadId/scope/memberCount/coverage/coverageReasons/asOf/
+revision/priceVersion/currency:'USD'/estimated:true/approximation/ranks. Changed
+rows add windows `{m20,h24,d7,lifetime}` of `{tokens:UsageVector,amount:number|null}`;
+unchanged rows omit windows but still carry current metadata and ranks. Revisions
+must fingerprint scope/archive policy/window content/series demand; a producer
+may return unchanged only for a matching known revision. Consumers merge the
+fresh metadata even when unchanged. Price corrections and sliding windows must
+invalidate content revisions. Approximation has bounded reasons and optional
+provider/model/rate attribution (matched, closest-model, provider-default,
+unpriced); missing price is last resort. Provider reported costs remain separate.
+
+Inputs are strict and byte bounded; outputs strip additive fields and enforce
+byte bounds before decoding. Suppliers echo only requested IDs once each; missing
+IDs are partial coverage, never implicit zero. Detail rows reconcile to the stated
+total only when complete; pagination and row limits are explicit. USD ranks must
+be computed from the host-wide dollar population using the same scope and archived
+policy, never token totals or the visible/requested set. Shared descendants count
+once per root. Overlap across separate family roots is comparative data and must
+never be summed into host spend. Ranks carry population asOf/count metadata per window.
+
+Discovery lists once, deduplicates target IDs, probes bounded candidates using
+bounded concurrency, per-call and overall deadlines. Aborting a probe does not
+release its slot until its actual SDK promise settles. A deadline ends the pass;
+late results cannot publish. Failures are independent, keyed by target plugin ID.
+Mount/refresh/reconnect/plugin-lifecycle triggers belong to the consumer; no poll.
+
+## Wire details and producer obligations
+
+Timestamps are Unix milliseconds, finite safe nonnegative integers. Revisions
+and price versions are nonempty strings <=256 characters. Thread/provider IDs
+are <=200 characters, begin alphanumeric and contain only letters, digits,
+underscore, period, colon or hyphen. Model and rate IDs are <=256 characters.
+Amounts are finite nonnegative USD values or null. Null is unknown, never zero;
+null estimates require `missing-price` approximation provenance. `reported`
+uses its own currency and timestamp and is never added to estimated amounts.
+
+Coverage is `complete|partial|unknown`; closed reasons are `source-gap`, `root-unattested`,
+`history-unavailable`, `member-cap`, `depth-cap`, `edge-cap`, `missing-thread`,
+`unpriced`, `retention`, `row-cap`, `pagination`, `population-incomplete`.
+Approximation reasons are `closest-model`, `provider-default`,
+`model-attribution`, `bucket-boundary`, `missing-price`, `source-gap`.
+Nonempty approximation reasons or unmatched rate attribution require the
+`approximate` flag. Each summary carries <=32 rate attribution records, not an
+unbounded catalog; a supplier may omit that optional list while retaining reasons.
+
+Family closure scans <=50,000 edge records and emits <=10,000 members to depth
+<=256. Policy may lower each cap; it may never increase a package bound. Roots
+are <=200. Duplicate edge identities are invalid. A missing root downgrades
+coverage and contributes no invented member. Archived nodes remain traversable
+when excluded from membership, so a live grandchild remains reachable. Deleted
+nodes and traversal through them are excluded. Family results are traversal-order
+arrays and callers must not infer rank from their order. Source completeness is
+an explicit policy input: a complete closure only proves the supplied snapshot.
+
+Dollar population input is explicitly supplied, one amount per distinct thread.
+Amounts must match the requested scope/archive policy at a common snapshot.
+Unknown and zero-dollar threads receive null rank and do not enter the active
+priced population. For N positive known-dollar threads, rank is the number of
+strictly lower amounts divided by N-1; N=1 yields zero. Thus equal peers share
+rank, an all-equal population ranks zero, a unique maximum ranks one, and a
+median thread receives no default heat. Unknown-priced active threads mean
+population coverage is incomplete and must be disclosed. Per-window
+`rankPopulation` contains priced-active count, asOf and coverage. The consumer
+may suppress heat on incomplete coverage without replacing null dollars with zero.
+
+Summary output is `{version:1,rows}`. Read omissions mean unavailable data;
+consumers retain prior values as stale or show unavailable. An omitted row is
+never zero spend. A changed row carries windows and optionally buckets;
+unchanged carries current metadata/ranks only. Recognized `windows` or `buckets`
+content is rejected on unchanged rows before output stripping, even if series was
+requested. Truly unknown additive output fields are stripped. With no series requested the registration adapter strips no known
+bucket field silently: it rejects it. The supplier must avoid computing raw
+breakdowns for summaries; no descendant/model detail field exists in that DTO.
+Buckets have aligned five-minute starts in the last 288 fixed buckets including
+the current bucket at asOf, are strictly increasing, never future, and never
+exceed the requested point count. Null bucket dollars require top-level
+`missing-price` approximation provenance, including when all windows are priced. The input explicitly names
+one active requested thread. The package cannot independently verify UI focus.
+
+Known revisions are bounded by requested IDs and must refer to content for that
+exact scope/archive/series projection. Ingest revision alone is insufficient:
+the revision MUST change with every input capable of changing membership or
+sums: rolling-window/bucket expiry, rate table generation, scope/archive/series
+policy, edge/index revision, membership evidence and retention all participate.
+A change to an input must change revision even if the current numeric sum happens
+to remain equal. A source unable to establish this revision must disclose unknown
+coverage and cannot safely reuse a known revision for an unchanged answer. An unchanged answer still updates asOf,
+coverage, approximation and rank metadata in the consumer cache. Suppliers must
+compare cheap projection revisions before expensive aggregation; the package
+validates the echoed revision and shape but cannot inspect supplier storage or
+prove that comparison cost.
+
+Detail outputs echo thread/scope/axis/window and include asOf, revision,
+priceVersion, currency, estimated, coverage, approximation, total, rows and an
+optional nextCursor. Rows carry tokens, amount and approximation, plus either
+providerId/modelId or start/end. Limits default to 200; cursors <=1024
+characters. Identities are unique per page. Complete unpaginated detail must
+reconcile all four vector components and dollars to total (relative tolerance
+1e-8); null row dollars require a null total. A null detail total always requires
+top-level `missing-price` approximation provenance, even on partial/unknown pages
+with no rows. Pagination must disclose partial
+coverage. Total describes the whole requested projection, not just the page.
+Across pages the supplier must keep one revision stable or reject/restart its
+cursor. Consumers must dedup page identities and discard mixed revisions.
+Model rows aggregate by provider/model after deduplicating family members; time
+rows partition the requested retained window without overlap. Sparse unoccupied
+gaps are allowed and never imply invented spend. Source
+observation/model/bucket uncertainty remains in coverage/approximation.
+
+## Runtime adapters and admission
+
+`registerThreadMetricsOwner(bb, port)` registers strict byte-admitted input
+schemas and validates all responses. Port has capabilities, async read, and
+optional async detail; detail capability must match the handler. Describe/read
+are always registered; detail is registered only when supported. All use
+`experimental_discoverable:true`; no experimental discovery endpoint is called.
+SDK imports in `/bb` are type-only. Public SDK server and browser types are
+accepted by client and discovery helpers.
+
+`createThreadMetricsClient(sdk, pluginId)` binds every call to that target.
+Describe negotiates wire 1 (highest shared supported wire version) before decoding
+capabilities. Fixed read/detail methods are v1; discovery must precede consumer
+use and optional capabilities must be honored. Native errors are classified:
+404/unknown_method -> absent; 503 -> disabled; AbortError -> aborted;
+TimeoutError -> timeout; ZodError -> malformed; other faults -> failed.
+
+`createThreadMetricsDiscovery(sdk)` is one retained per-mounted-coordinator
+resource. Its `discover(options?)` lists once and probes only running/degraded
+plugins, deduped by target ID. It examines <=10,000 listed entries, probes <=128
+candidates, with <=4 actual outstanding probe reads, <=2000ms per probe and a
+<=5000ms overall deadline. Options can lower all budgets. Truncated/unstarted
+candidates are counted in omittedCount and complete is false. This bounds work
+after the SDK list materializes; the SDK owns list transport bytes and its native
+list response is already materialized before this package can inspect it.
+
+A local probe timeout aborts its signal and publishes timeout, but its lane stays
+occupied until the actual promise settles. Overall deadline returns a result and
+suppresses late publication. The coordinator tracks actual list/probe settlement
+across passes, exposing `outstandingReads`. A new pass while running or draining
+returns `listError:'busy'` and performs no I/O. Consumers must retain the same
+coordinator over refresh/reconnect; recreating one bypasses admission. There is
+no global registry or singleton, no automatic retry, queue or poll. Abort stops
+publication, and failures remain per-target; callback faults do not discard
+other target results. A genuinely unresponsive SDK leaves this coordinator busy
+until that SDK read settles; this is honest backpressure, not proof of remote
+cancellation. Consumers retain their last good snapshot during busy/failure.
+
+Input byte limit is 64 KiB, all read/detail output 2 MiB, describe 16 KiB.
+UTF-8 JSON size is checked before schema decoding (including additive fields).
+SDK response objects are already materialized before this check. DTO/schema
+admission does not claim to bound remote transport memory or arbitrary supplier
+work. Output schemas strip additive fields and inputs reject unknown fields.
+
+## Verification and remaining proof
+
+`bun run test` builds JS and tsc declarations, then imports emitted public entries.
+`bun run typecheck` checks source, and `tsc -p tsconfig.public-tests.json --noEmit`
+checks emitted public types with both SDK environments. `npm pack --dry-run
+--json` inventories the package. No dist is committed.
+
+The `/testing` kit registers the adopter's real factory on createFakePluginHost,
+then exercises negotiated describe, representative read/detail cases, strict
+input rejection, count bounds and response semantics through real registered
+handlers. Advertised detail requires detail cases. Every check is locally
+bounded and the report identifies failures; registration/storage behavior and
+live network cancellation are not proven by the kit. The kit does not generate
+a replacement handler or claim exhaustive semantic proof. The supplier must add
+its own rolling-expiry, rate-change, retained-revision, paginated consistency,
+edge-index completeness and dollar-population tests. Host integration tests must
+prove absence/failure/recovery/caching and navigation; live composition and registry
+publication remain separate steward obligations. Optional SDK peers describe the
+intended range; local checks use installed SDK 0.6.52+phosphor, not every version.
+
+
+## Membership boundary and time clipping (owner rulings)
+
+Shared metrics detail supports **model and time only**. It does not enumerate
+members or offer descendant spend rows over RPC. The pure `familyClosure` export
+is reusable internal algebra over an explicitly supplied edge snapshot, not a
+membership discovery endpoint. `readV1` exposes memberCount only. Descendant
+spend/member listing belongs to a ledger-specific internal debrief RPC pending
+adoption of the existing `bb-thread-membership` protocol after stable publication.
+No membership package dependency is added while its exact registry version is
+unavailable. That protocol owns opaque scopes, member enumeration, revision-fenced
+paging and direct/inherited attribution; metrics must not duplicate it.
+
+Coverage vocabulary follows membership: `complete|partial|unknown`. Summary and
+detail may include `excluded`, a nonnegative safe integer counting members/rows
+known to be excluded under the supplier's projection. Omit it when not countable;
+its absence never implies zero. Coverage reasons retain `source-gap` and describe
+why data is partial. All membership/sum input revision duties above are mandatory.
+
+Time detail uses five-minute fixed buckets, consistent with usage-algebra's
+last-N windows. For asOf t, B=300000, and N=4/288/2016 for m20/h24/d7:
+`lower=max(0,floor(t/B)*B-(N-1)*B)`. Lifetime time detail is limited to the same
+retained 2016 buckets as d7; a lifetime total including earlier history therefore
+needs partial retention coverage rather than claiming complete reconciliation.
+`retainedWindowStart(asOf,window)` exposes this lower bound. Summary series uses
+the same boundary with N=288.
+
+Each time interval is half-open `[start,end)`. Start is aligned to B, at least
+lower and strictly less than asOf. End is an aligned bucket boundary or exactly
+asOf, is greater than start and no greater than asOf. Coarser groups spanning
+multiple buckets are allowed. The current interval **must be clipped to asOf**;
+it must not label future time up to the next bucket boundary. At an exact bucket
+boundary the new current bucket contributes zero duration and its zero-width
+interval is omitted. Within each page rows must be sorted by start and disjoint
+(`next.start >= previous.end`); gaps are allowed. The validator enforces these
+rules independently of whether dollar/vector totals happen to reconcile.
+Cross-page interval ordering, completeness and revision consistency remain the
+supplier/consumer paging obligation.
+
+
+## Unattested root evidence (initial 0.1.0 owner ruling)
+
+`root-unattested` means the supplier cannot attest the root thread's own usage
+evidence. It is distinct from `source-gap` and general retention: observed
+family/descendant spend does not establish the missing root's spend. The ledger
+owns detection, omission/floor policy and later recovery; this contract adds no
+membership enumeration or root-policy decision.
+
+For partial coverage with `root-unattested`, positive reported dollars are an
+observed lower bound (floor). Consumers phrase that value **"at least $X"**,
+not a complete spend total. Heat compares these floor dollar amounts under the
+same population policy, preserving partial population coverage; it must not
+invent missing root dollars or substitute tokens. Zero observed root evidence
+must not be shown as zero actual spend: omit the unsupported spend result or
+render it unavailable, retaining any previous good value only as explicitly stale.
+A missing/unattested root is never evidence that actual spend was $0.
+
+When root evidence is later attested, the ledger reconciles it idempotently,
+changes the projection revision when the membership/sum input changes and clears
+`root-unattested` only after the matching evidence is recovered. The consumer
+replaces its floor/unavailable state from the authoritative response. Actual
+recovery/deduplication and UI wording implementations are separate adopter work;
+this package supplies the reason codec and preserves observed values unchanged.
+
+## Byte conformance and aggregate approximation hardening
+
+The conformance kit admits every positive read/detail case with `parseBounded`
+before invoking a handler; shape-only parsing is insufficient. Every supplier
+must reject the mandatory shape-valid oversized read input: 200 unique IDs of
+200 characters plus a 256-character known revision per ID (133051 UTF-8 JSON
+bytes, above the 65536-byte input cap). Count/field validation alone accepts this
+input, so the kit requires a structured invalid_input or Zod validation failure
+from the real registered handler boundary. A raw-schema supplier that omits byte
+admission fails source conformance even if all ordinary reads work. This proves
+local handler admission, not a limit on the SDK's prior transport allocation.
+
+Detail's top-level `approximation` describes the **aggregate total**, not merely
+the page or a separate pricing lookup. If any contributing returned row has
+`approximate:true`, the aggregate must also be approximate and retain every
+reason on that row. A contradictory exact aggregate or a missing row reason is
+rejected. This requirement applies on partial/unknown pages too. Aggregate
+reasons may be a superset of current-page reasons (unseen contributors or
+aggregation uncertainty); partial pages still need not sum to the whole total.
+Across pages the supplier must retain the total's full provenance consistently.
+Existing null-money requirements remain: null total requires top-level
+missing-price provenance, and null row amounts require row missing-price
+provenance. Additive unknown output fields remain tolerated.
+
+Optional rate attribution remains optional; no caller is required to populate
+`rates`. When present, every matched/closest-model/provider-default record must
+have a non-null rateId identifying the selected priced rate. An unpriced record
+must have a null rateId. The codec rejects both contradictory pairings; it does
+not verify a rate against the supplier's operator-owned table.
+
+## Ordinary client deadlines and publication fences
+
+`createThreadMetricsClient` binds the owner and validates the wire data. It only
+forwards the caller's AbortSignal to the SDK. It creates no per-call deadline,
+queue, outstanding-read limit, generation fence or automatic retry, and does not
+promise that abort rejects the call or stops remote work. A supplier/transport
+that ignores abort can still return a schema-valid result after cancellation.
+The discovery coordinator's bounded lifetime/admission does not extend to these
+ordinary read/detail calls.
+
+Consumers own read/detail deadlines and actual outstanding admission across
+refresh/reconnect/replacement requests. Racing a call against a timeout permits
+local UI progress but must not free its transport slot until the actual promise
+settles. A new owner/client instance must not bypass the demand coordinator's
+retained admission budget. After **every await**, before publishing/caching any
+response or error, consumers check their abort state and current generation
+(owner, thread/scope/archive/window/series demand and view lifecycle) and discard
+obsolete outcomes. These post-await fences are required even when the SDK claims
+cancellation support. Keep last good data during failure according to the host's
+staleness policy; a late response cannot revive a disposed/replaced demand.
+No package-global lifecycle or client cancellation machinery is introduced.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Phosphor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# @phosphorco/bb-thread-metrics
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Version 0.1.0: bounded dollar summaries, family closure, heat ranks and optional
+on-demand breakdowns for independent BB plugins. See [CONTRACT.md](CONTRACT.md)
+for ownership, wire semantics and proof limits.
+
+```ts
+import { familyClosure, dollarPercentiles, heat } from '@phosphorco/bb-thread-metrics';
+import { createThreadMetricsDiscovery, createThreadMetricsClient } from '@phosphorco/bb-thread-metrics/bb';
+
+// Retain one coordinator per mounted demand resource, including across refresh.
+const discovery = createThreadMetricsDiscovery(sdk);
+const pass = await discovery.discover({ signal });
+for (const owner of pass.rows) {
+  if (owner.state !== 'ready') continue;
+  const client = createThreadMetricsClient(sdk, owner.pluginId);
+  const summary = await client.read({ threadIds: ['thr_example'], scope: 'family' });
+}
+```
+
+Trigger discovery on mount, refresh, reconnect or plugin lifecycle. `busy` means
+previous actual SDK reads are still outstanding; retain good data and retry only
+on a later consumer trigger. Creating another coordinator to bypass busy defeats
+the bound. No polling or automatic retry is supplied.
+
+`bun run test` builds public JS/declarations before testing emitted entries.
+`bun run typecheck` checks source; `tsc -p tsconfig.public-tests.json --noEmit`
+checks emitted declaration compatibility with server and browser SDKs. The
+`/testing` entry's `runSupplierConformance` accepts the adopter's real registration
+factory and representative read/detail cases. It returns explicit source
+conformance checks, never live host acceptance.

package/dist/bb.js

@@ -0,0 +1,197 @@
+// src/bb.ts
+import { z } from "zod";
+import { LIMITS, METHODS, describeInputSchema, describeEnvelopeSchema, capabilitiesSchema, readInputSchema, detailInputSchema, parseBounded, negotiateVersion, validateReadResult, validateDetailResult, classifyOwnerError } from "./index.js";
+function sdkSchema(schema, maxBytes) {
+  return { "~standard": { version: 1, vendor: "bb-thread-metrics", jsonSchema: { input: () => z.toJSONSchema(schema, { io: "input", unrepresentable: "any" }), output: () => z.toJSONSchema(schema, { io: "output", unrepresentable: "any" }) }, validate(value) {
+    try {
+      return { value: maxBytes === undefined ? schema.parse(value) : parseBounded(schema, value, maxBytes) };
+    } catch (e) {
+      return { issues: e instanceof z.ZodError ? e.issues.map((i) => ({ message: i.message, path: i.path })) : [{ message: "Payload byte limit" }] };
+    }
+  } } };
+}
+function registerThreadMetricsOwner(bb, port) {
+  const capabilities = capabilitiesSchema.parse(port.capabilities);
+  if (capabilities.detail !== Boolean(port.detail))
+    throw new Error("Detail capability/handler mismatch");
+  const describe = () => ({ protocol: "bb-thread-metrics", versions: [1], capabilities });
+  const contract = {
+    threadMetricsDescribe: { input: sdkSchema(describeInputSchema, LIMITS.inputBytes), output: sdkSchema(z.unknown()) },
+    threadMetricsReadV1: { input: sdkSchema(readInputSchema, LIMITS.inputBytes), output: sdkSchema(z.unknown()) }
+  };
+  const handlers = {
+    threadMetricsDescribe: (raw) => {
+      parseBounded(describeInputSchema, raw, LIMITS.inputBytes);
+      return describe();
+    },
+    threadMetricsReadV1: async (raw) => {
+      const input = parseBounded(readInputSchema, raw, LIMITS.inputBytes);
+      if (input.series && !capabilities.series)
+        throw new Error("Series not supported");
+      return validateReadResult(input, await port.read(input));
+    }
+  };
+  bb.rpc.register(contract, handlers, { experimental_discoverable: true });
+  if (port.detail)
+    bb.rpc.register({ threadMetricsDetailV1: { input: sdkSchema(detailInputSchema, LIMITS.inputBytes), output: sdkSchema(z.unknown()) } }, { threadMetricsDetailV1: async (raw) => {
+      const input = parseBounded(detailInputSchema, raw, LIMITS.inputBytes);
+      return validateDetailResult(input, await port.detail(input));
+    } }, { experimental_discoverable: true });
+}
+function createThreadMetricsClient(sdk, pluginId) {
+  if (!pluginId || pluginId.length > 200)
+    throw new Error("Invalid target plugin id");
+  async function call(method, input, signal) {
+    return sdk.plugins.callRpc({ pluginId, method, input, outputSchema: z.unknown(), ...signal ? { signal } : {} });
+  }
+  return {
+    pluginId,
+    async describe(signal) {
+      const raw = await call(METHODS.describe, {}, signal);
+      return negotiateVersion(parseBounded(describeEnvelopeSchema, raw, LIMITS.describeBytes));
+    },
+    async read(raw, signal) {
+      const input = parseBounded(readInputSchema, raw, LIMITS.inputBytes);
+      return validateReadResult(input, await call(METHODS.read, input, signal));
+    },
+    async detail(raw, signal) {
+      const input = parseBounded(detailInputSchema, raw, LIMITS.inputBytes);
+      return validateDetailResult(input, await call(METHODS.detail, input, signal));
+    }
+  };
+}
+async function discoverThreadMetricsOwners(options) {
+  const bounded = (v, max) => {
+    const n = v ?? max;
+    if (!Number.isInteger(n) || n < 1 || n > max)
+      throw new Error("Invalid discovery budget");
+    return n;
+  };
+  const count = bounded(options.maxCandidates, LIMITS.candidates), concurrency = bounded(options.concurrency, LIMITS.concurrency), callMs = bounded(options.callMs, LIMITS.callMs), deadlineMs = bounded(options.deadlineMs, LIMITS.discoveryMs);
+  const pass = new AbortController, rows = new Map, active = new Map;
+  let done = false, ending = false, listedReady = false, omittedCount = 0, eligibleCount = 0, started = 0;
+  const timers = new Set;
+  let finish;
+  const result = new Promise((resolve) => {
+    finish = resolve;
+  });
+  const publish = (row) => {
+    if (done)
+      return;
+    rows.set(row.pluginId, row);
+    try {
+      options.onRow?.(row);
+    } catch {}
+  };
+  const end = (complete, listError) => {
+    if (done || ending)
+      return;
+    ending = true;
+    for (const [pluginId] of active)
+      if (!rows.has(pluginId))
+        publish({ pluginId, state: "error", error: options.signal?.aborted ? "aborted" : "timeout" });
+    done = true;
+    pass.abort();
+    for (const c of active.values())
+      c.abort();
+    for (const t of timers)
+      clearTimeout(t);
+    timers.clear();
+    options.signal?.removeEventListener("abort", abort);
+    finish({ rows: [...rows.values()], omittedCount: omittedCount + Math.max(0, eligibleCount - started), complete, ...listError ? { listError } : {} });
+  };
+  const abort = () => end(false, "aborted");
+  options.signal?.addEventListener("abort", abort, { once: true });
+  if (options.signal?.aborted) {
+    abort();
+    return result;
+  }
+  const deadline = setTimeout(() => end(false, listedReady ? undefined : "timeout"), deadlineMs);
+  timers.add(deadline);
+  (async () => {
+    let listed;
+    try {
+      listed = await options.sdk.plugins.list({ signal: pass.signal });
+    } catch (e) {
+      end(false, classifyOwnerError(e));
+      return;
+    }
+    if (done)
+      return;
+    listedReady = true;
+    const unique = new Map;
+    for (const p of listed.plugins.slice(0, LIMITS.listedPlugins))
+      if (p.id.length <= 200 && (p.status === "running" || p.status === "degraded"))
+        unique.set(p.id, p);
+    const candidates = [...unique.values()].slice(0, count);
+    omittedCount = unique.size - candidates.length + Math.max(0, listed.plugins.length - LIMITS.listedPlugins);
+    eligibleCount = candidates.length;
+    let index = 0;
+    async function worker() {
+      while (!done && index < candidates.length) {
+        const p = candidates[index++];
+        started++;
+        const control = new AbortController;
+        active.set(p.id, control);
+        let timedOut = false;
+        const timer = setTimeout(() => {
+          timedOut = true;
+          control.abort();
+          publish({ pluginId: p.id, state: "error", error: "timeout" });
+        }, callMs);
+        timers.add(timer);
+        try {
+          const negotiated = await createThreadMetricsClient(options.sdk, p.id).describe(control.signal);
+          if (!timedOut && !done)
+            publish(negotiated.kind === "ready" ? { pluginId: p.id, state: "ready", version: 1, capabilities: negotiated.capabilities } : { pluginId: p.id, state: "incompatible" });
+        } catch (e) {
+          if (!timedOut && !done)
+            publish({ pluginId: p.id, state: "error", error: classifyOwnerError(e) });
+        } finally {
+          clearTimeout(timer);
+          timers.delete(timer);
+          active.delete(p.id);
+        }
+      }
+    }
+    await Promise.all(Array.from({ length: Math.min(concurrency, candidates.length) }, () => worker()));
+    if (!done)
+      end(omittedCount === 0);
+  })().catch(() => end(false, "failed"));
+  return result;
+}
+function createThreadMetricsDiscovery(sdk) {
+  let running = false, outstanding = 0;
+  async function track(fn) {
+    outstanding++;
+    try {
+      return await fn();
+    } finally {
+      outstanding--;
+    }
+  }
+  const admitted = { plugins: {
+    list: (args) => track(() => sdk.plugins.list(args)),
+    callRpc: (args) => track(() => sdk.plugins.callRpc(args))
+  } };
+  return {
+    get outstandingReads() {
+      return outstanding;
+    },
+    async discover(options = {}) {
+      if (running || outstanding > 0)
+        return { rows: [], omittedCount: 0, complete: false, listError: "busy" };
+      running = true;
+      try {
+        return await discoverThreadMetricsOwners({ ...options, sdk: admitted });
+      } finally {
+        running = false;
+      }
+    }
+  };
+}
+export {
+  registerThreadMetricsOwner,
+  createThreadMetricsDiscovery,
+  createThreadMetricsClient
+};