dravoice 0.1.2 → 0.1.3

package/src/v2/inspect.js

@@ -1,67 +1,67 @@
-export function renderInspectV2(profile) {
-  const lines = [
-    "Dravoice V2 Profile",
-    "",
-    `Source: ${profile.source.documentCount} document(s), ${profile.source.wordCount} words, ${profile.source.sentenceCount} sentences`,
-    `Corpus confidence: ${capitalize(profile.source.confidence.band)} - ${profile.source.confidence.message}`,
-    "",
-    "Feature families:",
-  ];
-
-  for (const [name, family] of Object.entries(profile.families)) {
-    lines.push(`- ${name}: ${family.confidence}`);
-    if (family.warnings.length) {
-      for (const warning of family.warnings) {
-        lines.push(`  warning: ${warning}`);
-      }
-    }
-  }
-
-  lines.push("", "Feature details:");
-  for (const [name, family] of Object.entries(profile.families)) {
-    lines.push(`- ${name}: ${featureSummary(name, family.features)}`);
-    if (family.revisionHandles?.length) {
-      lines.push("  Revision handles:");
-      for (const handle of family.revisionHandles) {
-        lines.push(`  - ${handle}`);
-      }
-    }
-  }
-
-  lines.push("", "Guidance:");
-  for (const rule of profile.guidance.draftingRules) {
-    lines.push(`- ${rule}`);
-  }
-
-  lines.push("");
-  return `${lines.join("\n")}`;
-}
-
-function capitalize(value) {
-  return value.charAt(0).toUpperCase() + value.slice(1);
-}
-
-function featureSummary(name, features) {
-  if (name === "rhythm") {
-    return `sentenceWords.median=${features.sentenceWords.median}; paragraphWords.median=${features.paragraphWords.median}; listDensity=${features.listDensity}; quoteDensity=${features.quoteDensity}`;
-  }
-  if (name === "lexical") {
-    return `wordCount=${features.wordCount}; contentTypeTokenRatio=${features.vocabularyRichness.contentTypeTokenRatio}; wordLength.median=${features.wordLength.median}; maskedCharacterFourgrams=${features.maskedCharacterFourgrams?.length ?? 0}; functionWordBigrams=${features.functionWordBigrams?.length ?? 0}`;
-  }
-  if (name === "register") {
-    return `primary=${features.primary.value} (${features.primary.score}); alternates=${features.scores.slice(1, 4).map((score) => `${score.value}:${score.score}`).join(", ")}`;
-  }
-  if (name === "discourse") {
-    return `transitionRates=${Object.entries(features.transitionRates).map(([key, value]) => `${key}:${value}`).join(", ")}; sentenceCallbacks=${features.sentenceCallbacks}`;
-  }
-  if (name === "rhetoricalShape") {
-    return `openingMoves=${features.openingMoves.slice(0, 5).join(" -> ") || "none"}; moveTrigrams=${features.moveTrigrams?.slice(0, 2).map((item) => `${item.value}:${item.count}`).join(", ") || "none"}; commonSequences=${features.commonSequences.slice(0, 3).map((item) => `${item.value}:${item.count}`).join(", ") || "none"}`;
-  }
-  if (name === "evidence") {
-    return `evidenceSentenceRate=${features.evidenceSentenceRate}; claimSentenceRate=${features.claimSentenceRate}; supportedClaimRate=${features.supportedClaimRate}; unsupportedClaimRate=${features.unsupportedClaimRate}; evidenceTypes=${features.evidenceTypes.map((item) => `${item.value}:${item.count}`).join(", ") || "none"}`;
-  }
-  if (name === "structure") {
-    return `sectionWords.median=${features.sectionWords.median}; headingCount.median=${features.headingCount.median}; listDocumentRate=${features.listDocumentRate}; quoteDocumentRate=${features.quoteDocumentRate}`;
-  }
-  return JSON.stringify(features);
-}
+export function renderInspectV2(profile) {
+  const lines = [
+    "Dravoice V2 Profile",
+    "",
+    `Source: ${profile.source.documentCount} document(s), ${profile.source.wordCount} words, ${profile.source.sentenceCount} sentences`,
+    `Corpus confidence: ${capitalize(profile.source.confidence.band)} - ${profile.source.confidence.message}`,
+    "",
+    "Feature families:",
+  ];
+
+  for (const [name, family] of Object.entries(profile.families)) {
+    lines.push(`- ${name}: ${family.confidence}`);
+    if (family.warnings.length) {
+      for (const warning of family.warnings) {
+        lines.push(`  warning: ${warning}`);
+      }
+    }
+  }
+
+  lines.push("", "Feature details:");
+  for (const [name, family] of Object.entries(profile.families)) {
+    lines.push(`- ${name}: ${featureSummary(name, family.features)}`);
+    if (family.revisionHandles?.length) {
+      lines.push("  Revision handles:");
+      for (const handle of family.revisionHandles) {
+        lines.push(`  - ${handle}`);
+      }
+    }
+  }
+
+  lines.push("", "Guidance:");
+  for (const rule of profile.guidance.draftingRules) {
+    lines.push(`- ${rule}`);
+  }
+
+  lines.push("");
+  return `${lines.join("\n")}`;
+}
+
+function capitalize(value) {
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}
+
+function featureSummary(name, features) {
+  if (name === "rhythm") {
+    return `sentenceWords.median=${features.sentenceWords.median}; paragraphWords.median=${features.paragraphWords.median}; listDensity=${features.listDensity}; quoteDensity=${features.quoteDensity}`;
+  }
+  if (name === "lexical") {
+    return `wordCount=${features.wordCount}; contentTypeTokenRatio=${features.vocabularyRichness.contentTypeTokenRatio}; wordLength.median=${features.wordLength.median}; maskedCharacterFourgrams=${features.maskedCharacterFourgrams?.length ?? 0}; functionWordBigrams=${features.functionWordBigrams?.length ?? 0}`;
+  }
+  if (name === "register") {
+    return `primary=${features.primary.value} (${features.primary.score}); alternates=${features.scores.slice(1, 4).map((score) => `${score.value}:${score.score}`).join(", ")}`;
+  }
+  if (name === "discourse") {
+    return `transitionRates=${Object.entries(features.transitionRates).map(([key, value]) => `${key}:${value}`).join(", ")}; sentenceCallbacks=${features.sentenceCallbacks}`;
+  }
+  if (name === "rhetoricalShape") {
+    return `openingMoves=${features.openingMoves.slice(0, 5).join(" -> ") || "none"}; moveTrigrams=${features.moveTrigrams?.slice(0, 2).map((item) => `${item.value}:${item.count}`).join(", ") || "none"}; commonSequences=${features.commonSequences.slice(0, 3).map((item) => `${item.value}:${item.count}`).join(", ") || "none"}`;
+  }
+  if (name === "evidence") {
+    return `evidenceSentenceRate=${features.evidenceSentenceRate}; claimSentenceRate=${features.claimSentenceRate}; supportedClaimRate=${features.supportedClaimRate}; unsupportedClaimRate=${features.unsupportedClaimRate}; evidenceTypes=${features.evidenceTypes.map((item) => `${item.value}:${item.count}`).join(", ") || "none"}`;
+  }
+  if (name === "structure") {
+    return `sectionWords.median=${features.sectionWords.median}; headingCount.median=${features.headingCount.median}; listDocumentRate=${features.listDocumentRate}; quoteDocumentRate=${features.quoteDocumentRate}`;
+  }
+  return JSON.stringify(features);
+}

