@phosphorco/bb-thread-metrics 0.1.0 → 0.2.1

package/dist/index.js

@@ -1,28 +1,562 @@
-// src/index.ts
+// src/recent.ts
 import { z } from "zod";
 import { UsageVectorSchema } from "@phosphorco/bb-usage-algebra/vector";
+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 flags = windowShape(z.boolean());
+var recentAttributionSchema = z.object({ unknownProvider: recentWindowsSchema, attributionComplete: flags, unpriced: flags }).strip();
+var recentPresentationSchema = z.object({ title: z.string().trim().min(1).max(512).nullable(), navigation: z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("personal") }).strip(),
+  z.object({ kind: z.literal("project"), projectId: id }).strip()
+]).nullable() }).strip();
+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 recentTokenValueSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("estimate"), value: UsageVectorSchema }).strip(),
+  z.object({ kind: z.literal("floor"), value: UsageVectorSchema }).strip(),
+  z.object({ kind: z.literal("unavailable"), value: z.null() }).strip()
+]);
+var recentTokenWindowsSchema = windowShape(recentTokenValueSchema);
+var recentUsageSchema = z.object({
+  windows: recentTokenWindowsSchema,
+  providers: z.array(z.object({ providerId: id, windows: recentTokenWindowsSchema }).strip()).max(RECENT_LIMITS.providers),
+  omittedProviders: count,
+  descendants: z.object({ count, exact: z.boolean() }).strip()
+}).strip();
+var recentScopeSchema = z.object({
+  memberCount: count,
+  coverage,
+  coverageReasons: reasons,
+  priceVersion: revision,
+  approximation: recentApproximationSchema,
+  usage: recentUsageSchema.optional(),
+  attribution: recentAttributionSchema.optional(),
+  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" });
+  if (v.usage) {
+    const u = v.usage, fail = (message) => c.addIssue({ code: "custom", path: ["usage"], message });
+    const providers = new Set(v.providers.map((p) => p.providerId));
+    if (u.providers.length !== providers.size || new Set(u.providers.map((p) => p.providerId)).size !== u.providers.length || u.providers.some((p) => !providers.has(p.providerId)) || u.omittedProviders !== v.omittedProviders)
+      fail("Token provider attribution mismatch");
+    if (u.descendants.count !== Math.max(0, v.memberCount - 1))
+      fail("Descendant/member count mismatch");
+    if (u.descendants.exact && v.coverageReasons.some((reason2) => ["member-cap", "depth-cap", "edge-cap"].includes(reason2)))
+      fail("Membership caps cannot carry an exact descendant count");
+    const near = (a, b) => Math.abs(a - b) <= 4 * Number.EPSILON * Math.max(a, b);
+    for (const w of ["m20", "h24", "d7", "lifetime"]) {
+      const total = u.windows[w], known = u.providers.filter((p) => p.windows[w].value !== null), all = !u.omittedProviders && known.length === u.providers.length;
+      if (total.kind === "estimate" && (u.omittedProviders > 0 || u.providers.some((p) => p.windows[w].kind !== "estimate")))
+        fail("Incomplete provider tokens cannot carry an aggregate estimate");
+      for (const k of ["inputUncached", "cacheRead", "cacheWrite", "output"]) {
+        const sum = known.reduce((n, p) => n + p.windows[w].value[k], 0), value = total.value?.[k];
+        if (!Number.isFinite(sum) || value === undefined && sum > 0 || value !== undefined && (sum > value && !near(sum, value) || all && !near(sum, value)))
+          fail("Token provider conservation mismatch");
+      }
+    }
+  }
+});
+var recentSnapshotInputSchema = z.object({ ifRevision: revision.optional() }).strict();
+var thresholds = windowShape(z.number().finite().min(0).max(1e6));
+var weights = z.record(id, z.number().finite().min(0).max(3)).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, lifetimeEnabled: z.boolean().optional() }).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 }) });
+var ROOT_FAMILY_HEAT_DOMAIN_V1 = Object.freeze({ version: 1, kind: "root-family" });
+var rootFamilyHeatDomainV1Schema = z.object({ version: z.literal(1), kind: z.literal("root-family") }).strip();
+var configV3Base = { schemaVersion: z.literal(3), domain: rootFamilyHeatDomainV1Schema, providerWeights: weights };
+var scoringConfigV3Schema = z.discriminatedUnion("mode", [
+  z.object({ ...configV3Base, 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({ ...configV3Base, mode: z.literal("absolute"), thresholds, lifetimeEnabled: z.literal(false).optional() }).strip()
+]);
+var storedScoringConfigSchema = z.union([scoringConfigV2Schema, scoringConfigV3Schema]);
+var DEFAULT_SCORING_CONFIG_V3 = Object.freeze({ schemaVersion: 3, domain: ROOT_FAMILY_HEAT_DOMAIN_V1, mode: "percentile", providerWeights: Object.freeze({}), gates: Object.freeze({ m20: 0.9, h24: 0.8, d7: 0.8 }) });
+var HEAT_WINDOWS = ["m20", "h24", "d7"];
+var rankWindows = z.object({ m20: rank, h24: rank, d7: rank }).strip();
+var rootTopologyV1Schema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("attested"), parentThreadId: id.nullable(), lifecycleOwnerThreadId: id.nullable(), deleted: z.boolean() }).strip(),
+  z.object({ kind: z.literal("unknown"), reasons }).strip()
+]);
+function rootFamilyEligibilityV1(input) {
+  const topology = rootTopologyV1Schema.parse(input);
+  if (topology.kind === "unknown")
+    return "unknown";
+  if (topology.deleted)
+    return "deleted";
+  return topology.parentThreadId === null && topology.lifecycleOwnerThreadId === null ? "eligible-root" : "ineligible-child";
+}
+var coveredPopulation = z.object({ count, coverage, reasons }).strip();
+var rootPopulations = z.object({ m20: coveredPopulation, h24: coveredPopulation, d7: coveredPopulation }).strip();
+var interval = z.object({ start: time, end: time }).strip();
+var rootFamilyHeatContextV1Schema = z.object({
+  version: z.literal(1),
+  domain: rootFamilyHeatDomainV1Schema,
+  contextRevision: revision,
+  configRevision: revision,
+  topologyRevision: revision,
+  rankRevision: revision,
+  rankAsOf: time,
+  windows: z.object({ m20: interval, h24: interval, d7: interval }).strip(),
+  population: z.object({ dollars: rootPopulations, scores: rootPopulations }).strip()
+}).strip().superRefine((v, c) => {
+  const duration = { m20: 20 * 60 * 1000, h24: 24 * 60 * 60 * 1000, d7: 7 * 24 * 60 * 60 * 1000 };
+  for (const w of HEAT_WINDOWS)
+    if (v.windows[w].end !== v.rankAsOf || v.windows[w].start !== Math.max(0, v.rankAsOf - duration[w]))
+      c.addIssue({ code: "custom", message: "Invalid root heat window provenance", path: ["windows", w] });
+});
+var decision = z.object({ decision: z.enum(["qualifies", "below", "suppressed", "unavailable"]), reason: z.enum(["threshold-met", "below-threshold", "gate-met", "below-gate", "not-root", "deleted", "topology-unknown", "unsupported-value", "zero", "insufficient-population", "rank-unavailable", "context-unavailable"]) }).strip();
+var rootFamilyDecisionSetV1Schema = z.object({ contextRevision: revision, signals: z.object({ m20: decision, h24: decision, d7: decision }).strip(), winner: z.enum(["on-fire", "hot", "heavy"]).nullable() }).strip();
+var recentRootHeatSchema = z.object({ topology: rootTopologyV1Schema, rootDollarRanks: rankWindows, rootScoreRanks: rankWindows, decisions: rootFamilyDecisionSetV1Schema }).strip();
+function rootFamilyHeatV1(input) {
+  const context = rootFamilyHeatContextV1Schema.parse(input.context), config = scoringConfigV3Schema.parse(input.config), family = input.family;
+  if (family.configRevision !== context.configRevision || family.contextRevision !== context.contextRevision)
+    throw new Error("Root heat configuration/context mismatch");
+  const eligibility = rootFamilyEligibilityV1(input.topology), signals = {};
+  for (const w of HEAT_WINDOWS) {
+    const score = recentDollarSchema.parse(family.scores[w]), r = rank.parse(family.rootScoreRanks[w]), pop = context.population.scores[w];
+    if (r !== null && (pop.count === 0 || pop.count === 1 && r !== 0 || pop.coverage === "unknown"))
+      throw new Error("Root rank population mismatch");
+    if (eligibility !== "eligible-root") {
+      signals[w] = { decision: eligibility === "unknown" ? "unavailable" : "suppressed", reason: eligibility === "unknown" ? "topology-unknown" : eligibility === "deleted" ? "deleted" : "not-root" };
+      continue;
+    }
+    if (score.amount === null) {
+      signals[w] = { decision: "unavailable", reason: "unsupported-value" };
+      continue;
+    }
+    if (score.amount === 0) {
+      signals[w] = score.kind === "floor" ? { decision: "unavailable", reason: "unsupported-value" } : { decision: "suppressed", reason: "zero" };
+      continue;
+    }
+    if (config.mode === "absolute") {
+      const hit = score.amount >= config.thresholds[w];
+      signals[w] = !hit && score.kind === "floor" ? { decision: "unavailable", reason: "unsupported-value" } : { decision: hit ? "qualifies" : "below", reason: hit ? "threshold-met" : "below-threshold" };
+    } else if (pop.coverage === "unknown")
+      signals[w] = { decision: "unavailable", reason: "rank-unavailable" };
+    else if (pop.count < 2)
+      signals[w] = { decision: "suppressed", reason: "insufficient-population" };
+    else if (r === null)
+      signals[w] = { decision: "unavailable", reason: "rank-unavailable" };
+    else {
+      const hit = r >= config.gates[w];
+      signals[w] = { decision: hit ? "qualifies" : "below", reason: hit ? "gate-met" : "below-gate" };
+    }
+  }
+  const winner = signals.m20.decision === "qualifies" ? "on-fire" : signals.h24.decision === "qualifies" ? "hot" : signals.d7.decision === "qualifies" ? "heavy" : null;
+  return { contextRevision: context.contextRevision, signals, winner };
+}
+var recentRowSchema = z.object({ threadId: id, revision, configRevision: revision, asOf: time, presentation: recentPresentationSchema.optional(), ownLastFoldAt: time.nullable(), familyLastFoldAt: time.nullable(), own: recentScopeSchema, family: recentScopeSchema, heat: recentRootHeatSchema.optional() }).strip();
+var recentRootInputSchema = z.object({ threadId: id, asOf: time, configRevision: revision, presentation: recentPresentationSchema.optional(), family: recentScopeSchema, heat: recentRootHeatSchema }).strip();
+var recentHeatInputsSchema = z.object({ contextRevision: revision, topologyRevision: revision, cohortComplete: z.boolean(), pending: count, omitted: z.object({ count, exact: z.boolean() }).strip(), rows: z.array(recentRootInputSchema).max(RECENT_LIMITS.rows) }).strip();
+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 recentPublicationIdentitySchema = z.object({ instance: z.string().min(1).max(128), sequence: z.number().int().positive().max(Number.MAX_SAFE_INTEGER) }).strip();
+var recentSnapshotFullSchema = z.object({
+  version: z.literal(1),
+  revision,
+  publication: recentPublicationIdentitySchema.optional(),
+  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: storedScoringConfigSchema }).strip(),
+  heat: rootFamilyHeatContextV1Schema.optional(),
+  heatInputs: recentHeatInputsSchema.optional(),
+  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;
+  let entries = 0;
+  for (const rows of [raw?.rows, raw?.heatInputs?.rows])
+    if (rows !== undefined) {
+      if (!Array.isArray(rows) || (entries += rows.length) > RECENT_LIMITS.rows)
+        throw new Error("Snapshot aggregate row limit");
+      for (const row of 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.config.value.schemaVersion === 3 && !out.heat)
+    throw new Error("Root-family configuration requires heat context");
+  if (out.heat && (out.config.value.schemaVersion !== 3 || out.heat.configRevision !== out.config.revision || out.heat.rankAsOf !== out.rankAsOf))
+    throw new Error("Root heat configuration/rank epoch mismatch");
+  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);
+    }
+    validateRootHeatRow(row, out.heat, out.config.value);
+  }
+  if (out.heat) {
+    for (const [axis, field] of [["dollars", "windows"], ["scores", "scores"]]) {
+      for (const w of HEAT_WINDOWS) {
+        const pop = out.heat.population[axis][w], supported = out.rows.filter((row) => row.heat && rootFamilyEligibilityV1(row.heat.topology) === "eligible-root" && row.asOf <= out.heat.rankAsOf && (row.family[field][w].amount ?? 0) > 0).length;
+        if (pop.coverage === "complete" && pop.count < supported)
+          throw new Error("Root population below supported displayed members");
+      }
+    }
+  }
+  if (out.heatInputs)
+    validateHeatInputs(out);
+  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);
+    const attribution = projection.attribution;
+    if (projection.windows[window].kind === "unavailable" && (dollars > 0 || (attribution?.unknownProvider[window].amount ?? 0) > 0))
+      throw new Error("Supported provider dollars require an aggregate floor or estimate");
+    if (attribution) {
+      const unknown = attribution.unknownProvider[window], complete = attribution.attributionComplete[window];
+      if (complete && (projection.omittedProviders > 0 || unknown.kind !== "estimate" || unknown.amount !== 0))
+        throw new Error("Complete attribution requires no unknown provider remainder");
+      if (attribution.unpriced[window] && !projection.approximation.reasons.includes("missing-price"))
+        throw new Error("Unpriced attribution requires missing-price provenance");
+      if (projection.windows[window].kind === "estimate" && (!complete || attribution.unpriced[window] || unknown.kind !== "estimate" || unknown.amount !== 0))
+        throw new Error("Incomplete attribution cannot carry an estimate");
+      const total = projection.windows[window], reconciled = dollars + (unknown.amount ?? 0);
+      if (!Number.isFinite(reconciled) || total.amount !== null && (reconciled > total.amount && !equal(reconciled, total.amount) || unknown.kind === "estimate" && !equal(reconciled, total.amount)))
+        throw new Error("Unknown provider reconciliation mismatch");
+    }
+    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 }, population2) {
+  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], n = population2?.[w].count ?? (r !== null && r > 0 ? 2 : 0);
+    if (n >= 2 && amount !== null && amount > 0 && r !== null && r >= gates[w])
+      return label;
+  }
+  return null;
+}
+function isFirstIndexRank(r, n) {
+  const nearest = Math.round(r * (n - 1)) / (n - 1);
+  return Math.abs(r - nearest) <= 4 * Number.EPSILON * Math.max(r, nearest);
+}
+function validateRootHeatRow(row, context, config) {
+  if (!context) {
+    if (row.heat)
+      throw new Error("Root row requires context");
+    return;
+  }
+  if (!row.heat || config.schemaVersion !== 3)
+    throw new Error("Missing root row topology/decisions");
+  const heat = row.heat, eligible = rootFamilyEligibilityV1(heat.topology) === "eligible-root";
+  for (const [ranks, population2, values] of [[heat.rootDollarRanks, context.population.dollars, row.family.windows], [heat.rootScoreRanks, context.population.scores, row.family.scores]]) {
+    for (const w of HEAT_WINDOWS) {
+      const r = ranks[w], n = population2[w].count;
+      if (!eligible && r !== null)
+        throw new Error("Ineligible thread carries root-domain rank");
+      if (r !== null && (n === 0 || n === 1 && r !== 0 || population2[w].coverage === "unknown"))
+        throw new Error("Root rank population mismatch");
+      if (r !== null && n >= 2 && population2[w].coverage === "complete" && !isFirstIndexRank(r, n))
+        throw new Error("Root rank outside complete first-index grid");
+      if (context.rankAsOf >= row.asOf && r !== null && population2[w].coverage === "complete" && values[w].kind !== "estimate")
+        throw new Error("Uncertified value cannot carry a complete root rank");
+      if (context.rankAsOf >= row.asOf && r !== null && (values[w].amount === null || values[w].amount <= 0))
+        throw new Error("Root rank needs supported positive amount");
+    }
+  }
+  const expected = rootFamilyHeatV1({ topology: heat.topology, family: { contextRevision: heat.decisions.contextRevision, configRevision: row.configRevision, scores: row.family.scores, rootScoreRanks: heat.rootScoreRanks }, context, config });
+  if (JSON.stringify(expected) !== JSON.stringify(heat.decisions))
+    throw new Error("Root heat decisions/winner mismatch");
+}
+function validateHeatInputs(snapshot) {
+  const { heatInputs: input, heat: context } = snapshot;
+  if (!context || snapshot.config.value.schemaVersion !== 3 || input.contextRevision !== context.contextRevision || input.topologyRevision !== context.topologyRevision)
+    throw new Error("Root input context mismatch");
+  if (!input.cohortComplete && snapshot.coverage === "complete")
+    throw new Error("Incomplete root inputs require partial snapshot");
+  if (input.cohortComplete && (input.pending || input.omitted.count || !input.omitted.exact))
+    throw new Error("Incomplete root input cohort");
+  const ids = new Set;
+  for (const row of input.rows) {
+    if (ids.has(row.threadId))
+      throw new Error("Duplicate root input");
+    ids.add(row.threadId);
+    if (row.asOf > context.rankAsOf || row.configRevision !== snapshot.config.revision || rootFamilyEligibilityV1(row.heat.topology) !== "eligible-root" || !row.family.attribution)
+      throw new Error("Invalid root input capture");
+    validateProjection(row.family, snapshot.config.value.providerWeights);
+    validateRootHeatRow(row, context, snapshot.config.value);
+  }
+  for (const [axis, field, ranks] of [["dollars", "windows", "rootDollarRanks"], ["scores", "scores", "rootScoreRanks"]])
+    for (const w of HEAT_WINDOWS) {
+      const pop = context.population[axis][w], supported = input.rows.filter((row) => (row.family[field][w].amount ?? 0) > 0);
+      if (input.cohortComplete && pop.count > input.rows.length)
+        throw new Error("Root cohort below declared population");
+      if (pop.coverage === "complete" && pop.count < supported.length)
+        throw new Error("Root input population below supported members");
+      if (!input.cohortComplete || pop.coverage !== "complete")
+        continue;
+      if (supported.some((row) => row.family[field][w].kind !== "estimate") || pop.count !== supported.length)
+        throw new Error("Complete root input population mismatch");
+      const sorted = supported.slice().sort((a, b) => a.family[field][w].amount - b.family[field][w].amount || (a.threadId < b.threadId ? -1 : 1)), expected = new Map;
+      let first = 0;
+      for (let i = 0;i < sorted.length; i++) {
+        if (!i || sorted[i].family[field][w].amount !== sorted[i - 1].family[field][w].amount)
+          first = i;
+        expected.set(sorted[i].threadId, sorted.length === 1 ? 0 : first / (sorted.length - 1));
+      }
+      for (const row of input.rows) {
+        const actual = row.heat[ranks][w], rank2 = expected.get(row.threadId) ?? null;
+        if (actual !== rank2)
+          throw new Error("Root input rank/order mismatch");
+      }
+    }
+}
+// src/heat-settings.ts
+import { z as z2 } from "zod";
+var HEAT_SETTINGS_METHODS = Object.freeze({ read: "threadMetricsHeatSettingsReadV1", save: "threadMetricsHeatSettingsSaveV1" });
+var HEAT_SETTINGS_LIMITS = Object.freeze({ configBytes: 16 * 1024, inputBytes: 18 * 1024, outputBytes: 40 * 1024, operationKeys: 128 });
+var version = z2.string().min(1).max(256);
+var key = z2.string().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9_.:-]*$/);
+var providerId = z2.string().min(1).max(200).regex(/^[A-Za-z0-9][A-Za-z0-9_.:-]*$/);
+var weights2 = z2.record(providerId, z2.number().finite().min(0).max(3)).refine((v) => Object.keys(v).length <= 32, "Too many provider weights");
+var gates = z2.object({ m20: z2.number().finite().min(0).max(1), h24: z2.number().finite().min(0).max(1), d7: z2.number().finite().min(0).max(1) }).strict();
+var thresholds2 = z2.object({ m20: z2.number().finite().min(0).max(1e6), h24: z2.number().finite().min(0).max(1e6), d7: z2.number().finite().min(0).max(1e6), lifetime: z2.number().finite().min(0).max(1e6) }).strict();
+var legacyHeatConfigInputSchema = z2.discriminatedUnion("mode", [
+  z2.object({ schemaVersion: z2.literal(2), mode: z2.literal("percentile"), providerWeights: weights2, gates }).strict(),
+  z2.object({ schemaVersion: z2.literal(2), mode: z2.literal("absolute"), providerWeights: weights2, thresholds: thresholds2, lifetimeEnabled: z2.boolean().optional() }).strict()
+]);
+var domain = z2.object({ version: z2.literal(1), kind: z2.literal("root-family") }).strict();
+var heatConfigInputSchema = z2.discriminatedUnion("mode", [
+  z2.object({ schemaVersion: z2.literal(3), domain, mode: z2.literal("percentile"), providerWeights: weights2, gates }).strict(),
+  z2.object({ schemaVersion: z2.literal(3), domain, mode: z2.literal("absolute"), providerWeights: weights2, thresholds: thresholds2, lifetimeEnabled: z2.literal(false).optional() }).strict()
+]);
+function canonicalHeatConfig(value) {
+  const v = value.schemaVersion === 2 ? legacyHeatConfigInputSchema.parse(value) : heatConfigInputSchema.parse(value);
+  return JSON.stringify({ ...v, providerWeights: Object.fromEntries(Object.entries(v.providerWeights).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)), ...v.mode === "absolute" ? { lifetimeEnabled: v.lifetimeEnabled ?? false } : {} });
+}
+function validateHeatConfig(value) {
+  const parsed = bounded(z2.union([legacyHeatConfigInputSchema, heatConfigInputSchema]), value, HEAT_SETTINGS_LIMITS.configBytes);
+  if (new TextEncoder().encode(canonicalHeatConfig(parsed)).byteLength > HEAT_SETTINGS_LIMITS.configBytes)
+    throw new Error("Config byte limit");
+  return parsed;
+}
+function validateRootFamilyHeatConfig(value) {
+  return bounded(heatConfigInputSchema, value, HEAT_SETTINGS_LIMITS.configBytes);
+}
+function prepareRootFamilyMigration(record, review) {
+  const value = validateHeatConfig(record.value);
+  if (value.schemaVersion === 3)
+    return { kind: "review", base: record, candidate: value };
+  if (value.mode === "absolute" && value.lifetimeEnabled && !review?.disableLifetime)
+    return { kind: "blocked", reason: "Legacy lifetime heat is enabled. Explicitly review and disable that behavior before root-family migration; stored values were preserved." };
+  const candidate = value.mode === "percentile" ? { schemaVersion: 3, domain: ROOT_FAMILY_HEAT_DOMAIN_V1, mode: value.mode, providerWeights: { ...value.providerWeights }, gates: { ...value.gates } } : { schemaVersion: 3, domain: ROOT_FAMILY_HEAT_DOMAIN_V1, mode: value.mode, providerWeights: { ...value.providerWeights }, thresholds: { ...value.thresholds }, lifetimeEnabled: false };
+  return { kind: "review", base: record, candidate };
+}
+var heatSettingsReadInputSchema = z2.object({ protocolVersion: z2.literal(1), operationKey: key.optional() }).strict();
+var heatSettingsSaveInputSchema = z2.object({ protocolVersion: z2.literal(1), baseConfigVersion: version, operationKey: key, candidate: heatConfigInputSchema }).strict();
+var heatConfigRecordSchema = z2.object({ version, value: storedScoringConfigSchema }).strip();
+var observation = z2.object({ instance: version, sequence: z2.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER), configVersion: version.nullable() }).strip();
+var outcome = z2.discriminatedUnion("kind", [
+  z2.object({ kind: z2.literal("saved"), operationKey: key, record: heatConfigRecordSchema }).strip(),
+  z2.object({ kind: z2.literal("conflict"), operationKey: key, record: heatConfigRecordSchema }).strip(),
+  z2.object({ kind: z2.literal("unknown"), operationKey: key }).strip()
+]);
+var heatSettingsReadResultSchema = z2.object({ protocolVersion: z2.literal(1), current: heatConfigRecordSchema, published: observation, writable: z2.boolean(), reason: z2.string().max(512).nullable(), migration: z2.object({ kind: z2.literal("domain-required"), target: z2.object({ version: z2.literal(1), kind: z2.literal("root-family") }).strip() }).strip().optional(), outcome: outcome.optional() }).strip();
+var heatSettingsSaveResultSchema = z2.object({ protocolVersion: z2.literal(1), kind: z2.enum(["saved", "conflict"]), operationKey: key, record: heatConfigRecordSchema, publicationPending: z2.boolean() }).strip();
+function scoringHeatV2(values, ranks, population2, config) {
+  legacyHeatConfigInputSchema.parse(config);
+  for (const w of ["m20", "h24", "d7"])
+    if (!Number.isSafeInteger(population2[w]) || population2[w] < 0 || ranks[w] !== null && (!Number.isFinite(ranks[w]) || ranks[w] < 0 || ranks[w] > 1))
+      throw new Error("Invalid heat rank population");
+  for (const [w, label] of [["m20", "on-fire"], ["h24", "hot"], ["d7", "heavy"]]) {
+    const n2 = values[w].amount;
+    if (n2 !== null && Number.isFinite(n2) && n2 > 0 && (config.mode === "absolute" ? n2 >= config.thresholds[w] : population2[w] >= 2 && ranks[w] !== null && ranks[w] >= config.gates[w]))
+      return label;
+  }
+  const n = values.lifetime.amount;
+  return config.mode === "absolute" && config.lifetimeEnabled && n !== null && Number.isFinite(n) && n > 0 && n >= config.thresholds.lifetime ? "heavy" : null;
+}
+function bounded(schema, value, maxBytes) {
+  const json = JSON.stringify(value);
+  if (json === undefined || new TextEncoder().encode(json).byteLength > maxBytes)
+    throw new Error("Heat settings byte limit");
+  return schema.parse(value);
+}
+function validateHeatSaveInput(value) {
+  const input = bounded(heatSettingsSaveInputSchema, value, HEAT_SETTINGS_LIMITS.inputBytes);
+  validateHeatConfig(input.candidate);
+  return input;
+}
+function reconcileHeatSave(input, read) {
+  const o = read.outcome;
+  if (o?.operationKey === input.operationKey && o.kind === "saved")
+    return canonicalHeatConfig(o.record.value) === canonicalHeatConfig(input.candidate) ? "saved" : "conflict";
+  if (o?.operationKey === input.operationKey && o.kind === "conflict")
+    return "conflict";
+  return read.current.version === input.baseConfigVersion ? "unchanged" : "unknown";
+}
+
+// src/index.ts
+import { z as z3 } from "zod";
+import { UsageVectorSchema as UsageVectorSchema2 } 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 = z3.string().min(1).max(200).regex(/^[A-Za-z0-9][A-Za-z0-9_.:-]*$/);
+var text = z3.string().min(1).max(256);
+var time2 = z3.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+var money = z3.number().finite().nonnegative().nullable();
+var scope = z3.enum(["own", "family"]);
+var windowSchema = z3.enum(["m20", "h24", "d7", "lifetime"]);
+var coverageSchema = z3.enum(["complete", "partial", "unknown"]);
+var coverageReasonSchema = z3.enum(["source-gap", "root-unattested", "history-unavailable", "member-cap", "depth-cap", "edge-cap", "missing-thread", "unpriced", "retention", "row-cap", "pagination", "population-incomplete"]);
+var reasons2 = z3.array(coverageReasonSchema).max(16);
+var approximationSchema = z3.object({
+  approximate: z3.boolean(),
+  reasons: z3.array(z3.enum(["closest-model", "provider-default", "model-attribution", "bucket-boundary", "missing-price", "source-gap"])).max(6),
+  rates: z3.array(z3.object({ providerId: id2, modelId: text, rateId: text.nullable(), basis: z3.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 +564,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 = z3.number().finite().min(0).max(1).nullable();
+var ranksSchema = z3.object({ m20: rank2, h24: rank2, d7: rank2 }).strip();
+var population2 = z3.object({ asOf: time2, count: z3.number().int().nonnegative(), coverage: coverageSchema }).strip();
+var rankPopulationSchema = z3.object({ m20: population2, h24: population2, d7: population2 }).strip();
+var windowValueSchema = z3.object({ tokens: UsageVectorSchema2, amount: money }).strip();
+var windowsSchema = z3.object({ m20: windowValueSchema, h24: windowValueSchema, d7: windowValueSchema, lifetime: windowValueSchema }).strip();
+var bucketSchema = z3.object({ start: time2, amount: money }).strip();
 var metadata = {
-  threadId: id,
+  threadId: id2,
   scope,
-  memberCount: z.number().int().nonnegative().max(LIMITS.familyMembers),
+  memberCount: z3.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: z3.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).optional(),
+  asOf: time2,
   revision: text,
   priceVersion: text,
-  currency: z.literal("USD"),
-  estimated: z.literal(true),
+  currency: z3.literal("USD"),
+  estimated: z3.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: z3.object({ amount: z3.number().finite().nonnegative(), currency: z3.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 = z3.discriminatedUnion("changed", [
+  z3.object({ ...metadata, changed: z3.literal(true), windows: windowsSchema, buckets: z3.array(bucketSchema).max(LIMITS.seriesPoints).optional() }).strip(),
+  z3.object({ ...metadata, changed: z3.literal(false), windows: z3.never().optional(), buckets: z3.never().optional() }).strip()
 ]);
-var readInputSchema = z.object({
-  threadIds: z.array(id).min(1).max(LIMITS.threadIds),
+var readInputSchema = z3.object({
+  threadIds: z3.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: z3.boolean().optional(),
+  knownRevisions: z3.record(id2, text).optional(),
+  series: z3.object({ activeThreadId: id2, maxPoints: z3.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 +606,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 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 readResultSchema = z3.object({ version: z3.literal(1), rows: z3.array(summaryRowSchema).max(LIMITS.threadIds) }).strip();
+var detailInputSchema = z3.object({ threadId: id2, scope, includeArchived: z3.boolean().optional(), axis: z3.enum(["model", "time"]), window: windowSchema, cursor: z3.string().min(1).max(1024).optional(), limit: z3.number().int().min(1).max(LIMITS.detailRows).optional() }).strict();
+var detailBase = { amount: money, tokens: UsageVectorSchema2, approximation: approximationSchema };
+var detailRowSchema = z3.discriminatedUnion("axis", [
+  z3.object({ ...detailBase, axis: z3.literal("model"), providerId: id2, modelId: text }).strip(),
+  z3.object({ ...detailBase, axis: z3.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 = z3.object({ version: z3.literal(1), threadId: id2, scope, axis: z3.enum(["model", "time"]), window: windowSchema, asOf: time2, revision: text, priceVersion: text, currency: z3.literal("USD"), estimated: z3.literal(true), coverage: coverageSchema, coverageReasons: reasons2, excluded: z3.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).optional(), approximation: approximationSchema, total: windowValueSchema, rows: z3.array(detailRowSchema).max(LIMITS.detailRows), nextCursor: z3.string().min(1).max(1024).optional() }).strip();
+var describeInputSchema = z3.object({}).strict();
+var describeEnvelopeSchema = z3.object({ protocol: z3.literal("bb-thread-metrics"), versions: z3.array(z3.number().int().positive()).max(16) }).passthrough();
+var capabilitiesSchema = z3.object({ summary: z3.literal(true), series: z3.boolean(), detail: z3.boolean(), recentSnapshotV1: z3.boolean().optional(), heatSettingsV1: z3.boolean().optional() }).strip();
 var describeV1Schema = describeEnvelopeSchema.extend({ capabilities: capabilitiesSchema });
 function parseBounded(schema, value, maxBytes) {
   const json = JSON.stringify(value);
@@ -100,29 +634,29 @@ 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 }) {
+function heat(ranks, gates2 = { 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)
+    if (!Number.isFinite(gates2[w]) || gates2[w] < 0 || gates2[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;
+  return ranks.m20 !== null && ranks.m20 >= gates2.m20 ? "on-fire" : ranks.h24 !== null && ranks.h24 >= gates2.h24 ? "hot" : ranks.d7 !== null && ranks.d7 >= gates2.d7 ? "heavy" : null;
 }
 function familyClosure(edges, roots, policy = {}) {
   const cap = (n, fallback) => {
@@ -222,7 +756,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");
@@ -233,15 +767,15 @@ function validateDetailResult(input, value) {
         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))
+    const key2 = row.axis === "model" ? JSON.stringify([row.providerId, row.modelId]) : String(row.start);
+    if (keys.has(key2))
       throw new Error("Duplicate detail row");
-    keys.add(key);
+    keys.add(key2);
   }
   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]))
+    for (const key2 of ["inputUncached", "cacheRead", "cacheWrite", "output"]) {
+      const sum = out.rows.reduce((n, r) => n + r.tokens[key2], 0);
+      if (!Number.isFinite(sum) || Math.abs(sum - out.total.tokens[key2]) > 0.00000001 * Math.max(1, sum, out.total.tokens[key2]))
         throw new Error("Detail token total mismatch");
     }
     const hasUnknown = out.rows.some((r) => r.amount === null);
@@ -273,16 +807,57 @@ export {
   windowsSchema,
   windowValueSchema,
   windowSchema,
+  weightedScoreV2,
+  validateRootFamilyHeatConfig,
+  validateRecentSnapshot,
   validateReadResult,
+  validateHeatSaveInput,
+  validateHeatConfig,
   validateDetailResult,
   summaryRowSchema,
+  storedScoringConfigSchema,
+  scoringHeatV2,
+  scoringConfigV3Schema,
+  scoringConfigV2Schema,
+  rootTopologyV1Schema,
+  rootFamilyHeatV1,
+  rootFamilyHeatDomainV1Schema,
+  rootFamilyHeatContextV1Schema,
+  rootFamilyEligibilityV1,
+  rootFamilyDecisionSetV1Schema,
   retainedWindowStart,
+  reconcileHeatSave,
+  recentWindowsSchema,
+  recentUsageSchema,
+  recentTokenWindowsSchema,
+  recentTokenValueSchema,
+  recentSnapshotResultSchema,
+  recentSnapshotInputSchema,
+  recentSnapshotFullSchema,
+  recentScopeSchema,
+  recentRowSchema,
+  recentRootInputSchema,
+  recentRootHeatSchema,
+  recentPublicationIdentitySchema,
+  recentPresentationSchema,
+  recentPercentileHeat,
+  recentHeatInputsSchema,
+  recentDollarSchema,
+  recentAttributionSchema,
+  recentApproximationSchema,
   readResultSchema,
   readInputSchema,
   ranksSchema,
   rankPopulationSchema,
+  prepareRootFamilyMigration,
   parseBounded,
   negotiateVersion,
+  heatSettingsSaveResultSchema,
+  heatSettingsSaveInputSchema,
+  heatSettingsReadResultSchema,
+  heatSettingsReadInputSchema,
+  heatConfigRecordSchema,
+  heatConfigInputSchema,
   heat,
   familyClosure,
   dollarPercentiles,
@@ -296,9 +871,18 @@ export {
   coverageReasonSchema,
   classifyOwnerError,
   capabilitiesSchema,
+  canonicalHeatConfig,
   bucketSchema,
+  bounded,
   approximationSchema,
+  ROOT_FAMILY_HEAT_DOMAIN_V1,
+  RECENT_LIMITS,
   METRIC_BUCKET_MS,
   METHODS,
-  LIMITS
+  LIMITS,
+  HEAT_WINDOWS,
+  HEAT_SETTINGS_METHODS,
+  HEAT_SETTINGS_LIMITS,
+  DEFAULT_SCORING_CONFIG_V3,
+  DEFAULT_SCORING_CONFIG_V2
 };