@phosphorco/bb-thread-metrics 0.1.0 → 0.2.0

package/CONTRACT.md

@@ -1,4 +1,4 @@
-# Thread metrics wire v1 (@phosphorco/bb-thread-metrics 0.1.0)
+# Thread metrics wire v1 (@phosphorco/bb-thread-metrics 0.2.0 candidate)
 
 | Supplier owns | Package owns | Host owns |
 | --- | --- | --- |
@@ -316,3 +316,85 @@ 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.
+
+
+## Additive recent snapshot capability (package0.2)
+
+The new optional boolean `recentSnapshotV1` capability requires the exact fixed
+`threadMetricsRecentSnapshotV1` handler; registration rejects either mismatch.
+Input is strict `{ifRevision?:string}` within1024 canonical UTF-8 JSON bytes.
+Full replies have wire version1, `unchanged:false`, opaque revision, immutable
+publication time, rank time,72h recent window, a published config revision/value,
+explicit coverage/materialization-pending/cap state and rows. Unchanged replies
+have version1, `unchanged:true`, revision and no recognized full-only payload.
+Recognized rows/config/times/population/coverage/cap fields are rejected BEFORE
+stripping; unrelated future additive fields remain allowed within the byte cap. The revision
+must exactly match requested ifRevision. A new supplier instance must not reuse a
+revision for different content. Reads do not advance revision or run fold,
+closure, rank or materializer work; suppliers serve a held published object.
+Adapters validate shape/bytes but cannot prove supplier implementation purity.
+
+Each row has independent own/family last-fold timestamps, asOf and content
+revision; at least one activity timestamp must be in the envelope's72h window.
+The row score-config revision must match the published envelope config. Own and
+family each carry memberCount/coverage/priceVersion, compact approximation
+provenance, four raw dollar windows and
+provider-attributed dollar windows, omitted-provider count, four weighted-score
+windows, and separately named dollar/score percentile ranks. `estimate`/`floor`
+values are finite nonnegative amounts; `unavailable` has null amount. Explicit
+floor0 is a supplier attestation; unsupported root zeros must be unavailable,
+never inferred from a partial population or a missing row. Family providers must
+represent deduplicated actual members, not sums of other family rows.
+
+Full canonical JSON is capped at4MiB including additive unknown fields,1000 rows,
+8KiB per raw row before stripping, and32 provider entries per scope. Omitted
+providers/rows, uncertain omission counts (`exact:false`, even lower-bound0),
+and pending materialization cannot claim complete coverage. These
+are post-transport decoded bounds, not raw-network/preparse allocation limits.
+Providers select most recent rows within both row/byte caps, publish cutoff and
+honest omission state; row omission alone proves neither absence nor zero. The
+codec always checks finite known provider subtotals and weighted arithmetic,
+including when other providers are unavailable or omitted. Available totals must
+cover every known subtotal within eight relative machine epsilons (no absolute
+small-dollar epsilon); incomplete provider sets or contributing floors
+require a floor rather than an estimate. Unknown components may yield unavailable
+totals, never invented zero. Complete provider sets reconcile exact totals.
+
+Each scope AND provider has `approximation:{approximate,reasons}` independently
+of observation coverage. Compact bounded reasons retain `closest-model`,
+`provider-default`, `model-attribution`, `bucket-boundary`, `missing-price`, and
+`source-gap`; aggregate provenance must include contributing provider reasons.
+Unavailable prices require `missing-price`. Unavailable observations are different:
+a partial/unknown projection with source-gap approximation and source-gap,
+root-unattested, history-unavailable or missing-thread coverage may retain
+unavailable values without claiming a price failure. Any explicit unpriced
+coverage still requires missing-price, and provider missing-price reasons must
+remain in aggregate approximation. Suppliers must not label an actual pricing
+gap as an observation gap. This is the lossless reason mapping
+from readV1; per-model rate associations remain in on-demand read/detail and are
+not copied into listing rows. `priceVersion` still identifies the price table.
+Real materializer conformance remains necessary before release.
+
+Scoring-config schemaVersion2 is versioned separately from normalization semantics.
+Default mode is percentile with gates .9 m20/h24/d7; omitted provider weights mean1.
+Absolute mode supplies thresholds for all four windows. `weightedScoreV2` sums
+provider dollars times weights, returns unknown when a component is unavailable,
+and rejects invalid/duplicate provider values and arithmetic overflow. Weighting
+never reprices the raw-dollar fields. UI, settings CAS and scoring policy remain
+ledger/surface-owned; this package contains no settings storage or sliders.
+
+Ranks cannot be non-null for an empty population; a positive singleton ranks0.
+When rankAsOf is at or after the row value epoch, zero or unavailable amounts require null rank.
+Older rank epochs may deliberately remain while newer amounts change; consumers
+must gate heat on supported positive CURRENT amounts as well as ranks.
+`recentPercentileHeat` applies that current weighted-score gate; legacy
+`heat(ranks)` alone is insufficient for recent rows. This codec does not rebuild
+or prove actual population percentiles.
+
+Supplier ranks recompute at most once/minute outside reads. A publication binds
+configuration and scored content atomically; pending changes retain explicit
+coverage. Consumers hold the object by SDK-owner identity and use keyed row
+selectors. They may conditionally poll at30s while interested/visible/connected,
+coalescing existing hints without a per-thread request. Covered listing rows need
+no readV1; explicit inspection outside the window may use the existing bounded
+read/detail lane. The contract package itself never polls or retries.

