@holdyourvoice/hyv 3.3.0 → 3.3.2

package/dist/fact-linter.js

@@ -0,0 +1,191 @@
+import { sentences } from './text.js';
+const STOP_WORDS = new Set(['a', 'an', 'and', 'are', 'as', 'at', 'be', 'by', 'for', 'from', 'has', 'have', 'in', 'is', 'it', 'of', 'on', 'or', 'that', 'the', 'this', 'to', 'was', 'were', 'will', 'with']);
+const DATE = /\b(?:\d{1,2}\s+(?:January|February|March|April|May|June|July|August|September|October|November|December)\s+\d{4}|(?:January|February|March|April|May|June|July|August|September|October|November|December)\s+\d{1,2},?\s+\d{4}|\d{4}-\d{2}-\d{2})\b/gi;
+const QUOTE = /["“]([^"”]+)["”]/;
+function normal(value) { return value.toLowerCase().replace(/[^\p{L}\p{N}%]+/gu, ' ').trim(); }
+function tokens(value) { return normal(value).split(' ').filter((word) => word.length > 1 && !STOP_WORDS.has(word)); }
+function evidence(source, text) { const start = source.text.indexOf(text); return { sourceId: source.id, excerpt: text, start: Math.max(0, start), end: Math.max(0, start) + text.length }; }
+function sourceSentences(sources) { return sources.flatMap((source) => sentences(source.text).map((sentence) => ({ source, text: sentence.text }))); }
+function hasOverlap(claim, source) {
+    const claimTokens = tokens(claim);
+    const sourceTokens = new Set(tokens(source));
+    return claimTokens.length > 0 && claimTokens.filter((token) => sourceTokens.has(token)).length / claimTokens.length >= 0.8;
+}
+function dates(value) { return [...value.matchAll(DATE)].map((match) => new Date(match[0]).toISOString().slice(0, 10)).filter((value) => value !== ''); }
+function numbers(value) { return value.match(/\b\d+(?:\.\d+)?\s*(?:%|days?|hours?|weeks?|months?|years?)?\b/gi) ?? []; }
+function negated(value) { return /\b(?:does not|do not|did not|is not|are not|cannot|can't|won't|not)\b/i.test(value); }
+const NON_ENTITIES = new Set(['A', 'An', 'And', 'After', 'As', 'At', 'But', 'For', 'From', 'He', 'I', 'In', 'It', 'Its', 'On', 'Or', 'She', 'The', 'This', 'That', 'They', 'We', 'With', 'You']);
+const CAPABILITY = /\b(?:exports?|supports|includes?|works with|can\s+(?:export|support|include)|(?:does not|do not|did not|is not|are not)\s+support)\s+([^.!?]+)/gi;
+const CAPABILITY_FILLER = new Set(['a', 'an', 'as', 'data', 'file', 'files', 'report', 'reports', 'the']);
+const CAPABILITY_FORMATS = new Set(['csv', 'json', 'pdf', 'xml']);
+function entities(value) {
+    return (value.match(/\b[A-Z][\p{L}\p{M}'-]*(?:\s+[A-Z][\p{L}\p{M}'-]+)?\b/gu) ?? []).filter((entity) => !NON_ENTITIES.has(entity) && entity !== entity.toUpperCase());
+}
+function capabilityObjects(text) {
+    return [...text.matchAll(CAPABILITY)].map((match) => [...new Set(tokens(match[1]).map((token) => token.replace(/s$/, '')).filter((token) => !CAPABILITY_FILLER.has(token)))]).filter((items) => items.length > 0);
+}
+function kindFor(text) {
+    const kinds = [];
+    if (/\b(i think|i feel|in my view|we believe)\b/i.test(text))
+        kinds.push('opinion');
+    if (/\b(may|might|could|likely|hypothesis)\b/i.test(text))
+        kinds.push('hypothesis');
+    if (/\b(caused?|because|led to|resulted in)\b/i.test(text))
+        kinds.push('causal');
+    if (/\b(best|better|more|less|fastest|largest|every alternative|than)\b/i.test(text))
+        kinds.push('comparative');
+    if (QUOTE.test(text) || /\b(said|according to|reported)\b/i.test(text))
+        kinds.push('attribution_quote');
+    if (dates(text).length)
+        kinds.push('date_time');
+    if (/\b\d+(?:\.\d+)?%?\b/.test(text))
+        kinds.push('number');
+    if (entities(text).length)
+        kinds.push('entity');
+    if (!kinds.length)
+        kinds.push('fact');
+    return kinds;
+}
+function findRelevant(claim, sources) {
+    const terms = tokens(claim);
+    return sources.filter(({ text }) => terms.some((term) => tokens(text).includes(term)));
+}
+function fallbackEvidence(sources) {
+    const line = sources[0];
+    return line ? [evidence(line.source, line.text)] : [];
+}
+function finding(claim, kind, severity, reason, evidenceItems, confidence, suggestedAction) {
+    return { severity, kind, claim: claim.text, draftLocation: { sentence: claim.sentence, start: claim.start, end: claim.end }, reason, evidence: evidenceItems, confidence, suggestedAction };
+}
+export function extractFactClaims(draft) {
+    const output = sentences(draft).map((sentence) => ({ text: sentence.text, sentence: sentence.index, start: sentence.start, end: sentence.end, kinds: kindFor(sentence.text) }));
+    for (const match of draft.matchAll(/["“]([^"”]+)["”]/g)) {
+        const start = match.index ?? 0;
+        const containing = output.find((claim) => claim.start <= start && claim.end >= start) ?? output.find((claim) => claim.start <= start) ?? output[0];
+        if (containing)
+            output.push({ text: match[0], sentence: containing.sentence, start, end: start + match[0].length, kinds: ['attribution_quote'] });
+    }
+    return output;
+}
+export function lintFacts(input) {
+    if (!input.sources.length)
+        throw new Error('Fact lint requires at least one source document.');
+    if (!input.sources.every((source) => source.id.trim() && source.text.trim()))
+        throw new Error('Every fact-lint source needs a non-empty id and text.');
+    const claims = extractFactClaims(input.draft);
+    const sourceLines = sourceSentences(input.sources);
+    const findings = [];
+    const semanticAdapter = input.semanticAdapter && (!input.semanticAdapter.external || input.allowExternalSemantic) ? input.semanticAdapter : undefined;
+    const approved = new Set(input.metadata?.approvedHypotheses?.map(normal) ?? []);
+    const allowed = new Set(input.metadata?.allowedAssumptions?.map(normal) ?? []);
+    for (const claim of claims) {
+        if (claim.kinds.includes('opinion') || allowed.has(normal(claim.text)) || (claim.kinds.includes('hypothesis') && approved.has(normal(claim.text))))
+            continue;
+        const relevant = findRelevant(claim.text, sourceLines);
+        const same = sourceLines.find(({ text }) => hasOverlap(claim.text, text));
+        const evidenceItems = relevant.length ? relevant.slice(0, 2).map(({ source, text }) => evidence(source, text)) : fallbackEvidence(sourceLines);
+        const quote = claim.text.match(QUOTE)?.[1];
+        const quoteRelevant = sourceLines.filter(({ text }) => /\b(said|according to|reported)\b/i.test(text));
+        if (quote && input.sources.some((source) => /\b(said|according to|reported)\b/i.test(source.text)) && !input.sources.some((source) => source.text.includes(quote))) {
+            const quoteEvidence = quoteRelevant.length ? quoteRelevant.slice(0, 2).map(({ source, text }) => evidence(source, text)) : input.sources.slice(0, 1).map((source) => evidence(source, source.text));
+            findings.push(finding(claim, 'quote_drift', 'error', 'The quoted wording differs from the supplied source.', quoteEvidence, 'high', 'Use the source wording or label the text as a paraphrase.'));
+            continue;
+        }
+        const claimDates = dates(claim.text);
+        const sourceDates = relevant.flatMap(({ text }) => dates(text));
+        const claimNumbers = numbers(claim.text);
+        const sourceNumbers = relevant.flatMap(({ text }) => numbers(text));
+        if (!claimDates.length && !claim.kinds.includes('attribution_quote') && claimNumbers.length && sourceNumbers.length && claimNumbers.some((number) => !sourceNumbers.some((sourceNumber) => normal(sourceNumber) === normal(number)))) {
+            findings.push(finding(claim, 'number_drift', 'error', 'A number or unit differs from relevant source evidence.', evidenceItems, 'high', 'Correct the number or unit, or cite a newer source.'));
+            continue;
+        }
+        if (claimDates.length && sourceDates.length && claimDates.some((date) => !sourceDates.includes(date))) {
+            findings.push(finding(claim, 'date_drift', 'error', 'The draft date differs from relevant source evidence.', evidenceItems, 'high', 'Correct the date or cite a newer source.'));
+            continue;
+        }
+        const claimEntities = entities(claim.text);
+        const sourceEntities = relevant.flatMap(({ text }) => entities(text));
+        if (claimEntities.length && sourceEntities.length && claimEntities.some((entity) => !sourceEntities.some((sourceEntity) => normal(sourceEntity) === normal(entity)))) {
+            findings.push(finding(claim, 'entity_drift', 'error', 'A named entity differs from relevant source evidence.', evidenceItems, 'high', 'Correct the name or cite the source that supports it.'));
+            continue;
+        }
+        const claimCapabilities = capabilityObjects(claim.text);
+        if (claimCapabilities.length && relevant.length) {
+            const sourceCapabilities = relevant.flatMap(({ text }) => capabilityObjects(text));
+            const supportedCapability = claimCapabilities.every((capability) => sourceCapabilities.some((sourceCapability) => capability.every((token) => sourceCapability.includes(token))));
+            if (supportedCapability && relevant.some(({ text }) => negated(text) !== negated(claim.text))) {
+                findings.push(finding(claim, 'capability_drift', 'error', 'The draft reverses the source capability.', evidenceItems, 'high', 'Match the source capability polarity or cite contrary evidence.'));
+                continue;
+            }
+            if (supportedCapability)
+                continue;
+            const knownFormatMismatch = claimCapabilities.some((capability) => {
+                const claimFormats = capability.filter((token) => CAPABILITY_FORMATS.has(token));
+                return claimFormats.length > 0 && sourceCapabilities.some((sourceCapability) => {
+                    const sourceFormats = sourceCapability.filter((token) => CAPABILITY_FORMATS.has(token));
+                    return sourceFormats.length > 0 && claimFormats.some((format) => !sourceFormats.includes(format));
+                });
+            });
+            if (knownFormatMismatch) {
+                findings.push(finding(claim, 'capability_drift', 'error', 'The product capability differs from the supplied source.', evidenceItems, 'high', 'Match the source capability or cite contrary evidence.'));
+                continue;
+            }
+            findings.push(finding(claim, 'missing_evidence', 'needs_human_review', 'The product capability is not established by the relevant source wording.', evidenceItems, 'medium', 'Confirm the capability with a reviewer or add evidence.'));
+            continue;
+        }
+        const causalOverreach = claim.kinds.includes('causal') && relevant.length && !relevant.some(({ text }) => /\b(caused?|because|led to|resulted in)\b/i.test(text));
+        const comparativeOverreach = claim.kinds.includes('comparative') && relevant.length && !relevant.some(({ text }) => /\b(better|more|less|than|best|largest|fastest)\b/i.test(text));
+        if (causalOverreach)
+            findings.push(finding(claim, 'causal_overreach', 'warning', 'The sources describe an outcome but do not establish causation.', evidenceItems, 'medium', 'Use an association claim or add causal evidence.'));
+        if (comparativeOverreach)
+            findings.push(finding(claim, 'comparative_overreach', 'warning', 'The sources do not establish the comparison.', evidenceItems, 'medium', 'Narrow the comparison or add comparative evidence.'));
+        if (causalOverreach || comparativeOverreach)
+            continue;
+        if (claimDates.length && claimDates.some((date) => sourceDates.includes(date)))
+            continue;
+        if (same)
+            continue;
+        if (!relevant.length && claim.kinds.includes('fact') && tokens(claim.text).length <= 4) {
+            findings.push(finding(claim, 'missing_evidence', 'needs_human_review', 'No close source evidence was found; the wording is too sparse for a reliable deterministic verdict.', evidenceItems, 'low', 'Confirm with a reviewer or provide a source.'));
+            continue;
+        }
+        if ((!relevant.length || (claim.kinds.includes('number') && !relevant.some(({ text }) => /\b\d+(?:\.\d+)?%?\b/.test(text))))) {
+            findings.push(finding(claim, 'unsupported_claim', 'error', 'No supplied source supports this checkable claim.', evidenceItems, 'medium', 'Add a source, remove the claim, or mark it as an approved hypothesis.'));
+            continue;
+        }
+        const semantic = semanticAdapter?.compare({ claim: claim.text, sources: input.sources });
+        if (semantic === 'supported')
+            continue;
+        if (semantic === 'contradicted') {
+            findings.push(finding(claim, 'semantic_contradiction', 'error', 'The configured semantic adapter found contradictory source evidence.', evidenceItems, 'medium', 'Review the cited sources and correct or qualify the claim.'));
+            continue;
+        }
+        findings.push(finding(claim, 'missing_evidence', 'needs_human_review', 'Relevant source material exists, but deterministic matching could not establish support.', evidenceItems, 'low', 'Review the source context or enable an approved semantic adapter.'));
+    }
+    const normalizedClaims = claims.map((claim) => ({ claim, text: normal(claim.text) }));
+    for (let index = 0; index < normalizedClaims.length; index += 1)
+        for (let other = index + 1; other < normalizedClaims.length; other += 1) {
+            const left = normalizedClaims[index];
+            const right = normalizedClaims[other];
+            const leftCore = normal(left.text.replace(/\bnot\b/g, ''));
+            const rightCore = normal(right.text.replace(/\bnot\b/g, ''));
+            if (leftCore === rightCore && /\bnot\b/.test(left.text) !== /\bnot\b/.test(right.text)) {
+                findings.push(finding(right.claim, 'draft_contradiction', 'error', 'This draft claim contradicts an earlier draft claim.', fallbackEvidence(sourceLines), 'high', 'Resolve the two claims before publishing.'));
+            }
+        }
+    const claimKey = (item) => `${item.draftLocation.start}:${item.draftLocation.end}`;
+    const unsupported = new Set(findings.filter((item) => item.kind === 'unsupported_claim').map(claimKey)).size;
+    const contradicted = new Set(findings.filter((item) => ['draft_contradiction', 'number_drift', 'date_drift', 'entity_drift', 'quote_drift', 'capability_drift', 'semantic_contradiction'].includes(item.kind)).map(claimKey)).size;
+    const humanReview = new Set(findings.filter((item) => item.severity === 'needs_human_review' || item.severity === 'warning').map(claimKey)).size;
+    const checked = claims.filter((claim) => !claim.kinds.includes('opinion')).length;
+    const affected = new Set(findings.map(claimKey)).size;
+    return { version: '1', summary: { checked, supported: Math.max(0, checked - affected), unsupported, contradicted, humanReview }, claims, findings, skippedChecks: semanticAdapter ? [] : ['semantic_matching'] };
+}
+export function formatFactLintReport(report) {
+    const lines = [`fact lint: ${report.summary.checked} checked, ${report.summary.supported} supported, ${report.findings.length} findings`];
+    for (const item of report.findings)
+        lines.push(`${item.severity} ${item.kind} s${item.draftLocation.sentence} [${item.evidence[0]?.sourceId ?? 'no-source'}]: ${item.reason}`);
+    if (report.skippedChecks.length)
+        lines.push(`skipped: ${report.skippedChecks.join(', ')}`);
+    return lines.join('\n');
+}

package/dist/fact-linter.test.js

@@ -0,0 +1,85 @@
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import test from 'node:test';
+import { lintFacts } from './fact-linter.js';
+test('supports evidence-backed facts and harmless paraphrases', () => {
+    const report = lintFacts({
+        sources: [{ id: 'release-notes', text: 'Acme launched Atlas on 14 August 2026. Atlas exports reports as CSV.' }],
+        draft: 'Atlas shipped on August 14, 2026. It can export reports as CSV.',
+    });
+    assert.equal(report.summary.supported, 2);
+    assert.equal(report.findings.length, 0);
+});
+test('flags numeric, date, entity, quote, and capability drift with exact evidence', () => {
+    const report = lintFacts({
+        sources: [{ id: 'brief', text: 'Maya Chen said, "We support 12 teams." The launch is on 14 August 2026. Atlas exports CSV reports.' }],
+        draft: 'Maya Chan said, "We support 20 teams." The launch is on 15 August 2026. Atlas exports PDF reports.',
+    });
+    assert.deepEqual(new Set(report.findings.map((finding) => finding.kind)), new Set(['entity_drift', 'quote_drift', 'date_drift', 'capability_drift']));
+    assert.ok(report.findings.every((finding) => finding.evidence[0]?.sourceId === 'brief' && finding.evidence[0]?.excerpt));
+});
+test('flags numeric values and units that differ from relevant evidence', () => {
+    const report = lintFacts({ sources: [{ id: 'brief', text: 'Acme retains exports for 12 days.' }], draft: 'Acme retains exports for 12 hours.' });
+    assert.equal(report.findings[0]?.kind, 'number_drift');
+});
+test('flags a capability whose polarity reverses the supplied source', () => {
+    const report = lintFacts({ sources: [{ id: 'brief', text: 'Atlas supports CSV exports.' }], draft: 'Atlas does not support CSV exports.' });
+    assert.equal(report.findings[0]?.kind, 'capability_drift');
+});
+test('routes an unsupported product capability to human review', () => {
+    const report = lintFacts({ sources: [{ id: 'brief', text: 'Atlas supports CSV exports.' }], draft: 'Atlas supports real-time API alerts.' });
+    assert.equal(report.findings[0]?.kind, 'missing_evidence');
+    assert.equal(report.findings[0]?.severity, 'needs_human_review');
+});
+test('routes sparse overlap without a matching predicate to human review', () => {
+    const report = lintFacts({ sources: [{ id: 'brief', text: 'Harbor Studio exists.' }], draft: 'Harbor Studio grows.' });
+    assert.equal(report.findings[0]?.kind, 'missing_evidence');
+    assert.equal(report.findings[0]?.severity, 'needs_human_review');
+});
+test('flags a single-token product name that drifts from source evidence', () => {
+    const report = lintFacts({ sources: [{ id: 'brief', text: 'Atlas exports CSV reports.' }], draft: 'Atlus exports CSV reports.' });
+    assert.equal(report.findings[0]?.kind, 'entity_drift');
+});
+test('flags unsupported facts and draft-internal contradictions', () => {
+    const report = lintFacts({
+        sources: [{ id: 'brief', text: 'The service is available in India.' }],
+        draft: 'The service is available in India. The service is not available in India. The service has 99.99% uptime.',
+    });
+    assert.ok(report.findings.some((finding) => finding.kind === 'draft_contradiction'));
+    assert.ok(report.findings.some((finding) => finding.kind === 'unsupported_claim'));
+});
+test('treats causal and comparative overreach as reviewable material problems', () => {
+    const report = lintFacts({
+        sources: [{ id: 'study', text: 'After the training, support tickets fell from 12 to 8. The study did not test causes or competitors.' }],
+        draft: 'The training caused support tickets to fall and is better than every alternative.',
+    });
+    assert.deepEqual(new Set(report.findings.map((finding) => finding.kind)), new Set(['causal_overreach', 'comparative_overreach']));
+});
+test('does not flag opinions or approved hypotheses, and routes ambiguous gaps to human review', () => {
+    const report = lintFacts({
+        sources: [{ id: 'brief', text: 'The team is exploring a mobile app.' }],
+        draft: 'I think the mobile app is a good idea. The app may reduce churn. The team is popular.',
+        metadata: { approvedHypotheses: ['The app may reduce churn.'], allowedAssumptions: ['The team is popular.'] },
+    });
+    assert.equal(report.findings.some((finding) => finding.claim.includes('good idea')), false);
+    assert.equal(report.findings.some((finding) => finding.claim.includes('may reduce churn')), false);
+    assert.equal(report.findings.some((finding) => finding.claim.includes('popular')), false);
+});
+test('reports skipped semantic checks unless an explicitly configured adapter runs them', () => {
+    const report = lintFacts({ sources: [{ id: 'brief', text: 'Atlas exists.' }], draft: 'Atlas exists.' });
+    assert.deepEqual(report.skippedChecks, ['semantic_matching']);
+    const external = { id: 'remote', external: true, compare: () => 'supported' };
+    assert.deepEqual(lintFacts({ sources: [{ id: 'brief', text: 'Atlas exists.' }], draft: 'Atlas exists.', semanticAdapter: external }).skippedChecks, ['semantic_matching']);
+    assert.deepEqual(lintFacts({ sources: [{ id: 'brief', text: 'Atlas exists.' }], draft: 'Atlas exists.', semanticAdapter: external, allowExternalSemantic: true }).skippedChecks, []);
+    const contradicted = lintFacts({ sources: [{ id: 'brief', text: 'Atlas exists.' }], draft: 'Atlas is reliable.', semanticAdapter: { id: 'local', compare: () => 'contradicted' } });
+    assert.equal(contradicted.findings[0]?.kind, 'semantic_contradiction');
+});
+test('keeps twenty synthetic source-grounded posts as supported regression fixtures', () => {
+    const fixture = new URL('../fixtures/fact-linter/posts.json', import.meta.url);
+    const posts = JSON.parse(readFileSync(fixture, 'utf8'));
+    assert.equal(posts.length, 20);
+    for (const post of posts) {
+        const report = lintFacts({ sources: [{ id: post.id, text: post.source }], draft: post.draft });
+        assert.equal(report.findings.filter((finding) => finding.severity === 'error').length, 0, post.id);
+    }
+});

package/dist/hidden-text.js

@@ -0,0 +1,77 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson } from './canonical-json.js';
+const ACKNOWLEDGEMENT = 'Removes only listed non-semantic controls; all other findings remain review-only.';
+export const minimalHiddenTextPolicy = {
+    version: '1', name: 'minimal-text-control-cleanup', approvedRemovals: ['ascii_control', 'mid_document_bom'], acknowledgement: ACKNOWLEDGEMENT,
+};
+function hash(value) { return createHash('sha256').update(typeof value === 'string' ? value : canonicalJson(value)).digest('hex'); }
+function codepoint(value) { return `U+${value.toString(16).toUpperCase().padStart(4, '0')}`; }
+export function parseHiddenTextPolicy(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Hidden-text policy must be an object.');
+    const policy = value;
+    const removals = policy.approvedRemovals;
+    if (policy.version !== '1' || policy.name !== 'minimal-text-control-cleanup' || policy.acknowledgement !== ACKNOWLEDGEMENT
+        || !Array.isArray(removals) || removals.some((item) => item !== 'ascii_control' && item !== 'mid_document_bom')
+        || new Set(removals).size !== removals.length)
+        throw new Error('Hidden-text policy is not valid.');
+    return { ...policy, approvedRemovals: [...removals] };
+}
+function classified(codepointValue, offset) {
+    if ((codepointValue <= 0x1f && ![0x09, 0x0a, 0x0d].includes(codepointValue)) || codepointValue === 0x7f)
+        return { kind: 'ascii_control', action: 'remove', reason: 'ASCII control is not permitted in user-facing text.' };
+    if (codepointValue >= 0x80 && codepointValue <= 0x9f)
+        return { kind: 'c1_control', action: 'review', reason: 'C1 controls can change terminal or renderer behavior.' };
+    if (codepointValue === 0xfeff && offset > 0)
+        return { kind: 'mid_document_bom', action: 'remove', reason: 'A byte-order mark is only valid at document start.' };
+    if ([0x200b, 0x200c, 0x200d, 0x2060, 0x180e].includes(codepointValue))
+        return { kind: 'zero_width', action: 'review', reason: 'May be required for script shaping or word boundaries.' };
+    if ([0x061c, 0x200e, 0x200f, 0x202a, 0x202b, 0x202c, 0x202d, 0x202e, 0x2066, 0x2067, 0x2068, 0x2069].includes(codepointValue))
+        return { kind: 'bidi', action: 'review', reason: 'May be required for bidirectional text.' };
+    if (codepointValue >= 0xe0001 && codepointValue <= 0xe007f)
+        return { kind: 'tag', action: 'review', reason: 'Unicode tags can be meaningful in emoji sequences.' };
+    if ([0x00a0, 0x1680, 0x2000, 0x2001, 0x2002, 0x2003, 0x2004, 0x2005, 0x2006, 0x2007, 0x2008, 0x2009, 0x200a, 0x202f, 0x205f, 0x3000].includes(codepointValue))
+        return { kind: 'unusual_space', action: 'review', reason: 'Spacing may be intentional or language-specific.' };
+    return undefined;
+}
+export function inspectHiddenText(text, policy = minimalHiddenTextPolicy) {
+    const parsed = parseHiddenTextPolicy(policy);
+    const findings = [];
+    for (let offset = 0; offset < text.length;) {
+        const value = text.codePointAt(offset);
+        const found = classified(value, offset);
+        if (found) {
+            const action = found.action === 'remove' && !parsed.approvedRemovals.includes(found.kind) ? 'review' : found.action;
+            findings.push({ kind: found.kind, action, codepoint: codepoint(value), offset, reason: found.reason });
+        }
+        offset += String.fromCodePoint(value).length;
+    }
+    return { version: '1', inputHash: hash(text), policyFingerprint: hash(parsed), findings, proposedChanges: findings.filter((item) => item.action === 'remove').map((item) => ({ offset: item.offset, codepoint: item.codepoint, action: 'removed' })) };
+}
+export function applyHiddenTextPolicy(text, policy = minimalHiddenTextPolicy) {
+    const report = inspectHiddenText(text, policy);
+    const offsets = new Set(report.proposedChanges.map((item) => item.offset));
+    let output = '';
+    for (let offset = 0; offset < text.length;) {
+        const value = text.codePointAt(offset);
+        const character = String.fromCodePoint(value);
+        if (!offsets.has(offset))
+            output += character;
+        offset += character.length;
+    }
+    const remaining = inspectHiddenText(output, policy).findings;
+    const again = applyOnce(output, policy);
+    return { ...report, outputHash: hash(output), output, remaining, idempotent: again === output };
+}
+function applyOnce(text, policy) {
+    const offsets = new Set(inspectHiddenText(text, policy).proposedChanges.map((item) => item.offset));
+    let output = '';
+    for (let offset = 0; offset < text.length;) {
+        const value = text.codePointAt(offset);
+        const character = String.fromCodePoint(value);
+        if (!offsets.has(offset))
+            output += character;
+        offset += character.length;
+    }
+    return output;
+}

