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

package/dist/index.js

@@ -0,0 +1,304 @@
+// src/index.ts
+import { z } from "zod";
+import { UsageVectorSchema } from "@phosphorco/bb-usage-algebra/vector";
+var LIMITS = Object.freeze({ threadIds: 200, seriesPoints: 288, detailRows: 200, inputBytes: 65536, outputBytes: 2097152, describeBytes: 16384, candidates: 128, listedPlugins: 1e4, concurrency: 4, callMs: 2000, discoveryMs: 5000, familyEdges: 50000, familyMembers: 1e4, familyDepth: 256 });
+var METRIC_BUCKET_MS = 300000;
+var WINDOW_BUCKETS = { m20: 4, h24: 288, d7: 2016, lifetime: 2016 };
+function retainedWindowStart(asOf, window) {
+  time.parse(asOf);
+  windowSchema.parse(window);
+  return Math.max(0, Math.floor(asOf / METRIC_BUCKET_MS) * METRIC_BUCKET_MS - (WINDOW_BUCKETS[window] - 1) * METRIC_BUCKET_MS);
+}
+var METHODS = Object.freeze({ describe: "threadMetricsDescribe", read: "threadMetricsReadV1", detail: "threadMetricsDetailV1" });
+var id = z.string().min(1).max(200).regex(/^[A-Za-z0-9][A-Za-z0-9_.:-]*$/);
+var text = z.string().min(1).max(256);
+var time = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+var money = z.number().finite().nonnegative().nullable();
+var scope = z.enum(["own", "family"]);
+var windowSchema = z.enum(["m20", "h24", "d7", "lifetime"]);
+var coverageSchema = z.enum(["complete", "partial", "unknown"]);
+var coverageReasonSchema = z.enum(["source-gap", "root-unattested", "history-unavailable", "member-cap", "depth-cap", "edge-cap", "missing-thread", "unpriced", "retention", "row-cap", "pagination", "population-incomplete"]);
+var reasons = z.array(coverageReasonSchema).max(16);
+var approximationSchema = z.object({
+  approximate: z.boolean(),
+  reasons: z.array(z.enum(["closest-model", "provider-default", "model-attribution", "bucket-boundary", "missing-price", "source-gap"])).max(6),
+  rates: z.array(z.object({ providerId: id, modelId: text, rateId: text.nullable(), basis: z.enum(["matched", "closest-model", "provider-default", "unpriced"]) }).superRefine((rate, ctx) => {
+    if (rate.basis === "unpriced" !== (rate.rateId === null))
+      ctx.addIssue({ code: "custom", path: ["rateId"], message: "Priced basis requires rateId; unpriced basis requires null" });
+  })).max(32).optional()
+}).strip().superRefine((v, ctx) => {
+  if (!v.approximate && (v.reasons.length || v.rates?.some((r) => r.basis !== "matched")))
+    ctx.addIssue({ code: "custom", message: "Approximation provenance requires approximate flag" });
+});
+var rank = z.number().finite().min(0).max(1).nullable();
+var ranksSchema = z.object({ m20: rank, h24: rank, d7: rank }).strip();
+var population = z.object({ asOf: time, count: z.number().int().nonnegative(), coverage: coverageSchema }).strip();
+var rankPopulationSchema = z.object({ m20: population, h24: population, d7: population }).strip();
+var windowValueSchema = z.object({ tokens: UsageVectorSchema, amount: money }).strip();
+var windowsSchema = z.object({ m20: windowValueSchema, h24: windowValueSchema, d7: windowValueSchema, lifetime: windowValueSchema }).strip();
+var bucketSchema = z.object({ start: time, amount: money }).strip();
+var metadata = {
+  threadId: id,
+  scope,
+  memberCount: z.number().int().nonnegative().max(LIMITS.familyMembers),
+  coverage: coverageSchema,
+  coverageReasons: reasons,
+  excluded: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).optional(),
+  asOf: time,
+  revision: text,
+  priceVersion: text,
+  currency: z.literal("USD"),
+  estimated: z.literal(true),
+  approximation: approximationSchema,
+  ranks: ranksSchema,
+  rankPopulation: rankPopulationSchema,
+  reported: z.object({ amount: z.number().finite().nonnegative(), currency: z.string().min(1).max(16), asOf: time }).strip().optional()
+};
+var summaryRowSchema = z.discriminatedUnion("changed", [
+  z.object({ ...metadata, changed: z.literal(true), windows: windowsSchema, buckets: z.array(bucketSchema).max(LIMITS.seriesPoints).optional() }).strip(),
+  z.object({ ...metadata, changed: z.literal(false), windows: z.never().optional(), buckets: z.never().optional() }).strip()
+]);
+var readInputSchema = z.object({
+  threadIds: z.array(id).min(1).max(LIMITS.threadIds),
+  scope,
+  includeArchived: z.boolean().optional(),
+  knownRevisions: z.record(id, text).optional(),
+  series: z.object({ activeThreadId: id, maxPoints: z.number().int().min(1).max(LIMITS.seriesPoints) }).strict().optional()
+}).strict().superRefine((v, ctx) => {
+  if (new Set(v.threadIds).size !== v.threadIds.length)
+    ctx.addIssue({ code: "custom", message: "Duplicate thread IDs" });
+  if (v.series && !v.threadIds.includes(v.series.activeThreadId))
+    ctx.addIssue({ code: "custom", message: "Series requires requested active thread" });
+  if (v.knownRevisions && Object.keys(v.knownRevisions).some((k) => !v.threadIds.includes(k)))
+    ctx.addIssue({ code: "custom", message: "Unrequested revision key" });
+});
+var readResultSchema = z.object({ version: z.literal(1), rows: z.array(summaryRowSchema).max(LIMITS.threadIds) }).strip();
+var detailInputSchema = z.object({ threadId: id, scope, includeArchived: z.boolean().optional(), axis: z.enum(["model", "time"]), window: windowSchema, cursor: z.string().min(1).max(1024).optional(), limit: z.number().int().min(1).max(LIMITS.detailRows).optional() }).strict();
+var detailBase = { amount: money, tokens: UsageVectorSchema, approximation: approximationSchema };
+var detailRowSchema = z.discriminatedUnion("axis", [
+  z.object({ ...detailBase, axis: z.literal("model"), providerId: id, modelId: text }).strip(),
+  z.object({ ...detailBase, axis: z.literal("time"), start: time, end: time }).strip().refine((v) => v.end > v.start, { message: "Empty time interval" })
+]);
+var detailResultSchema = z.object({ version: z.literal(1), threadId: id, scope, axis: z.enum(["model", "time"]), window: windowSchema, asOf: time, revision: text, priceVersion: text, currency: z.literal("USD"), estimated: z.literal(true), coverage: coverageSchema, coverageReasons: reasons, excluded: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).optional(), approximation: approximationSchema, total: windowValueSchema, rows: z.array(detailRowSchema).max(LIMITS.detailRows), nextCursor: z.string().min(1).max(1024).optional() }).strip();
+var describeInputSchema = z.object({}).strict();
+var describeEnvelopeSchema = z.object({ protocol: z.literal("bb-thread-metrics"), versions: z.array(z.number().int().positive()).max(16) }).passthrough();
+var capabilitiesSchema = z.object({ summary: z.literal(true), series: z.boolean(), detail: z.boolean() }).strip();
+var describeV1Schema = describeEnvelopeSchema.extend({ capabilities: capabilitiesSchema });
+function parseBounded(schema, value, maxBytes) {
+  const json = JSON.stringify(value);
+  if (json === undefined || new TextEncoder().encode(json).byteLength > maxBytes) {
+    const error = new Error("Payload byte limit");
+    error.name = "MetricsCodecError";
+    throw error;
+  }
+  return schema.parse(value);
+}
+function negotiateVersion(value) {
+  const env = describeEnvelopeSchema.safeParse(value);
+  if (!env.success || !env.data.versions.includes(1))
+    return { kind: "incompatible" };
+  const v = describeV1Schema.safeParse(value);
+  return v.success ? { kind: "ready", version: 1, capabilities: v.data.capabilities } : { kind: "incompatible" };
+}
+function dollarPercentiles(population2) {
+  const seen = new Set;
+  for (const p of population2) {
+    if (seen.has(p.threadId))
+      throw new Error("Duplicate population thread");
+    seen.add(p.threadId);
+    if (p.amount !== null && (!Number.isFinite(p.amount) || p.amount < 0))
+      throw new Error("Invalid dollars");
+  }
+  const active = population2.filter((p) => p.amount !== null && p.amount > 0);
+  const sorted = active.map((p) => p.amount).sort((a, b) => a - b);
+  const lower = new Map;
+  sorted.forEach((x, i) => {
+    if (!lower.has(x))
+      lower.set(x, i);
+  });
+  return new Map(population2.map((p) => [p.threadId, p.amount === null || p.amount === 0 ? null : active.length < 2 ? 0 : lower.get(p.amount) / (active.length - 1)]));
+}
+function heat(ranks, gates = { m20: 0.9, h24: 0.9, d7: 0.9 }) {
+  for (const w of ["m20", "h24", "d7"])
+    if (!Number.isFinite(gates[w]) || gates[w] < 0 || gates[w] > 1)
+      throw new Error("Invalid gate");
+  return ranks.m20 !== null && ranks.m20 >= gates.m20 ? "on-fire" : ranks.h24 !== null && ranks.h24 >= gates.h24 ? "hot" : ranks.d7 !== null && ranks.d7 >= gates.d7 ? "heavy" : null;
+}
+function familyClosure(edges, roots, policy = {}) {
+  const cap = (n, fallback) => {
+    const v = n ?? fallback;
+    if (!Number.isInteger(v) || v < 1 || v > fallback)
+      throw new Error("Invalid family cap");
+    return v;
+  };
+  const maxMembers = cap(policy.maxMembers, LIMITS.familyMembers), maxDepth = cap(policy.maxDepth, LIMITS.familyDepth), maxEdges = cap(policy.maxEdges, LIMITS.familyEdges);
+  if (roots.length > LIMITS.threadIds)
+    throw new Error("Too many roots");
+  const why = new Set, nodes = new Map, children = new Map;
+  if (edges.length > maxEdges)
+    why.add("edge-cap");
+  for (const e of edges.slice(0, maxEdges)) {
+    if (nodes.has(e.threadId))
+      throw new Error("Duplicate edge thread");
+    nodes.set(e.threadId, e);
+    for (const p of [e.parentThreadId, e.lifecycleOwnerThreadId])
+      if (p) {
+        let c = children.get(p);
+        if (!c)
+          children.set(p, c = new Set);
+        c.add(e.threadId);
+      }
+  }
+  const queue = Array.from(new Set(roots), (threadId) => ({ threadId, depth: 0 })), seen = new Set, members = [];
+  for (let i = 0;i < queue.length; i++) {
+    const { threadId, depth } = queue[i];
+    if (seen.has(threadId))
+      continue;
+    seen.add(threadId);
+    const node = nodes.get(threadId);
+    if (!node) {
+      why.add("missing-thread");
+      continue;
+    }
+    if (node.deleted)
+      continue;
+    if (policy.includeArchived !== false || !node.archived) {
+      if (members.length >= maxMembers) {
+        why.add("member-cap");
+        break;
+      }
+      members.push(threadId);
+    }
+    const next = children.get(threadId);
+    if (next) {
+      if (depth >= maxDepth) {
+        if ([...next].some((c) => !seen.has(c)))
+          why.add("depth-cap");
+      } else
+        for (const c of next)
+          if (!seen.has(c))
+            queue.push({ threadId: c, depth: depth + 1 });
+    }
+  }
+  const source = coverageSchema.parse(policy.sourceCoverage ?? "complete");
+  if (source === "partial")
+    why.add("source-gap");
+  if (source === "unknown")
+    why.add("history-unavailable");
+  return { members, coverage: source === "unknown" ? "unknown" : why.size ? "partial" : "complete", coverageReasons: [...why] };
+}
+function validateReadResult(input, value) {
+  const out = parseBounded(readResultSchema, value, LIMITS.outputBytes), seen = new Set;
+  for (const row of out.rows) {
+    if (!input.threadIds.includes(row.threadId) || row.scope !== input.scope || seen.has(row.threadId))
+      throw new Error("Unrequested, duplicate or wrong-scope row");
+    seen.add(row.threadId);
+    if (!row.changed && input.knownRevisions?.[row.threadId] !== row.revision)
+      throw new Error("Unmatched unchanged revision");
+    if (row.changed && Object.values(row.windows).some((w) => w.amount === null) && !row.approximation.reasons.includes("missing-price"))
+      throw new Error("Unknown dollars require missing-price provenance");
+    if (row.changed && row.buckets) {
+      if (input.series?.activeThreadId !== row.threadId || row.buckets.length > input.series.maxPoints)
+        throw new Error("Unrequested series");
+      for (let i = 0;i < row.buckets.length; i++) {
+        const b = row.buckets[i];
+        if (b.amount === null && !row.approximation.reasons.includes("missing-price"))
+          throw new Error("Unknown bucket dollars require missing-price provenance");
+        if (b.start % METRIC_BUCKET_MS !== 0 || b.start > row.asOf || b.start < retainedWindowStart(row.asOf, "h24") || i > 0 && b.start <= row.buckets[i - 1].start)
+          throw new Error("Invalid series range/order");
+      }
+    }
+  }
+  return out;
+}
+function validateDetailResult(input, value) {
+  const out = parseBounded(detailResultSchema, value, LIMITS.outputBytes);
+  if (out.total.amount === null && !out.approximation.reasons.includes("missing-price"))
+    throw new Error("Unknown total dollars require missing-price provenance");
+  if (out.nextCursor && out.coverage === "complete")
+    throw new Error("Pagination must disclose incomplete coverage");
+  if (out.threadId !== input.threadId || out.scope !== input.scope || out.axis !== input.axis || out.window !== input.window || out.rows.length > (input.limit ?? LIMITS.detailRows))
+    throw new Error("Detail request mismatch");
+  let priorEnd;
+  const keys = new Set;
+  for (const row of out.rows) {
+    if (row.approximation.approximate && (!out.approximation.approximate || row.approximation.reasons.some((reason) => !out.approximation.reasons.includes(reason))))
+      throw new Error("Aggregate total must retain contributing row approximation provenance");
+    if (row.amount === null && !row.approximation.reasons.includes("missing-price"))
+      throw new Error("Unknown dollars require missing-price provenance");
+    if (row.axis !== input.axis)
+      throw new Error("Detail axis mismatch");
+    if (row.axis === "time") {
+      if (row.start < retainedWindowStart(out.asOf, input.window) || row.start >= out.asOf || row.end > out.asOf || row.start % METRIC_BUCKET_MS !== 0 || row.end !== out.asOf && row.end % METRIC_BUCKET_MS !== 0 || priorEnd !== undefined && row.start < priorEnd)
+        throw new Error("Invalid time detail range/order/overlap");
+      priorEnd = row.end;
+    }
+    const key = row.axis === "model" ? JSON.stringify([row.providerId, row.modelId]) : String(row.start);
+    if (keys.has(key))
+      throw new Error("Duplicate detail row");
+    keys.add(key);
+  }
+  if (out.coverage === "complete" && !input.cursor && !out.nextCursor) {
+    for (const key of ["inputUncached", "cacheRead", "cacheWrite", "output"]) {
+      const sum = out.rows.reduce((n, r) => n + r.tokens[key], 0);
+      if (!Number.isFinite(sum) || Math.abs(sum - out.total.tokens[key]) > 0.00000001 * Math.max(1, sum, out.total.tokens[key]))
+        throw new Error("Detail token total mismatch");
+    }
+    const hasUnknown = out.rows.some((r) => r.amount === null);
+    if (hasUnknown && out.total.amount !== null)
+      throw new Error("Unknown detail dollars must remain unknown");
+    if (!hasUnknown) {
+      const sum = out.rows.reduce((n, r) => n + (r.amount ?? 0), 0);
+      if (out.total.amount === null || !Number.isFinite(sum) || Math.abs(sum - out.total.amount) > 0.00000001 * Math.max(1, sum, out.total.amount))
+        throw new Error("Detail dollar total mismatch");
+    }
+  }
+  return out;
+}
+function classifyOwnerError(error) {
+  const e = error;
+  if (e?.status === 404 || e?.code === "unknown_method")
+    return "absent";
+  if (e?.status === 503)
+    return "disabled";
+  if (e?.name === "TimeoutError")
+    return "timeout";
+  if (e?.name === "AbortError")
+    return "aborted";
+  if (e?.name === "ZodError" || e?.name === "MetricsCodecError")
+    return "malformed";
+  return "failed";
+}
+export {
+  windowsSchema,
+  windowValueSchema,
+  windowSchema,
+  validateReadResult,
+  validateDetailResult,
+  summaryRowSchema,
+  retainedWindowStart,
+  readResultSchema,
+  readInputSchema,
+  ranksSchema,
+  rankPopulationSchema,
+  parseBounded,
+  negotiateVersion,
+  heat,
+  familyClosure,
+  dollarPercentiles,
+  detailRowSchema,
+  detailResultSchema,
+  detailInputSchema,
+  describeV1Schema,
+  describeInputSchema,
+  describeEnvelopeSchema,
+  coverageSchema,
+  coverageReasonSchema,
+  classifyOwnerError,
+  capabilitiesSchema,
+  bucketSchema,
+  approximationSchema,
+  METRIC_BUCKET_MS,
+  METHODS,
+  LIMITS
+};

