@phosphorco/bb-thread-metrics 0.1.0 → 0.2.1

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,215 @@ 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.
+
+### Optional recent token/count observations
+
+A recent scope may carry `usage` with aggregate and per-provider token windows,
+explicit `estimate`/`floor`/`unavailable` values, matching provider omissions,
+and a descendant count with an exactness flag. Missing `usage` is unsupported,
+not zero. Positive tokens do not depend on a price match or lifetime dollar
+observations: wholly unpriced and bucket-only tokens can remain floors while
+USD is unavailable. Unknown/legacy token inputs stay unavailable. A supplied
+zero is an explicit observation attestation.
+
+Provider identities must match the displayed dollar providers. The codec checks
+componentwise conservation of known token observations and reconciles descendant
+count with the loaded membership; it does not certify unseen global membership.
+Omitted providers permit a larger aggregate supported subtotal, never a smaller
+one. Presentation fitting removes dollar/token provider entries together and
+retains aggregate supported observations with an explicit cap qualification.
+
+Per-provider dollar contributions are the primary money presentation. Aggregate
+cross-provider dollar windows remain internal reconciliation/ranking inputs and
+must not be presented as a grand total. Weighted attention scores are unitless,
+not currency; token counts and descendants are secondary to provider dollars.
+
+An aggregate token `estimate` requires estimate-kind tokens for every displayed
+provider and no omitted providers in that window. A floor or unavailable provider
+cannot be upgraded by numerical equality alone. This requirement is independent
+of USD pricing coverage: completely observed zero or positive tokens may remain
+estimates while dollars are unpriced. Explicit member-cap, depth-cap or edge-cap
+coverage cannot carry `descendants.exact=true`; other supplier membership
+attestations still require evidence the codec cannot reconstruct.
+
+
+### Unique seven-day root inputs (unpublished0.2 producer extension)
+
+Optional `heatInputs` is a unique all-window root-family table captured in the SAME durable rank publication as `heat`. It is independent of `rows`, whose actual fold activity covers only72h and whose money may be newer. Never join current display money into captured ranks by ID, infer missing activity timestamps, or compare cross-epoch money as equal. Each input carries its financial `asOf`, config revision, explicit attested root topology, root-domain dollar/weighted ranks and all three decisions. `family.dollarRanks/scoreRanks` retain their original scoped meaning; root ranks live only under `heat`. Unknown metadata remains absent/null; title/native personal-or-project navigation is only bounded already-collected data, not identity/membership proof.
+
+`cohortComplete` attests the supplied ROOT table, not complete source observation or exact spend. It requires no pending or omitted input and exact omission accounting. Per-window context population coverage and each family value/attribution remain independent. Full certified windows reconcile exact supported-positive counts and first-tie ordering against the complete table; partial transport preserves published ranks but cannot give exact reweighted draft percentiles. A five-day root can appear here without any72h display row. Hidden/archive activity is included; child/deleted/unknown topology never enters this table.
+
+Display rows PLUS captured input rows share one aggregate1000 physical-entry budget, whole4MiB canonical JSON,8KiB per entry; duplicate IDs across these two DIFFERENT captures still consume two physical entries. Raw additive fields count before output stripping. Producer packing may retain only a subset; omissions/capped membership are explicit and prevent a complete input attestation. It never reconstructs from display rows or adds a per-ID population endpoint.
+
+Optional scope `attribution` carries per-window `unknownProvider`, `attributionComplete` and `unpriced` evidence. Known provider USD is primary presentation. Cross-provider `windows` and unitless weighted `scores` are INTERNAL reconciliation/ranking inputs, not a dollar grand total. Unknown remainder is a lower bound/unavailable reconciliation amount, NEVER an invented provider at weight1. No omitted provider IDs and exact zero remainder are required for complete attribution; complete observation/price are separately required for estimates. Explicit unpriced usage retains missing-price provenance. Legacy scopes lacking this extension remain readable diagnostics; they cannot populate the new certified heat input table. No numeric evidence is invented on migration.
+
+The supplier still attests actual membership and ordering; codecs prove internal coherence, not unseen global source truth. Bounds are post-transport parsing containment. The optional producer remains source-only until reviewed publication, exact registry pins, fresh composition gates and host byte/time measurement; the contract extension alone is no activation/adoption/freshness proof.
+
+
+### Full publication identity and ordered consumer admission
+
+An additive full-only `publication:{instance,sequence}` header exposes the
+supplier's committed publication identity. `instance` is an opaque1–128-character
+string; `sequence` is a positive safe integer. Old stored/full responses may omit
+this header and remain readable for legacy diagnostics. New changed publications
+from the ledger include it. A Heat capture adopter requires the header; absence
+is unavailable, never inferred by parsing `revision`, rank time or a request
+ordinal. Unchanged replies carry only the previously requested opaque revision,
+never a new identity or recognized full-only fields.
+
+Within one durable source history, changed committed publications strictly
+increase sequence across writer-instance changes. No-op attempts and reopening
+retain the exact held revision/pair/content. The publisher injects revision and
+pair inside its guarded commit and excludes BOTH from the semantic digest. The
+pair is validated against the stored instance/counter on hydration; reads return
+the stored payload identity, not the newly registered writer. Actual encoded
+header bytes count toward the same4MiB cap; no new allowance is created.
+
+A retained owner resource, outside component mounts, must order validated full
+responses by sequence before feeding Heat: lower is stale; equal accepts only
+the same immutable pair/revision/content; greater with a new instance is an
+ordered writer successor. Null, ordinary reconnect, facade changes and timeouts
+do not reset this watermark or release actual transport admission. Source
+replacement fences captured old callbacks. These are adopter obligations, not
+facts proved by a stateless wire decoder or the presence of this header.
+
+The persisted counter does NOT attest order across external database rollback,
+reset or replacement. Such images may repeat or lower sequences while changed
+writer UUIDs keep revisions distinct. A UUID alone must never authorize a reset;
+a retained consumer holds/reports lower or equal-conflicting data until an
+explicit authoritative selected-source replacement. This unit adds no restore
+protocol or automatic reset. Counter exhaustion is explicit refusal, never wrap.
+Settings Save CAS remains keyed by config version, not publication sequence;
+settings published metadata must describe the exact held publication/config.
+
+
+### Retained snapshot client session (unpublished0.2)
+
+The optional `/bb` `createRecentSnapshotSession(ownerBoundClient)` helper is an
+imperative admission and ordering boundary, owned by the existing selected-source
+resource outside React. The surface owns discovery, source-selection authority,
+refresh cadence, retries, observable state and rendering. The helper creates no
+subscription, refresh loop, retry queue or shared global store; construction is
+quiet. It holds at most one decoded immutable full snapshot and one actual read.
+A native adopter must retain the SAME session through zero interest, remount,
+ordinary reconnect and facade/writer changes while a read remains outstanding.
+Independent factories do not share admission. This helper alone does not prove
+an adopter's resource lifetime.
+
+`read()` sends the held opaque revision conditionally; `read({full:true})` requests
+a full response. Original full envelopes are publicly validated before ordering.
+A full response requires the publication pair: lower sequences fail, equal
+sequences require the same immutable pair/revision/decoded content, and greater
+sequences must use a new opaque revision. An ordered new writer advances the
+private owner generation once; an ordinary same-source facade update does not.
+Valid unchanged content returns the exact held observation object, allowing the
+caller to confirm recovery without allocating or notifying for changed data.
+Null, invalid, missing-identity, stale or failed responses preserve last content
+and highwater. Validation/content comparison still costs bounded payload work;
+this is not a claim of constant-time end-to-end decoding.
+
+The default local observation deadline is the existing2000ms contract call
+limit (configurable1–2000ms). Timeout, caller abort, inactive state or explicit
+replacement rejects local observation and aborts its signal, but the actual slot
+remains held until the underlying source Promise settles, even if abort is
+ignored. Busy/inactive/already-aborted reads return typed local
+`RecentSnapshotNotStarted` without invoking the source. A source-thrown instance
+of that type is wrapped and cannot claim this session's pre-invocation proof.
+There is no queued replay. A permanently held transport keeps this lane
+unavailable; caller deadline never proves remote cancellation.
+
+`updateSource` is only a same-plugin facade update and retains ordering.
+`replaceSource` requires authoritative selected-source replacement, fences old
+callbacks and clears held lineage while retaining any actual old transport slot.
+Do not invoke it for a new UUID, timeout, remount, lower sequence or an ordinary
+reconnect. External restored/reset images require authority supplied by the
+native resource; this API does not establish that authority. `setActive` changes
+interest without clearing the lineage. Only admitted observations may feed Heat
+owner-generation transitions. Publication identity is independent of matching
+Save config bytes/version, which the retained Heat adapter must still check.
+
+These are client source conformance guarantees, not released pins, native
+resource adoption, host latency/freshness or live bytes/time acceptance. No
+existing consumer is switched merely by exporting this helper.

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,247 @@
 // src/bb.ts
 import { z } from "zod";