package/dist/hidden-text.test.js

@@ -0,0 +1,26 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { applyHiddenTextPolicy, inspectHiddenText, minimalHiddenTextPolicy, parseHiddenTextPolicy } from './hidden-text.js';
+test('removes only explicitly approved ASCII controls and mid-document BOMs with a stable receipt', () => {
+    const source = 'start\u0007middle\uFEFFend';
+    const receipt = applyHiddenTextPolicy(source);
+    assert.equal(receipt.output, 'startmiddleend');
+    assert.deepEqual(receipt.proposedChanges.map((item) => [item.codepoint, item.offset]), [['U+0007', 5], ['U+FEFF', 12]]);
+    assert.equal(receipt.remaining.length, 0);
+    assert.equal(receipt.idempotent, true);
+    assert.notEqual(receipt.inputHash, receipt.outputHash);
+});
+test('keeps bidi, script joiners, emoji joiners, Markdown and tabs review-only', () => {
+    const source = '```ts\nconst x = 1;\n```\nالعربية\u202E ไทย\u200Bภาษา 👩\u200D💻\tend';
+    const report = inspectHiddenText(source);
+    const receipt = applyHiddenTextPolicy(source);
+    assert.equal(receipt.output, source);
+    assert.equal(receipt.proposedChanges.length, 0);
+    assert.ok(report.findings.some((item) => item.kind === 'bidi' && item.action === 'review'));
+    assert.ok(report.findings.some((item) => item.kind === 'zero_width' && item.action === 'review'));
+});
+test('requires the exact policy shape and never broadens removals from malformed input', () => {
+    assert.deepEqual(parseHiddenTextPolicy(minimalHiddenTextPolicy), minimalHiddenTextPolicy);
+    assert.throws(() => parseHiddenTextPolicy({ ...minimalHiddenTextPolicy, approvedRemovals: ['zero_width'] }), /not valid/);
+    assert.throws(() => parseHiddenTextPolicy({ ...minimalHiddenTextPolicy, acknowledgement: 'watermark removed' }), /not valid/);
+});