package/README.md

@@ -1,6 +1,6 @@
 # @phosphorco/bb-thread-metrics
 
-Version 0.1.0: bounded dollar summaries, family closure, heat ranks and optional
+Version0.2.0 candidate (not released): adds a bounded recent snapshot and scoring-configv2. Existing wirev1 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.
 
@@ -29,3 +29,30 @@ 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.
+
+
+## Recent snapshot (0.2 candidate)
+
+Owners may advertise `capabilities.recentSnapshotV1:true` with a matching
+`recentSnapshot(input)` handler. `createThreadMetricsClient(...).recentSnapshot({ifRevision?})`
+returns the immutable precomputed object or an unchanged revision. Absence of this
+optional capability leaves the0.1 read/detail contract intact. Old consumers may
+ignore it. The adapter does not add refresh timers, caches or materialization.
+
+The full response holds own/family raw estimated-dollar windows and provider
+contributions, separately named weighted scores, raw dollar ranks and score ranks,
+activity/materialization/rank times, coverage/cap/pending flags and the published
+scoring configuration. Zero is explicit supplier evidence; omission/unavailable is
+not zero. Config weights affect heat scores, never retained dollars. Defaults are
+weight1 and current p90 percentile gates. Raw/scored populations remain distinct.
+
+Bounds:72h recent activity,1000 rows,4MiB canonical JSON and8KiB/row,32 provider
+entries per projection/config. Bounds include unknown additive fields before
+schema stripping; the SDK has already parsed transport JSON. Providers enforce
+materializer work/storage and publication bounds independently. Clients must not
+turn row omission into an eager per-ID read storm. The planned coordinator uses
+one held snapshot/mount+30s conditional cadence; the package schedules nothing.
+
+Current source tests are package/adapter proof only. Registry release, ledger
+materialization, live byte/time measurement, all consumer adoptions and native
+host/freshness proof remain separate gates.

package/dist/bb.js

@@ -1,6 +1,6 @@
 // src/bb.ts
 import { z } from "zod";