package/src/v2/io-utils.js

@@ -0,0 +1,51 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const DEFAULT_MAX_READ_BYTES = 5 * 1024 * 1024;
+
+export function readUtf8FileBounded(filePath, {
+  label = "File",
+  maxBytes = DEFAULT_MAX_READ_BYTES,
+  rejectBinary = true,
+} = {}) {
+  const resolved = path.resolve(filePath);
+  const stats = fs.statSync(resolved);
+  if (!stats.isFile()) {
+    throw new Error(`${label} is not a regular file: ${filePath}`);
+  }
+  if (stats.size > maxBytes) {
+    throw new Error(`${label} ${displayPath(filePath)} exceeds the ${maxBytes} byte limit.`);
+  }
+  const contents = fs.readFileSync(resolved, "utf8");
+  if (rejectBinary && contents.includes("\0")) {
+    throw new Error(`${label} ${displayPath(filePath)} looks like binary-looking text and cannot be analyzed.`);
+  }
+  return contents;
+}
+
+export function readJsonFileBounded(filePath, options = {}) {
+  const label = options.label ?? "JSON file";
+  const contents = readUtf8FileBounded(filePath, { ...options, label });
+  try {
+    return JSON.parse(contents);
+  } catch (error) {
+    throw new Error(`${label} ${displayPath(filePath)} is not valid JSON: ${error.message}`);
+  }
+}
+
+export function writeUtf8FileSafely(filePath, contents) {
+  rejectSymlink(filePath);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  rejectSymlink(filePath);
+  fs.writeFileSync(filePath, contents, "utf8");
+}
+
+function rejectSymlink(filePath) {
+  if (fs.existsSync(filePath) && fs.lstatSync(filePath).isSymbolicLink()) {
+    throw new Error(`Refusing to write through symlink: ${filePath}`);
+  }
+}
+
+function displayPath(filePath) {
+  return String(filePath).split(path.sep).join("/");
+}