package/dist/hygiene.js

@@ -24,13 +24,20 @@ function formattedCodepoint(codepoint) {
     return `U+${codepoint.toString(16).toUpperCase().padStart(4, '0')}`;
 }
 function classification(codepoint) {
+    if ((codepoint <= 0x1f && ![0x09, 0x0a, 0x0d].includes(codepoint)) || codepoint === 0x7f) {
+        return { kind: 'ascii_control', label: 'ASCII control character', fix: 'remove' };
+    }
+    if (codepoint >= 0x80 && codepoint <= 0x9f)
+        return { kind: 'c1_control', label: 'C1 control character', fix: 'none' };
     return CHARACTER_POLICIES.get(codepoint) ?? (codepoint >= 0xe0001 && codepoint <= 0xe007f
         ? { kind: 'tag', label: 'Unicode tag character', fix: 'none' }
         : undefined);
 }
 function policyAt(codepoint, offset) {
     const policy = classification(codepoint);
-    return codepoint === 0xfeff && offset === 0 && policy ? { ...policy, fix: 'remove' } : policy;
+    if (codepoint === 0xfeff && policy)
+        return { ...policy, kind: offset === 0 ? 'zero_width' : 'mid_document_bom', fix: 'remove' };
+    return policy;
 }
 function scanHygiene(text, clean) {
     const grouped = new Map();

package/dist/hygiene.test.js

@@ -14,14 +14,14 @@ test('reports zero-width, bidi, tag, and unusual-space characters with exact off
     ]);
     assert.deepEqual(report.hits.find((hit) => hit.codepoint === 'U+E0001')?.offsets, [13]);
 });
