deepline 0.3.113 → 0.3.114

package/dist/bundling-sources/sdk/src/client.ts

@@ -558,6 +558,8 @@ function resolveToolExecuteTimeoutMs(
     normalized === 'deeplineagent_deeplineagent' ||
     normalized === 'ai_inference' ||
     normalized === 'deeplineagent_ai_inference' ||
+    normalized === 'ai_evaluate' ||
+    normalized === 'deeplineagent_ai_evaluate' ||
     normalized === 'aiinference'
     ? DEEPLINEAGENT_EXECUTE_TIMEOUT_MS
     : undefined;
@@ -2782,7 +2784,7 @@ export class DeeplineClient {
    * maximum and contains Deepline credits only.
    */
   async quoteInferenceTool(
-    toolId: 'ai_inference' | 'deeplineagent',
+    toolId: 'ai_evaluate' | 'ai_inference' | 'deeplineagent',
     payload: Record<string, unknown>,
   ): Promise<InferenceQuote> {
     return this.http.post<InferenceQuote>(

package/dist/bundling-sources/sdk/src/compat.ts

@@ -62,7 +62,28 @@ export type SdkCompatibilitySkillsUpdate = {
 };
 
 const CHECK_TIMEOUT_MS = 2_000;
-export const SDK_COMPATIBILITY_CACHE_TTL_MS = 5 * 60 * 1000;
+/**
+ * A cached clean policy younger than this is trusted outright: the command
+ * runs without a live request. Policy floors move on a release cadence; the
+ * one control designed to move in minutes, a forced rollback, is delayed by
+ * at most this window and only for commands run within it. The live check
+ * is best-effort already (a network failure runs the command with no policy),
+ * so trusting a fresh clean answer is strictly stronger than that path.
+ */
+export const SDK_COMPATIBILITY_TRUST_MS = 10 * 60 * 1000;
+/**
+ * A cached entry older than the trust window but younger than this still
+ * qualifies for the short live budget and for the offline fallback.
+ */
+export const SDK_COMPATIBILITY_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+/**
+ * Blocking budget for the live compatibility check when a fresh, clean policy
+ * for the same command is already cached. The live check still runs and still
+ * wins whenever the server answers inside this window; on a slow or proxied
+ * network the command proceeds on the cached policy instead of waiting the
+ * full timeout. Blocking policies never use this budget.
+ */
+export const SDK_COMPATIBILITY_FAST_DEADLINE_MS = 400;
 
 type CompatCacheFile = {
   entries?: Record<
@@ -118,11 +139,83 @@ function legacyCompatibilityCacheKey(
   });
 }
 
+/**
+ * A cached policy is "clean" when it carries no blocking or mutating control:
+ * proceeding on it can at most delay an advisory notice, never bypass a
+ * required update, a server-directed auto-update, or a CLI-family rollback.
+ */
+export function isCleanCompatibilityPolicy(
+  response: SdkCompatibilityResponse | null,
+): boolean {
+  if (!response) return false;
+  // `ok` is the server's own "this is a policy" marker (426 otherwise); a
+  // proxy error body or other junk JSON never earns the trusted tiers.
+  return (
+    response.ok === true &&
+    response.update_required !== true &&
+    response.status !== 'unsupported' &&
+    !response.auto_update?.should_auto_update &&
+    !response.cli_family
+  );
+}
+
+/**
+ * The cached response for this exact command, only when it is inside the
+ * cache TTL and clean. Used to decide whether the live check may run with the
+ * short deadline instead of its full timeout.
+ */
+export function readFreshCleanCompatibility(
+  baseUrl: string,
+  command: string | null | undefined,
+  skillsVersion: string | null | undefined,
+): SdkCompatibilityResponse | null {
+  const cached = readCachedCompatibility(baseUrl, command, skillsVersion);
+  return isCleanCompatibilityPolicy(cached) ? cached : null;
+}
+
+/**
+ * The cached response for this exact command when it is clean and younger
+ * than the trust window: the command may run on it without a live request.
+ */
+export function readTrustedCleanCompatibility(
+  baseUrl: string,
+  command: string | null | undefined,
+  skillsVersion: string | null | undefined,
+  now = Date.now(),
+): SdkCompatibilityResponse | null {
+  const entry = readCachedCompatibilityEntry(baseUrl, command, skillsVersion);
+  if (!entry || !isSavedWithin(entry.savedAt, SDK_COMPATIBILITY_TRUST_MS, now))
+    return null;
+  return isCleanCompatibilityPolicy(entry.response) ? entry.response : null;
+}
+
+/**
+ * A cache entry is usable only when its age is a real, non-negative number
+ * inside the window. A missing timestamp (NaN) or a future one (after a clock
+ * correction) would otherwise pass a plain `age > window` check forever.
+ */
+function isSavedWithin(savedAt: unknown, windowMs: number, now: number) {
+  if (typeof savedAt !== 'number') return false;
+  const age = now - savedAt;
+  return Number.isFinite(age) && age >= 0 && age <= windowMs;
+}
+
 function readCachedCompatibility(
   baseUrl: string,
   command: string | null | undefined,
   skillsVersion: string | null | undefined,
 ): SdkCompatibilityResponse | null {
+  return (
+    readCachedCompatibilityEntry(baseUrl, command, skillsVersion)?.response ??
+    null
+  );
+}
+
+function readCachedCompatibilityEntry(
+  baseUrl: string,
+  command: string | null | undefined,
+  skillsVersion: string | null | undefined,
+): { savedAt: number; response: SdkCompatibilityResponse } | null {
   try {
     const path = sdkCompatibilityCachePath(baseUrl);
     const legacyPath = legacySdkCompatibilityCachePath();
@@ -141,15 +234,50 @@ function readCachedCompatibility(
       (useLegacyCache
         ? parsed.entries?.[legacyCompatibilityCacheKey(baseUrl, command)]
         : undefined);
-    if (!entry || Date.now() - entry.savedAt > SDK_COMPATIBILITY_CACHE_TTL_MS) {
+    if (
+      !entry ||
+      !isSavedWithin(entry.savedAt, SDK_COMPATIBILITY_CACHE_TTL_MS, Date.now())
+    ) {
       return null;
     }
-    return entry.response;
+    return entry;
   } catch {
     return null;
   }
 }
 
+/**
+ * Drop one cached entry so the next check for this command runs with the full
+ * budget. Used after a short-deadline check fell back to the cache: the
+ * command proceeds on the cached clean policy once, but a blocking policy the
+ * server may have published meanwhile is enforced on the very next command
+ * instead of after the cache TTL.
+ */
+function invalidateCachedCompatibility(
+  baseUrl: string,
+  command: string | null | undefined,
+  skillsVersion: string | null | undefined,
+): void {
+  try {
+    // Mirror the reader: an upgraded client may still be served from the
+    // legacy cache file until the host-scoped one is first written.
+    const path = sdkCompatibilityCachePath(baseUrl);
+    const legacyPath = legacySdkCompatibilityCachePath();
+    const cachePath =
+      !existsSync(path) && existsSync(legacyPath) ? legacyPath : path;
+    if (!existsSync(cachePath)) return;
+    const existing = JSON.parse(
+      readFileSync(cachePath, 'utf8'),
+    ) as CompatCacheFile;
+    const entries = existing.entries ?? {};
+    delete entries[compatibilityCacheKey(baseUrl, command, skillsVersion)];
+    delete entries[legacyCompatibilityCacheKey(baseUrl, command)];
+    writeFileSync(cachePath, `${JSON.stringify({ entries }, null, 2)}\n`);
+  } catch {
+    // A cache that cannot be edited simply expires on its own TTL.
+  }
+}
+
 function writeCachedCompatibility(
   baseUrl: string,
   command: string | null | undefined,
@@ -176,7 +304,12 @@ function writeCachedCompatibility(
 
 export async function checkSdkCompatibility(
   baseUrl: string,
-  options: { command?: string | null; skillsVersion?: string | null } = {},
+  options: {
+    command?: string | null;
+    skillsVersion?: string | null;
+    /** Blocking budget for the live request; defaults to the full timeout. */
+    timeoutMs?: number;
+  } = {},
 ): Promise<{
   response: SdkCompatibilityResponse | null;
   error: Error | null;
@@ -185,7 +318,10 @@ export async function checkSdkCompatibility(
     return { response: null, error: null };
   }
   const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), CHECK_TIMEOUT_MS);
+  const timeout = setTimeout(
+    () => controller.abort(),
+    options.timeoutMs ?? CHECK_TIMEOUT_MS,
+  );
   try {
     const url = new URL('/api/v2/sdk/compat', baseUrl);
     url.searchParams.set('version', SDK_VERSION);
@@ -209,14 +345,24 @@ export async function checkSdkCompatibility(
     const data = (await response
       .json()
       .catch(() => null)) as SdkCompatibilityResponse | null;
-    if (data) {
-      writeCachedCompatibility(
-        baseUrl,
-        options.command,
-        options.skillsVersion,
-        data,
+    // Only a policy-shaped body counts as a response. A JSON error page from
+    // a proxy is a failed check: it is never cached, and it falls through to
+    // the cached-policy fallback below like a network error would.
+    if (
+      !data ||
+      typeof data.ok !== 'boolean' ||
+      typeof data.status !== 'string'
+    ) {
+      throw new Error(
+        `SDK compatibility endpoint returned a non-policy response (HTTP ${response.status}).`,
       );
     }
+    writeCachedCompatibility(
+      baseUrl,
+      options.command,
+      options.skillsVersion,
+      data,
+    );
     return { response: data, error: null };
   } catch (error) {
     // Live compat policy must win when the server is reachable: rollback and
@@ -228,6 +374,16 @@ export async function checkSdkCompatibility(
       options.skillsVersion,
     );
     if (cached) {
+      if (
+        options.timeoutMs !== undefined &&
+        options.timeoutMs < CHECK_TIMEOUT_MS
+      ) {
+        invalidateCachedCompatibility(
+          baseUrl,
+          options.command,
+          options.skillsVersion,
+        );
+      }
       return { response: cached, error: null };
     }
     return {

package/dist/bundling-sources/sdk/src/release.ts

@@ -200,7 +200,7 @@ export const SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: '0.3.113',
+  version: '0.3.114',
   updateSummary:
     'Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.',
   packageCapabilities: {

package/dist/bundling-sources/sdk/src/skills-version.ts

@@ -31,11 +31,37 @@ function readPluginSkillsVersion(): string {
   }
 }
 
+/**
+ * Agent names can reach the CLI from `--agent`. Every state path derived from
+ * an agent name goes through this slug so no value can escape the SDK state
+ * directory.
+ */
+/**
+ * Every agent an installer may write for. `*` targets all of them, so any
+ * coordination keyed by agent must treat `*` as this whole set.
+ */
+export const KNOWN_SKILL_AGENTS = [
+  'antigravity',
+  'claude-code',
+  'cline',
+  'codex',
+  'cursor',
+  'gemini-cli',
+  'windsurf',
+] as const;
+
+export function skillsAgentPathSegment(agent: string): string {
+  if (agent === '*') return 'all';
+  const slug = agent.replace(/[^a-z0-9]+/gi, '-').replace(/^-+|-+$/g, '');
+  return slug || 'agent';
+}
+
 function sdkSkillsVersionPath(
   baseUrl: string,
   agents: readonly string[] = [],
 ): string {
-  const suffix = agents.length > 0 ? `-${agents.join('-')}` : '';
+  const suffix =
+    agents.length > 0 ? `-${agents.map(skillsAgentPathSegment).join('-')}` : '';
   return join(sdkCliStateDirPath(baseUrl), `skills${suffix}-version`);
 }
 

package/dist/bundling-sources/shared_libs/monitors/inbound-queue.ts

@@ -13,8 +13,8 @@ import {
 import type { SignalRadarInboundMessage } from '@deepline/monitors/signal-radars/inbound-message';
 
 // Public inbound-queue surface used by the thin provider-callback receiver.
-// Re-exports the topic + producer and adds the Neon-free publish key helper and
-// the retry classifier the receiver/worker share.
+// The receiver stays on this established producer until the receipt dispatch
+// endpoint is already serving in the preceding reader release.
 export const SIGNAL_RADAR_INBOUND_TOPIC = SIGNAL_RADAR_INBOUND_TOPIC_VALUE;
 
 function headersToObject(headers: Headers): Record<string, string> {
@@ -38,6 +38,10 @@ export async function sendSignalRadarInboundMessage(
   return sendSignalRadarInbound(message, options);
 }
 
+// The reconciliation runner uses the same queue while this reader release
+// waits for the signed receipt endpoint to be live.
+export { send } from '@deepline/monitors/signal-radars/inbound-queue';
+
 // Transient (retry) vs permanent (dead-letter) classifier, shared with the
 // worker's retry callback. See classifyInboundFailure for the semantics.
 export function classifySignalRadarInboundError(

package/dist/bundling-sources/shared_libs/observability/queue-health.ts

@@ -1,6 +1,7 @@
 /** Scheduler-neutral queue/workset health contract. */
 
 import { measuredValue, type Measured } from './scheduled-work-v2';
+import type { Telemetry, TelemetryFields } from './telemetry';
 export type { Measured } from './scheduled-work-v2';
 export {
   exact,
@@ -448,6 +449,7 @@ export type QueueHealth = {
 
 export const QUEUE_HEALTH_TELEMETRY_EVENT = 'operations.queue.health' as const;
 export const QUEUE_HEALTH_TELEMETRY_SCHEMA_VERSION = 1 as const;
+const UNOBSERVED_SIGNAL_REPEAT_MS = 5 * 60_000;
 
 export type QueueHealthSignal = {
   readonly schemaVersion: typeof QUEUE_HEALTH_TELEMETRY_SCHEMA_VERSION;
@@ -478,9 +480,10 @@ export type QueueHealthSignal = {
  * Project a durable observation into the one cross-runtime queue signal.
  * Healthy steady state is deliberately silent. Actionable backlog problems
  * repeat on every observation so a log-based monitor cannot resolve while the
- * queue remains unhealthy; persistent adapter absence is emitted once because
- * the dashboard already keeps that configuration state visible. The first
- * healthy observation after a problem emits recovery.
+ * queue remains unhealthy. Persistent adapter absence is repeated on a
+ * five-minute boundary so a log-backed dashboard cannot go blank while an
+ * adapter remains absent. The first healthy observation after a problem emits
+ * recovery.
  */
 export function deriveQueueHealthSignal(input: {
   definition: QueueCatalogEntry;
@@ -500,14 +503,19 @@ export function deriveQueueHealthSignal(input: {
     previousHealth.status !== 'healthy';
   if (health.status === 'healthy' && !recovering) return null;
   // A permanently unavailable adapter is a catalog/configuration finding, not
-  // a one-minute incident. Emit it once; the dashboard keeps the state visible
-  // and a later observation with real evidence emits recovery.
+  // a one-minute incident. Repeat it only when the five-minute bucket changes;
+  // this keeps the state visible without recreating one log per observer tick.
   if (
     health.status === 'unobserved' &&
     previousHealth?.status === 'unobserved' &&
     previousHealth.reason === health.reason
   ) {
-    return null;
+    const previousBucket = Math.floor(
+      (input.previousObservation?.observedAt ?? 0) /
+        UNOBSERVED_SIGNAL_REPEAT_MS,
+    );
+    const currentBucket = Math.floor(now / UNOBSERVED_SIGNAL_REPEAT_MS);
+    if (previousBucket === currentBucket) return null;
   }
   return {
     schemaVersion: QUEUE_HEALTH_TELEMETRY_SCHEMA_VERSION,
@@ -676,3 +684,280 @@ export function deriveQueueHealth(
     ...(worstAgeMs === undefined ? {} : { worstAgeMs, worstAgeRatio: ratio }),
   };
 }
+
+// Legacy v1 snapshot helpers remain exported for the webhook/cron collectors
+// during the v1 -> v2 observability rollout. They are intentionally isolated
+// from the scheduler-neutral v2 contract above.
+export const QUEUE_HEALTH_SCHEMA_VERSION = 1 as const;
+export type QueueHealthAvailability = 'available' | 'unavailable';
+export type QueueHealthFreshness = 'fresh' | 'stale';
+export type QueueHealthLayer =
+  | 'admission'
+  | 'delivery'
+  | 'execution'
+  | 'projection'
+  | 'reconciliation'
+  | 'other';
+export type QueueHealthAttentionReason =
+  | 'source_unavailable'
+  | 'snapshot_stale'
+  | 'blocked_work'
+  | 'dead_letter_work'
+  | 'backlog_aged'
+  | 'backlog_count_inexact'
+  | 'backlog_age_unavailable';
+export type QueueHealthCount = { value: number | null; exact: boolean };
+export type QueueHealthCapacity = { active: number | null; limit: number | null };
+export type QueueHealthSnapshot = {
+  schemaVersion: typeof QUEUE_HEALTH_SCHEMA_VERSION;
+  queueId: string;
+  owner: string;
+  layer: QueueHealthLayer;
+  transport: string;
+  observedAt: number;
+  freshness: { staleAfterMs: number };
+  availability: QueueHealthAvailability;
+  queued: QueueHealthCount;
+  running: QueueHealthCount;
+  retryWaiting: QueueHealthCount;
+  blocked: QueueHealthCount;
+  deadLetter: QueueHealthCount;
+  oldestQueuedAgeMs: number | null;
+  oldestBlockedAgeMs: number | null;
+  capacity: QueueHealthCapacity;
+  thresholds: { degradedOldestQueuedAgeMs: number };
+};
+export type QueueHealthSnapshotInput = Omit<
+  QueueHealthSnapshot,
+  'schemaVersion'
+>;
+type LegacyQueueHealthStatus = 'healthy' | 'degraded' | 'blocked' | 'unknown';
+type LegacyQueueHealthAssessment = {
+  status: LegacyQueueHealthStatus;
+  freshness: QueueHealthFreshness;
+  observedAgeMs: number;
+  attentionReasons: readonly QueueHealthAttentionReason[];
+};
+export type QueueHealthAssessment = LegacyQueueHealthAssessment;
+
+const legacyLayers = new Set<QueueHealthLayer>([
+  'admission',
+  'delivery',
+  'execution',
+  'projection',
+  'reconciliation',
+  'other',
+]);
+const legacyCountNames = [
+  'queued',
+  'running',
+  'retryWaiting',
+  'blocked',
+  'deadLetter',
+] as const;
+
+export function parseQueueHealthSnapshot(input: unknown): QueueHealthSnapshot {
+  const record = legacyRecord(input, 'Queue health snapshot');
+  if (record.schemaVersion !== 1)
+    throw new Error('Queue health schemaVersion must be 1.');
+  const layer = legacyString(record.layer, 'layer') as QueueHealthLayer;
+  if (!legacyLayers.has(layer)) throw new Error('Queue health layer is not supported.');
+  const availability = legacyString(
+    record.availability,
+    'availability',
+  ) as QueueHealthAvailability;
+  if (availability !== 'available' && availability !== 'unavailable')
+    throw new Error('Queue health availability must be available or unavailable.');
+  const freshness = legacyRecord(record.freshness, 'freshness');
+  const capacity = legacyRecord(record.capacity, 'capacity');
+  const thresholds = legacyRecord(record.thresholds, 'thresholds');
+  const snapshot: QueueHealthSnapshot = {
+    schemaVersion: 1,
+    queueId: legacyIdentifier(record.queueId, 'queueId'),
+    owner: legacyIdentifier(record.owner, 'owner'),
+    layer,
+    transport: legacyIdentifier(record.transport, 'transport'),
+    observedAt: legacyNumber(record.observedAt, 'observedAt'),
+    freshness: { staleAfterMs: legacyPositive(freshness.staleAfterMs, 'freshness.staleAfterMs') },
+    availability,
+    queued: legacyCount(record.queued, 'queued'),
+    running: legacyCount(record.running, 'running'),
+    retryWaiting: legacyCount(record.retryWaiting, 'retryWaiting'),
+    blocked: legacyCount(record.blocked, 'blocked'),
+    deadLetter: legacyCount(record.deadLetter, 'deadLetter'),
+    oldestQueuedAgeMs: legacyNullableNumber(record.oldestQueuedAgeMs, 'oldestQueuedAgeMs'),
+    oldestBlockedAgeMs: legacyNullableNumber(record.oldestBlockedAgeMs, 'oldestBlockedAgeMs'),
+    capacity: {
+      active: legacyNullableNumber(capacity.active, 'capacity.active'),
+      limit: legacyNullableNumber(capacity.limit, 'capacity.limit'),
+    },
+    thresholds: {
+      degradedOldestQueuedAgeMs: legacyPositive(
+        thresholds.degradedOldestQueuedAgeMs,
+        'thresholds.degradedOldestQueuedAgeMs',
+      ),
+    },
+  };
+  if (snapshot.availability === 'unavailable') {
+    for (const name of legacyCountNames) {
+      const count = snapshot[name];
+      if (count.value !== null || count.exact)
+        throw new Error(`Queue health ${name} must be unknown when availability is unavailable.`);
+    }
+    if (snapshot.oldestQueuedAgeMs !== null || snapshot.oldestBlockedAgeMs !== null)
+      throw new Error('Queue health oldestQueuedAgeMs must be null when availability is unavailable.');
+  }
+  if (
+    snapshot.queued.exact &&
+    snapshot.queued.value === 0 &&
+    snapshot.retryWaiting.exact &&
+    snapshot.retryWaiting.value === 0 &&
+    snapshot.oldestQueuedAgeMs !== null
+  ) {
+    throw new Error('Queue health oldestQueuedAgeMs requires queued or retry-waiting work.');
+  }
+  if (
+    snapshot.blocked.exact &&
+    snapshot.blocked.value === 0 &&
+    snapshot.deadLetter.exact &&
+    snapshot.deadLetter.value === 0 &&
+    snapshot.oldestBlockedAgeMs !== null
+  ) {
+    throw new Error('Queue health oldestBlockedAgeMs requires blocked or dead-letter work.');
+  }
+  return snapshot;
+}
+
+export function createQueueHealthSnapshot(
+  input: QueueHealthSnapshotInput,
+): QueueHealthSnapshot {
+  return parseQueueHealthSnapshot({ ...input, schemaVersion: 1 });
+}
+
+export function assessQueueHealth(
+  input: QueueHealthSnapshot,
+  now = Date.now(),
+): LegacyQueueHealthAssessment {
+  const snapshot = parseQueueHealthSnapshot(input);
+  const observedAgeMs = Math.max(0, now - snapshot.observedAt);
+  const freshness: QueueHealthFreshness =
+    observedAgeMs > snapshot.freshness.staleAfterMs ? 'stale' : 'fresh';
+  if (snapshot.availability === 'unavailable')
+    return { status: 'unknown', freshness, observedAgeMs, attentionReasons: ['source_unavailable'] };
+  if (freshness === 'stale')
+    return { status: 'unknown', freshness, observedAgeMs, attentionReasons: ['snapshot_stale'] };
+  const attentionReasons: QueueHealthAttentionReason[] = [];
+  if (knownItems(snapshot.blocked)) attentionReasons.push('blocked_work');
+  if (knownItems(snapshot.deadLetter)) attentionReasons.push('dead_letter_work');
+  if (attentionReasons.length)
+    return { status: 'blocked', freshness, observedAgeMs, attentionReasons };
+  if (
+    snapshot.oldestQueuedAgeMs !== null &&
+    snapshot.oldestQueuedAgeMs >= snapshot.thresholds.degradedOldestQueuedAgeMs
+  )
+    return { status: 'degraded', freshness, observedAgeMs, attentionReasons: ['backlog_aged'] };
+  if (
+    !snapshot.queued.exact ||
+    !snapshot.retryWaiting.exact ||
+    !snapshot.blocked.exact ||
+    !snapshot.deadLetter.exact
+  )
+    return { status: 'unknown', freshness, observedAgeMs, attentionReasons: ['backlog_count_inexact'] };
+  if (
+    (knownItems(snapshot.queued) || knownItems(snapshot.retryWaiting)) &&
+    snapshot.oldestQueuedAgeMs === null
+  )
+    return { status: 'unknown', freshness, observedAgeMs, attentionReasons: ['backlog_age_unavailable'] };
+  return { status: 'healthy', freshness, observedAgeMs, attentionReasons: [] };
+}
+
+export function queueHealthTelemetryFields(
+  input: QueueHealthSnapshot,
+  assessment = assessQueueHealth(input),
+): TelemetryFields {
+  const snapshot = parseQueueHealthSnapshot(input);
+  return {
+    queueHealthSchemaVersion: snapshot.schemaVersion,
+    queueId: snapshot.queueId,
+    queueOwner: snapshot.owner,
+    queueLayer: snapshot.layer,
+    queueTransport: snapshot.transport,
+    queueAvailability: snapshot.availability,
+    queueObservedAt: snapshot.observedAt,
+    queueFreshnessStaleAfterMs: snapshot.freshness.staleAfterMs,
+    queueFreshness: assessment.freshness,
+    queueHealth: assessment.status,
+    queueHealthObservedAgeMs: assessment.observedAgeMs,
+    queueQueued: snapshot.queued.value,
+    queueQueuedExact: snapshot.queued.exact,
+    queueRunning: snapshot.running.value,
+    queueRunningExact: snapshot.running.exact,
+    queueRetryWaiting: snapshot.retryWaiting.value,
+    queueRetryWaitingExact: snapshot.retryWaiting.exact,
+    queueBlocked: snapshot.blocked.value,
+    queueBlockedExact: snapshot.blocked.exact,
+    queueDeadLetter: snapshot.deadLetter.value,
+    queueDeadLetterExact: snapshot.deadLetter.exact,
+    queueOldestQueuedAgeMs: snapshot.oldestQueuedAgeMs,
+    queueOldestBlockedAgeMs: snapshot.oldestBlockedAgeMs,
+    queueCapacityActive: snapshot.capacity.active,
+    queueCapacityLimit: snapshot.capacity.limit,
+    queueDegradedOldestQueuedAgeMs: snapshot.thresholds.degradedOldestQueuedAgeMs,
+    queueAttentionReasons: assessment.attentionReasons,
+  };
+}
+
+export async function emitQueueHealthSnapshot(input: {
+  telemetry: Pick<Telemetry, 'info' | 'warn'>;
+  snapshot: QueueHealthSnapshot;
+  now?: number;
+}): Promise<LegacyQueueHealthAssessment> {
+  const assessment = assessQueueHealth(input.snapshot, input.now);
+  const fields = queueHealthTelemetryFields(input.snapshot, assessment);
+  await input.telemetry.info('queue.health.snapshot', fields);
+  if (assessment.status !== 'healthy')
+    await input.telemetry.warn('queue.health.attention', fields);
+  return assessment;
+}
+
+function legacyRecord(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value))
+    throw new Error(`${label} must be an object.`);
+  return value as Record<string, unknown>;
+}
+function legacyString(value: unknown, label: string): string {
+  if (typeof value !== 'string' || !value.trim())
+    throw new Error(`Queue health ${label} must be a non-empty string.`);
+  return value.trim();
+}
+function legacyIdentifier(value: unknown, label: string): string {
+  const result = legacyString(value, label);
+  if (result.length > 96 || !/^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/.test(result))
+    throw new Error(`Queue health ${label} must be a stable low-cardinality identifier.`);
+  return result;
+}
+function legacyNumber(value: unknown, label: string): number {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0)
+    throw new Error(`Queue health ${label} must be a finite non-negative number.`);
+  return value;
+}
+function legacyPositive(value: unknown, label: string): number {
+  const result = legacyNumber(value, label);
+  if (result === 0) throw new Error(`Queue health ${label} must be positive.`);
+  return result;
+}
+function legacyNullableNumber(value: unknown, label: string): number | null {
+  return value === null ? null : legacyNumber(value, label);
+}
+function legacyCount(value: unknown, label: string): QueueHealthCount {
+  const record = legacyRecord(value, label);
+  if (typeof record.exact !== 'boolean')
+    throw new Error(`Queue health ${label}.exact must be a boolean.`);
+  const count = legacyNullableNumber(record.value, `${label}.value`);
+  if (count === null && record.exact)
+    throw new Error(`Queue health ${label}.exact cannot be true when value is unknown.`);
+  return { value: count, exact: record.exact };
+}
+function knownItems(count: QueueHealthCount): boolean {
+  return count.value !== null && count.value > 0;
+}