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

package/dist/index.js

@@ -0,0 +1,529 @@
+// src/recent.ts
+import { z } from "zod";
+var RECENT_LIMITS = Object.freeze({ rows: 1000, bytes: 4 * 1024 * 1024, rowBytes: 8 * 1024, inputBytes: 1024, providers: 32, windowMs: 3 * 24 * 60 * 60 * 1000 });
+var id = z.string().min(1).max(200).regex(/^[A-Za-z0-9][A-Za-z0-9_.:-]*$/);
+var revision = z.string().min(1).max(256);
+var time = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+var coverage = z.enum(["complete", "partial", "unknown"]);
+var rank = z.number().finite().min(0).max(1).nullable();
+var count = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+var windowShape = (value) => z.object({ m20: value, h24: value, d7: value, lifetime: value }).strip();
+var reason = z.string().min(1).max(64);
+var reasons = z.array(reason).max(16);
+var recentDollarSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("estimate"), amount: z.number().finite().nonnegative() }).strip(),
+  z.object({ kind: z.literal("floor"), amount: z.number().finite().nonnegative() }).strip(),
+  z.object({ kind: z.literal("unavailable"), amount: z.null() }).strip()
+]);
+var recentWindowsSchema = windowShape(recentDollarSchema);
+var recentApproximationSchema = z.object({ approximate: z.boolean(), reasons: z.array(z.enum(["closest-model", "provider-default", "model-attribution", "bucket-boundary", "missing-price", "source-gap"])).max(6) }).strip().superRefine((v, c) => {
+  if (!v.approximate && v.reasons.length)
+    c.addIssue({ code: "custom", message: "Approximation reasons require approximate flag" });
+});
+var provider = z.object({ providerId: id, windows: recentWindowsSchema, approximation: recentApproximationSchema }).strip();
+var recentScopeSchema = z.object({
+  memberCount: count,
+  coverage,
+  coverageReasons: reasons,
+  priceVersion: revision,
+  approximation: recentApproximationSchema,
+  windows: recentWindowsSchema,
+  scores: recentWindowsSchema,
+  providers: z.array(provider).max(RECENT_LIMITS.providers),
+  omittedProviders: count,
+  dollarRanks: z.object({ m20: rank, h24: rank, d7: rank }).strip(),
+  scoreRanks: z.object({ m20: rank, h24: rank, d7: rank }).strip()
+}).strip().superRefine((v, c) => {
+  if (new Set(v.providers.map((x) => x.providerId)).size !== v.providers.length)
+    c.addIssue({ code: "custom", message: "Duplicate providers" });
+  if (v.omittedProviders && v.coverage === "complete")
+    c.addIssue({ code: "custom", message: "Omitted providers require partial coverage" });
+});
+var recentRowSchema = z.object({ threadId: id, revision, configRevision: revision, asOf: time, ownLastFoldAt: time.nullable(), familyLastFoldAt: time.nullable(), own: recentScopeSchema, family: recentScopeSchema }).strip();
+var recentSnapshotInputSchema = z.object({ ifRevision: revision.optional() }).strict();
+var thresholds = windowShape(z.number().finite().nonnegative());
+var weights = z.record(id, z.number().finite().nonnegative()).refine((v) => Object.keys(v).length <= RECENT_LIMITS.providers, "Too many provider weights");
+var configBase = { schemaVersion: z.literal(2), providerWeights: weights };
+var scoringConfigV2Schema = z.discriminatedUnion("mode", [
+  z.object({ ...configBase, mode: z.literal("percentile"), gates: z.object({ m20: z.number().finite().min(0).max(1), h24: z.number().finite().min(0).max(1), d7: z.number().finite().min(0).max(1) }).strip() }).strip(),
+  z.object({ ...configBase, mode: z.literal("absolute"), thresholds }).strip()
+]);
+var DEFAULT_SCORING_CONFIG_V2 = Object.freeze({ schemaVersion: 2, mode: "percentile", providerWeights: Object.freeze({}), gates: Object.freeze({ m20: 0.9, h24: 0.9, d7: 0.9 }) });
+function weightedScoreV2(values, providerWeights) {
+  if (values.length > RECENT_LIMITS.providers)
+    throw new Error("Too many score providers");
+  weights.parse(providerWeights);
+  let sum = 0, unknown = false;
+  const seen = new Set;
+  for (const v of values) {
+    id.parse(v.providerId);
+    if (seen.has(v.providerId))
+      throw new Error("Duplicate score provider");
+    seen.add(v.providerId);
+    if (v.amount === null) {
+      unknown = true;
+      continue;
+    }
+    if (!Number.isFinite(v.amount) || v.amount < 0)
+      throw new Error("Invalid provider dollars");
+    const w = Object.hasOwn(providerWeights, v.providerId) ? providerWeights[v.providerId] : 1;
+    sum += w * v.amount;
+    if (!Number.isFinite(sum))
+      throw new Error("Weighted dollar overflow");
+  }
+  return unknown ? null : sum;
+}
+var population = z.object({ count, coverage }).strip();
+var populations = z.object({ m20: population, h24: population, d7: population }).strip();
+var scopedPopulations = z.object({ dollars: populations, scores: populations }).strip();
+var recentSnapshotFullSchema = z.object({
+  version: z.literal(1),
+  revision,
+  unchanged: z.literal(false),
+  currency: z.literal("USD"),
+  estimated: z.literal(true),
+  cutoffLastFoldAt: time.nullable(),
+  asOf: time,
+  rankAsOf: time,
+  recentWindowMs: z.literal(RECENT_LIMITS.windowMs),
+  config: z.object({ revision, value: scoringConfigV2Schema }).strip(),
+  coverage,
+  coverageReasons: reasons,
+  materializationPending: count,
+  omittedRows: z.object({ count, exact: z.boolean() }).strip(),
+  population: z.object({ own: scopedPopulations, family: scopedPopulations }).strip(),
+  rows: z.array(recentRowSchema).max(RECENT_LIMITS.rows)
+}).strip();
+var recentSnapshotResultSchema = z.union([z.object({ version: z.literal(1), revision, unchanged: z.literal(true) }).strip(), recentSnapshotFullSchema]);
+function validateRecentSnapshot(input, value) {
+  recentSnapshotInputSchema.parse(input);
+  const bytes = (v) => new TextEncoder().encode(JSON.stringify(v)).byteLength;
+  if (bytes(value) > RECENT_LIMITS.bytes)
+    throw new Error("Snapshot byte limit");
+  const raw = value;
+  if (raw?.rows !== undefined) {
+    if (!Array.isArray(raw.rows) || raw.rows.length > RECENT_LIMITS.rows)
+      throw new Error("Snapshot row limit");
+    for (const row of raw.rows)
+      if (bytes(row) > RECENT_LIMITS.rowBytes)
+        throw new Error("Snapshot row byte limit");
+  }
+  if (value && typeof value === "object" && value.unchanged === true) {
+    for (const field of Object.keys(recentSnapshotFullSchema.shape))
+      if (!["version", "revision", "unchanged"].includes(field) && Object.hasOwn(value, field))
+        throw new Error("Unchanged snapshot carries recognized full content");
+  }
+  const out = recentSnapshotResultSchema.parse(value);
+  if (out.unchanged) {
+    if (input.ifRevision !== out.revision)
+      throw new Error("Unmatched snapshot revision");
+    return out;
+  }
+  if (out.rankAsOf > out.asOf)
+    throw new Error("Future rank time");
+  if ((out.materializationPending || out.omittedRows.count || !out.omittedRows.exact) && out.coverage === "complete")
+    throw new Error("Pending/capped snapshot must disclose coverage");
+  let previousActivity = Infinity, previousId = "";
+  const ids = new Set;
+  for (const row of out.rows) {
+    if (ids.has(row.threadId))
+      throw new Error("Duplicate snapshot thread");
+    ids.add(row.threadId);
+    if (row.asOf > out.asOf)
+      throw new Error("Future row time");
+    if (row.configRevision !== out.config.revision)
+      throw new Error("Row score configuration mismatch");
+    if (row.ownLastFoldAt === null && row.familyLastFoldAt === null)
+      throw new Error("Missing fold activity timestamp");
+    const activity = Math.max(row.ownLastFoldAt ?? 0, row.familyLastFoldAt ?? 0);
+    if (activity > out.asOf || activity < Math.max(0, out.asOf - out.recentWindowMs))
+      throw new Error("Row outside recent activity window");
+    if (activity > previousActivity || activity === previousActivity && row.threadId < previousId)
+      throw new Error("Rows must be newest first with ID tie-break");
+    previousActivity = activity;
+    previousId = row.threadId;
+    for (const scope of ["own", "family"]) {
+      validateProjection(row[scope], out.config.value.providerWeights);
+      validateRanks(row[scope], out.population[scope], out.rankAsOf >= row.asOf);
+    }
+  }
+  if (out.omittedRows.count && out.rows.length && out.cutoffLastFoldAt !== previousActivity)
+    throw new Error("Missing eviction cutoff");
+  return out;
+}
+function validateProjection(projection, providerWeights) {
+  if (projection.coverageReasons.includes("unpriced") && !projection.approximation.reasons.includes("missing-price"))
+    throw new Error("Unpriced coverage requires missing-price provenance");
+  const observationGap = projection.coverage !== "complete" && !projection.coverageReasons.includes("unpriced") && projection.approximation.reasons.includes("source-gap") && projection.coverageReasons.some((r) => ["source-gap", "root-unattested", "history-unavailable", "missing-thread"].includes(r));
+  const unavailableProvenance = (approximation) => approximation.reasons.includes("missing-price") || observationGap && approximation.reasons.includes("source-gap");
+  for (const p of projection.providers) {
+    if (p.approximation.approximate && (!projection.approximation.approximate || p.approximation.reasons.some((reason2) => !projection.approximation.reasons.includes(reason2))))
+      throw new Error("Aggregate must retain provider approximation provenance");
+    if (Object.values(p.windows).some((v) => v.kind === "unavailable") && !unavailableProvenance(p.approximation))
+      throw new Error("Unavailable provider requires missing-price provenance");
+  }
+  if ([...Object.values(projection.windows), ...Object.values(projection.scores)].some((v) => v.kind === "unavailable") && !unavailableProvenance(projection.approximation))
+    throw new Error("Unavailable total requires missing-price provenance");
+  for (const window of ["m20", "h24", "d7", "lifetime"]) {
+    const known = projection.providers.filter((p) => p.windows[window].kind !== "unavailable");
+    const parts = known.map((p) => ({ providerId: p.providerId, amount: p.windows[window].amount }));
+    const dollars = parts.reduce((sum, p) => sum + p.amount, 0), score = weightedScoreV2(parts, providerWeights);
+    if (!Number.isFinite(dollars))
+      throw new Error("Provider dollar overflow");
+    const incomplete = projection.omittedProviders > 0 || known.length !== projection.providers.length;
+    const floor = incomplete || known.some((p) => p.windows[window].kind === "floor");
+    const equal = (a, b) => Math.abs(a - b) <= 8 * Number.EPSILON * Math.max(a, b);
+    for (const [total, subtotal, label] of [[projection.windows[window], dollars, "dollar"], [projection.scores[window], score, "score"]]) {
+      if (total.kind === "unavailable")
+        continue;
+      if (floor && total.kind === "estimate")
+        throw new Error("Partial/provider floor cannot become an exact estimate");
+      if (incomplete) {
+        if (total.amount < subtotal && !equal(total.amount, subtotal))
+          throw new Error(`Known provider ${label} subtotal exceeds total`);
+      } else if (!equal(total.amount, subtotal))
+        throw new Error(`Provider ${label} total mismatch`);
+    }
+  }
+}
+function validateRanks(projection, population2, contemporaneous) {
+  for (const [values, ranks, pops] of [[projection.windows, projection.dollarRanks, population2.dollars], [projection.scores, projection.scoreRanks, population2.scores]]) {
+    for (const w of ["m20", "h24", "d7"]) {
+      const r = ranks[w], n = pops[w].count;
+      if (r !== null && (n === 0 || n === 1 && r !== 0))
+        throw new Error("Rank contradicts empty/singleton population");
+      if (contemporaneous && r !== null && (values[w].amount === null || values[w].amount <= 0))
+        throw new Error("Rank requires supported positive contemporaneous amount");
+    }
+  }
+}
+function recentPercentileHeat(projection, 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");
+  for (const [w, label] of [["m20", "on-fire"], ["h24", "hot"], ["d7", "heavy"]]) {
+    const amount = projection.scores[w].amount, r = projection.scoreRanks[w];
+    if (amount !== null && amount > 0 && r !== null && r >= gates[w])
+      return label;
+  }
+  return null;
+}
+
+// src/index.ts
+import { z as z2 } 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) {
+  time2.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", recentSnapshot: "threadMetricsRecentSnapshotV1" });
+var id2 = z2.string().min(1).max(200).regex(/^[A-Za-z0-9][A-Za-z0-9_.:-]*$/);
+var text = z2.string().min(1).max(256);
+var time2 = z2.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+var money = z2.number().finite().nonnegative().nullable();
+var scope = z2.enum(["own", "family"]);
+var windowSchema = z2.enum(["m20", "h24", "d7", "lifetime"]);
+var coverageSchema = z2.enum(["complete", "partial", "unknown"]);
+var coverageReasonSchema = z2.enum(["source-gap", "root-unattested", "history-unavailable", "member-cap", "depth-cap", "edge-cap", "missing-thread", "unpriced", "retention", "row-cap", "pagination", "population-incomplete"]);
+var reasons2 = z2.array(coverageReasonSchema).max(16);
+var approximationSchema = z2.object({
+  approximate: z2.boolean(),
+  reasons: z2.array(z2.enum(["closest-model", "provider-default", "model-attribution", "bucket-boundary", "missing-price", "source-gap"])).max(6),
+  rates: z2.array(z2.object({ providerId: id2, modelId: text, rateId: text.nullable(), basis: z2.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 rank2 = z2.number().finite().min(0).max(1).nullable();
+var ranksSchema = z2.object({ m20: rank2, h24: rank2, d7: rank2 }).strip();
+var population2 = z2.object({ asOf: time2, count: z2.number().int().nonnegative(), coverage: coverageSchema }).strip();
+var rankPopulationSchema = z2.object({ m20: population2, h24: population2, d7: population2 }).strip();
+var windowValueSchema = z2.object({ tokens: UsageVectorSchema, amount: money }).strip();
+var windowsSchema = z2.object({ m20: windowValueSchema, h24: windowValueSchema, d7: windowValueSchema, lifetime: windowValueSchema }).strip();
+var bucketSchema = z2.object({ start: time2, amount: money }).strip();
+var metadata = {
+  threadId: id2,
+  scope,
+  memberCount: z2.number().int().nonnegative().max(LIMITS.familyMembers),
+  coverage: coverageSchema,
+  coverageReasons: reasons2,
+  excluded: z2.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).optional(),
+  asOf: time2,
+  revision: text,
+  priceVersion: text,
+  currency: z2.literal("USD"),
+  estimated: z2.literal(true),
+  approximation: approximationSchema,
+  ranks: ranksSchema,
+  rankPopulation: rankPopulationSchema,
+  reported: z2.object({ amount: z2.number().finite().nonnegative(), currency: z2.string().min(1).max(16), asOf: time2 }).strip().optional()
+};
+var summaryRowSchema = z2.discriminatedUnion("changed", [
+  z2.object({ ...metadata, changed: z2.literal(true), windows: windowsSchema, buckets: z2.array(bucketSchema).max(LIMITS.seriesPoints).optional() }).strip(),
+  z2.object({ ...metadata, changed: z2.literal(false), windows: z2.never().optional(), buckets: z2.never().optional() }).strip()
+]);
+var readInputSchema = z2.object({
+  threadIds: z2.array(id2).min(1).max(LIMITS.threadIds),
+  scope,
+  includeArchived: z2.boolean().optional(),
+  knownRevisions: z2.record(id2, text).optional(),
+  series: z2.object({ activeThreadId: id2, maxPoints: z2.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 = z2.object({ version: z2.literal(1), rows: z2.array(summaryRowSchema).max(LIMITS.threadIds) }).strip();
+var detailInputSchema = z2.object({ threadId: id2, scope, includeArchived: z2.boolean().optional(), axis: z2.enum(["model", "time"]), window: windowSchema, cursor: z2.string().min(1).max(1024).optional(), limit: z2.number().int().min(1).max(LIMITS.detailRows).optional() }).strict();
+var detailBase = { amount: money, tokens: UsageVectorSchema, approximation: approximationSchema };
+var detailRowSchema = z2.discriminatedUnion("axis", [
+  z2.object({ ...detailBase, axis: z2.literal("model"), providerId: id2, modelId: text }).strip(),
+  z2.object({ ...detailBase, axis: z2.literal("time"), start: time2, end: time2 }).strip().refine((v) => v.end > v.start, { message: "Empty time interval" })
+]);
+var detailResultSchema = z2.object({ version: z2.literal(1), threadId: id2, scope, axis: z2.enum(["model", "time"]), window: windowSchema, asOf: time2, revision: text, priceVersion: text, currency: z2.literal("USD"), estimated: z2.literal(true), coverage: coverageSchema, coverageReasons: reasons2, excluded: z2.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).optional(), approximation: approximationSchema, total: windowValueSchema, rows: z2.array(detailRowSchema).max(LIMITS.detailRows), nextCursor: z2.string().min(1).max(1024).optional() }).strip();
+var describeInputSchema = z2.object({}).strict();
+var describeEnvelopeSchema = z2.object({ protocol: z2.literal("bb-thread-metrics"), versions: z2.array(z2.number().int().positive()).max(16) }).passthrough();
+var capabilitiesSchema = z2.object({ summary: z2.literal(true), series: z2.boolean(), detail: z2.boolean(), recentSnapshotV1: z2.boolean().optional() }).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(population3) {
+  const seen = new Set;
+  for (const p of population3) {
+    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 = population3.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(population3.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((reason2) => !out.approximation.reasons.includes(reason2))))
+      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,
+  weightedScoreV2,
+  validateRecentSnapshot,
+  validateReadResult,
+  validateDetailResult,
+  summaryRowSchema,
+  scoringConfigV2Schema,
+  retainedWindowStart,
+  recentWindowsSchema,
+  recentSnapshotResultSchema,
+  recentSnapshotInputSchema,
+  recentSnapshotFullSchema,
+  recentScopeSchema,
+  recentRowSchema,
+  recentPercentileHeat,
+  recentDollarSchema,
+  recentApproximationSchema,
+  readResultSchema,
+  readInputSchema,
+  ranksSchema,
+  rankPopulationSchema,
+  parseBounded,
+  negotiateVersion,
+  heat,
+  familyClosure,
+  dollarPercentiles,
+  detailRowSchema,
+  detailResultSchema,
+  detailInputSchema,
+  describeV1Schema,
+  describeInputSchema,
+  describeEnvelopeSchema,
+  coverageSchema,
+  coverageReasonSchema,
+  classifyOwnerError,
+  capabilitiesSchema,
+  bucketSchema,
+  approximationSchema,
+  RECENT_LIMITS,
+  METRIC_BUCKET_MS,
+  METHODS,
+  LIMITS,
+  DEFAULT_SCORING_CONFIG_V2
+};

package/dist/testing.js

@@ -0,0 +1,92 @@
+// src/testing.ts
+import { createFakePluginHost } from "@get-bb/plugin-sdk/testing";
+import { RECENT_LIMITS, recentSnapshotInputSchema, validateRecentSnapshot, 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, recent = 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;
+      recent = Boolean(n.capabilities.recentSnapshotV1);
+    });
+    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 (recent) {
+      if (!options.recentCases?.length)
+        checks.push({ name: "recent-cases-required", passed: false, error: "Advertised recent snapshot needs real cases" });
+      for (let i = 0;i < (options.recentCases?.length ?? 0); i++)
+        await check(`recent-${i}`, async () => {
+          const input = parseBounded(recentSnapshotInputSchema, options.recentCases[i], RECENT_LIMITS.inputBytes);
+          validateRecentSnapshot(input, await call(METHODS.recentSnapshot, input));
+        });
+      await check("strict-recent-input", () => rejectsInput(METHODS.recentSnapshot, { unexpected: true }));
+    }
+    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
+};