@holdyourvoice/hyv 3.3.1 → 3.3.2

package/dist/mcp.test.js

@@ -64,8 +64,8 @@ test('serves local Claude tools over stdio', async () => {
     assert.equal(code, 0);
     const responses = stdout.trim().split('\n').map((line) => JSON.parse(line));
     const tools = responses.find((response) => response.id === 2)?.result?.tools;
-    assert.deepEqual(tools?.map((tool) => tool.name), ['hyv_build_profile', 'hyv_analyze', 'hyv_hygiene', 'hyv_final_check', 'hyv_rewrite_prompt', 'hyv_prepare_rewrite', 'hyv_apply_rewrite', 'hyv_prepare_judgment', 'hyv_reduce_judgment', 'hyv_verify', 'hyv_verify_copy_spec', 'hyv_batch_analyze', 'hyv_patterns', 'hyv_learning_inspect', 'hyv_learning_record', 'hyv_learning_ratify', 'hyv_learning_supersede', 'hyv_learning_migrate', 'hyv_learning_clear', 'hyv_lifecycle_prepare_semantic', 'hyv_lifecycle_submit_verdict', 'hyv_lifecycle_inspect', 'hyv_lifecycle_finalize']);
-    assert.ok(tools?.filter((tool) => !['hyv_verify', 'hyv_verify_copy_spec', 'hyv_learning_record', 'hyv_learning_ratify', 'hyv_learning_supersede', 'hyv_learning_migrate', 'hyv_learning_clear'].includes(tool.name)).every((tool) => tool.annotations?.readOnlyHint));
+    assert.deepEqual(tools?.map((tool) => tool.name), ['hyv_build_profile', 'hyv_analyze', 'hyv_hygiene', 'hyv_inspect_hidden_text', 'hyv_apply_hidden_text_policy', 'hyv_final_check', 'hyv_rewrite_prompt', 'hyv_prepare_rewrite', 'hyv_apply_rewrite', 'hyv_prepare_judgment', 'hyv_reduce_judgment', 'hyv_verify', 'hyv_verify_copy_spec', 'hyv_batch_analyze', 'hyv_patterns', 'hyv_learning_inspect', 'hyv_learning_record', 'hyv_learning_ratify', 'hyv_learning_supersede', 'hyv_learning_migrate', 'hyv_learning_clear', 'hyv_lifecycle_prepare_semantic', 'hyv_lifecycle_submit_verdict', 'hyv_lifecycle_inspect', 'hyv_lifecycle_finalize']);
+    assert.ok(tools?.filter((tool) => !['hyv_verify', 'hyv_verify_copy_spec', 'hyv_apply_hidden_text_policy', 'hyv_learning_record', 'hyv_learning_ratify', 'hyv_learning_supersede', 'hyv_learning_migrate', 'hyv_learning_clear'].includes(tool.name)).every((tool) => tool.annotations?.readOnlyHint));
     assert.equal(tools?.find((tool) => tool.name === 'hyv_verify')?.annotations?.readOnlyHint, true);
     assert.equal(tools?.find((tool) => tool.name === 'hyv_verify_copy_spec')?.annotations?.readOnlyHint, true);
     assert.equal(tools?.some((tool) => tool.name === 'hyv_lifecycle_validate_final_approval'), false);
@@ -74,6 +74,8 @@ test('serves local Claude tools over stdio', async () => {
     assert.equal(tools?.some((tool) => tool.name === 'hyv_apply_rebuild'), false);
     assert.equal('capability_json' in (tools?.find((tool) => tool.name === 'hyv_lifecycle_finalize')?.inputSchema?.properties ?? {}), false);
     assert.equal(tools?.find((tool) => tool.name === 'hyv_learning_inspect')?.annotations?.readOnlyHint, true);
+    assert.equal(tools?.find((tool) => tool.name === 'hyv_inspect_hidden_text')?.annotations?.readOnlyHint, true);
+    assert.equal(tools?.find((tool) => tool.name === 'hyv_apply_hidden_text_policy')?.annotations?.readOnlyHint, false);
     assert.equal(tools?.find((tool) => tool.name === 'hyv_learning_clear')?.annotations?.readOnlyHint, false);
     assert.deepEqual(tools?.filter((tool) => tool.name.startsWith('hyv_learning_')).map((tool) => [tool.name, tool.annotations?.readOnlyHint, tool.annotations?.destructiveHint]), [
         ['hyv_learning_inspect', true, undefined], ['hyv_learning_record', false, false], ['hyv_learning_ratify', false, false],
@@ -95,11 +97,12 @@ test('registers capability tools only with host redaction attestation', async ()
     assert.equal(stderr, '');
     const response = stdout.trim().split('\n').map((line) => JSON.parse(line)).find((item) => item.id === 2);
     const names = response.result.tools.map((tool) => tool.name);
-    assert.equal(names.length, 27);
+    assert.equal(names.length, 30);
     assert.ok(names.includes('hyv_lifecycle_validate_final_approval'));
     assert.ok(names.includes('hyv_learning_record_approved'));
     assert.ok(names.includes('hyv_prepare_rebuild'));
     assert.ok(names.includes('hyv_apply_rebuild'));
+    assert.ok(names.includes('hyv_rebuild_writer_request'));
     const finalize = response.result.tools.find((tool) => tool.name === 'hyv_lifecycle_finalize');
     assert.equal('capability_json' in finalize.inputSchema.properties, true);
 });

package/dist/pipeline.js

@@ -7,6 +7,8 @@ import { analyzeEditorial } from './editorial-packs.js';
 import { finalOutputCheck, inspectHygiene } from './hygiene.js';
 import { analyzeVoiceDna } from './voice-dna.js';
 import { legacySetPreservation } from './preservation.js';
+import { lintFacts } from './fact-linter.js';
+import { sentences } from './text.js';
 export function analyze(text, profile, brief) {
     const voiceDna = analyzeVoiceDna(text, profile);
     const aiEditor = analyzeAiEditor(text, profile);
@@ -87,15 +89,40 @@ function compareCandidates(original, candidate, profile, brief) {
     const preservation = legacySetPreservation(original, candidate).score;
     return { baseline, checked, regressions, preservation };
 }
+function verifyRequiredFacts(candidate, brief) {
+    if (!brief?.requiredFacts?.length)
+        return undefined;
+    const result = verifyClaims(candidate, {
+        version: '1', audience: brief.audience, intent: brief.intent, channel: brief.format,
+        claims: brief.requiredFacts.map((fact) => ({ ...fact, evidence: 'WritingBrief required fact.' })),
+    });
+    const draftSentences = sentences(candidate);
+    const reversed = brief.requiredFacts.filter((fact) => {
+        const terms = fact.atoms?.length ? fact.atoms : [fact.text];
+        return terms.some((term) => {
+            const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            const quotedDenial = new RegExp(`${escaped}(?:["']|\\s)*(?:is|was|are|were)?\\s*(?:not|false|untrue|incorrect)`, 'i');
+            return quotedDenial.test(candidate) || draftSentences.some((sentence, index) => sentence.text.toLowerCase().includes(term.toLowerCase()) && (/\b(?:not|false|untrue|incorrect)\b/i.test(sentence.text) || /^(?:that|this) (?:statement|claim|fact|assertion|point) (?:is|was) (?:not|false|untrue|incorrect)\b/i.test(draftSentences[index + 1]?.text.trim() ?? '')));
+        });
+    });
+    if (!reversed.length)
+        return result;
+    return { ...result, passed: false, failures: [...result.failures, ...reversed.map((fact) => ({ id: fact.id, code: 'missing_immutable_claim', message: `Required fact ${fact.id} is negated or denied.`, evidence: 'WritingBrief required fact.' }))] };
+}
 export function verify(original, candidate, profile, brief) {
     const { baseline, checked, regressions, preservation } = compareCandidates(original, candidate, profile, brief);
+    const finalOutput = finalOutputCheck(candidate);
+    const factLint = brief?.factSources?.length ? lintFacts({ sources: brief.factSources, draft: candidate, metadata: brief.factMetadata }) : undefined;
+    const requiredFacts = verifyRequiredFacts(candidate, brief);
     return {
         version: '2',
         original: baseline,
         candidate: checked,
         preservationScore: preservation,
         regressions,
-        passed: checked.passed && !regressions.some(isBlockingFinding) && preservation >= 70,
+        finalOutput,
+        ...(factLint ? { factLint } : {}), ...(requiredFacts ? { requiredFacts } : {}),
+        passed: checked.passed && !regressions.some(isBlockingFinding) && preservation >= 70 && finalOutput.accepted && !factLint?.findings.some((finding) => finding.severity === 'error') && (requiredFacts?.passed ?? true),
     };
 }
 export function verifyWithCopySpec(original, candidate, profile, spec, brief) {
@@ -106,8 +133,9 @@ export function verifyWithCopySpec(original, candidate, profile, spec, brief) {
 export function verifyRebuildWithCopySpec(original, candidate, profile, spec, brief) {
     const { baseline, checked, regressions, preservation } = compareCandidates(original, candidate, profile, brief);
     const claims = verifyClaims(candidate, spec);
-    const hygiene = inspectHygiene(candidate);
     const finalCheck = finalOutputCheck(candidate);
+    const factLint = brief?.factSources?.length ? lintFacts({ sources: brief.factSources, draft: candidate, metadata: brief.factMetadata }) : undefined;
+    const requiredFacts = verifyRequiredFacts(candidate, brief);
     return {
         version: '2',
         original: baseline,
@@ -115,7 +143,9 @@ export function verifyRebuildWithCopySpec(original, candidate, profile, spec, br
         preservationScore: preservation,
         regressions,
         claims,
-        passed: checked.passed && !regressions.some(isBlockingFinding) && claims.passed && hygiene.suspiciousCount === 0 && finalCheck.accepted,
+        finalOutput: finalCheck,
+        ...(factLint ? { factLint } : {}), ...(requiredFacts ? { requiredFacts } : {}),
+        passed: checked.passed && !regressions.some(isBlockingFinding) && claims.passed && finalCheck.accepted && !factLint?.findings.some((finding) => finding.severity === 'error') && (requiredFacts?.passed ?? true),
     };
 }
 function digest(value) { return createHash('sha256').update(value).digest('hex'); }

package/dist/pipeline.test.js

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { analyze, rewritePrompt, verify, verifyDeterministically, verifyWithCopySpec } from './pipeline.js';
+import { analyze, rewritePrompt, verify, verifyDeterministically, verifyRebuildWithCopySpec, verifyWithCopySpec } from './pipeline.js';
 import { parseCopySpec } from './copy-spec.js';
 import { parseWritingBrief } from './editorial-packs.js';
 import { buildProfile } from './voice-dna.js';
@@ -32,6 +32,45 @@ test('keeps the existing VoiceDNA and AI Editor reports unchanged when no Writin
     assert.deepEqual(contextual.voiceDna, baseline.voiceDna);
     assert.deepEqual(contextual.aiEditor, baseline.aiEditor);
 });
+test('runs fact lint automatically when a WritingBrief supplies valid local sources', () => {
+    const brief = parseWritingBrief({ version: '1', audience: 'operators', intent: 'explain', format: 'general', factSources: [{ id: 'release', text: 'Atlas launches on 14 August 2026.' }] });
+    const result = verify('Atlas launches on 14 August 2026.', 'Atlas launches on 15 August 2026.', profile, brief);
+    assert.equal(result.factLint?.findings[0]?.kind, 'date_drift');
+    assert.equal(result.passed, false);
+});
+test('blocks a final draft that drops a required source-backed fact', () => {
+    const brief = parseWritingBrief({ version: '1', audience: 'founders', intent: 'write a post', format: 'social', factSources: [{ id: 'bio', text: 'Shashank is a LinkedIn Top Voice.' }], requiredFacts: [{ id: 'linkedin-top-voice', text: 'Shashank is a LinkedIn Top Voice.' }] });
+    const missing = verify('Shashank is a LinkedIn Top Voice.', 'Shashank writes about AI systems.', profile, brief);
+    assert.equal(missing.requiredFacts?.failures[0]?.code, 'missing_immutable_claim');
+    assert.equal(missing.passed, false);
+    const retained = verify('Shashank is a LinkedIn Top Voice.', 'Shashank is a LinkedIn Top Voice. Shashank writes about AI systems.', profile, brief);
+    assert.equal(retained.requiredFacts?.passed, true);
+});
+test('requires source provenance and rejects negated required facts', () => {
+    assert.throws(() => parseWritingBrief({ version: '1', audience: 'founders', intent: 'write a post', format: 'social', requiredFacts: [{ id: 'unsupported', text: 'Mars has two moons.' }] }), /WritingBrief/);
+    assert.throws(() => parseWritingBrief({ version: '1', audience: 'founders', intent: 'write a post', format: 'social', factSources: [{ id: 'denial', text: 'It is false that Shashank is a LinkedIn Top Voice.' }], requiredFacts: [{ id: 'linkedin-top-voice', text: 'Shashank is a LinkedIn Top Voice.' }] }), /WritingBrief/);
+    assert.throws(() => parseWritingBrief({ version: '1', audience: 'founders', intent: 'write a post', format: 'social', factSources: [{ id: 'cross-sentence-denial', text: 'Shashank is a LinkedIn Top Voice. That statement is false.' }], requiredFacts: [{ id: 'linkedin-top-voice', text: 'Shashank is a LinkedIn Top Voice.' }] }), /WritingBrief/);
+    const brief = parseWritingBrief({ version: '1', audience: 'founders', intent: 'write a post', format: 'social', factSources: [{ id: 'bio', text: 'Shashank is a LinkedIn Top Voice.' }], requiredFacts: [{ id: 'linkedin-top-voice', text: 'Shashank is a LinkedIn Top Voice.' }] });
+    const negated = verify('Shashank is a LinkedIn Top Voice.', 'Shashank is not a LinkedIn Top Voice.', profile, brief);
+    assert.equal(negated.requiredFacts?.passed, false);
+    const denied = verify('Shashank is a LinkedIn Top Voice.', 'The claim "Shashank is a LinkedIn Top Voice." is false.', profile, brief);
+    assert.equal(denied.requiredFacts?.passed, false);
+    assert.match(denied.requiredFacts?.failures.at(-1)?.message ?? '', /negated or denied/);
+    const crossSentenceDenial = verify('Shashank is a LinkedIn Top Voice.', 'Shashank is a LinkedIn Top Voice. That statement is false.', profile, brief);
+    assert.equal(crossSentenceDenial.requiredFacts?.passed, false);
+    const affirmed = verify('Shashank is a LinkedIn Top Voice.', 'This is not a controversial claim. Shashank is a LinkedIn Top Voice.', profile, brief);
+    assert.equal(affirmed.requiredFacts?.passed, true);
+    const atomBrief = parseWritingBrief({ version: '1', audience: 'founders', intent: 'write a post', format: 'social', factSources: [{ id: 'model', text: 'Kimi K2.6 uses INT4 weights. The payload is roughly 600 GB.' }], requiredFacts: [{ id: 'model-weights', text: 'Kimi K2.6 has roughly 600 GB of INT4 weights.', atoms: ['Kimi K2.6 uses INT4 weights', 'payload is roughly 600 GB'] }] });
+    const atomDenial = verify('Kimi K2.6 has roughly 600 GB of INT4 weights.', 'Kimi K2.6 uses INT4 weights, which is false. The payload is roughly 600 GB.', profile, atomBrief);
+    assert.equal(atomDenial.requiredFacts?.passed, false);
+});
+test('runs fact lint during source-backed rebuild verification', () => {
+    const brief = parseWritingBrief({ version: '1', audience: 'operators', intent: 'explain', format: 'general', factSources: [{ id: 'release', text: 'Atlas launches on 14 August 2026.' }] });
+    const spec = parseCopySpec({ version: '1', audience: 'operators', intent: 'explain', channel: 'email', claims: [{ id: 'date', text: 'Atlas launches on 15 August 2026.', evidence: 'release' }] });
+    const result = verifyRebuildWithCopySpec('Atlas launches on 14 August 2026.', 'Atlas launches on 15 August 2026.', profile, spec, brief);
+    assert.equal(result.factLint?.findings[0]?.kind, 'date_drift');
+    assert.equal(result.passed, false);
+});
 test('builds all thirteen VoiceDNA measurements', () => {
     assert.deepEqual(Object.keys(profile.metrics), ['sentenceLength', 'sentenceVariation', 'sentenceStructure', 'rhythm', 'paragraphLength', 'openingMoves', 'vocabulary', 'lexicalDensity', 'pointOfView', 'punctuation', 'caseStyle', 'questionRate', 'transitions']);
 });
@@ -49,6 +88,12 @@ test('post gate reports a new AI regression', () => {
     assert.equal(result.original.aiEditor.passed, true);
     assert.equal(result.candidate.aiEditor.passed, false);
 });
+test('verification applies the final-output gate by default', () => {
+    const result = verify('I ship clear ideas.', 'I ship clear ideas.\u200B', profile);
+    assert.equal(result.passed, false);
+    assert.equal(result.finalOutput.accepted, false);
+    assert.equal('output' in result.finalOutput, false);
+});
 test('advisory and pending-judgment findings pass while blocking findings fail', () => {
     const advisory = analyze('Firstly, check the invoice.', profile);
     assert.equal(advisory.passed, true);

package/dist/provenance-status.js

@@ -0,0 +1,15 @@
+import { canonicalJson } from './canonical-json.js';
+import { createHash } from 'node:crypto';
+function fingerprint(value) { return createHash('sha256').update(canonicalJson(value)).digest('hex'); }
+export function writerRequestForRebuild(task) {
+    return {
+        version: '1', taskFingerprint: task.fingerprint, prompt: task.prompt,
+        copySpecFingerprint: fingerprint(task.copySpec),
+        ...(task.recompositionPolicy ? { recompositionPolicyFingerprint: fingerprint(task.recompositionPolicy) } : {}),
+    };
+}
+export function provenanceStatusForRebuild(task) {
+    return task.recompositionPolicy
+        ? { version: '1', state: 'unknown', reason: 'private_or_unavailable_verifier' }
+        : { version: '1', state: 'not_configured' };
+}

package/dist/provenance-status.test.js

@@ -0,0 +1,22 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { provenanceStatusForRebuild, writerRequestForRebuild } from './provenance-status.js';
+const policy = { version: '1', mode: 'meaning-first', lexicalResidual: { ngramSize: 5, maxSharedNgramFraction: 0.1, maxLongestSharedRunTokens: 8 }, acknowledgement: 'Measures shared wording only; does not detect or prove removal of a watermark.' };
+const task = {
+    version: '1', fingerprint: 'a'.repeat(64), draft: 'private source phrase that must never leave the task', prompt: 'structured CopySpec-only prompt',
+    copySpec: { version: '1', audience: 'operators', intent: 'explain', channel: 'email', claims: [{ id: 'one', text: 'The date is fixed.', evidence: 'calendar' }] },
+    recommendationFingerprint: 'b'.repeat(64), authorizationFingerprint: 'c'.repeat(64), profileId: 'profile', profileRevisionDigest: 'd'.repeat(64), recompositionPolicy: policy,
+};
+test('writer request omits source, authorization, and profile body while retaining stable bindings', () => {
+    const request = writerRequestForRebuild(task);
+    const serialized = JSON.stringify(request);
+    assert.equal(request.taskFingerprint, task.fingerprint);
+    assert.match(request.prompt, /structured CopySpec-only prompt/);
+    assert.doesNotMatch(serialized, /private source phrase|authorizationFingerprint|profileRevisionDigest|draft/);
+    assert.match(request.copySpecFingerprint, /^[a-f0-9]{64}$/);
+    assert.match(request.recompositionPolicyFingerprint ?? '', /^[a-f0-9]{64}$/);
+});
+test('private-provider status is unknown and ordinary rebuild has no configured verifier', () => {
+    assert.deepEqual(provenanceStatusForRebuild(task), { version: '1', state: 'unknown', reason: 'private_or_unavailable_verifier' });
+    assert.deepEqual(provenanceStatusForRebuild({ ...task, recompositionPolicy: undefined }), { version: '1', state: 'not_configured' });
+});

package/dist/rebuild-task.js

@@ -5,8 +5,11 @@ import { parseWritingBrief } from './editorial-packs.js';
 import { verifyApprovalCapability } from './approval-capability.js';
 import { fingerprintPreEditReduction } from './judgment-task.js';
 import { verifyRebuildDeterministically } from './pipeline.js';
+import { finalOutputCheck } from './hygiene.js';
 import { sentences } from './text.js';
 import { HYV_VERSION } from './version.js';
+import { buildRecompositionBrief, measureLexicalResidual, parseRecompositionPolicy } from './recomposition.js';
+import { provenanceStatusForRebuild, writerRequestForRebuild } from './provenance-status.js';
 const MAX_RESPONSE_BYTES = 100_000;
 const MAX_CANDIDATE_CHARACTERS = 100_000;
 function fingerprint(value) {
@@ -66,7 +69,9 @@ function parseRebuildResponse(value) {
     }
     return response;
 }
-function renderRebuildPrompt(draft, copySpec, writingBrief) {
+function renderRebuildPrompt(draft, copySpec, writingBrief, recompositionPolicy) {
+    if (recompositionPolicy)
+        return buildRecompositionBrief(copySpec, writingBrief);
     return [
         '# Rebuild contract',
         'Return a whole-document candidate. Do not emit sentence replacements or range operations.',
@@ -107,7 +112,7 @@ function verifyRebuildAuthorization(draft, profile, recommendationFingerprint, c
         throw new Error('Rebuild authorization is invalid.');
     return authorized;
 }
-export function prepareRebuildTask(draft, profile, reduction, copySpec, capability, trustStore, now, writingBrief) {
+export function prepareRebuildTask(draft, profile, reduction, copySpec, capability, trustStore, now, writingBrief, recompositionPolicy) {
     if (reduction.decision !== 'REBUILD')
         throw new Error('Rebuild requires an upstream REBUILD recommendation.');
     if (fingerprintPreEditReduction(reduction) !== reduction.recommendationFingerprint || reduction.recommendationFingerprint.length !== 64) {
@@ -118,16 +123,19 @@ export function prepareRebuildTask(draft, profile, reduction, copySpec, capabili
     const authorized = verifyRebuildAuthorization(draft, profile, reduction.recommendationFingerprint, capability, trustStore, now);
     if (writingBrief)
         parseWritingBrief(writingBrief);
+    if (recompositionPolicy)
+        parseRecompositionPolicy(recompositionPolicy);
     const taskBase = {
         version: '1',
         draft,
-        prompt: renderRebuildPrompt(draft, spec, writingBrief),
+        prompt: renderRebuildPrompt(draft, spec, writingBrief, recompositionPolicy),
         copySpec: spec,
         recommendationFingerprint: reduction.recommendationFingerprint,
         authorizationFingerprint: authorized.capabilityFingerprint,
         profileId: identity.profileId,
         profileRevisionDigest: identity.profileRevisionDigest,
         ...(writingBrief ? { writingBrief } : {}),
+        ...(recompositionPolicy ? { recompositionPolicy } : {}),
     };
     return { ...taskBase, fingerprint: fingerprint(taskBase) };
 }
@@ -143,6 +151,8 @@ export function parseRebuildTask(value) {
     parseCopySpec(task.copySpec);
     if (task.writingBrief !== undefined)
         parseWritingBrief(task.writingBrief);
+    if (task.recompositionPolicy !== undefined)
+        parseRecompositionPolicy(task.recompositionPolicy);
     const { fingerprint: suppliedFingerprint, ...base } = task;
     if (fingerprint(base) !== suppliedFingerprint)
         throw new Error('Rebuild task fingerprint does not match its contents.');
@@ -196,18 +206,38 @@ export function evaluateRebuildResponse(task, raw, profile, capability, trustSto
     const applied = applyRebuildResponse(task, raw);
     if (applied.status !== 'accepted' || !applied.candidate)
         return applied;
-    const { verification, artifact: deterministicArtifact } = verifyRebuildDeterministically(task.draft, applied.candidate, profile, task.copySpec, task.writingBrief);
+    const output = finalOutputCheck(applied.candidate);
+    const candidate = output.accepted ? output.output : applied.candidate;
+    const checked = verifyRebuildDeterministically(task.draft, candidate, profile, task.copySpec, task.writingBrief);
+    const verification = { ...checked.verification, finalOutput: output };
+    const deterministicArtifact = checked.artifact;
     const receipt = {
         ...applied.receipt,
         preservationBypass: true,
         authorizationFingerprint: authorized.capabilityFingerprint,
         preservationScore: verification.preservationScore,
+        ...(task.recompositionPolicy ? { lexicalResidual: measureLexicalResidual(task.draft, candidate, task.copySpec, task.recompositionPolicy) } : {}),
+        provenanceStatus: provenanceStatusForRebuild(task),
     };
-    if (!verification.passed)
-        return { ...applied, receipt, status: 'needs_escalation', verification, deterministicArtifact };
+    if (!verification.passed) {
+        const { candidate: _candidate, ...withheld } = applied;
+        return { ...withheld, receipt, status: 'needs_escalation', verification, deterministicArtifact };
+    }
+    if (receipt.lexicalResidual && !receipt.lexicalResidual.passed) {
+        const { candidate: _candidate, ...withheld } = applied;
+        return {
+            ...withheld,
+            receipt,
+            failures: [failure('lexical_residual_exceeds_policy', 'Candidate exceeds the configured lexical-residual policy.')],
+            status: 'needs_escalation',
+            verification,
+            deterministicArtifact,
+        };
+    }
     const lifecycleBinding = createRebuildLifecycleBinding(task, receipt, deterministicArtifact);
-    return { ...applied, receipt, status: 'needs_semantic_review', verification, deterministicArtifact, lifecycleBinding };
+    return { ...applied, candidate, receipt, status: 'needs_semantic_review', verification, deterministicArtifact, lifecycleBinding };
 }
+export { writerRequestForRebuild };
 export function createRebuildLifecycleBinding(task, receipt, deterministic) {
     if (!deterministic.passed || receipt.taskFingerprint !== task.fingerprint || receipt.mode !== 'REBUILD' || deterministic.verificationKind !== 'rebuild') {
         throw new Error('Lifecycle binding requires a passed rebuild artifact for this rebuild task.');

package/dist/rebuild-task.test.js

@@ -22,6 +22,11 @@ const copySpec = {
     channel: 'email',
     claims: [{ id: 'launch-date', text: 'The launch is on 14 August.', evidence: 'Release calendar, 7 August.' }],
 };
+const recompositionPolicy = {
+    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 { publicKey, privateKey } = generateKeyPairSync('ed25519');
 const trustStore = {
     version: '1',
@@ -129,6 +134,13 @@ test('authorized rebuild allows low lexical survival while claims and hygiene st
     assert.equal(missingClaim.status, 'needs_escalation');
     const hygiene = evaluate(task, { version: '1', mode: 'REBUILD', taskFingerprint: task.fingerprint, candidate: `${rebuilt}\u200B` }, reduction);
     assert.equal(hygiene.status, 'needs_escalation');
+    assert.equal(hygiene.candidate, undefined);
+    assert.equal(hygiene.verification?.finalOutput.accepted, false);
+    const cleaned = evaluate(task, { version: '1', mode: 'REBUILD', taskFingerprint: task.fingerprint, candidate: `${rebuilt}\u0007` }, reduction);
+    assert.equal(cleaned.status, 'needs_semantic_review');
+    assert.equal(cleaned.candidate, rebuilt);
+    assert.equal(cleaned.verification?.finalOutput.changed, true);
+    assert.equal(cleaned.deterministicArtifact?.candidateHash, createHash('sha256').update(rebuilt).digest('hex'));
 });
 test('rebuild disagreement cannot record accepted learning', () => {
     const reduction = rebuildRecommendation();
@@ -162,7 +174,7 @@ test('CLI and MCP rebuild helpers share fingerprints', () => {
         version: '1', audience: 'operators', intent: 'explain', format: 'outreach',
     });
     assert.match(briefTask.prompt, /# WritingBrief/);
-    assert.equal(HYV_VERSION, '3.3.1');
+    assert.equal(HYV_VERSION, '3.3.2');
 });
 test('apply rejects forged tasks, missing capability, and substituted profiles', () => {
     const reduction = rebuildRecommendation();
@@ -177,3 +189,18 @@ test('apply rejects forged tasks, missing capability, and substituted profiles',
     const other = buildProfile(['I speak in a different register altogether.', 'I keep every sentence longer than the first profile would.'], ['mechanism']);
     assert.throws(() => evaluate(task, response, reduction, other), /Rebuild profile binding does not match this task/);
 });
+test('meaning-first rebuild binds the residual policy and blocks carried-over wording', () => {
+    const source = 'The operating review keeps the launch checklist small and the handoff calm. The launch is on 14 August.';
+    const reduction = rebuildRecommendation(source);
+    const task = prepareRebuildTask(source, profile, reduction, copySpec, capability(reduction, {}, source), trustStore, 150, undefined, recompositionPolicy);
+    assert.doesNotMatch(task.prompt, /The operating review keeps the launch checklist/);
+    assert.match(task.prompt, /Meaning-first recomposition contract/);
+    const repeated = evaluateRebuildResponse(task, { version: '1', mode: 'REBUILD', taskFingerprint: task.fingerprint, candidate: source }, profile, capability(reduction, {}, source), trustStore, 150);
+    assert.equal(repeated.status, 'needs_escalation');
+    assert.equal(repeated.failures[0]?.code, 'lexical_residual_exceeds_policy');
+    assert.equal(repeated.receipt.lexicalResidual?.passed, false);
+    assert.equal(repeated.candidate, undefined);
+    const fresh = evaluateRebuildResponse(task, { version: '1', mode: 'REBUILD', taskFingerprint: task.fingerprint, candidate: 'Release owners now work from a compact calendar note. The launch is on 14 August. Nothing else in this message repeats the original framing.' }, profile, capability(reduction, {}, source), trustStore, 150);
+    assert.equal(fresh.status, 'needs_semantic_review');
+    assert.equal(fresh.receipt.lexicalResidual?.passed, true);
+});

package/dist/recomposition.js

@@ -0,0 +1,97 @@
+import { canonicalJson } from './canonical-json.js';
+import { words } from './text.js';
+const ACKNOWLEDGEMENT = 'Measures shared wording only; does not detect or prove removal of a watermark.';
+const STATEMENT = 'Lexical overlap is not a watermark detector.';
+function tokens(text) {
+    return words(text.normalize('NFKC')).map((word) => word.toLowerCase());
+}
+function ngrams(value, size) {
+    const result = [];
+    for (let index = 0; index + size <= value.length; index += 1)
+        result.push(value.slice(index, index + size).join('\u0001'));
+    return result;
+}
+function allowedPhrases(copySpec) {
+    const result = [];
+    for (const claim of copySpec.claims) {
+        if (claim.atoms?.length)
+            result.push(...claim.atoms.map((text) => ({ reason: 'copy-spec-atom', text })));
+        else
+            result.push({ reason: 'copy-spec-claim', text: claim.text });
+    }
+    return result;
+}
+function longestSharedRun(source, candidate, allowed) {
+    let longest = 0;
+    let previous = new Array(source.length + 1).fill(0);
+    for (let candidateIndex = 1; candidateIndex <= candidate.length; candidateIndex += 1) {
+        const current = new Array(source.length + 1).fill(0);
+        for (let sourceIndex = 1; sourceIndex <= source.length; sourceIndex += 1) {
+            if (candidate[candidateIndex - 1] !== source[sourceIndex - 1])
+                continue;
+            current[sourceIndex] = previous[sourceIndex - 1] + 1;
+            const run = current[sourceIndex];
+            const key = candidate.slice(candidateIndex - run, candidateIndex).join('\u0001');
+            if (!allowed.has(key))
+                longest = Math.max(longest, run);
+        }
+        previous = current;
+    }
+    return longest;
+}
+export function parseRecompositionPolicy(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Recomposition policy must be an object.');
+    const policy = value;
+    const residual = policy.lexicalResidual;
+    if (policy.version !== '1' || policy.mode !== 'meaning-first' || policy.acknowledgement !== ACKNOWLEDGEMENT
+        || !residual || residual.ngramSize !== 5
+        || typeof residual.maxSharedNgramFraction !== 'number' || !Number.isFinite(residual.maxSharedNgramFraction) || residual.maxSharedNgramFraction < 0 || residual.maxSharedNgramFraction > 1
+        || !Number.isInteger(residual.maxLongestSharedRunTokens) || residual.maxLongestSharedRunTokens < 0 || residual.maxLongestSharedRunTokens > 100_000) {
+        throw new Error('Recomposition policy is not valid.');
+    }
+    return policy;
+}
+export function buildRecompositionBrief(copySpec, writingBrief) {
+    return [
+        '# Meaning-first recomposition contract',
+        'Write a new whole-document candidate from the structured facts and constraints below.',
+        'Do not edit, quote, or mirror source wording unless a CopySpec claim or atom requires it.',
+        'Return only the candidate. Do not claim anything about authorship, AI origin, or watermark status.',
+        '',
+        '# CopySpec',
+        canonicalJson({ audience: copySpec.audience, intent: copySpec.intent, channel: copySpec.channel, claims: copySpec.claims, ...(copySpec.prohibitedClaims ? { prohibitedClaims: copySpec.prohibitedClaims } : {}) }),
+        ...(writingBrief ? ['', '# WritingBrief', canonicalJson(writingBrief)] : []),
+    ].join('\n');
+}
+export function measureLexicalResidual(sourceText, candidateText, copySpec, policy) {
+    const source = tokens(sourceText);
+    const candidate = tokens(candidateText);
+    const allowed = allowedPhrases(copySpec);
+    const allowedNgrams = new Set();
+    const allowedRuns = new Set();
+    const counts = new Map();
+    for (const phrase of allowed) {
+        const phraseTokens = tokens(phrase.text);
+        counts.set(phrase.reason, (counts.get(phrase.reason) ?? 0) + phraseTokens.length);
+        for (const ngram of ngrams(phraseTokens, policy.lexicalResidual.ngramSize))
+            allowedNgrams.add(ngram);
+        for (let length = 1; length <= phraseTokens.length; length += 1) {
+            for (let index = 0; index + length <= phraseTokens.length; index += 1)
+                allowedRuns.add(phraseTokens.slice(index, index + length).join('\u0001'));
+        }
+    }
+    const sourceNgrams = new Set(ngrams(source, policy.lexicalResidual.ngramSize).filter((ngram) => !allowedNgrams.has(ngram)));
+    const candidateNgrams = ngrams(candidate, policy.lexicalResidual.ngramSize).filter((ngram) => !allowedNgrams.has(ngram));
+    const shared = candidateNgrams.filter((ngram) => sourceNgrams.has(ngram)).length;
+    const sharedNgramFraction = candidateNgrams.length === 0 ? 0 : shared / candidateNgrams.length;
+    const longestSharedRunTokens = longestSharedRun(source, candidate, allowedRuns);
+    const passed = sharedNgramFraction <= policy.lexicalResidual.maxSharedNgramFraction
+        && longestSharedRunTokens <= policy.lexicalResidual.maxLongestSharedRunTokens;
+    return {
+        version: '1', sourceTokenCount: source.length, candidateTokenCount: candidate.length, ngramSize: policy.lexicalResidual.ngramSize,
+        sharedNgramFraction, longestSharedRunTokens,
+        allowedResiduals: [...counts.entries()].map(([reason, count]) => ({ reason, count })),
+        passed, statement: STATEMENT,
+    };
+}

package/dist/recomposition.test.js

@@ -0,0 +1,34 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { buildRecompositionBrief, measureLexicalResidual, parseRecompositionPolicy } from './recomposition.js';
+const policy = {
+    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 copySpec = {
+    version: '1', audience: 'operators', intent: 'explain', channel: 'email',
+    claims: [{ id: 'launch-date', text: 'The launch is on 14 August.', evidence: 'Release calendar.', atoms: ['The launch is on 14 August.'] }],
+};
+test('parses only explicit meaning-first recomposition policies', () => {
+    assert.deepEqual(parseRecompositionPolicy(policy), policy);
+    assert.throws(() => parseRecompositionPolicy({ ...policy, lexicalResidual: { ...policy.lexicalResidual, ngramSize: 4 } }), /not valid/);
+    assert.throws(() => parseRecompositionPolicy({ ...policy, acknowledgement: 'watermark removed' }), /not valid/);
+});
+test('builds a recomposition brief without carrying the source draft', () => {
+    const brief = buildRecompositionBrief(copySpec, { version: '1', audience: 'operators', intent: 'explain', format: 'outreach' });
+    assert.match(brief, /Meaning-first recomposition contract/);
+    assert.match(brief, /The launch is on 14 August/);
+    assert.doesNotMatch(brief, /watermark-free|dewatermarked/i);
+});
+test('measures lexical carry-over without calling it watermark detection', () => {
+    const source = 'The operating review keeps the launch checklist small and the handoff calm. The launch is on 14 August.';
+    const identical = measureLexicalResidual(source, source, copySpec, policy);
+    assert.equal(identical.passed, false);
+    assert.ok(identical.sharedNgramFraction > 0);
+    assert.match(identical.statement, /not a watermark detector/);
+    const fresh = measureLexicalResidual(source, 'Release owners now work from a compact calendar note. The launch is on 14 August. Nothing else in this message repeats the original framing.', copySpec, policy);
+    assert.equal(fresh.passed, true);
+    assert.equal(fresh.sharedNgramFraction, 0);
+    assert.ok(fresh.allowedResiduals.some((item) => item.reason === 'copy-spec-atom'));
+});

package/dist/rewrite-task.js

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto';
 import { canonicalJson } from './canonical-json.js';
 import { parseWritingBrief } from './editorial-packs.js';
-import { hygieneSourceFindings } from './hygiene.js';
+import { finalOutputCheck, hygieneSourceFindings } from './hygiene.js';
 import { analyze, deriveEditScope, renderRewritePrompt, verifyDeterministically } from './pipeline.js';
 import { sentences } from './text.js';
 const MAX_RESPONSE_BYTES = 100_000;
@@ -251,11 +251,17 @@ export function evaluateRewriteResponse(task, raw, profile) {
     const applied = applyRewriteResponse(task, raw);
     if (applied.status !== 'accepted' || !applied.candidate)
         return applied;
-    const { verification, artifact: deterministicArtifact } = verifyDeterministically(task.draft, applied.candidate, profile, task.copySpec, task.writingBrief);
-    if (!verification.passed)
-        return { ...applied, status: 'needs_escalation', verification };
+    const output = finalOutputCheck(applied.candidate);
+    const candidate = output.accepted ? output.output : applied.candidate;
+    const checked = verifyDeterministically(task.draft, candidate, profile, task.copySpec, task.writingBrief);
+    const verification = { ...checked.verification, finalOutput: output };
+    const deterministicArtifact = checked.artifact;
+    if (!verification.passed) {
+        const { candidate: _candidate, ...withheld } = applied;
+        return { ...withheld, status: 'needs_escalation', verification };
+    }
     const lifecycleBinding = createRewriteLifecycleBinding(task, applied.receipt, deterministicArtifact);
-    return { ...applied, status: 'needs_semantic_review', verification, deterministicArtifact, lifecycleBinding };
+    return { ...applied, candidate, status: 'needs_semantic_review', verification, deterministicArtifact, lifecycleBinding };
 }
 export function createRewriteLifecycleBinding(task, receipt, deterministic) {
     if (!deterministic.passed || receipt.taskFingerprint !== task.fingerprint)

package/dist/rewrite-task.test.js

@@ -116,6 +116,21 @@ test('keeps a valid response byte-for-byte unchanged by repair adapters', () =>
     assert.deepEqual(result.receipt.adapterIds, []);
     assert.deepEqual(result.receipt.replacementSentenceIds, [1]);
 });
+test('withholds an unresolved final-output candidate from evaluation results', () => {
+    const task = prepareRewriteTask('I leverage the answer.', profile);
+    const result = evaluateRewriteResponse(task, { version: '1', taskFingerprint: task.fingerprint, replacements: [{ sentenceId: 1, text: 'I use the answer.\u200B' }] }, profile);
+    assert.equal(result.status, 'needs_escalation');
+    assert.equal(result.candidate, undefined);
+    assert.equal(result.verification?.finalOutput.accepted, false);
+});
+test('returns the final-gate-cleaned candidate and hashes that value', () => {
+    const task = prepareRewriteTask('I leverage the answer with useful detail and clear mechanism.', profile);
+    const result = evaluateRewriteResponse(task, { version: '1', taskFingerprint: task.fingerprint, replacements: [{ sentenceId: 1, text: 'I use the\u0007 answer with useful detail and clear mechanism.' }] }, profile);
+    assert.equal(result.status, 'needs_semantic_review');
+    assert.equal(result.candidate, 'I use the answer with useful detail and clear mechanism.');
+    assert.equal(result.verification?.finalOutput.changed, true);
+    assert.equal(result.deterministicArtifact?.candidateHash, createHash('sha256').update('I use the answer with useful detail and clear mechanism.').digest('hex'));
+});
 test('binds the task, response, deterministic artifact, text hashes, and profile revision', () => {
     const draft = 'I write clear notes.';
     const task = prepareRewriteTask(draft, profile);

package/dist/text-provenance.feature.test.js

@@ -0,0 +1,45 @@
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import test from 'node:test';
+import { applyHiddenTextPolicy, inspectHiddenText } from './hidden-text.js';
+import { provenanceStatusForRebuild, writerRequestForRebuild } from './provenance-status.js';
+const feature = readFileSync(new URL('../features/text-provenance.feature', import.meta.url), 'utf8');
+const policy = { version: '1', mode: 'meaning-first', lexicalResidual: { ngramSize: 5, maxSharedNgramFraction: 0.1, maxLongestSharedRunTokens: 8 }, acknowledgement: 'Measures shared wording only; does not detect or prove removal of a watermark.' };
+const task = {
+    version: '1', fingerprint: 'a'.repeat(64), draft: 'private source phrase', prompt: 'structured task prompt',
+    copySpec: { version: '1', audience: 'operators', intent: 'explain', channel: 'email', claims: [{ id: 'date', text: 'The date is fixed.', evidence: 'calendar' }] },
+    recommendationFingerprint: 'b'.repeat(64), authorizationFingerprint: 'c'.repeat(64), profileId: 'profile', profileRevisionDigest: 'd'.repeat(64), recompositionPolicy: policy,
+};
+function scenario(name, verify) {
+    test(`Feature: bounded text provenance sanitation — Scenario: ${name}`, () => {
+        assert.match(feature, new RegExp(`Scenario: ${name}`));
+        verify();
+    });
+}
+scenario('explicitly approved non-semantic controls are removed with evidence', () => {
+    const receipt = applyHiddenTextPolicy('one\u0007two\uFEFFthree');
+    assert.deepEqual(receipt.proposedChanges.map((item) => item.codepoint), ['U+0007', 'U+FEFF']);
+    assert.match(receipt.inputHash, /^[a-f0-9]{64}$/);
+    assert.match(receipt.outputHash, /^[a-f0-9]{64}$/);
+    assert.equal(receipt.idempotent, true);
+});
+scenario('multilingual and structured text is review-only by default', () => {
+    const source = '```md\nالعربية\u202E ไทย\u200B 👩\u200D💻\t\n```';
+    const receipt = applyHiddenTextPolicy(source);
+    assert.equal(receipt.output, source);
+    assert.equal(receipt.proposedChanges.length, 0);
+    assert.ok(inspectHiddenText(source).findings.every((item) => item.action === 'review'));
+});
+scenario('an external writer receives no source prose', () => {
+    const request = writerRequestForRebuild(task);
+    assert.match(request.prompt, /structured task prompt/);
+    assert.doesNotMatch(JSON.stringify(request), /private source phrase|authorizationFingerprint|profileRevisionDigest|draft/);
+});
+scenario('unknown provider status remains explicit', () => {
+    assert.deepEqual(provenanceStatusForRebuild(task), { version: '1', state: 'unknown', reason: 'private_or_unavailable_verifier' });
+    assert.match(feature, /does not claim watermark removal or absence/);
+});
+scenario('a controlled verifier is not configured', () => {
+    assert.deepEqual(provenanceStatusForRebuild({ ...task, recompositionPolicy: undefined }), { version: '1', state: 'not_configured' });
+    assert.match(feature, /lexical residual is not used as a provider verifier/);
+});

package/dist/version.js

@@ -1 +1 @@
-export const HYV_VERSION = '3.3.1';
+export const HYV_VERSION = '3.3.2';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holdyourvoice/hyv",
-  "version": "3.3.1",
+  "version": "3.3.2",
   "description": "A local-first dual-engine writing gate that protects voice and catches generic AI patterns.",
   "type": "module",
   "bin": { "hyv": "dist/cli.js" },