package/dist/testing.js

@@ -0,0 +1,81 @@
+// src/testing.ts
+import { createFakePluginHost } from "@get-bb/plugin-sdk/testing";
+import { METHODS, LIMITS, readInputSchema, detailInputSchema, describeEnvelopeSchema, parseBounded, negotiateVersion, validateReadResult, validateDetailResult } from "./index.js";
+async function runSupplierConformance(options) {
+  if (!options.readCases.length)
+    throw new Error("At least one real read case required");
+  const host = createFakePluginHost({ pluginId: options.pluginId }), checks = [];
+  const deadline = options.deadlineMs ?? LIMITS.callMs;
+  if (!Number.isInteger(deadline) || deadline < 1 || deadline > LIMITS.discoveryMs)
+    throw new Error("Invalid conformance deadline");
+  const call = (method, input) => host.harness.behavior.callRpc(method, input);
+  async function check(name, fn) {
+    let timer;
+    try {
+      await Promise.race([fn(), new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error("Conformance deadline")), deadline);
+      })]);
+      checks.push({ name, passed: true });
+    } catch (e) {
+      checks.push({ name, passed: false, error: e instanceof Error ? e.message : String(e) });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  function validationError(e) {
+    const v = e;
+    return v.name === "ZodError" && Array.isArray(v.issues) || v.code === "invalid_input" || v.body?.code === "invalid_input";
+  }
+  async function rejectsInput(method, input) {
+    try {
+      await call(method, input);
+    } catch (e) {
+      if (validationError(e))
+        return;
+      throw new Error("Expected structured invalid_input or ZodError");
+    }
+    throw new Error("Invalid input accepted");
+  }
+  try {
+    await options.register(host.bb);
+    let detail = false;
+    await check("describe-negotiation", async () => {
+      const n = negotiateVersion(parseBounded(describeEnvelopeSchema, await call(METHODS.describe, {}), LIMITS.describeBytes));
+      if (n.kind !== "ready")
+        throw new Error("No compatible v1");
+      detail = n.capabilities.detail;
+    });
+    await check("strict-describe-input", () => rejectsInput(METHODS.describe, { unexpected: true }));
+    for (let i = 0;i < options.readCases.length; i++)
+      await check(`read-${i}`, async () => {
+        const input = parseBounded(readInputSchema, options.readCases[i], LIMITS.inputBytes);
+        validateReadResult(input, await call(METHODS.read, input));
+      });
+    await check("strict-read-input", () => rejectsInput(METHODS.read, { ...options.readCases[0], unexpected: true }));
+    await check("oversized-id-count", () => rejectsInput(METHODS.read, { scope: "family", threadIds: Array.from({ length: 201 }, (_, i) => `thr_${i}`) }));
+    await check("oversized-input-bytes", async () => {
+      const threadIds = Array.from({ length: 200 }, (_, i) => `thr_${i}_`.padEnd(200, "x"));
+      const oversized = { scope: "family", threadIds, knownRevisions: Object.fromEntries(threadIds.map((id) => [id, "r".repeat(256)])) };
+      readInputSchema.parse(oversized);
+      if (new TextEncoder().encode(JSON.stringify(oversized)).byteLength <= LIMITS.inputBytes)
+        throw new Error("Byte fixture is not oversized");
+      await rejectsInput(METHODS.read, oversized);
+    });
+    if (detail) {
+      if (!options.detailCases?.length)
+        checks.push({ name: "detail-cases-required", passed: false, error: "Advertised detail needs real cases" });
+      for (let i = 0;i < (options.detailCases?.length ?? 0); i++)
+        await check(`detail-${i}`, async () => {
+          const input = parseBounded(detailInputSchema, options.detailCases[i], LIMITS.inputBytes);
+          validateDetailResult(input, await call(METHODS.detail, input));
+        });
+      await check("strict-detail-input", () => rejectsInput(METHODS.detail, { ...options.detailCases?.[0], unexpected: true }));
+    }
+  } finally {
+    await host.harness.lifecycle.dispose();
+  }
+  return { passed: checks.every((c) => c.passed), checks, proof: "source-conformance" };
+}
+export {
+  runSupplierConformance
+};

