mixdog 0.9.2 → 0.9.4

package/src/runtime/agent/orchestrator/providers/openai-ws.mjs

@@ -15,6 +15,7 @@
 import { sendViaWebSocket } from './openai-oauth-ws.mjs';
 import { buildRequestBody } from './openai-oauth.mjs';
 import { enrichModels } from './model-catalog.mjs';
+import { sanitizeModelList } from './model-list-sanitize.mjs';
 import {
     resolveProviderCacheKey,
     resolveProviderPromptCacheLane,
@@ -143,7 +144,7 @@ export class OpenAIDirectProvider {
                 // cutoff) can drop deprecated generations.
                 created: typeof m.created === 'number' ? m.created : null,
             }));
-            return await enrichModels(models);
+            return sanitizeModelList(await enrichModels(models), { provider: 'openai' });
         } catch {
             return [];
         }

package/src/runtime/agent/orchestrator/providers/opencode-go-usage.mjs

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { updateJsonAtomicSync } from '../../../shared/atomic-file.mjs';
 import { resolvePluginData } from '../../../shared/plugin-paths.mjs';
 import { getOpenCodeGoAuthCookie } from '../../../shared/config.mjs';
+import { round, cleanString as clean } from './lib/usage-primitives.mjs';
 
 const CACHE_FILE = 'opencode-go-usage-cache.json';
 const LIVE_TTL_MS = 5 * 60_000;