package/src/v2/profile.js

@@ -1,203 +1,227 @@
-import fs from "node:fs";
-import path from "node:path";
-import { analyzeDiscourse } from "./analyzers/discourse.js";
-import { analyzeEvidence } from "./analyzers/evidence.js";
-import { analyzeLexical } from "./analyzers/lexical.js";
-import { analyzeRegister } from "./analyzers/register.js";
-import { analyzeRhetoricalShape } from "./analyzers/rhetorical-shape.js";
-import { analyzeRhythm } from "./analyzers/rhythm.js";
-import { analyzeStructure } from "./analyzers/structure.js";
-import { loadDocuments } from "./document-model.js";
-import {
-  STYLOMETRIC_REFERENCES,
-  defaultStyleThresholds,
-  distanceByFamily,
-  percentile,
-  stabilityFromDistances,
-} from "./stylometry.js";
-
-export function learnVoicePackV2({ examplesDir, outDir }) {
-  const documents = loadDocuments({ examplesDir });
-  const profile = buildVoiceProfileV2({ documents });
-  if (outDir) {
-    writeVoicePackV2(outDir, profile);
-  }
-  return profile;
-}
-
-export function loadVoicePackV2(voiceDir) {
-  const profilePath = path.join(voiceDir, "profile.json");
-  if (!fs.existsSync(profilePath)) {
-    throw new Error(`No Dravoice V2 profile found at ${voiceDir}`);
-  }
-  const profile = JSON.parse(fs.readFileSync(profilePath, "utf8"));
-  if (profile.schemaVersion !== 2) {
-    throw new Error(`Expected a Dravoice V2 profile at ${voiceDir}; found schemaVersion ${profile.schemaVersion ?? "unknown"}.`);
-  }
-  return profile;
-}
-
-export function buildVoiceProfileV2({ documents }) {
-  const source = sourceSummary(documents);
-  const families = analyzeFeatureFamilies(documents);
-
-  return {
-    schemaVersion: 2,
-    generatedBy: "dravoice-v2",
-    tool: { name: "Dravoice", cli: "drav" },
-    source,
-    families,
-    guidance: guidanceFor({ source, families }),
-    calibration: {
-      featureStability: Object.fromEntries(Object.entries(families).map(([name, family]) => [name, family.confidence])),
-      tolerances: {
-        rhythmMedianWords: toleranceFor(source.confidence.band, 5, 8, 12),
-        evidenceRate: toleranceFor(source.confidence.band, 0.12, 0.18, 0.25),
-      },
-      styleThresholds: styleThresholdsFor(documents, families),
-      minimumDraftSize: {
-        words: source.confidence.band === "weak" ? 25 : 35,
-        sentences: source.confidence.band === "weak" ? 3 : 4,
-      },
-    },
-  };
-}
-
-function analyzeFeatureFamilies(documents) {
-  return {
-    rhythm: analyzeRhythm(documents),
-    lexical: analyzeLexical(documents),
-    register: analyzeRegister(documents),
-    discourse: analyzeDiscourse(documents),
-    rhetoricalShape: analyzeRhetoricalShape(documents),
-    evidence: analyzeEvidence(documents),
-    structure: analyzeStructure(documents),
-  };
-}
-
-function styleThresholdsFor(documents, fallbackFamilies) {
-  const fallbackThresholds = defaultStyleThresholds();
-  const distancesByFamily = Object.fromEntries(Object.keys(fallbackFamilies).map((family) => [family, []]));
-
-  if (documents.length >= 2) {
-    for (let index = 0; index < documents.length; index += 1) {
-      const referenceDocuments = documents.filter((_, candidateIndex) => candidateIndex !== index);
-      const referenceFamilies = analyzeFeatureFamilies(referenceDocuments);
-      const heldoutFamilies = analyzeFeatureFamilies([documents[index]]);
-      for (const family of Object.keys(fallbackFamilies)) {
-        distancesByFamily[family].push(distanceByFamily(
-          family,
-          referenceFamilies[family].features,
-          heldoutFamilies[family].features,
-        ));
-      }
-    }
-  }
-
-  const families = {};
-  for (const family of Object.keys(fallbackFamilies)) {
-    const observations = distancesByFamily[family];
-    const observedThreshold = observations.length > 0 ? percentile(observations, 0.9) : 0;
-    const fallback = fallbackThresholds[family].threshold;
-    families[family] = {
-      threshold: Math.max(0.01, Math.min(0.95, observedThreshold || fallback)),
-      observations: observations.length,
-      stability: stabilityFromDistances(observations),
-    };
-  }
-
-  return {
-    method: "leave-one-out-cosine-delta",
-    references: STYLOMETRIC_REFERENCES,
-    families,
-  };
-}
-
-function writeVoicePackV2(outDir, profile) {
-  fs.mkdirSync(outDir, { recursive: true });
-  fs.writeFileSync(path.join(outDir, "profile.json"), `${JSON.stringify(profile, null, 2)}\n`, "utf8");
-  fs.writeFileSync(
-    path.join(outDir, ".dravoice.yml"),
-    [
-      "schemaVersion: 2",
-      "generatedBy: dravoice-v2",
-      `confidence: ${profile.source.confidence.band}`,
-      "",
-    ].join("\n"),
-    "utf8",
-  );
-}
-
-function sourceSummary(documents) {
-  const wordCount = documents.reduce((sum, document) => sum + document.wordCount, 0);
-  const sentenceCount = documents.reduce((sum, document) => sum + document.sentences.length, 0);
-  const confidence = confidenceFor(documents.length, sentenceCount, wordCount);
-  return {
-    files: documents.map((document, index) => ({
-      id: `source-${index + 1}`,
-      extension: path.extname(document.path || document.file).toLowerCase() || ".txt",
-      wordCount: document.wordCount,
-      sentenceCount: document.sentences.length,
-    })),
-    documentCount: documents.length,
-    wordCount,
-    sentenceCount,
-    genres: [],
-    confidence,
-  };
-}
-
-function confidenceFor(documentCount, sentenceCount, wordCount) {
-  if (documentCount >= 10 && sentenceCount >= 80 && wordCount >= 5000) {
-    return { band: "deep", message: "Enough material for stricter family-level review." };
-  }
-  if (documentCount >= 5 && sentenceCount >= 30) {
-    return { band: "strong", message: "Enough examples for stable family-level review." };
-  }
-  if (documentCount >= 3 && sentenceCount >= 10) {
-    return { band: "usable", message: "Enough text for prompt guidance and cautious review." };
-  }
-  return { band: "weak", message: "Limited corpus; use findings as weak signals." };
-}
-
-function guidanceFor({ source, families }) {
-  const primaryRegister = families.register.features.primary.value;
-  const evidenceRate = families.evidence.features.evidenceSentenceRate;
-  const sentenceMedian = families.rhythm.features.sentenceWords.median;
-  const opening = families.rhetoricalShape.features.openingMoves.slice(0, 3).join(" -> ");
-
-  const draftingRules = [
-    `Keep sentence pacing near the learned median of ${sentenceMedian} words when it fits the draft.`,
-    `Use ${primaryRegister} register as the default genre signal unless the piece intentionally changes genre.`,
-    evidenceRate > 0.35
-      ? "Anchor broad claims with concrete scenes, numbers, quotes, citations, or specific examples."
-      : "Do not force evidence density higher than the source corpus supports.",
-    opening
-      ? `Prefer opening moves compatible with: ${opening}.`
-      : "Start from the article's real subject rather than generic positioning.",
-  ];
-
-  return {
-    summary: [
-      `Local Dravoice V2 profile from ${source.documentCount} document(s), ${source.wordCount} words, confidence ${source.confidence.band}.`,
-      `Primary register signal: ${primaryRegister}.`,
-    ],
-    draftingRules,
-    avoid: [
-      "Do not treat topic vocabulary as proof of voice fit.",
-      "Do not claim a draft is or is not the writer's true voice.",
-      "Do not invent concrete evidence to satisfy a style finding.",
-    ],
-    examples: [],
-  };
-}
-
-function toleranceFor(band, deep, strong, weak) {
-  if (band === "deep") {
-    return deep;
-  }
-  if (band === "strong") {
-    return strong;
-  }
-  return weak;
-}
+import fs from "node:fs";
+import path from "node:path";
+import { analyzeDiscourse } from "./analyzers/discourse.js";
+import { analyzeEvidence } from "./analyzers/evidence.js";
+import { analyzeLexical } from "./analyzers/lexical.js";
+import { analyzeRegister } from "./analyzers/register.js";
+import { analyzeRhetoricalShape } from "./analyzers/rhetorical-shape.js";
+import { analyzeRhythm } from "./analyzers/rhythm.js";
+import { analyzeStructure } from "./analyzers/structure.js";
+import { loadDocuments } from "./document-model.js";
+import { readJsonFileBounded, writeUtf8FileSafely } from "./io-utils.js";
+import {
+  STYLOMETRIC_REFERENCES,
+  defaultStyleThresholds,
+  distanceByFamily,
+  percentile,
+  stabilityFromDistances,
+} from "./stylometry.js";
+
+export function learnVoicePackV2({ examplesDir, outDir, excludePaths = [] }) {
+  const documents = loadDocuments({ examplesDir, excludePaths });
+  const profile = buildVoiceProfileV2({ documents });
+  if (outDir) {
+    writeVoicePackV2(outDir, profile);
+  }
+  return profile;
+}
+
+export function loadVoicePackV2(voiceDir) {
+  const profilePath = path.join(voiceDir, "profile.json");
+  if (!fs.existsSync(profilePath)) {
+    throw new Error(`No Dravoice V2 profile found at ${voiceDir}`);
+  }
+  const profile = readJsonFileBounded(profilePath, { label: "Dravoice profile", maxBytes: 2 * 1024 * 1024 });
+  if (profile.schemaVersion !== 2) {
+    throw new Error(`Expected a Dravoice V2 profile at ${voiceDir}; found schemaVersion ${profile.schemaVersion ?? "unknown"}.`);
+  }
+  validateVoiceProfileV2(profile, voiceDir);
+  return profile;
+}
+
+export function buildVoiceProfileV2({ documents }) {
+  const source = sourceSummary(documents);
+  const families = analyzeFeatureFamilies(documents);
+
+  return {
+    schemaVersion: 2,
+    generatedBy: "dravoice-v2",
+    tool: { name: "Dravoice", cli: "drav" },
+    source,
+    families,
+    guidance: guidanceFor({ source, families }),
+    calibration: {
+      featureStability: Object.fromEntries(Object.entries(families).map(([name, family]) => [name, family.confidence])),
+      tolerances: {
+        rhythmMedianWords: toleranceFor(source.confidence.band, 5, 8, 12),
+        evidenceRate: toleranceFor(source.confidence.band, 0.12, 0.18, 0.25),
+      },
+      styleThresholds: styleThresholdsFor(documents, families),
+      minimumDraftSize: {
+        words: source.confidence.band === "weak" ? 25 : 35,
+        sentences: source.confidence.band === "weak" ? 3 : 4,
+      },
+    },
+  };
+}
+
+function analyzeFeatureFamilies(documents) {
+  return {
+    rhythm: analyzeRhythm(documents),
+    lexical: analyzeLexical(documents),
+    register: analyzeRegister(documents),
+    discourse: analyzeDiscourse(documents),
+    rhetoricalShape: analyzeRhetoricalShape(documents),
+    evidence: analyzeEvidence(documents),
+    structure: analyzeStructure(documents),
+  };
+}
+
+function styleThresholdsFor(documents, fallbackFamilies) {
+  const fallbackThresholds = defaultStyleThresholds();
+  const distancesByFamily = Object.fromEntries(Object.keys(fallbackFamilies).map((family) => [family, []]));
+
+  if (documents.length >= 2) {
+    for (let index = 0; index < documents.length; index += 1) {
+      const referenceDocuments = documents.filter((_, candidateIndex) => candidateIndex !== index);
+      const referenceFamilies = analyzeFeatureFamilies(referenceDocuments);
+      const heldoutFamilies = analyzeFeatureFamilies([documents[index]]);
+      for (const family of Object.keys(fallbackFamilies)) {
+        distancesByFamily[family].push(distanceByFamily(
+          family,
+          referenceFamilies[family].features,
+          heldoutFamilies[family].features,
+        ));
+      }
+    }
+  }
+
+  const families = {};
+  for (const family of Object.keys(fallbackFamilies)) {
+    const observations = distancesByFamily[family];
+    const observedThreshold = observations.length > 0 ? percentile(observations, 0.9) : 0;
+    const fallback = fallbackThresholds[family].threshold;
+    families[family] = {
+      threshold: Math.max(0.01, Math.min(0.95, observedThreshold || fallback)),
+      observations: observations.length,
+      stability: stabilityFromDistances(observations),
+    };
+  }
+
+  return {
+    method: "leave-one-out-cosine-delta",
+    references: STYLOMETRIC_REFERENCES,
+    families,
+  };
+}
+
+function writeVoicePackV2(outDir, profile) {
+  fs.mkdirSync(outDir, { recursive: true });
+  writeUtf8FileSafely(path.join(outDir, "profile.json"), `${JSON.stringify(profile, null, 2)}\n`);
+  writeUtf8FileSafely(
+    path.join(outDir, ".dravoice.yml"),
+    [
+      "schemaVersion: 2",
+      "generatedBy: dravoice-v2",
+      `confidence: ${profile.source.confidence.band}`,
+      "",
+    ].join("\n"),
+  );
+}
+
+function validateVoiceProfileV2(profile, voiceDir) {
+  assertObject(profile.source, "profile.source", voiceDir);
+  assertObject(profile.source.confidence, "profile.source.confidence", voiceDir);
+  assertObject(profile.families, "profile.families", voiceDir);
+  for (const family of ["rhythm", "lexical", "register", "discourse", "rhetoricalShape", "evidence", "structure"]) {
+    assertObject(profile.families[family], `profile.families.${family}`, voiceDir);
+    assertObject(profile.families[family].features, `profile.families.${family}.features`, voiceDir);
+  }
+  assertObject(profile.guidance, "profile.guidance", voiceDir);
+  if (!Array.isArray(profile.guidance.summary) || !Array.isArray(profile.guidance.draftingRules) || !Array.isArray(profile.guidance.avoid)) {
+    throw new Error(`Invalid Dravoice V2 profile at ${voiceDir}: profile.guidance must include summary, draftingRules, and avoid arrays.`);
+  }
+  assertObject(profile.calibration, "profile.calibration", voiceDir);
+  assertObject(profile.calibration.minimumDraftSize, "profile.calibration.minimumDraftSize", voiceDir);
+  assertObject(profile.calibration.styleThresholds, "profile.calibration.styleThresholds", voiceDir);
+}
+
+function assertObject(value, field, voiceDir) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Invalid Dravoice V2 profile at ${voiceDir}: missing ${field}.`);
+  }
+}
+
+function sourceSummary(documents) {
+  const wordCount = documents.reduce((sum, document) => sum + document.wordCount, 0);
+  const sentenceCount = documents.reduce((sum, document) => sum + document.sentences.length, 0);
+  const confidence = confidenceFor(documents.length, sentenceCount, wordCount);
+  return {
+    files: documents.map((document, index) => ({
+      id: `source-${index + 1}`,
+      extension: path.extname(document.path || document.file).toLowerCase() || ".txt",
+      wordCount: document.wordCount,
+      sentenceCount: document.sentences.length,
+    })),
+    documentCount: documents.length,
+    wordCount,
+    sentenceCount,
+    genres: [],
+    confidence,
+  };
+}
+
+function confidenceFor(documentCount, sentenceCount, wordCount) {
+  if (documentCount >= 10 && sentenceCount >= 80 && wordCount >= 5000) {
+    return { band: "deep", message: "Enough material for stricter family-level review." };
+  }
+  if (documentCount >= 5 && sentenceCount >= 30) {
+    return { band: "strong", message: "Enough examples for stable family-level review." };
+  }
+  if (documentCount >= 3 && sentenceCount >= 10) {
+    return { band: "usable", message: "Enough text for prompt guidance and cautious review." };
+  }
+  return { band: "weak", message: "Limited corpus; use findings as weak signals." };
+}
+
+function guidanceFor({ source, families }) {
+  const primaryRegister = families.register.features.primary.value;
+  const evidenceRate = families.evidence.features.evidenceSentenceRate;
+  const sentenceMedian = families.rhythm.features.sentenceWords.median;
+  const opening = families.rhetoricalShape.features.openingMoves.slice(0, 3).join(" -> ");
+
+  const draftingRules = [
+    `Keep sentence pacing near the learned median of ${sentenceMedian} words when it fits the draft.`,
+    `Use ${primaryRegister} register as the default genre signal unless the piece intentionally changes genre.`,
+    evidenceRate > 0.35
+      ? "Anchor broad claims with concrete scenes, numbers, quotes, citations, or specific examples."
+      : "Do not force evidence density higher than the source corpus supports.",
+    opening
+      ? `Prefer opening moves compatible with: ${opening}.`
+      : "Start from the article's real subject rather than generic positioning.",
+  ];
+
+  return {
+    summary: [
+      `Local Dravoice V2 profile from ${source.documentCount} document(s), ${source.wordCount} words, confidence ${source.confidence.band}.`,
+      `Primary register signal: ${primaryRegister}.`,
+    ],
+    draftingRules,
+    avoid: [
+      "Do not treat topic vocabulary as proof of voice fit.",
+      "Do not claim a draft is or is not the writer's true voice.",
+      "Do not invent concrete evidence to satisfy a style finding.",
+    ],
+    examples: [],
+  };
+}
+
+function toleranceFor(band, deep, strong, weak) {
+  if (band === "deep") {
+    return deep;
+  }
+  if (band === "strong") {
+    return strong;
+  }
+  return weak;
+}