-test('removes only a leading byte-order mark and preserves language, spacing, bidi, and tag controls', () => {
+test('removes byte-order marks and preserves language, spacing, bidi, and tag controls', () => {
     const text = `\uFEFFa\u200Bb\uFEFFc\u00A0d\u200Ce\u200Df\u202Eg\u{E0001}`;
     const result = cleanHygiene(text);
-    assert.equal(result.cleaned, `a\u200Bb\uFEFFc\u00A0d\u200Ce\u200Df\u202Eg\u{E0001}`);
+    assert.equal(result.cleaned, `a\u200Bbc\u00A0d\u200Ce\u200Df\u202Eg\u{E0001}`);
     assert.equal(result.changed, true);
-    assert.deepEqual(result.changes.map((change) => [change.codepoint, change.action]), [['U+FEFF', 'removed']]);
+    assert.deepEqual(result.changes.map((change) => [change.codepoint, change.action]), [['U+FEFF', 'removed'], ['U+FEFF', 'removed']]);
     assert.equal(result.report.suspiciousCount, 8);
-    assert.equal(result.report.fixableCount, 1);
+    assert.equal(result.report.fixableCount, 2);
 });
 test('leaves clean text byte-for-byte unchanged', () => {
     const text = 'plain text\nwith normal spaces.';
@@ -54,7 +54,7 @@ test('preserves multilingual spacing and word-boundary controls byte-for-byte',
     assert.equal(result.report.suspiciousCount, 5);
     assert.equal(result.report.fixableCount, 0);
 });
-test('accepts exact clean output and minimally removes only a leading BOM', () => {
+test('accepts exact clean output and removes only non-semantic controls by default', () => {
     const clean = finalOutputCheck('exact output\n');
     assert.equal(clean.accepted, true);
     assert.equal(clean.accepted && clean.output, 'exact output\n');
@@ -63,6 +63,10 @@ test('accepts exact clean output and minimally removes only a leading BOM', () =
     assert.equal(bom.accepted, true);
     assert.equal(bom.accepted && bom.output, 'exact output');
     assert.deepEqual(bom.changes, [{ offset: 0, codepoint: 'U+FEFF', action: 'removed' }]);
+    const controls = finalOutputCheck('one\u0007two\uFEFFthree');
+    assert.equal(controls.accepted, true);
+    assert.equal(controls.accepted && controls.output, 'onetwothree');
+    assert.deepEqual(controls.changes.map((change) => change.codepoint), ['U+0007', 'U+FEFF']);
 });
 test('withholds output when hidden characters remain unresolved', () => {
     const result = finalOutputCheck('Thai\u200Bboundary 👩\u200D💻');
@@ -71,3 +75,9 @@ test('withholds output when hidden characters remain unresolved', () => {
     assert.equal(result.changed, false);
     assert.deepEqual(result.remaining.hits.map((hit) => hit.codepoint), ['U+200B', 'U+200D']);
 });
+test('withholds C1 controls rather than removing them', () => {
+    const result = finalOutputCheck('safe\u009Bhidden');
+    assert.equal(result.accepted, false);
+    assert.equal('output' in result, false);
+    assert.deepEqual(result.remaining.hits.map((hit) => [hit.codepoint, hit.kind]), [['U+009B', 'c1_control']]);
+});

package/dist/mcp-tools.js

@@ -6,7 +6,8 @@ import { analyze, rewritePrompt, verify, verifyWithCopySpec } from './pipeline.j
 import { parseProfile } from './profile.js';
 import { evaluateRewriteResponse, parseRewriteTask, prepareRewriteTask } from './rewrite-task.js';
 import { parseJudgmentEnvelope, preparePostCandidateJudgment, preparePreEditJudgment, reducePostCandidate, reducePreEdit } from './judgment-task.js';
-import { evaluateRebuildResponse, parseRebuildTask, prepareRebuildTask } from './rebuild-task.js';
+import { evaluateRebuildResponse, parseRebuildTask, prepareRebuildTask, writerRequestForRebuild } from './rebuild-task.js';
+import { inspectHiddenText, applyHiddenTextPolicy, parseHiddenTextPolicy } from './hidden-text.js';
 import { buildProfile } from './voice-dna.js';
 import { finalOutputCheck, inspectHygiene } from './hygiene.js';
 import { finalizeLifecycle, inspectLifecycle, prepareLifecycle, recordApprovedLearning, submitSemanticVerdict, validateFinalApproval } from './lifecycle-adapter.js';
@@ -74,12 +75,21 @@ export function reduceJudgmentForMcp(envelopesJson) {
     const envelopes = parsed(envelopesJson, 'Judgment envelopes').map(parseJudgmentEnvelope);
     return envelopes[0]?.stage === 'pre-edit' ? reducePreEdit(envelopes) : reducePostCandidate(envelopes);
 }
-export function prepareRebuildForMcp(draft, profileJson, reductionJson, copySpecJson, capabilityJson, context, writingBriefJson) {
-    return prepareRebuildTask(draft, profileFromJson(profileJson), parsed(reductionJson, 'Rebuild recommendation'), copySpecFromJson(copySpecJson), parsed(capabilityJson, 'Approval capability'), context.trustStore, context.now, writingBriefFromJson(writingBriefJson));
+export function prepareRebuildForMcp(draft, profileJson, reductionJson, copySpecJson, capabilityJson, context, writingBriefJson, recompositionPolicyJson) {
+    return prepareRebuildTask(draft, profileFromJson(profileJson), parsed(reductionJson, 'Rebuild recommendation'), copySpecFromJson(copySpecJson), parsed(capabilityJson, 'Approval capability'), context.trustStore, context.now, writingBriefFromJson(writingBriefJson), recompositionPolicyJson ? parsed(recompositionPolicyJson, 'Recomposition policy') : undefined);
 }
 export function applyRebuildForMcp(taskJson, responseJson, profileJson, capabilityJson, context) {
     return evaluateRebuildResponse(parseRebuildTask(JSON.parse(taskJson)), responseJson, profileFromJson(profileJson), parsed(capabilityJson, 'Approval capability'), context.trustStore, context.now);
 }
+export function inspectHiddenTextForMcp(text, policyJson) {
+    return inspectHiddenText(text, policyJson ? parseHiddenTextPolicy(parsed(policyJson, 'Hidden-text policy')) : undefined);
+}
+export function applyHiddenTextPolicyForMcp(text, policyJson) {
+    return applyHiddenTextPolicy(text, parseHiddenTextPolicy(parsed(policyJson, 'Hidden-text policy')));
+}
+export function rebuildWriterRequestForMcp(taskJson) {
+    return writerRequestForRebuild(parseRebuildTask(parsed(taskJson, 'Rebuild task')));
+}
 export function verifyForMcp(original, candidate, profileJson, writingBriefJson) {
     const profile = profileFromJson(profileJson);
     return verify(original, candidate, profile, writingBriefFromJson(writingBriefJson));

package/dist/mcp-tools.test.js

@@ -4,7 +4,7 @@ import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import test from 'node:test';
-import { analyzeBatchForMcp, analyzeForMcp, applyRebuildForMcp, applyRewriteForMcp, buildProfileForMcp, clearLearningForMcp, finalOutputCheckForMcp, finalizeLifecycleForMcp, inspectHygieneForMcp, inspectLearningForMcp, inspectLifecycleForMcp, patternsForMcp, prepareJudgmentForMcp, prepareLifecycleForMcp, prepareRebuildForMcp, prepareRewriteForMcp, ratifyLearningForMcp, recordApprovedLearningForMcp, recordLearningForMcp, reduceJudgmentForMcp, rewritePromptForMcp, submitSemanticVerdictForMcp, supersedeLearningForMcp, validateFinalApprovalForMcp, verifyCopySpecForMcp, verifyForMcp } from './mcp-tools.js';
+import { analyzeBatchForMcp, analyzeForMcp, applyHiddenTextPolicyForMcp, applyRebuildForMcp, applyRewriteForMcp, buildProfileForMcp, clearLearningForMcp, finalOutputCheckForMcp, finalizeLifecycleForMcp, inspectHiddenTextForMcp, inspectHygieneForMcp, inspectLearningForMcp, inspectLifecycleForMcp, patternsForMcp, prepareJudgmentForMcp, prepareLifecycleForMcp, prepareRebuildForMcp, prepareRewriteForMcp, ratifyLearningForMcp, recordApprovedLearningForMcp, recordLearningForMcp, rebuildWriterRequestForMcp, reduceJudgmentForMcp, rewritePromptForMcp, submitSemanticVerdictForMcp, supersedeLearningForMcp, validateFinalApprovalForMcp, verifyCopySpecForMcp, verifyForMcp } from './mcp-tools.js';
 import { canonicalJson } from './canonical-json.js';
 const profile = buildProfileForMcp(['I write clearly. I keep the useful detail.', 'I make the call. Then I explain the trade-off.'], ['leverage']);
 const profileJson = JSON.stringify(profile);
@@ -23,6 +23,14 @@ test('inspects Unicode hygiene through MCP without a voice profile', () => {
     assert.equal(result.suspiciousCount, 2);
     assert.equal(result.fixableCount, 0);
 });
+test('applies only explicit hidden-text removals through MCP', () => {
+    const policy = JSON.stringify({ version: '1', name: 'minimal-text-control-cleanup', approvedRemovals: ['ascii_control'], acknowledgement: 'Removes only listed non-semantic controls; all other findings remain review-only.' });
+    const inspected = inspectHiddenTextForMcp('one\u0007two\uFEFFthree\u200D', policy);
+    assert.deepEqual(inspected.proposedChanges.map((change) => change.codepoint), ['U+0007']);
+    const applied = applyHiddenTextPolicyForMcp('one\u0007two\uFEFFthree\u200D', policy);
+    assert.equal(applied.output, 'onetwo\uFEFFthree\u200D');
+    assert.equal(applied.idempotent, true);
+});
 test('gates exact final output through MCP without a voice profile', () => {
     const accepted = finalOutputCheckForMcp('exact output');
     assert.equal(accepted.accepted && accepted.output, 'exact output');
@@ -226,11 +234,16 @@ test('prepares and evaluates authorized rebuild through MCP helpers', () => {
     const capability = { payload: payload.toString('base64url'), signature: sign(null, payload, privateKey).toString('base64url') };
     const copySpec = JSON.stringify({ version: '1', audience: 'operators', intent: 'explain', channel: 'email', claims: [{ id: 'launch-date', text: 'The launch is on 14 August.', evidence: 'Release calendar, 7 August.' }] });
     const context = { now: 150, trustStore, authorizedSemanticEvaluatorIds: { normal: [], highAssurance: [] }, authorizedHumanFinalizerIds: [] };
-    const task = prepareRebuildForMcp(draft, profileJson, JSON.stringify(reduction), copySpec, JSON.stringify(capability), context);
+    const policy = JSON.stringify({ version: '1', mode: 'meaning-first', lexicalResidual: { ngramSize: 5, maxSharedNgramFraction: 0, maxLongestSharedRunTokens: 4 }, acknowledgement: 'Measures shared wording only; does not detect or prove removal of a watermark.' });
+    const task = prepareRebuildForMcp(draft, profileJson, JSON.stringify(reduction), copySpec, JSON.stringify(capability), context, undefined, policy);
+    assert.doesNotMatch(task.prompt, /I leverage the answer/);
+    const writerRequest = rebuildWriterRequestForMcp(JSON.stringify(task));
+    assert.doesNotMatch(JSON.stringify(writerRequest), /I leverage the answer|capability|profile/i);
     const result = applyRebuildForMcp(JSON.stringify(task), JSON.stringify({
         version: '1', mode: 'REBUILD', taskFingerprint: task.fingerprint,
         candidate: 'Ship planning now treats one calendar fact as fixed. The launch is on 14 August. Every other sentence in this note is new operational language for the release desk.',
     }), profileJson, JSON.stringify(capability), context);
     assert.equal(result.status, 'needs_semantic_review');
     assert.equal(result.receipt.mode, 'REBUILD');
+    assert.equal(result.receipt.lexicalResidual?.passed, true);
 });

package/dist/mcp.js

@@ -1,7 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
-import { analyzeBatchForMcp, analyzeForMcp, applyRebuildForMcp, applyRewriteForMcp, buildProfileForMcp, clearLearningForMcp, finalOutputCheckForMcp, finalizeLifecycleForMcp, finalizeRejectionForMcp, inspectHygieneForMcp, inspectLearningForMcp, inspectLifecycleForMcp, migrateLearningForMcp, patternsForMcp, prepareJudgmentForMcp, prepareLifecycleForMcp, prepareRebuildForMcp, prepareRewriteForMcp, ratifyLearningForMcp, recordApprovedLearningForMcp, recordLearningForMcp, reduceJudgmentForMcp, rewritePromptForMcp, submitSemanticVerdictForMcp, supersedeLearningForMcp, validateFinalApprovalForMcp, verifyCopySpecForMcp, verifyForMcp } from './mcp-tools.js';
+import { analyzeBatchForMcp, analyzeForMcp, applyHiddenTextPolicyForMcp, applyRebuildForMcp, applyRewriteForMcp, buildProfileForMcp, clearLearningForMcp, finalOutputCheckForMcp, finalizeLifecycleForMcp, finalizeRejectionForMcp, inspectHiddenTextForMcp, inspectHygieneForMcp, inspectLearningForMcp, inspectLifecycleForMcp, migrateLearningForMcp, patternsForMcp, prepareJudgmentForMcp, prepareLifecycleForMcp, prepareRebuildForMcp, prepareRewriteForMcp, ratifyLearningForMcp, rebuildWriterRequestForMcp, recordApprovedLearningForMcp, recordLearningForMcp, reduceJudgmentForMcp, rewritePromptForMcp, submitSemanticVerdictForMcp, supersedeLearningForMcp, validateFinalApprovalForMcp, verifyCopySpecForMcp, verifyForMcp } from './mcp-tools.js';
 import { HYV_VERSION } from './version.js';
 import { loadApprovalContext } from './approval-context.js';
 const writing = z.string().min(1).max(100_000);
@@ -65,6 +65,14 @@ server.registerTool('hyv_hygiene', {
     inputSchema: { draft: hygieneText },
     annotations: { readOnlyHint: true },
 }, async ({ draft }) => json(inspectHygieneForMcp(draft)));
+server.registerTool('hyv_inspect_hidden_text', {
+    description: 'Inspect hidden text controls with a non-mutating policy report. Findings are not watermark verdicts.',
+    inputSchema: { text: hygieneText, policy_json: lifecycleJson.optional() }, annotations: { readOnlyHint: true },
+}, async ({ text, policy_json }) => json(inspectHiddenTextForMcp(text, policy_json)));
+server.registerTool('hyv_apply_hidden_text_policy', {
+    description: 'Apply only explicitly approved minimal hidden-text removals and return hashes, exact changes, and remaining review findings.',
+    inputSchema: { text: hygieneText, policy_json: lifecycleJson }, annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+}, async ({ text, policy_json }) => json(applyHiddenTextPolicyForMcp(text, policy_json)));
 server.registerTool('hyv_final_check', {
     description: 'Gate exact user-facing text from any model, tool, or interface. Returns output only when clean or after removing a leading byte-order mark; unresolved hidden characters withhold output.',
     inputSchema: { text: hygieneText },
@@ -299,11 +307,12 @@ if (redactsSensitiveInputs) {
             copy_spec_json: copySpecJson,
             capability_json: lifecycleJson,
             writing_brief_json: writingBriefJson.optional(),
+            recomposition_policy_json: lifecycleJson.optional(),
         },
         annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
     }, async (args) => {
         try {
-            return json(prepareRebuildForMcp(args.draft, args.profile_json, args.reduction_json, args.copy_spec_json, args.capability_json, loadApprovalContext(), args.writing_brief_json));
+            return json(prepareRebuildForMcp(args.draft, args.profile_json, args.reduction_json, args.copy_spec_json, args.capability_json, loadApprovalContext(), args.writing_brief_json, args.recomposition_policy_json));
         }
         catch {
             return failure(new Error('Rebuild preparation failed.'));
@@ -321,6 +330,17 @@ if (redactsSensitiveInputs) {
             return failure(new Error('Rebuild application failed.'));
         }
     });
+    server.registerTool('hyv_rebuild_writer_request', {
+        description: 'Create the writer-only payload for a prepared rebuild. It excludes source draft, capability, profile body, and validation evidence.',
+        inputSchema: { task_json: lifecycleJson }, annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+    }, async ({ task_json }) => {
+        try {
+            return json(rebuildWriterRequestForMcp(task_json));
+        }
+        catch {
+            return failure(new Error('Writer request could not be prepared.'));
+        }
+    });
 }
 else {
     server.registerTool('hyv_lifecycle_finalize', {