@@ -18,23 +19,14 @@ const LIMITS_USD = Object.freeze({
 const DISK_JSON_MEMORY_TTL_MS = 1000;
 let diskJsonCache = { at: 0, file: '', value: null };
 
+// Local unguarded `num`: this module intentionally coerces '' to 0 via
+// Number(''), unlike the guarded shared num() in lib/usage-primitives.mjs.
+// Behavior differs on empty-string input, so it stays local.
 function num(value, fallback = null) {
   const n = Number(value);
   return Number.isFinite(n) ? n : fallback;
 }
 
-function round(value, digits = 4) {
-  const n = Number(value);
-  if (!Number.isFinite(n)) return null;
-  const scale = 10 ** digits;
-  return Math.round(n * scale) / scale;
-}
-
-function clean(value) {
-  const text = typeof value === 'string' ? value.trim() : '';
-  return text || null;
-}
-
 function cachePath() {
   return join(resolvePluginData(), CACHE_FILE);
 }
@@ -249,7 +241,41 @@ export function openCodeGoUsageConfigStatus(config = {}) {
   };
 }
 
+// Primary discovery: GET /auth with the auth cookie, follow-manual. The
+// console redirects authenticated sessions straight to /workspace/{id};
+// unauthenticated/invalid cookies redirect to /auth/authorize instead.
+// This avoids depending on the hashed server-fn id used by the /_server
+// probe (WORKSPACES_SERVER_ID), which can change across console deploys.
+async function fetchWorkspaceIdFromAuthRedirect(authCookie, { signal } = {}) {
+  let res;
+  try {
+    res = await fetch(`${BASE_URL}/auth`, {
+      signal,
+      redirect: 'manual',
+      headers: requestHeaders(authCookie),
+    });
+  } catch {
+    return null; // network/redirect-mode quirk: let the _server fallback decide
+  }
+  if (res.status === 401 || res.status === 403) {
+    const err = new Error('OpenCode Go console auth failed');
+    err.code = 'OPENCODE_GO_USAGE_AUTH_FAILED';
+    throw err;
+  }
+  const location = res.headers.get('location') || '';
+  if (!location) return null;
+  if (/(?:^|\/|\.\/)auth\/authorize\b/.test(location)) {
+    const err = new Error('OpenCode Go console auth failed');
+    err.code = 'OPENCODE_GO_USAGE_AUTH_FAILED';
+    throw err;
+  }
+  const workspaceMatch = location.match(/\/workspace\/(wrk_[a-zA-Z0-9]+)/);
+  return normalizeWorkspaceId(workspaceMatch ? workspaceMatch[1] : location);
+}
+
 async function fetchWorkspaceId(authCookie, { signal } = {}) {
+  const fromRedirect = await fetchWorkspaceIdFromAuthRedirect(authCookie, { signal });
+  if (fromRedirect) return fromRedirect;
   const url = new URL(`${BASE_URL}/_server`);
   url.searchParams.set('id', WORKSPACES_SERVER_ID);
   const res = await fetch(url, {

package/src/runtime/agent/orchestrator/providers/retry-classifier.mjs

@@ -232,12 +232,11 @@ export function jitterDelayMs(ms, ratio = PROVIDER_RETRY_JITTER_RATIO, mode = 's
 }
 
 // ── Shared network-resilience interface ──────────────────────────────────────
-// One home for the logic that used to be copied per provider: mid-stream
-// classifier (WS + SSE), transport fallback predicate, stream-safety stamp
-// latches, abort-aware sleep, handshake classifier, and the retry-budget table.
-// Provider differences are passed as ARGUMENTS (policy objects), never branched
-// on a hardcoded provider name. Behavior is preserved EXACTLY — each path below
-// is the relocated original, selected by policy.mode.
+// One home for the logic shared across providers: mid-stream classifier
+// (WS + SSE), transport fallback predicate, stream-safety stamp latches,
+// abort-aware sleep, handshake classifier, and the retry-budget table.
+// Provider differences are passed as ARGUMENTS (policy objects), never
+// branched on a hardcoded provider name.
 
 // F) Retry-budget profiles as DATA. The numbers live ONLY here now.
 //    ws.transientCloseRetries (4) — ws_1006 / ws_1011 connection-loss buckets.
@@ -260,8 +259,8 @@ function _midstreamLimitFor(classifier, policy) {
   return policy.defaultRetries
 }
 
-// WS gates each classifier against its own budget (mirrors the old
-// _allowMidstreamRetry). SSE applies a single top-of-function budget gate and
+// WS gates each classifier against its own budget. SSE applies a single
+// top-of-function budget gate and
 // then returns raw classifier strings, so perClassifierGate:false returns the
 // classifier unconditionally here.
 function _allowMidstream(classifier, attemptIndex, policy) {

package/src/runtime/agent/orchestrator/session/compact/budget.mjs

@@ -0,0 +1,288 @@
+// Budget math, tool-output pruning, cycle1 draining, and preserved-fact
+// extraction. Extracted verbatim from compact.mjs (behavior-preserving).
+import { createHash } from 'node:crypto';
+import {
+    sanitizeToolPairs,
+    dedupToolResultBodies,
+    reconcileDedupStubs,
+    estimateMessagesTokens,
+    DEFAULT_COMPACTION_KEEP_TOKENS,
+} from '../context-utils.mjs';
+import { extractText, summarizeToolCall, redactRawSecretString, TOOL_CALL_FACT_ARGS_MAX_CHARS } from './text-utils.mjs';
+
+// Floor for the reserve-adjusted compact budget. When the tool-schema/request
+// reserve rivals the whole budget (huge agent tool surfaces), subtracting the
+// full reserve could leave a degenerate target; keep enough room to attempt a
+// summary and let the final fit check decide. Logged as degraded because a
+// floored budget can still overflow on the next send.
+const MIN_EFFECTIVE_COMPACT_BUDGET_TOKENS = 1024;
+export function effectiveBudget(budgetTokens, opts) {
+    if (!(budgetTokens > 0)) throw new Error('compact: budgetTokens must be > 0');
+    const reserve = Number(opts?.reserveTokens) || 0;
+    if (reserve <= 0) return budgetTokens;
+    // Subtract the FULL reserve so an accepted compact actually fits next to
+    // the request reserve on the following send. The previous 50%-of-budget cap
+    // under-reserved large tool surfaces (agent sessions): a compact could be
+    // "accepted" at budget/2 while the true remaining room was smaller, then
+    // overflow immediately on the next request.
+    const remaining = budgetTokens - reserve;
+    if (remaining >= MIN_EFFECTIVE_COMPACT_BUDGET_TOKENS) return remaining;
+    const floored = Math.max(1, Math.min(budgetTokens, MIN_EFFECTIVE_COMPACT_BUDGET_TOKENS));
+    try { process.stderr.write(`[compact] degraded budget: reserve=${reserve} leaves ${remaining} of budget=${budgetTokens}; flooring to ${floored}\n`); } catch { /* best-effort */ }
+    return floored;
+}
+
+const PRUNE_TOOL_OUTPUT_MAX_CHARS = 2_000;
+const PRUNE_TOOL_OUTPUT_HEAD_CHARS = 1_000;
+const PRUNE_TOOL_OUTPUT_TAIL_CHARS = 600;
+const PRUNE_TAIL_TURNS = 2;
+export const MIN_PRESERVE_RECENT_TOKENS = 2_000;
+export const PRESERVED_FACTS_MAX_CHARS = 600;
+
+// Count raw (unchunked) pending rows still present in a dump_session_roots
+// payload. recall-fasttrack must keep cycle1-chunking until this reaches 0 so
+// the injected root is the chunked summary, not the raw transcript tail.
+export function countRawPendingRows(dumpText) {
+    const text = String(dumpText || '');
+    const matches = text.match(/(?:^|\n)# raw_pending\s+\d+\s+id=/gi);
+    return matches ? matches.length : 0;
+}
+
+// Drain a single session's cycle1 in fixed window×concurrency units, looping
+// until no raw rows remain (or a pass stops making progress / the deadline
+// elapses). This replaces the previous single-pass cycle1 so large sessions
+// get fully chunked before their root is injected into the compacted context.
+export async function drainSessionCycle1(runTool, { sessionId, cycleArgs = {}, dumpArgs, maxPasses = 0, deadlineMs = 0 } = {}) {
+    if (typeof runTool !== 'function') throw new Error('drainSessionCycle1: runTool is required');
+    if (!sessionId) throw new Error('drainSessionCycle1: sessionId is required');
+    if (!dumpArgs) throw new Error('drainSessionCycle1: dumpArgs is required');
+    const startedAt = Date.now();
+    const hardPasses = Math.max(1, Number(maxPasses) || 50);
+    const lines = [];
+    let cycle1Error = null;
+    let recallText = await runTool('memory', dumpArgs);
+    let rawRemaining = countRawPendingRows(recallText);
+    let pass = 0;
+    while (rawRemaining > 0 && pass < hardPasses) {
+        if (deadlineMs > 0 && (Date.now() - startedAt) >= deadlineMs) break;
+        pass += 1;
+        const passDeadline = deadlineMs > 0
+            ? Math.max(1, deadlineMs - (Date.now() - startedAt))
+            : 0;
+        let passText = '';
+        try {
+            passText = await runTool('memory', {
+                action: 'cycle1',
+                sessionId,
+                ...cycleArgs,
+                ...(passDeadline > 0 ? { _callerDeadlineMs: passDeadline } : {}),
+            });
+        } catch (err) {
+            cycle1Error = err?.message ? String(err.message) : String(err);
+            lines.push(`cycle1 pass=${pass} error=${cycle1Error}`);
+            break;
+        }
+        if (passText) lines.push(`cycle1 pass=${pass}: ${String(passText).trim()}`);
+        recallText = await runTool('memory', dumpArgs);
+        const nextRaw = countRawPendingRows(recallText);
+        // No forward progress (raw not shrinking) — stop instead of spinning.
+        if (nextRaw >= rawRemaining) {
+            rawRemaining = nextRaw;
+            break;
+        }
+        rawRemaining = nextRaw;
+    }
+    return {
+        recallText,
+        cycle1Text: lines.join('\n'),
+        passes: pass,
+        rawRemaining,
+        error: cycle1Error,
+    };
+}
+
+function preservedFactHints() {
+    return String(process.env.MIXDOG_COMPACT_FACT_HINTS || '')
+        .split(/[\n,;]+/u)
+        .map(s => s.trim())
+        .filter(Boolean)
+        .map(s => s.toLocaleLowerCase());
+}
+
+const PRESERVED_FACT_HINTS = preservedFactHints();
+
+function hasConfiguredPreservedFactHint(text) {
+    const lower = String(text || '').toLocaleLowerCase();
+    return PRESERVED_FACT_HINTS.some(hint => hint && lower.includes(hint));
+}
+
+export function extractPreservedFacts(messages) {
+    if (!messages || messages.length === 0) return '';
+    const candidates = [];
+    const seenSignatures = new Set();
+    const add = (prefix, text, score, messageIndex, lineIndex = 0) => {
+        const clean = text.replace(/`/g, '').trim();
+        if (clean.length < 10) return;
+        const sig = clean.slice(0, 80).toLowerCase().replace(/\s+/g, ' ');
+        if (seenSignatures.has(sig)) return;
+        seenSignatures.add(sig);
+        candidates.push({ prefix, text: clean, score, messageIndex, lineIndex });
+    };
+    const classifyLine = (t) => {
+        // Language-neutral structural cues: exact assignments, paths, URLs,
+        // symbolic error/constant identifiers, and optional user-configured
+        // locale/domain hints. Do not bake human-language keyword lists here.
+        if (/[\p{L}\p{N}_$./:-]{2,}\s*=\s*\S+/u.test(t)) return { prefix: '•', score: 100 };
+        if (/(?:^|[\s('"`])https?:\/\/[^\s'"`<>]+/iu.test(t)) return { prefix: '•', score: 95 };
+        if (/(?:^|[\s('"`])(?:[A-Za-z]:[\\/]|\.{1,2}[\\/]|~?[\\/][^\s'"`<>]+|[\p{L}\p{N}_$.-]+[\\/][^\s'"`<>]+|[\p{L}\p{N}_$.-]+\.(?:mjs|cjs|js|jsx|ts|tsx|json|md|rs|go|py|java|kt|cs|cpp|c|h|hpp|css|html|yml|yaml|toml|lock|sh|ps1)\b)/iu.test(t)) return { prefix: '•', score: 95 };
+        if (/\b[A-Z][A-Z0-9_:-]{2,}\b/.test(t)) return { prefix: '•', score: 90 };
+        if (hasConfiguredPreservedFactHint(t)) return { prefix: '!', score: 70 };
+        return null;
+    };
+    for (let mi = 0; mi < messages.length; mi += 1) {
+        const m = messages[mi];
+        const text = extractText(m);
+        if (!text) continue;
+        const lines = text.split('\n');
+        for (let li = 0; li < lines.length; li += 1) {
+            const line = lines[li];
+            const t = line.trim();
+            if (t.length < 10 || t.length > 250) continue;
+            const cls = classifyLine(t);
+            if (cls) add(cls.prefix, redactRawSecretString(t), cls.score, mi, li);
+        }
+        if (m?.role === 'assistant' && Array.isArray(m.toolCalls)) {
+            for (const tc of m.toolCalls) {
+                const name = tc?.function?.name || tc?.name || '';
+                if (name) {
+                    const summary = summarizeToolCall(tc, TOOL_CALL_FACT_ARGS_MAX_CHARS);
+                    const sig = `tool:${summary.slice(0, 160).toLowerCase()}`;
+                    if (seenSignatures.has(sig)) continue;
+                    seenSignatures.add(sig);
+                    candidates.push({ prefix: '•', text: `Tool: ${summary}`, score: 50, messageIndex: mi, lineIndex: Number.MAX_SAFE_INTEGER });
+                }
+            }
+        }
+    }
+    if (candidates.length === 0) return '';
+    candidates.sort((a, b) =>
+        (b.score - a.score)
+        || (b.messageIndex - a.messageIndex)
+        || (b.lineIndex - a.lineIndex)
+    );
+    let result = '## Preserved Facts\n';
+    let kept = 0;
+    for (const c of candidates) {
+        if (kept >= 25) break;
+        let line = `- ${c.prefix} ${c.text}\n`;
+        if (result.length + line.length > PRESERVED_FACTS_MAX_CHARS) {
+            const room = PRESERVED_FACTS_MAX_CHARS - result.length - 8;
+            if (kept === 0 && room > 32) line = `- ${c.prefix} ${c.text.slice(0, room)}…\n`;
+            else continue;
+        }
+        result += line;
+        kept += 1;
+    }
+    return kept > 0 ? result : '';
+}
+
+function protectedTailStart(messages, tailTurns = PRUNE_TAIL_TURNS) {
+    let seenUsers = 0;
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        if (messages[i]?.role !== 'user') continue;
+        seenUsers += 1;
+        if (seenUsers >= tailTurns) return i;
+    }
+    return 0;
+}
+
+function pruneToolOutputText(text, maxChars, toolCallId) {
+    const value = String(text ?? '').replace(/\r\n/g, '\n');
+    if (value.length <= maxChars) return value;
+    const hash = createHash('sha256').update(value).digest('hex').slice(0, 16);
+    const head = value.slice(0, PRUNE_TOOL_OUTPUT_HEAD_CHARS);
+    const tail = value.slice(-PRUNE_TOOL_OUTPUT_TAIL_CHARS);
+    return [
+        `[mixdog pruned old tool output: ${value.length} chars, sha256:${hash}${toolCallId ? `, tool_use_id=${toolCallId}` : ''}]`,
+        head,
+        '... [old tool output omitted during worker compaction] ...',
+        tail,
+    ].join('\n');
+}
+
+export function pruneToolOutputs(messages, budgetTokens, opts = {}) {
+    const budget = effectiveBudget(budgetTokens, opts);
+    let result = reconcileDedupStubs(dedupToolResultBodies(sanitizeToolPairs(messages)));
+    if (estimateMessagesTokens(result) <= budget) return result;
+
+    const maxChars = Math.max(256, Number(opts?.maxToolOutputChars) || PRUNE_TOOL_OUTPUT_MAX_CHARS);
+    const protectFrom = protectedTailStart(result, Number(opts?.tailTurns) || PRUNE_TAIL_TURNS);
+    const candidates = [];
+    for (let i = 0; i < protectFrom; i += 1) {
+        const m = result[i];
+        if (m?.role !== 'tool' || typeof m.content !== 'string') continue;
+        if (m.content.length <= maxChars) continue;
+        candidates.push({ index: i, length: m.content.length });
+    }
+    candidates.sort((a, b) => b.length - a.length);
+    for (const c of candidates) {
+        const m = result[c.index];
+        result[c.index] = {
+            ...m,
+            content: pruneToolOutputText(m.content, maxChars, m.toolCallId),
+            compacted: true,
+            compactedKind: 'tool_output_prune',
+        };
+        if (estimateMessagesTokens(result) <= budget) break;
+    }
+    return reconcileDedupStubs(result);
+}
+
+// Anchor-independent tool-output prune (loop overflow safety net).
+//
+// pruneToolOutputs protects the most-recent tailTurns of USER-anchored history,
+// so a single-turn transcript with no user boundary yields protectFrom=0 and
+// prunes nothing. This variant needs no user anchor: it middle-truncates the
+// OLDEST oversized tool_result bodies first, walking forward, until the
+// transcript fits the budget. The newest tool_result is truncated last (and
+// only if still necessary) so fresh state is preserved as long as possible.
+// Structure/pairing is preserved (only string content shrinks), and the result
+// is re-reconciled so tool pairing stays provider-valid.
+export function pruneToolOutputsUnanchored(messages, budgetTokens, opts = {}) {
+    const budget = effectiveBudget(budgetTokens, opts);
+    let result = reconcileDedupStubs(dedupToolResultBodies(sanitizeToolPairs(messages)));
+    if (estimateMessagesTokens(result) <= budget) return result;
+
+    const maxChars = Math.max(256, Number(opts?.maxToolOutputChars) || PRUNE_TOOL_OUTPUT_MAX_CHARS);
+    // Oldest -> newest so recent tool output survives longest. No user-turn
+    // protection: every oversized tool_result is a candidate.
+    for (let i = 0; i < result.length; i += 1) {
+        const m = result[i];
+        if (m?.role !== 'tool' || typeof m.content !== 'string') continue;
+        if (m.content.length <= maxChars) continue;
+        result[i] = {
+            ...m,
+            content: pruneToolOutputText(m.content, maxChars, m.toolCallId),
+            compacted: true,
+            compactedKind: 'tool_output_prune',
+        };
+        if (estimateMessagesTokens(result) <= budget) break;
+    }
+    return reconcileDedupStubs(result);
+}
+
+export function preserveRecentBudget(budget, opts = {}) {
+    const maxForBudget = Math.max(1, Math.floor(Number(budget || 0) * 0.8));
+    const explicit = Number(opts.preserveRecentTokens ?? opts.keepTokens);
+    if (Number.isFinite(explicit) && explicit > 0) {
+        return Math.max(1, Math.min(Math.floor(explicit), maxForBudget));
+    }
+    return Math.max(
+        1,
+        Math.min(
+            DEFAULT_COMPACTION_KEEP_TOKENS,
+            Math.max(MIN_PRESERVE_RECENT_TOKENS, Math.floor(budget * 0.25)),
+            maxForBudget,
+        ),
+    );
+}

package/src/runtime/agent/orchestrator/session/compact/constants.mjs

@@ -0,0 +1,85 @@
+// Shared compaction constants and compact-type helpers. Extracted verbatim
+// from compact.mjs (behavior-preserving). compact.mjs re-exports the public
+// members from here so the external surface is unchanged.
+import {
+    DEFAULT_COMPACTION_BUFFER_TOKENS,
+    DEFAULT_COMPACTION_BUFFER_RATIO,
+    MAX_COMPACTION_BUFFER_RATIO,
+    DEFAULT_COMPACTION_KEEP_TOKENS,
+    normalizeCompactionBufferRatio,
+    compactionBufferTokensForBoundary,
+} from '../context-utils.mjs';
+
+export {
+    DEFAULT_COMPACTION_BUFFER_TOKENS,
+    DEFAULT_COMPACTION_BUFFER_RATIO,
+    MAX_COMPACTION_BUFFER_RATIO,
+    DEFAULT_COMPACTION_KEEP_TOKENS,
+    normalizeCompactionBufferRatio,
+    compactionBufferTokensForBoundary,
+};
+
+export const SUMMARY_PREFIX = 'A previous model worked on this task and produced the compacted handoff summary below. Build on the work already done and avoid duplicating it; treat the summary as authoritative context for continuing the task. You also retain the preserved recent turns that follow.';
+export const SUMMARY_OUTPUT_TOKENS = 4_096;
+// Unified context-share rule: every derived "how much of the model context
+// may this budget take" ratio uses ONE number — 5%. Consumers:
+//   - compact target budget (loop/compact-policy.mjs COMPACT_TARGET_RATIO)
+//   - recall-fasttrack injection cap (loop.mjs recallTokenCap)
+// Keep them in lockstep; do not fork per-consumer ratios without a decision.
+export const CONTEXT_SHARE_RATIO = 0.05;
+// Floor for the recall-injection cap so small-context models still get a
+// usable recall slice (cap = max(floor, contextWindow * CONTEXT_SHARE_RATIO)).
+export const RECALL_TOKEN_CAP_FLOOR_TOKENS = 2_048;
+// Minimum room the generated summary needs after the mandatory (system +
+// preserved tail) cost is accounted for. When the configured target budget is
+// smaller than the mandatory cost (e.g. the preserved recent turn carries a
+// large tool result), the compaction MUST still proceed: the old head is the
+// part being summarized away, so dropping it already shrinks the transcript.
+// Refusing with "exceeds budget" here is what surfaced as auto-clear / overflow
+// compact failures. Floor the working budget to mandatory + this room instead.
+export const COMPACT_SUMMARY_MIN_ROOM_TOKENS = 4_000;
+
+export const COMPACT_TYPE_SEMANTIC = 'semantic';
+export const COMPACT_TYPE_RECALL_FASTTRACK = 'recall-fasttrack';
+export const DEFAULT_COMPACT_TYPE = COMPACT_TYPE_SEMANTIC;
+export const COMPACT_TYPES = Object.freeze([
+    COMPACT_TYPE_SEMANTIC,
+    COMPACT_TYPE_RECALL_FASTTRACK,
+]);
+
+export function normalizeCompactType(value, fallback = DEFAULT_COMPACT_TYPE) {
+    const raw = String(value ?? '').trim().toLowerCase().replace(/_/g, '-');
+    if (!raw) return fallback;
+    if (raw === '1' || raw === 'type1' || raw === 'type-1' || raw === 'bench1' || raw === 'bench-1' || raw === 'semantic' || raw === 'summary') {
+        return COMPACT_TYPE_SEMANTIC;
+    }
+    // Recall fast-track aliases. `replace(/_/g,'-')` above already folds
+    // snake_case (fast_track -> fast-track), but list both dash/no-dash forms
+    // explicitly so callers passing either spelling resolve deterministically.
+    if (raw === '2' || raw === 'type2' || raw === 'type-2' || raw === 'recall' || raw === 'recall-fast' || raw === 'recall-fasttrack' || raw === 'recall-fast-track' || raw === 'fasttrack' || raw === 'fast-track') {
+        return COMPACT_TYPE_RECALL_FASTTRACK;
+    }
+    // Unknown / unrecognized value: fall back to the caller-provided default
+    // (semantic by default). Callers that need to detect an unknown value
+    // should compare the input against COMPACT_TYPES before normalizing.
+    return fallback;
+}
+
+export function compactTypeIsSemantic(value) {
+    return normalizeCompactType(value) === COMPACT_TYPE_SEMANTIC;
+}
+
+export function compactTypeIsRecallFastTrack(value) {
+    return normalizeCompactType(value) === COMPACT_TYPE_RECALL_FASTTRACK;
+}
+
+export function compactDebugEnabled() {
+    return String(process.env.MIXDOG_COMPACT_DEBUG || '').trim() === '1';
+}
+
+export function compactDebugLog(scope, details = {}) {
+    if (!compactDebugEnabled()) return;
+    try {
+        process.stderr.write(`[compact] ${scope} ${JSON.stringify(details)}\n`);
+    } catch { /* best-effort diagnostics only */ }
+}