package/dist/types/bb.d.ts

@@ -0,0 +1,286 @@
+import type { BbPluginApi } from '@get-bb/plugin-sdk';
+import type { PluginBrowserBbSdk } from '@get-bb/plugin-sdk/app';
+import type { ReadInput, ReadResult, DetailInput, DetailResult, Capabilities, OwnerErrorKind } from './index.js';
+export type MetricsSdk = {
+    readonly plugins: Pick<BbPluginApi['sdk']['plugins'], 'list' | 'callRpc'>;
+} | {
+    readonly plugins: Pick<PluginBrowserBbSdk['plugins'], 'list' | 'callRpc'>;
+};
+export interface MetricsPort {
+    capabilities: Capabilities;
+    read(input: ReadInput): Promise<ReadResult>;
+    detail?(input: DetailInput): Promise<DetailResult>;
+}
+export declare function registerThreadMetricsOwner(bb: Pick<BbPluginApi, 'rpc'>, port: MetricsPort): void;
+export declare function createThreadMetricsClient(sdk: MetricsSdk, pluginId: string): {
+    pluginId: string;
+    describe(signal?: AbortSignal): Promise<{
+        kind: "ready";
+        version: 1;
+        capabilities: Capabilities;
+    } | {
+        kind: "incompatible";
+    }>;
+    read(raw: ReadInput, signal?: AbortSignal): Promise<{
+        version: 1;
+        rows: ({
+            changed: true;
+            windows: {
+                m20: {
+                    tokens: {
+                        inputUncached: number;
+                        cacheRead: number;
+                        cacheWrite: number;
+                        output: number;
+                    };
+                    amount: number | null;
+                };
+                h24: {
+                    tokens: {
+                        inputUncached: number;
+                        cacheRead: number;
+                        cacheWrite: number;
+                        output: number;
+                    };
+                    amount: number | null;
+                };
+                d7: {
+                    tokens: {
+                        inputUncached: number;
+                        cacheRead: number;
+                        cacheWrite: number;
+                        output: number;
+                    };
+                    amount: number | null;
+                };
+                lifetime: {
+                    tokens: {
+                        inputUncached: number;
+                        cacheRead: number;
+                        cacheWrite: number;
+                        output: number;
+                    };
+                    amount: number | null;
+                };
+            };
+            threadId: string;
+            scope: "own" | "family";
+            memberCount: number;
+            coverage: "complete" | "partial" | "unknown";
+            coverageReasons: ("source-gap" | "root-unattested" | "history-unavailable" | "member-cap" | "depth-cap" | "edge-cap" | "missing-thread" | "unpriced" | "retention" | "row-cap" | "pagination" | "population-incomplete")[];
+            asOf: number;
+            revision: string;
+            priceVersion: string;
+            currency: "USD";
+            estimated: true;
+            approximation: {
+                approximate: boolean;
+                reasons: ("source-gap" | "closest-model" | "provider-default" | "model-attribution" | "bucket-boundary" | "missing-price")[];
+                rates?: {
+                    providerId: string;
+                    modelId: string;
+                    rateId: string | null;
+                    basis: "unpriced" | "closest-model" | "provider-default" | "matched";
+                }[] | undefined;
+            };
+            ranks: {
+                m20: number | null;
+                h24: number | null;
+                d7: number | null;
+            };
+            rankPopulation: {
+                m20: {
+                    asOf: number;
+                    count: number;
+                    coverage: "complete" | "partial" | "unknown";
+                };
+                h24: {
+                    asOf: number;
+                    count: number;
+                    coverage: "complete" | "partial" | "unknown";
+                };
+                d7: {
+                    asOf: number;
+                    count: number;
+                    coverage: "complete" | "partial" | "unknown";
+                };
+            };
+            buckets?: {
+                start: number;
+                amount: number | null;
+            }[] | undefined;
+            excluded?: number | undefined;
+            reported?: {
+                amount: number;
+                currency: string;
+                asOf: number;
+            } | undefined;
+        } | {
+            changed: false;
+            threadId: string;
+            scope: "own" | "family";
+            memberCount: number;
+            coverage: "complete" | "partial" | "unknown";
+            coverageReasons: ("source-gap" | "root-unattested" | "history-unavailable" | "member-cap" | "depth-cap" | "edge-cap" | "missing-thread" | "unpriced" | "retention" | "row-cap" | "pagination" | "population-incomplete")[];
+            asOf: number;
+            revision: string;
+            priceVersion: string;
+            currency: "USD";
+            estimated: true;
+            approximation: {
+                approximate: boolean;
+                reasons: ("source-gap" | "closest-model" | "provider-default" | "model-attribution" | "bucket-boundary" | "missing-price")[];
+                rates?: {
+                    providerId: string;
+                    modelId: string;
+                    rateId: string | null;
+                    basis: "unpriced" | "closest-model" | "provider-default" | "matched";
+                }[] | undefined;
+            };
+            ranks: {
+                m20: number | null;
+                h24: number | null;
+                d7: number | null;
+            };
+            rankPopulation: {
+                m20: {
+                    asOf: number;
+                    count: number;
+                    coverage: "complete" | "partial" | "unknown";
+                };
+                h24: {
+                    asOf: number;
+                    count: number;
+                    coverage: "complete" | "partial" | "unknown";
+                };
+                d7: {
+                    asOf: number;
+                    count: number;
+                    coverage: "complete" | "partial" | "unknown";
+                };
+            };
+            windows?: undefined;
+            buckets?: undefined;
+            excluded?: number | undefined;
+            reported?: {
+                amount: number;
+                currency: string;
+                asOf: number;
+            } | undefined;
+        })[];
+    }>;
+    detail(raw: DetailInput, signal?: AbortSignal): Promise<{
+        version: 1;
+        threadId: string;
+        scope: "own" | "family";
+        axis: "model" | "time";
+        window: "m20" | "h24" | "d7" | "lifetime";
+        asOf: number;
+        revision: string;
+        priceVersion: string;
+        currency: "USD";
+        estimated: true;
+        coverage: "complete" | "partial" | "unknown";
+        coverageReasons: ("source-gap" | "root-unattested" | "history-unavailable" | "member-cap" | "depth-cap" | "edge-cap" | "missing-thread" | "unpriced" | "retention" | "row-cap" | "pagination" | "population-incomplete")[];
+        approximation: {
+            approximate: boolean;
+            reasons: ("source-gap" | "closest-model" | "provider-default" | "model-attribution" | "bucket-boundary" | "missing-price")[];
+            rates?: {
+                providerId: string;
+                modelId: string;
+                rateId: string | null;
+                basis: "unpriced" | "closest-model" | "provider-default" | "matched";
+            }[] | undefined;
+        };
+        total: {
+            tokens: {
+                inputUncached: number;
+                cacheRead: number;
+                cacheWrite: number;
+                output: number;
+            };
+            amount: number | null;
+        };
+        rows: ({
+            axis: "time";
+            start: number;
+            end: number;
+            amount: number | null;
+            tokens: {
+                inputUncached: number;
+                cacheRead: number;
+                cacheWrite: number;
+                output: number;
+            };
+            approximation: {
+                approximate: boolean;
+                reasons: ("source-gap" | "closest-model" | "provider-default" | "model-attribution" | "bucket-boundary" | "missing-price")[];
+                rates?: {
+                    providerId: string;
+                    modelId: string;
+                    rateId: string | null;
+                    basis: "unpriced" | "closest-model" | "provider-default" | "matched";
+                }[] | undefined;
+            };
+        } | {
+            axis: "model";
+            providerId: string;
+            modelId: string;
+            amount: number | null;
+            tokens: {
+                inputUncached: number;
+                cacheRead: number;
+                cacheWrite: number;
+                output: number;
+            };
+            approximation: {
+                approximate: boolean;
+                reasons: ("source-gap" | "closest-model" | "provider-default" | "model-attribution" | "bucket-boundary" | "missing-price")[];
+                rates?: {
+                    providerId: string;
+                    modelId: string;
+                    rateId: string | null;
+                    basis: "unpriced" | "closest-model" | "provider-default" | "matched";
+                }[] | undefined;
+            };
+        })[];
+        excluded?: number | undefined;
+        nextCursor?: string | undefined;
+    }>;
+};
+export type DiscoveryRow = {
+    pluginId: string;
+    state: 'ready';
+    version: 1;
+    capabilities: Capabilities;
+} | {
+    pluginId: string;
+    state: 'incompatible';
+} | {
+    pluginId: string;
+    state: 'error';
+    error: OwnerErrorKind;
+};
+export interface DiscoveryResult {
+    rows: DiscoveryRow[];
+    omittedCount: number;
+    complete: boolean;
+    listError?: OwnerErrorKind | 'busy';
+}
+export interface DiscoveryOptions {
+    sdk: MetricsSdk;
+    signal?: AbortSignal;
+    maxCandidates?: number;
+    concurrency?: number;
+    callMs?: number;
+    deadlineMs?: number;
+    onRow?: (row: DiscoveryRow) => void;
+}
+/** One instance per mounted demand coordinator, retained across refresh/reconnect passes.
+ * A completed local deadline does not free underlying reads. Busy passes do no I/O.
+ * No queue, retries, timers or global singleton are created by the coordinator itself.
+ */
+export declare function createThreadMetricsDiscovery(sdk: MetricsSdk): {
+    readonly outstandingReads: number;
+    discover(options?: Omit<DiscoveryOptions, "sdk">): Promise<DiscoveryResult>;
+};