patina-cli 3.11.0 → 4.0.0

package/src/providers.js

@@ -1,15 +1,24 @@
+// @ts-check
 // Provider presets: shortcuts for common OpenAI-compatible endpoints.
 // Each provider maps to a base URL + a recommended default model + the env
 // variable users typically set to authenticate. Selecting a provider is
 // equivalent to manually setting --base-url, --model, and the right key.
 import { inputError } from './errors.js';
+import { DEFAULT_BEST_MODELS } from './model-defaults.js';
 
+/**
+ * Built-in OpenAI-compatible provider presets.
+ *
+ * @type {Record<string, {name: string, baseURL: string, apiKeyEnv: string, defaultModel: string, freeTier: boolean, note: string}>}
+ * @example
+ * const openaiBaseURL = PROVIDERS.openai.baseURL;
+ */
 export const PROVIDERS = {
   openai: {
     name: 'openai',
     baseURL: 'https://api.openai.com/v1',
     apiKeyEnv: 'OPENAI_API_KEY',
-    defaultModel: 'gpt-4o',
+    defaultModel: DEFAULT_BEST_MODELS.openai,
     freeTier: false,
     note: 'Paid. Default OpenAI Platform API.',
   },
@@ -17,7 +26,7 @@ export const PROVIDERS = {
     name: 'gemini',
     baseURL: 'https://generativelanguage.googleapis.com/v1beta/openai',
     apiKeyEnv: 'GEMINI_API_KEY',
-    defaultModel: 'gemini-1.5-flash',
+    defaultModel: DEFAULT_BEST_MODELS.geminiCli,
     freeTier: true,
     note: 'Free tier available. Get a key at https://aistudio.google.com/app/apikey',
   },
@@ -29,6 +38,22 @@ export const PROVIDERS = {
     freeTier: true,
     note: 'Free tier with rate limits. Get a key at https://console.groq.com/keys',
   },
+  kimi: {
+    name: 'kimi',
+    baseURL: 'https://api.moonshot.ai/v1',
+    apiKeyEnv: 'KIMI_API_KEY',
+    defaultModel: 'kimi-k2.5',
+    freeTier: false,
+    note: 'Moonshot AI Kimi OpenAI-compatible API. Set KIMI_API_KEY or PATINA_API_KEY.',
+  },
+  moonshot: {
+    name: 'moonshot',
+    baseURL: 'https://api.moonshot.ai/v1',
+    apiKeyEnv: 'MOONSHOT_API_KEY',
+    defaultModel: 'kimi-k2.5',
+    freeTier: false,
+    note: 'Moonshot AI Kimi OpenAI-compatible API. Set MOONSHOT_API_KEY or PATINA_API_KEY.',
+  },
   together: {
     name: 'together',
     baseURL: 'https://api.together.xyz/v1',
@@ -39,6 +64,15 @@ export const PROVIDERS = {
   },
 };
 
+/**
+ * Resolve a provider preset by name.
+ *
+ * @param {string|null|undefined} name Provider name; falsy returns null.
+ * @returns {object|null} Provider preset or null.
+ * @throws {PatinaCliError} When name is unknown.
+ * @example
+ * const provider = selectProvider('openai');
+ */
 export function selectProvider(name) {
   if (!name) return null;
   const provider = PROVIDERS[name];
@@ -46,12 +80,25 @@ export function selectProvider(name) {
     throw inputError(
       `Unknown provider: ${name}`,
       `Available providers are: ${Object.keys(PROVIDERS).join(', ')}.`,
-      'Run `patina --list-providers` to inspect provider presets.'
+      'Run `patina --help` to see provider presets.'
     );
   }
   return provider;
 }
 
+/**
+ * Resolve effective API key, base URL, and model from explicit values, provider, and env.
+ *
+ * @param {object} options Provider resolution inputs.
+ * @param {object|null} [options.provider] Provider preset from {@link selectProvider}.
+ * @param {string} [options.apiKey] Explicit API key.
+ * @param {string} [options.baseURL] Explicit base URL.
+ * @param {string} [options.model] Explicit model id.
+ * @returns {{apiKey: string|null, baseURL: string, model: string, apiKeySource: string|null, baseURLSource: string|null, modelSource: string|null}} Resolved provider config.
+ * @throws {Error} Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+ * @example
+ * const resolved = resolveProviderConfig({ provider: selectProvider('openai') });
+ */
 export function resolveProviderConfig({ provider, apiKey, baseURL, model }) {
   // Explicit args win. Then provider preset. Then PATINA_* env vars.
   // Returns the resolved { apiKey, baseURL, model } and the source for each
@@ -92,7 +139,7 @@ export function resolveProviderConfig({ provider, apiKey, baseURL, model }) {
     resolved.baseURLSource = process.env.PATINA_API_BASE ? 'env:PATINA_API_BASE' : 'default';
   }
   if (!resolved.model) {
-    resolved.model = process.env.PATINA_MODEL || 'gpt-4o';
+    resolved.model = process.env.PATINA_MODEL || DEFAULT_BEST_MODELS.openai;
     resolved.modelSource = process.env.PATINA_MODEL ? 'env:PATINA_MODEL' : 'default';
   }
 

package/src/scoring.js

@@ -1,10 +1,33 @@
+// @ts-check
 import { callLLM as defaultCallLLM } from './api.js';
 import { getRepoRoot } from './config.js';
 import { analyzeText } from './features/index.js';
+import { summarizeSignalStrength } from './features/signal-strength.js';
 import { createLogger } from './logger.js';
 
+/**
+ * Default maximum delta before deterministic and LLM scores are reconciled upward.
+ *
+ * @type {number}
+ * @example
+ * const threshold = DEFAULT_DETERMINISTIC_DIVERGENCE_THRESHOLD;
+ */
 export const DEFAULT_DETERMINISTIC_DIVERGENCE_THRESHOLD = 20;
 
+/**
+ * Score floor applied when deterministic markup-leakage is detected.
+ *
+ * Model-output leakage (issue #332) is near-proof-grade: a single token that
+ * LLM tooling injects and humans never type. Unlike the stylometric/lexical
+ * signals it is decisive on its own, so any hit short-circuits the deterministic
+ * `overall` into the 'heavily AI' band (>70) regardless of the per-paragraph
+ * hot ratio. It is a floor, not a hard 100, because the surrounding prose may
+ * still be genuinely human and we avoid claiming absolute proof.
+ *
+ * @type {number}
+ */
+export const LEAKAGE_SCORE_FLOOR = 90;
+
 class SchemaError extends Error {
   constructor(message, raw) {
     super(message);
@@ -43,7 +66,8 @@ async function callAndParseJson({
   temperature = 0.1,
   deadline,
   signal,
-  callLLM = defaultCallLLM,
+  timeout,
+  callLLM = /** @type {Function} */ (defaultCallLLM),
   logger = createLogger(),
   now,
   sleep,
@@ -59,6 +83,7 @@ async function callAndParseJson({
       temperature: t,
       deadline,
       signal,
+      timeout,
       now,
       sleep,
     });
@@ -76,6 +101,28 @@ async function callAndParseJson({
   throw lastError;
 }
 
+/**
+ * Score text for AI-likeness using an LLM JSON scorer plus deterministic shadow signals.
+ *
+ * @param {object} options Scoring options.
+ * @param {string} options.text Text to score.
+ * @param {object} options.config Effective patina config.
+ * @param {object[]} options.patterns Loaded pattern packs, retained for scorer compatibility.
+ * @param {string} [options.apiKey] Provider API key.
+ * @param {string} [options.baseURL] Provider base URL.
+ * @param {string} [options.model] Model id.
+ * @param {number} [options.deadline] Absolute epoch-millisecond deadline.
+ * @param {AbortSignal} [options.signal] External cancellation signal.
+ * @param {number} [options.timeout] Per-attempt backend timeout in milliseconds.
+ * @param {Function} [options.callLLM] Injectable LLM implementation.
+ * @param {object} [options.logger] patina logger.
+ * @param {Function} [options.now] Clock returning epoch milliseconds.
+ * @param {Function} [options.sleep] Sleep helper for tests.
+ * @returns {Promise<object>} Score payload with overall, interpretation, llmScore, and deterministicScore.
+ * @throws {Error} When the operation is aborted.
+ * @example
+ * const score = await scoreText({ text: 'Draft', config, patterns, callLLM: async () => '{"categories":{},"overall":20,"interpretation":"mostly human"}' });
+ */
 export async function scoreText({
   text,
   config,
@@ -85,6 +132,7 @@ export async function scoreText({
   model,
   deadline,
   signal,
+  timeout,
   callLLM = defaultCallLLM,
   logger = createLogger(),
   now,
@@ -133,6 +181,7 @@ ${text}
       deadline,
       signal,
       callLLM,
+      timeout,
       logger,
       now,
       sleep,
@@ -153,6 +202,19 @@ ${text}
   }
 }
 
+/**
+ * Compute deterministic stylometry/lexicon AI-likeness signals.
+ *
+ * @param {object} [options] Deterministic scoring options.
+ * @param {string} [options.text] Text to analyze.
+ * @param {object} [options.config={}] Effective config.
+ * @param {string} [options.repoRoot] Repository root for analyzer resources.
+ * @param {Function} [options.analyzer] Analyzer implementation.
+ * @returns {object|null} Deterministic score payload, skipped payload, or null when disabled.
+ * @throws {Error} Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+ * @example
+ * const deterministic = scoreDeterministicSignals({ text: 'Draft', config });
+ */
 export function scoreDeterministicSignals({
   text,
   config = {},
@@ -172,23 +234,37 @@ export function scoreDeterministicSignals({
       skipReason: 'language-disabled',
       paragraphCount: 0,
       hotParagraphs: 0,
+      signalScore: 0,
       bands: emptyDeterministicBands(),
     };
   }
 
   try {
+    const lexiconAllowed = isLexiconEnabledForLanguage(config, lang);
     const result = analyzer(String(text || ''), {
       lang,
       repoRoot,
       burstinessBands: config.stylometry?.burstiness?.bands,
       mattrBands: config.stylometry?.ttr?.bands,
       mattrWindow: config.stylometry?.ttr?.window,
+      koDiagnosticsEnabled: config.stylometry?.ko_diagnostics?.enabled !== false,
+      koDiagnosticBands: config.stylometry?.ko_diagnostics?.bands,
       lexiconDensityThreshold: config.lexicon?.density_threshold,
+      ...(lexiconAllowed ? {} : { lexicon: { lang, path: null, strict: [], phrases: [] } }),
     });
     const paragraphs = Array.isArray(result?.paragraphs) ? result.paragraphs : [];
     const paragraphCount = paragraphs.length;
     const hotParagraphs = paragraphs.filter((p) => p.hot).length;
-    const overall = paragraphCount > 0 ? roundScore((hotParagraphs / paragraphCount) * 100) : 0;
+    const hotRatioOverall = paragraphCount > 0 ? roundScore((hotParagraphs / paragraphCount) * 100) : 0;
+    // Model-output leakage (#332) is near-proof-grade and lives at the document
+    // level, so it short-circuits the hot-ratio score into the 'heavily AI' band.
+    const leaked = Boolean(result?.markupLeakage?.leaked);
+    const overall = leaked ? Math.max(hotRatioOverall, LEAKAGE_SCORE_FLOOR) : hotRatioOverall;
+    const signalScore = roundScore(summarizeSignalStrength(paragraphs, {
+      burstinessBands: config.stylometry?.burstiness?.bands,
+      mattrBands: config.stylometry?.ttr?.bands,
+      lexiconDensityThreshold: config.lexicon?.density_threshold,
+    }));
 
     return {
       overall,
@@ -197,6 +273,7 @@ export function scoreDeterministicSignals({
       skipReason: result?.skipReason ?? null,
       paragraphCount,
       hotParagraphs,
+      signalScore,
       bands: {
         burstiness: countBands(paragraphs.map((p) => p.burstiness?.band)),
         mattr: countBands(paragraphs.map((p) => p.mattr?.band)),
@@ -204,6 +281,15 @@ export function scoreDeterministicSignals({
           hot: paragraphs.filter((p) => p.lexicon?.hot).length,
           threshold: config.lexicon?.density_threshold ?? null,
         },
+        koDiagnostics: {
+          hot: paragraphs.filter((p) => p.koDiagnostics?.hot).length,
+          thresholds: config.stylometry?.ko_diagnostics?.bands ?? null,
+        },
+        markupLeakage: {
+          leaked,
+          hits: Array.isArray(result?.markupLeakage?.hits) ? result.markupLeakage.hits.length : 0,
+          floor: LEAKAGE_SCORE_FLOOR,
+        },
       },
     };
   } catch (err) {
@@ -214,12 +300,26 @@ export function scoreDeterministicSignals({
       skipReason: 'deterministic-failure',
       paragraphCount: 0,
       hotParagraphs: 0,
+      signalScore: 0,
       bands: emptyDeterministicBands(),
       error: err?.message || 'deterministic scoring failed',
     };
   }
 }
 
+/**
+ * Merge an LLM score payload with deterministic shadow-score reconciliation.
+ *
+ * @param {object} parsed Parsed LLM scoring JSON.
+ * @param {object} [options] Reconciliation options.
+ * @param {object|null} [options.deterministicScore] Deterministic score payload.
+ * @param {object} [options.config={}] Effective config.
+ * @param {object} [options.logger] Logger for reconciliation warnings.
+ * @returns {object} Score payload preserving llmScore and deterministicScore details.
+ * @throws {Error} Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+ * @example
+ * const score = withShadowScore({ overall: 20 }, { deterministicScore: { overall: 25 } });
+ */
 export function withShadowScore(parsed, { deterministicScore, config = {}, logger } = {}) {
   const llmOverall = toFiniteScore(parsed?.overall);
   const llmScore = {
@@ -246,6 +346,19 @@ export function withShadowScore(parsed, { deterministicScore, config = {}, logge
   };
 }
 
+/**
+ * Reconcile LLM and deterministic overall scores according to config thresholds.
+ *
+ * @param {object} [options] Reconciliation inputs.
+ * @param {number|null} [options.llmOverall] LLM overall score.
+ * @param {object|null} [options.deterministicScore] Deterministic score payload.
+ * @param {object} [options.config={}] Effective config.
+ * @param {object} [options.logger] Logger for warnings.
+ * @returns {{overall: number|null, scorePreference: (object|null)}} Reconciled score and preference source.
+ * @throws {Error} Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+ * @example
+ * const result = reconcileScoreOverall({ llmOverall: 20, deterministicScore: { overall: 60 } });
+ */
 export function reconcileScoreOverall({
   llmOverall,
   deterministicScore,
@@ -281,6 +394,27 @@ export function reconcileScoreOverall({
   return { overall, scorePreference };
 }
 
+/**
+ * Score meaning preservation between original and rewritten text.
+ *
+ * @param {object} options MPS options.
+ * @param {string} options.original Original text.
+ * @param {string} options.rewritten Rewritten text.
+ * @param {string} [options.apiKey] Provider API key.
+ * @param {string} [options.baseURL] Provider base URL.
+ * @param {string} [options.model] Model id.
+ * @param {number} [options.deadline] Absolute epoch-millisecond deadline.
+ * @param {AbortSignal} [options.signal] External cancellation signal.
+ * @param {number} [options.timeout] Per-attempt backend timeout in milliseconds.
+ * @param {Function} [options.callLLM] Injectable LLM implementation.
+ * @param {object} [options.logger] patina logger.
+ * @param {Function} [options.now] Clock returning epoch milliseconds.
+ * @param {Function} [options.sleep] Sleep helper for tests.
+ * @returns {Promise<Object>} MPS result.
+ * @throws {Error} When the operation is aborted.
+ * @example
+ * const mps = await scoreMPS({ original: 'A', rewritten: 'A', callLLM: async () => '{"mps":100,"anchors":[]}' });
+ */
 export async function scoreMPS({
   original,
   rewritten,
@@ -289,6 +423,7 @@ export async function scoreMPS({
   model,
   deadline,
   signal,
+  timeout,
   callLLM = defaultCallLLM,
   logger = createLogger(),
   now,
@@ -333,6 +468,7 @@ ${rewritten}
       model,
       deadline,
       signal,
+      timeout,
       callLLM,
       logger,
       now,
@@ -348,6 +484,15 @@ ${rewritten}
   }
 }
 
+/**
+ * Convert a numeric AI-likeness score to a human-readable band.
+ *
+ * @param {number} score AI-likeness score from 0 to 100.
+ * @returns {string} Interpretation band.
+ * @throws {Error} Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+ * @example
+ * const label = interpretScore(28); // mostly human
+ */
 export function interpretScore(score) {
   if (score <= 15) return 'human';
   if (score <= 30) return 'mostly human';
@@ -357,6 +502,16 @@ export function interpretScore(score) {
 }
 
 // Length ratio is deterministic — bucket per core/scoring.md §10.4.
+/**
+ * Score rewritten length ratio on the 0-3 fidelity scale.
+ *
+ * @param {string} original Original text.
+ * @param {string} rewritten Rewritten text.
+ * @returns {number} Length-ratio points from 0 to 3.
+ * @throws {Error} Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+ * @example
+ * const points = lengthRatioPoints('abcd', 'abcde');
+ */
 export function lengthRatioPoints(original, rewritten) {
   if (!original || original.length === 0) return 3;
   const ratio = (rewritten.length / original.length) * 100;
@@ -366,6 +521,27 @@ export function lengthRatioPoints(original, rewritten) {
   return 0;
 }
 
+/**
+ * Score fidelity between original and rewritten text using length plus LLM criteria.
+ *
+ * @param {object} options Fidelity options.
+ * @param {string} options.original Original text.
+ * @param {string} options.rewritten Rewritten text.
+ * @param {string} [options.apiKey] Provider API key.
+ * @param {string} [options.baseURL] Provider base URL.
+ * @param {string} [options.model] Model id.
+ * @param {number} [options.deadline] Absolute epoch-millisecond deadline.
+ * @param {AbortSignal} [options.signal] External cancellation signal.
+ * @param {number} [options.timeout] Per-attempt backend timeout in milliseconds.
+ * @param {Function} [options.callLLM] Injectable LLM implementation.
+ * @param {object} [options.logger] patina logger.
+ * @param {Function} [options.now] Clock returning epoch milliseconds.
+ * @param {Function} [options.sleep] Sleep helper for tests.
+ * @returns {Promise<Object>} Fidelity result.
+ * @throws {Error} When the operation is aborted.
+ * @example
+ * const fidelity = await scoreFidelity({ original: 'A', rewritten: 'A', callLLM: async () => '{"criteria":{"meaning":3,"tone":3,"no_unintended_additions":3}}' });
+ */
 export async function scoreFidelity({
   original,
   rewritten,
@@ -374,6 +550,7 @@ export async function scoreFidelity({
   model,
   deadline,
   signal,
+  timeout,
   callLLM = defaultCallLLM,
   logger = createLogger(),
   now,
@@ -421,6 +598,7 @@ ${rewritten}
       deadline,
       signal,
       callLLM,
+      timeout,
       logger,
       now,
       sleep,
@@ -453,6 +631,15 @@ ${rewritten}
   };
 }
 
+/**
+ * Clamp and round a value into the inclusive 0-3 scoring range.
+ *
+ * @param {number|string} v Value to clamp.
+ * @returns {number} Integer from 0 to 3.
+ * @throws {Error} Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+ * @example
+ * const value = clamp03(4.2); // 3
+ */
 export function clamp03(v) {
   const n = Number(v);
   if (!Number.isFinite(n)) return 0;
@@ -467,6 +654,20 @@ function rethrowIfAborted(err, signal) {
 
 // Combined score per core/scoring.md §13: AI-likeness × ai_weight + (100 - fidelity) × fidelity_weight.
 // Lower is better. Falls back to default weights if profile not configured.
+/**
+ * Combine AI-likeness, inverted fidelity, and optional deterministic score.
+ *
+ * @param {object} options Combined score inputs.
+ * @param {number} options.aiLikeness AI-likeness score, lower is better.
+ * @param {number} options.fidelity Fidelity score, higher is better.
+ * @param {string} [options.profile] Profile name for configured weights.
+ * @param {object} [options.config] Effective config.
+ * @param {number|object|null} [options.deterministicScore] Optional deterministic score.
+ * @returns {number} Combined score, lower is better.
+ * @throws {Error} Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+ * @example
+ * const score = combinedScore({ aiLikeness: 20, fidelity: 90, profile: 'default', config: {} });
+ */
 export function combinedScore({ aiLikeness, fidelity, profile, config, deterministicScore }) {
   const profileWeights = config?.ouroboros?.['combined-weights']?.[profile];
   const ai = profileWeights?.['ai-likeness'] ?? 0.6;
@@ -484,6 +685,12 @@ export function combinedScore({ aiLikeness, fidelity, profile, config, determini
   return roundScore(aiLikeness * ai + fidelityInverted * fid);
 }
 
+function isLexiconEnabledForLanguage(config = {}, lang) {
+  if (config.lexicon?.enabled === false) return false;
+  const enabledLanguages = config.lexicon?.languages;
+  return !Array.isArray(enabledLanguages) || enabledLanguages.includes(lang);
+}
+
 function deterministicScoringOptions(config = {}) {
   const cfg = config.scoring?.deterministic || {};
   const enabled = cfg.enabled !== false;
@@ -517,6 +724,7 @@ function emptyDeterministicBands() {
     burstiness: { low: 0, mid: 0, high: 0, null: 0 },
     mattr: { low: 0, mid: 0, high: 0, null: 0 },
     lexicon: { hot: 0, threshold: null },
+    koDiagnostics: { hot: 0, thresholds: null },
   };
 }
 

package/src/security.js

@@ -8,6 +8,15 @@ import { inputError } from './errors.js';
 
 const PROFILE_NAME_RE = /^[A-Za-z0-9_][A-Za-z0-9_-]*$/;
 
+/**
+ * Validate a profile name before resolving profiles/{name}.md.
+ *
+ * @param {string} name Profile name supplied by CLI or config.
+ * @returns {void}
+ * @throws {PatinaCliError} When the name is empty, non-string, or contains unsafe characters.
+ * @example
+ * validateProfileName('default');
+ */
 export function validateProfileName(name) {
   if (typeof name !== 'string' || !PROFILE_NAME_RE.test(name)) {
     throw inputError(
@@ -18,6 +27,15 @@ export function validateProfileName(name) {
   }
 }
 
+/**
+ * Check whether a hostname is localhost or loopback.
+ *
+ * @param {string} hostname Hostname from a URL.
+ * @returns {boolean} True for localhost, 127/8, or ::1.
+ * @throws {Error} Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+ * @example
+ * const local = isLoopbackHost('127.0.0.1');
+ */
 export function isLoopbackHost(hostname) {
   if (!hostname) return false;
   if (hostname === 'localhost') return true;
@@ -31,6 +49,15 @@ export function isLoopbackHost(hostname) {
 // so DNS rebinding is NOT covered by this check. The goal is to catch the
 // common case: --base-url pointed at 169.254.169.254 (cloud metadata) or
 // internal RFC 1918 hosts that should not receive Bearer tokens.
+/**
+ * Detect literal private, reserved, link-local, metadata, or multicast IP hosts.
+ *
+ * @param {string} hostname Hostname or bracketed IPv6 literal.
+ * @returns {boolean} True when the literal IP is private or special-use.
+ * @throws {Error} Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+ * @example
+ * const blocked = isPrivateOrSpecialIP('169.254.169.254');
+ */
 export function isPrivateOrSpecialIP(hostname) {
   if (!hostname) return false;
   const h = hostname.startsWith('[') && hostname.endsWith(']')
@@ -63,6 +90,18 @@ export function isPrivateOrSpecialIP(hostname) {
   return false;
 }
 
+/**
+ * Validate a provider base URL before sending prompts and bearer tokens.
+ *
+ * @param {string} baseURL URL to validate.
+ * @param {object} [options] Validation opt-ins.
+ * @param {boolean} [options.allowInsecure=false] Allow non-loopback HTTP.
+ * @param {boolean} [options.allowPrivate=false] Allow private/reserved literal IPs.
+ * @returns {void}
+ * @throws {PatinaCliError} When the URL is invalid, unsupported, insecure, or private without opt-in.
+ * @example
+ * validateBaseURL('https://api.openai.com/v1');
+ */
 export function validateBaseURL(baseURL, { allowInsecure = false, allowPrivate = false } = {}) {
   let url;
   try {
@@ -108,24 +147,60 @@ export function validateBaseURL(baseURL, { allowInsecure = false, allowPrivate =
   }
 }
 
+/**
+ * Read CLI/env opt-in for non-loopback HTTP base URLs.
+ *
+ * @param {object} [parsed] Parsed CLI options.
+ * @returns {boolean} True when insecure base URLs are explicitly allowed.
+ * @throws {Error} Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+ * @example
+ * const allowed = shouldAllowInsecureBaseURL({ allowInsecureBaseURL: true });
+ */
 export function shouldAllowInsecureBaseURL(parsed) {
   if (parsed && parsed.allowInsecureBaseURL) return true;
   const env = process.env.PATINA_ALLOW_INSECURE_BASE_URL;
   return env === '1' || env === 'true' || env === 'yes';
 }
 
+/**
+ * Persist CLI insecure-base-url opt-in into process.env for downstream calls.
+ *
+ * @param {object} [parsed] Parsed CLI options.
+ * @returns {void}
+ * @throws {Error} Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+ * @example
+ * applyInsecureBaseURLOptIn({ allowInsecureBaseURL: true });
+ */
 export function applyInsecureBaseURLOptIn(parsed) {
   if (parsed && parsed.allowInsecureBaseURL) {
     process.env.PATINA_ALLOW_INSECURE_BASE_URL = '1';
   }
 }
 
+/**
+ * Read CLI/env opt-in for private or reserved literal IP base URLs.
+ *
+ * @param {object} [parsed] Parsed CLI options.
+ * @returns {boolean} True when private base URLs are explicitly allowed.
+ * @throws {Error} Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+ * @example
+ * const allowed = shouldAllowPrivateBaseURL({ allowPrivateBaseURL: true });
+ */
 export function shouldAllowPrivateBaseURL(parsed) {
   if (parsed && parsed.allowPrivateBaseURL) return true;
   const env = process.env.PATINA_ALLOW_PRIVATE_BASE_URL;
   return env === '1' || env === 'true' || env === 'yes';
 }
 
+/**
+ * Persist CLI private-base-url opt-in into process.env for downstream calls.
+ *
+ * @param {object} [parsed] Parsed CLI options.
+ * @returns {void}
+ * @throws {Error} Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+ * @example
+ * applyPrivateBaseURLOptIn({ allowPrivateBaseURL: true });
+ */
 export function applyPrivateBaseURLOptIn(parsed) {
   if (parsed && parsed.allowPrivateBaseURL) {
     process.env.PATINA_ALLOW_PRIVATE_BASE_URL = '1';

package/tests/fixtures/live-quality/en/public-docs-01.md

@@ -0,0 +1,26 @@
+---
+fixture_id: en-public-docs-01
+language: en
+profile: default
+register: public-docs
+source_type: synthetic-ai
+model_family: fixture
+prompt_id: live-quality-v2
+redistribution: repo-ok
+anchors:
+  - coffee
+  - Paris
+  - Tokyo
+  - climate change
+  - supply chains
+expected_focus:
+  - reduce promotional abstractions
+  - preserve concrete locations and constraints
+---
+Coffee has emerged as a pivotal cultural phenomenon that has fundamentally transformed social interactions across the globe. This beloved beverage serves as a catalyst for community building, fosters meaningful connections, and facilitates cross-cultural dialogue.
+
+In Paris, some cafes still work as neighborhood meeting places. In Tokyo, compact coffee bars often serve commuters who stay for only a few minutes.
+
+Roasters are also dealing with climate change. Heat, irregular rain, and disease pressure have made harvest volume less predictable in several growing regions.
+
+Supply chains are part of the same problem. A delayed shipment can change a small cafe's menu for a week, even when demand stays steady.

package/tests/fixtures/live-quality/ko/public-docs-01.md

@@ -0,0 +1,26 @@
+---
+fixture_id: ko-public-docs-01
+language: ko
+profile: default
+register: public-docs
+source_type: synthetic-ai
+model_family: fixture
+prompt_id: live-quality-v2
+redistribution: repo-ok
+anchors:
+  - 커피
+  - 서울
+  - 부산
+  - 기후 변화
+  - 공급망
+expected_focus:
+  - 번역투 완화
+  - 장소와 제약 보존
+---
+커피는 현대 사회적 상호작용을 근본적으로 변화시킨 핵심적인 문화 현상으로 자리매김하고 있습니다. 이 음료는 공동체 형성을 촉진하고 의미 있는 연결을 가능하게 하며, 다양한 문화권 사이의 대화를 활성화하는 중요한 매개체로 기능합니다.
+
+서울의 카페 거리는 출근 전 짧게 들르는 사람과 오래 앉아 일하는 사람이 같이 쓰는 공간이다. 부산의 로스터리들은 관광객보다 동네 단골을 먼저 상대하는 곳도 많다.
+
+기후 변화는 원두 수급을 흔들고 있다. 산지의 비와 더위가 달라지면 같은 농장의 생두도 해마다 품질 차이가 커진다.
+
+공급망 문제도 작지 않다. 선적이 늦어지면 작은 카페는 일주일 메뉴를 바꿔야 하고, 손님 수요와는 별개로 원가가 흔들린다.