-import { LIMITS, METHODS, describeInputSchema, describeEnvelopeSchema, capabilitiesSchema, readInputSchema, detailInputSchema, parseBounded, negotiateVersion, validateReadResult, validateDetailResult, classifyOwnerError } from "./index.js";
+import { HEAT_SETTINGS_METHODS, HEAT_SETTINGS_LIMITS, bounded, validateHeatSaveInput, heatSettingsReadInputSchema, heatSettingsSaveInputSchema, heatSettingsReadResultSchema, heatSettingsSaveResultSchema } from "./index.js";
+import { RECENT_LIMITS, recentSnapshotInputSchema, validateRecentSnapshot as validateRecentSnapshot2, LIMITS as LIMITS2, METHODS, describeInputSchema, describeEnvelopeSchema, capabilitiesSchema, readInputSchema, detailInputSchema, parseBounded, negotiateVersion, validateReadResult, validateDetailResult, classifyOwnerError } from "./index.js";
+
+// src/recent-session.ts
+import { LIMITS, validateRecentSnapshot } from "./index.js";
+
+class RecentSnapshotSessionError extends Error {
+  reason;
+  constructor(reason) {
+    super(`Recent snapshot session: ${reason}`);
+    this.reason = reason;
+  }
+}
+
+class RecentSnapshotNotStarted extends RecentSnapshotSessionError {
+  notStarted = true;
+  constructor(reason) {
+    super(reason);
+  }
+}
+var clock = { later(run, ms) {
+  const timer = setTimeout(run, ms);
+  return () => clearTimeout(timer);
+} };
+function next(n) {
+  if (n === Number.MAX_SAFE_INTEGER)
+    throw new Error("Recent session generation exhausted");
+  return n + 1;
+}
+function sourceCopy(source) {
+  if (!source.pluginId || source.pluginId.length > 200 || typeof source.recentSnapshot !== "function")
+    throw new Error("Invalid recent snapshot source");
+  return { pluginId: source.pluginId, recentSnapshot: source.recentSnapshot.bind(source) };
+}
+function freeze(value) {
+  if (value && typeof value === "object" && !Object.isFrozen(value)) {
+    for (const child of Object.values(value))
+      freeze(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+function same(a, b) {
+  if (a === b)
+    return true;
+  if (!a || !b || typeof a !== "object" || typeof b !== "object")
+    return false;
+  if (Array.isArray(a) !== Array.isArray(b))
+    return false;
+  const ak = Object.keys(a), bk = Object.keys(b);
+  if (ak.length !== bk.length)
+    return false;
+  return ak.every((key) => Object.hasOwn(b, key) && same(a[key], b[key]));
+}
+function createRecentSnapshotSession(initial, options = {}) {
+  const timeoutMs = options.timeoutMs ?? LIMITS.callMs;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > LIMITS.callMs)
+    throw new Error("Invalid recent session deadline");
+  const time = options.clock ?? clock;
+  let source = sourceCopy(initial), active = true, epoch = Symbol("view"), sourceGeneration = 1, ownerGeneration = 1;
+  let held;
+  let actual;
+  const admit = (input, raw, current) => {
+    if (!current())
+      throw new RecentSnapshotSessionError("stale-call");
+    const value = validateRecentSnapshot(input, raw);
+    if (!current())
+      throw new RecentSnapshotSessionError("stale-call");
+    if (value.unchanged) {
+      if (!held || held.snapshot.revision !== value.revision)
+        throw new RecentSnapshotSessionError("publication-conflict");
+      return held;
+    }
+    const publication = value.publication;
+    if (!publication)
+      throw new RecentSnapshotSessionError("missing-publication");
+    if (held) {
+      if (publication.sequence < held.publication.sequence)
+        throw new RecentSnapshotSessionError("stale-publication");
+      if (publication.sequence === held.publication.sequence) {
+        if (publication.instance !== held.publication.instance || value.revision !== held.snapshot.revision || !same(value, held.snapshot))
+          throw new RecentSnapshotSessionError("publication-conflict");
+        return held;
+      }
+      if (value.revision === held.snapshot.revision)
+        throw new RecentSnapshotSessionError("publication-conflict");
+      if (publication.instance !== held.publication.instance)
+        ownerGeneration = next(ownerGeneration);
+    }
+    held = freeze({ snapshot: value, publication, ownerGeneration, sourceGeneration });
+    return held;
+  };
+  return {
+    get current() {
+      return held;
+    },
+    get outstandingReads() {
+      return actual ? 1 : 0;
+    },
+    get ownerGeneration() {
+      return ownerGeneration;
+    },
+    get sourceGeneration() {
+      return sourceGeneration;
+    },
+    get pluginId() {
+      return source.pluginId;
+    },
+    updateSource(value) {
+      const updated = sourceCopy(value);
+      if (updated.pluginId !== source.pluginId)
+        throw new Error("Selected source change requires explicit replacement");
+      source = updated;
+    },
+    replaceSource(value) {
+      const updated = sourceCopy(value), sg = next(sourceGeneration), og = next(ownerGeneration);
+      source = updated;
+      sourceGeneration = sg;
+      ownerGeneration = og;
+      held = undefined;
+      epoch = Symbol("source");
+      actual?.cancel?.("source-replaced");
+    },
+    setActive(value) {
+      if (value === active)
+        return;
+      active = value;
+      epoch = Symbol("view");
+      if (!active)
+        actual?.cancel?.("inactive");
+    },
+    read(options2 = {}) {
+      const { signal, full } = options2;
+      options2 = {};
+      if (!active)
+        return Promise.reject(new RecentSnapshotNotStarted("inactive"));
+      if (signal?.aborted)
+        return Promise.reject(new RecentSnapshotNotStarted("aborted-before-start"));
+      if (actual)
+        return Promise.reject(new RecentSnapshotNotStarted("busy"));
+      const input = !full && held ? { ifRevision: held.snapshot.revision } : {};
+      let selected = source;
+      const binding = sourceGeneration, view = epoch, control = new AbortController, slot = { cancel: undefined };
+      actual = slot;
+      let finished = false;
+      const current = () => !finished && active && epoch === view && sourceGeneration === binding;
+      let resolve, reject;
+      const result = new Promise((yes, no) => {
+        resolve = yes;
+        reject = no;
+      });
+      let cancelTimer;
+      const finish = (error, observation) => {
+        if (finished)
+          return;
+        finished = true;
+        cancelTimer?.();
+        cancelTimer = undefined;
+        signal?.removeEventListener("abort", abort);
+        slot.cancel = undefined;
+        const yes = resolve, no = reject;
+        resolve = undefined;
+        reject = undefined;
+        if (observation === undefined)
+          no?.(error);
+        else
+          yes?.(observation);
+      };
+      const cancel = (reason) => {
+        finish(new RecentSnapshotSessionError(reason));
+        control.abort();
+      };
+      const abort = () => cancel("aborted");
+      slot.cancel = cancel;
+      signal?.addEventListener("abort", abort, { once: true });
+      try {
+        cancelTimer = time.later(() => cancel("timeout"), timeoutMs);
+      } catch (error) {
+        finish(error);
+        actual = undefined;
+        return result;
+      }
+      if (finished) {
+        actual = undefined;
+        cancelTimer?.();
+        return result;
+      }
+      let pending;
+      try {
+        pending = Promise.resolve(selected.recentSnapshot(Object.freeze(input), control.signal));
+      } catch (error) {
+        pending = Promise.reject(error);
+      } finally {
+        selected = undefined;
+      }
+      pending.then((value) => {
+        try {
+          if (!finished)
+            finish(undefined, admit(input, value, current));
+        } catch (error) {
+          finish(error);
+        } finally {
+          if (actual === slot)
+            actual = undefined;
+        }
+      }, (error) => {
+        try {
+          finish(error instanceof RecentSnapshotNotStarted ? new Error("Recent snapshot source rejected after invocation", { cause: error }) : error);
+        } finally {
+          if (actual === slot)
+            actual = undefined;
+        }
+      });
+      return result;
+    }
+  };
+}
+
+// src/bb.ts
+function registerHeatSettingsOwner(bb, port) {
+  bb.rpc.register({
+    threadMetricsHeatSettingsReadV1: { input: sdkSchema(heatSettingsReadInputSchema, HEAT_SETTINGS_LIMITS.inputBytes), output: sdkSchema(z.unknown()) },
+    threadMetricsHeatSettingsSaveV1: { input: sdkSchema(heatSettingsSaveInputSchema, HEAT_SETTINGS_LIMITS.inputBytes), output: sdkSchema(z.unknown()) }
+  }, {
+    threadMetricsHeatSettingsReadV1: async (raw) => bounded(heatSettingsReadResultSchema, await port.read(bounded(heatSettingsReadInputSchema, raw, HEAT_SETTINGS_LIMITS.inputBytes)), HEAT_SETTINGS_LIMITS.outputBytes),
+    threadMetricsHeatSettingsSaveV1: async (raw) => bounded(heatSettingsSaveResultSchema, await port.save(validateHeatSaveInput(raw)), HEAT_SETTINGS_LIMITS.outputBytes)
+  }, { experimental_discoverable: true });
+}
+function createHeatSettingsClient(sdk, pluginId) {
+  if (!pluginId || pluginId.length > 200)
+    throw new Error("Invalid target plugin id");
+  const call = async (method, input, signal) => sdk.plugins.callRpc({ pluginId, method, input, outputSchema: z.unknown(), ...signal ? { signal } : {} });
+  return {
+    read: async (input, signal) => bounded(heatSettingsReadResultSchema, await call(HEAT_SETTINGS_METHODS.read, bounded(heatSettingsReadInputSchema, input, HEAT_SETTINGS_LIMITS.inputBytes), signal), HEAT_SETTINGS_LIMITS.outputBytes),
+    save: async (input, signal) => {
+      const result = bounded(heatSettingsSaveResultSchema, await call(HEAT_SETTINGS_METHODS.save, validateHeatSaveInput(input), signal), HEAT_SETTINGS_LIMITS.outputBytes);
+      if (result.operationKey !== input.operationKey)
+        throw new Error("Save operation mismatch");
+      return result;
+    }
+  };
+}
 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,29 +253,40 @@ 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 (Boolean(capabilities.heatSettingsV1) !== Boolean(port.heatSettings))
+    throw new Error("Heat settings 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 });
   const contract = {
-    threadMetricsDescribe: { input: sdkSchema(describeInputSchema, LIMITS.inputBytes), output: sdkSchema(z.unknown()) },
-    threadMetricsReadV1: { input: sdkSchema(readInputSchema, LIMITS.inputBytes), output: sdkSchema(z.unknown()) }
+    threadMetricsDescribe: { input: sdkSchema(describeInputSchema, LIMITS2.inputBytes), output: sdkSchema(z.unknown()) },
+    threadMetricsReadV1: { input: sdkSchema(readInputSchema, LIMITS2.inputBytes), output: sdkSchema(z.unknown()) }
   };
   const handlers = {
     threadMetricsDescribe: (raw) => {
-      parseBounded(describeInputSchema, raw, LIMITS.inputBytes);
+      parseBounded(describeInputSchema, raw, LIMITS2.inputBytes);
       return describe();
     },
     threadMetricsReadV1: async (raw) => {
-      const input = parseBounded(readInputSchema, raw, LIMITS.inputBytes);
+      const input = parseBounded(readInputSchema, raw, LIMITS2.inputBytes);
       if (input.series && !capabilities.series)
         throw new Error("Series not supported");
       return validateReadResult(input, await port.read(input));
     }
   };
   bb.rpc.register(contract, handlers, { experimental_discoverable: true });
+  if (port.heatSettings)
+    registerHeatSettingsOwner(bb, port.heatSettings);
+  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 validateRecentSnapshot2(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);
+    bb.rpc.register({ threadMetricsDetailV1: { input: sdkSchema(detailInputSchema, LIMITS2.inputBytes), output: sdkSchema(z.unknown()) } }, { threadMetricsDetailV1: async (raw) => {
+      const input = parseBounded(detailInputSchema, raw, LIMITS2.inputBytes);
       return validateDetailResult(input, await port.detail(input));
     } }, { experimental_discoverable: true });
 }
@@ -48,26 +300,30 @@ function createThreadMetricsClient(sdk, pluginId) {
     pluginId,
     async describe(signal) {
       const raw = await call(METHODS.describe, {}, signal);
-      return negotiateVersion(parseBounded(describeEnvelopeSchema, raw, LIMITS.describeBytes));
+      return negotiateVersion(parseBounded(describeEnvelopeSchema, raw, LIMITS2.describeBytes));
+    },
+    async recentSnapshot(raw = {}, signal) {
+      const input = parseBounded(recentSnapshotInputSchema, raw, RECENT_LIMITS.inputBytes);
+      return validateRecentSnapshot2(input, await call(METHODS.recentSnapshot, input, signal));
     },
     async read(raw, signal) {
-      const input = parseBounded(readInputSchema, raw, LIMITS.inputBytes);
+      const input = parseBounded(readInputSchema, raw, LIMITS2.inputBytes);
       return validateReadResult(input, await call(METHODS.read, input, signal));
     },
     async detail(raw, signal) {
-      const input = parseBounded(detailInputSchema, raw, LIMITS.inputBytes);
+      const input = parseBounded(detailInputSchema, raw, LIMITS2.inputBytes);
       return validateDetailResult(input, await call(METHODS.detail, input, signal));
     }
   };
 }
 async function discoverThreadMetricsOwners(options) {
-  const bounded = (v, max) => {
+  const bounded2 = (v, max) => {
     const n = v ?? max;
     if (!Number.isInteger(n) || n < 1 || n > max)
       throw new Error("Invalid discovery budget");
     return n;
   };
-  const count = bounded(options.maxCandidates, LIMITS.candidates), concurrency = bounded(options.concurrency, LIMITS.concurrency), callMs = bounded(options.callMs, LIMITS.callMs), deadlineMs = bounded(options.deadlineMs, LIMITS.discoveryMs);
+  const count = bounded2(options.maxCandidates, LIMITS2.candidates), concurrency = bounded2(options.concurrency, LIMITS2.concurrency), callMs = bounded2(options.callMs, LIMITS2.callMs), deadlineMs = bounded2(options.deadlineMs, LIMITS2.discoveryMs);
   const pass = new AbortController, rows = new Map, active = new Map;
   let done = false, ending = false, listedReady = false, omittedCount = 0, eligibleCount = 0, started = 0;
   const timers = new Set;
@@ -120,11 +376,11 @@ async function discoverThreadMetricsOwners(options) {
       return;
     listedReady = true;
     const unique = new Map;
-    for (const p of listed.plugins.slice(0, LIMITS.listedPlugins))
+    for (const p of listed.plugins.slice(0, LIMITS2.listedPlugins))
       if (p.id.length <= 200 && (p.status === "running" || p.status === "degraded"))
         unique.set(p.id, p);
     const candidates = [...unique.values()].slice(0, count);
-    omittedCount = unique.size - candidates.length + Math.max(0, listed.plugins.length - LIMITS.listedPlugins);
+    omittedCount = unique.size - candidates.length + Math.max(0, listed.plugins.length - LIMITS2.listedPlugins);
     eligibleCount = candidates.length;
     let index = 0;
     async function worker() {
@@ -192,6 +448,11 @@ function createThreadMetricsDiscovery(sdk) {
 }
 export {
   registerThreadMetricsOwner,
+  registerHeatSettingsOwner,
   createThreadMetricsDiscovery,
-  createThreadMetricsClient
+  createThreadMetricsClient,
+  createRecentSnapshotSession,
+  createHeatSettingsClient,
+  RecentSnapshotSessionError,
+  RecentSnapshotNotStarted
 };