-import { LIMITS, METHODS, describeInputSchema, describeEnvelopeSchema, capabilitiesSchema, readInputSchema, detailInputSchema, parseBounded, negotiateVersion, validateReadResult, validateDetailResult, classifyOwnerError } from "./index.js";
+import { RECENT_LIMITS, recentSnapshotInputSchema, validateRecentSnapshot, 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 {
@@ -12,6 +12,8 @@ function sdkSchema(schema, maxBytes) {
 }
 function registerThreadMetricsOwner(bb, port) {
   const capabilities = capabilitiesSchema.parse(port.capabilities);
+  if (Boolean(capabilities.recentSnapshotV1) !== Boolean(port.recentSnapshot))
+    throw new Error("Recent snapshot capability/handler mismatch");
   if (capabilities.detail !== Boolean(port.detail))
     throw new Error("Detail capability/handler mismatch");
   const describe = () => ({ protocol: "bb-thread-metrics", versions: [1], capabilities });
@@ -32,6 +34,11 @@ function registerThreadMetricsOwner(bb, port) {
     }
   };
   bb.rpc.register(contract, handlers, { experimental_discoverable: true });
+  if (port.recentSnapshot)
+    bb.rpc.register({ threadMetricsRecentSnapshotV1: { input: sdkSchema(recentSnapshotInputSchema, RECENT_LIMITS.inputBytes), output: sdkSchema(z.unknown()) } }, { threadMetricsRecentSnapshotV1: async (raw) => {
+      const input = parseBounded(recentSnapshotInputSchema, raw, RECENT_LIMITS.inputBytes);
+      return validateRecentSnapshot(input, await port.recentSnapshot(input));
+    } }, { 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);
@@ -50,6 +57,10 @@ function createThreadMetricsClient(sdk, pluginId) {
       const raw = await call(METHODS.describe, {}, signal);
       return negotiateVersion(parseBounded(describeEnvelopeSchema, raw, LIMITS.describeBytes));
     },
+    async recentSnapshot(raw = {}, signal) {
+      const input = parseBounded(recentSnapshotInputSchema, raw, RECENT_LIMITS.inputBytes);
+      return validateRecentSnapshot(input, await call(METHODS.recentSnapshot, input, signal));
+    },
     async read(raw, signal) {
       const input = parseBounded(readInputSchema, raw, LIMITS.inputBytes);
       return validateReadResult(input, await call(METHODS.read, input, signal));

package/dist/index.js

@@ -1,28 +1,239 @@
-// src/index.ts
+// 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) {
-  time.parse(asOf);
+  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" });
-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) => {
+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()
@@ -30,40 +241,40 @@ var approximationSchema = z.object({
   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 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: id,
+  threadId: id2,
   scope,
-  memberCount: z.number().int().nonnegative().max(LIMITS.familyMembers),
+  memberCount: z2.number().int().nonnegative().max(LIMITS.familyMembers),
   coverage: coverageSchema,
-  coverageReasons: reasons,
-  excluded: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).optional(),
-  asOf: time,
+  coverageReasons: reasons2,
+  excluded: z2.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).optional(),
+  asOf: time2,
   revision: text,
   priceVersion: text,
-  currency: z.literal("USD"),
-  estimated: z.literal(true),
+  currency: z2.literal("USD"),
+  estimated: z2.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()
+  reported: z2.object({ amount: z2.number().finite().nonnegative(), currency: z2.string().min(1).max(16), asOf: time2 }).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 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 = z.object({
-  threadIds: z.array(id).min(1).max(LIMITS.threadIds),
+var readInputSchema = z2.object({
+  threadIds: z2.array(id2).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()
+  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" });
@@ -72,17 +283,17 @@ var readInputSchema = z.object({
   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 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 = 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 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 = 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 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);
@@ -100,23 +311,23 @@ function negotiateVersion(value) {
   const v = describeV1Schema.safeParse(value);
   return v.success ? { kind: "ready", version: 1, capabilities: v.data.capabilities } : { kind: "incompatible" };
 }
-function dollarPercentiles(population2) {
+function dollarPercentiles(population3) {
   const seen = new Set;
-  for (const p of population2) {
+  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 = population2.filter((p) => p.amount !== null && p.amount > 0);
+  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(population2.map((p) => [p.threadId, p.amount === null || p.amount === 0 ? null : active.length < 2 ? 0 : lower.get(p.amount) / (active.length - 1)]));
+  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"])
@@ -222,7 +433,7 @@ function validateDetailResult(input, value) {
   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))))
+    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");
@@ -273,10 +484,22 @@ export {
   windowsSchema,
   windowValueSchema,
   windowSchema,
+  weightedScoreV2,
+  validateRecentSnapshot,
   validateReadResult,
   validateDetailResult,
   summaryRowSchema,
+  scoringConfigV2Schema,
   retainedWindowStart,
+  recentWindowsSchema,
+  recentSnapshotResultSchema,
+  recentSnapshotInputSchema,
+  recentSnapshotFullSchema,
+  recentScopeSchema,
+  recentRowSchema,
+  recentPercentileHeat,
+  recentDollarSchema,
+  recentApproximationSchema,
   readResultSchema,
   readInputSchema,
   ranksSchema,
@@ -298,7 +521,9 @@ export {
   capabilitiesSchema,
   bucketSchema,
   approximationSchema,
+  RECENT_LIMITS,
   METRIC_BUCKET_MS,
   METHODS,
-  LIMITS
+  LIMITS,
+  DEFAULT_SCORING_CONFIG_V2
 };

package/dist/testing.js

@@ -1,6 +1,6 @@
 // src/testing.ts
 import { createFakePluginHost } from "@get-bb/plugin-sdk/testing";
-import { METHODS, LIMITS, readInputSchema, detailInputSchema, describeEnvelopeSchema, parseBounded, negotiateVersion, validateReadResult, validateDetailResult } from "./index.js";
+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");
@@ -38,12 +38,13 @@ async function runSupplierConformance(options) {
   }
   try {
     await options.register(host.bb);
-    let detail = false;
+    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++)
@@ -61,6 +62,16 @@ async function runSupplierConformance(options) {
         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" });