@holdyourvoice/hyv 3.1.1 → 3.3.0

package/dist/mcp-tools.test.js

@@ -1,9 +1,11 @@
 import assert from 'node:assert/strict';
+import { createHash, generateKeyPairSync, sign } from 'node:crypto';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import test from 'node:test';
-import { analyzeBatchForMcp, analyzeForMcp, applyRewriteForMcp, buildProfileForMcp, patternsForMcp, prepareRewriteForMcp, rewritePromptForMcp, verifyCopySpecForMcp, verifyForMcp } from './mcp-tools.js';
+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 { 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);
 test('builds a portable profile for MCP without files', () => {
@@ -11,33 +13,154 @@ test('builds a portable profile for MCP without files', () => {
     assert.equal(profile.sampleCount, 2);
 });
 test('keeps the dual-engine analysis shape through MCP tools', () => {
-    const result = analyzeForMcp('I leverage a clear plan.', profileJson);
+    const result = analyzeForMcp('I leverage a clear plan.\u200B', profileJson);
     assert.equal(result.voiceDna.engine, 'voice_dna');
     assert.equal(result.aiEditor.engine, 'ai_editor');
+    assert.equal(result.hygiene.suspiciousCount, 1);
+});
+test('inspects Unicode hygiene through MCP without a voice profile', () => {
+    const result = inspectHygieneForMcp('one\u200Btwo\u00A0three');
+    assert.equal(result.suspiciousCount, 2);
+    assert.equal(result.fixableCount, 0);
+});
+test('gates exact final output through MCP without a voice profile', () => {
+    const accepted = finalOutputCheckForMcp('exact output');
+    assert.equal(accepted.accepted && accepted.output, 'exact output');
+    const rejected = finalOutputCheckForMcp('hidden\u200Boutput');
+    assert.equal(rejected.accepted, false);
+    assert.equal('output' in rejected, false);
 });
 test('accepts optional WritingBrief context and exposes batch findings through MCP helpers', () => {
-    const brief = JSON.stringify({ version: '1', audience: 'founders', intent: 'start a discussion', format: 'social' });
+    const brief = JSON.stringify({
+        version: '1', audience: 'founders', intent: 'start a discussion', format: 'social', evidenceStatus: 'unverified',
+        argumentMap: { observation: 'Founders repeat vague advice.', mechanism: 'The advice skips the work.', consequence: 'Readers cannot act.', readerValue: 'Avoid a vague post.' },
+    });
     const analysis = analyzeForMcp('A pattern I keep seeing in founder posts is vague advice.', profileJson, brief);
-    assert.equal(analysis.editorial?.findings[0]?.id, 'editorial.social.generic-opener');
+    assert.ok(analysis.editorial?.findings.some((item) => item.id === 'editorial.social.generic-opener'));
+    assert.ok(analysis.editorial?.findings.some((item) => item.id === 'editorial.evidence.unverified'));
     const batch = analyzeBatchForMcp(['The launch needs a clear owner.', 'The launch needs a clear owner.']);
     assert.equal(batch.findings.length, 2);
 });
-test('creates and verifies an editing loop through MCP tools', () => {
+test('keeps MCP verification read-only', () => {
     const root = mkdtempSync(join(tmpdir(), 'holdyourvoice-mcp-'));
     try {
-        const result = verifyForMcp('I leverage the answer with useful detail and clear mechanism.', 'I use the answer with useful detail and clear mechanism.', profileJson, { root });
+        const result = verifyForMcp('I leverage the answer with useful detail and clear mechanism.', 'I use the answer with useful detail and clear mechanism.', profileJson);
         const brief = rewritePromptForMcp('I leverage a clear plan.', profileJson, { root });
         assert.match(brief.prompt, /Tier 0/);
-        assert.match(brief.prompt, /Learned local preferences/);
+        assert.doesNotMatch(brief.prompt, /Learned local preferences/);
         assert.equal(result.preservationScore >= 70, true);
-        assert.equal(result.learning, 'recorded');
+        assert.equal('learning' in result, false);
+        assert.deepEqual(inspectLearningForMcp(profileJson, { root }), []);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('prepares, submits, and inspects the normal lifecycle through MCP helpers', () => {
+    const deterministicBase = { version: '1', verificationKind: 'standard', passed: true, analysisVersion: '2', rulesetVersion: '3.2.0', preservationMetricVersion: 'legacy-set-v1', preservationScore: 100, sourceHash: '4'.repeat(64), candidateHash: '5'.repeat(64), profileId: 'founder.primary', profileRevisionDigest: '6'.repeat(64), regressionKeys: [] };
+    const deterministic = { ...deterministicBase, artifactFingerprint: createHash('sha256').update(`hyv:deterministic-verification:v1\0${canonicalJson(deterministicBase)}`).digest('hex') };
+    const binding = { rewriteTaskFingerprint: '1'.repeat(64), rewriteResponseFingerprint: '2'.repeat(64), deterministicArtifactFingerprint: deterministic.artifactFingerprint, sourceHash: deterministic.sourceHash, candidateHash: deterministic.candidateHash, profileId: deterministic.profileId, profileRevisionDigest: deterministic.profileRevisionDigest, rulesetVersion: deterministic.rulesetVersion, schemaVersion: '1' };
+    const receipt = { version: '1', taskFingerprint: binding.rewriteTaskFingerprint, responseFingerprint: binding.rewriteResponseFingerprint, adapterIds: [], replacementSentenceIds: [1] };
+    const prepared = prepareLifecycleForMcp(JSON.stringify(deterministic), JSON.stringify(binding), JSON.stringify(receipt), 'normal', ['action_change']);
+    const context = { now: 0, trustStore: { version: '1', audience: '@holdyourvoice/hyv', maxCapabilityLifetimeSeconds: 1, keys: [] }, authorizedSemanticEvaluatorIds: { normal: ['reviewer-1'], highAssurance: [] }, authorizedHumanFinalizerIds: [] };
+    const submitted = submitSemanticVerdictForMcp(JSON.stringify(prepared.artifact), JSON.stringify(prepared.task), 'reviewer-1', JSON.stringify({ approved: true, violations: [] }), context);
+    assert.equal(submitted.ok && submitted.artifact.status, 'ready_for_human_review');
+    assert.equal(inspectLifecycleForMcp(JSON.stringify(submitted.ok && submitted.artifact)).status, 'ready_for_human_review');
+    assert.throws(() => prepareLifecycleForMcp(JSON.stringify(deterministic), JSON.stringify(binding), JSON.stringify(receipt), 'high_assurance', ['action_change']), /trusted embedding/);
+    const forgedTask = { ...prepared.task, allowedViolations: ['unsupported_claim'] };
+    assert.throws(() => submitSemanticVerdictForMcp(JSON.stringify(prepared.artifact), JSON.stringify(forgedTask), 'reviewer-1', JSON.stringify({ approved: false, violations: ['unsupported_claim'] }), context));
+});
+test('validates and finalizes signed approval with helper/core parity and no bearer output', () => {
+    const deterministicBase = { version: '1', verificationKind: 'standard', passed: true, analysisVersion: '2', rulesetVersion: '3.2.0', preservationMetricVersion: 'legacy-set-v1', preservationScore: 100, sourceHash: '4'.repeat(64), candidateHash: '5'.repeat(64), profileId: 'founder.primary', profileRevisionDigest: '6'.repeat(64), regressionKeys: [] };
+    const deterministic = { ...deterministicBase, artifactFingerprint: createHash('sha256').update(`hyv:deterministic-verification:v1\0${canonicalJson(deterministicBase)}`).digest('hex') };
+    const binding = { rewriteTaskFingerprint: '1'.repeat(64), rewriteResponseFingerprint: '2'.repeat(64), deterministicArtifactFingerprint: deterministic.artifactFingerprint, sourceHash: deterministic.sourceHash, candidateHash: deterministic.candidateHash, profileId: deterministic.profileId, profileRevisionDigest: deterministic.profileRevisionDigest, rulesetVersion: deterministic.rulesetVersion, schemaVersion: '1' };
+    const receipt = { version: '1', taskFingerprint: binding.rewriteTaskFingerprint, responseFingerprint: binding.rewriteResponseFingerprint, adapterIds: [], replacementSentenceIds: [1] };
+    const prepared = prepareLifecycleForMcp(JSON.stringify(deterministic), JSON.stringify(binding), JSON.stringify(receipt), 'normal', ['action_change']);
+    const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+    const trustStore = { version: '1', audience: '@holdyourvoice/hyv', maxCapabilityLifetimeSeconds: 300, keys: [{ issuer: 'host', keyId: 'k1', publicKeySpki: publicKey.export({ type: 'spki', format: 'der' }).toString('base64url'), status: 'active' }] };
+    const context = { now: 150, trustStore, authorizedSemanticEvaluatorIds: { normal: ['reviewer-1'], highAssurance: [] }, authorizedHumanFinalizerIds: ['human-1'] };
+    const submitted = submitSemanticVerdictForMcp(JSON.stringify(prepared.artifact), JSON.stringify(prepared.task), 'reviewer-1', JSON.stringify({ approved: true, violations: [] }), context);
+    assert.equal(submitted.ok, true);
+    if (!submitted.ok)
+        return;
+    const claims = { version: '1', purpose: 'hyv.final-approval', issuer: 'host', audience: '@holdyourvoice/hyv', subjectArtifactFingerprint: submitted.artifact.artifactFingerprint, sourceHash: binding.sourceHash, candidateHash: binding.candidateHash, profileId: binding.profileId, profileRevisionDigest: binding.profileRevisionDigest, keyId: 'k1', issuedAt: 100, notBefore: 100, expiresAt: 200, nonce: 'mcp-secret-nonce' };
+    const payload = Buffer.from(canonicalJson(claims));
+    const capability = { payload: payload.toString('base64url'), signature: sign(null, payload, privateKey).toString('base64url') };
+    const validated = validateFinalApprovalForMcp(JSON.stringify(submitted.artifact), canonicalJson(capability), context);
+    assert.equal(validated.ok, true);
+    const finalized = finalizeLifecycleForMcp(JSON.stringify(submitted.artifact), JSON.stringify({ evaluatorId: 'human-1', decision: 'approve' }), context, canonicalJson(capability));
+    assert.equal(finalized.ok && finalized.artifact.status, 'approved');
+    assert.throws(() => finalizeLifecycleForMcp(JSON.stringify(submitted.artifact), JSON.stringify({ evaluatorId: 'human-1', decision: 'reject' }), context, canonicalJson(capability)), /does not accept/);
+    assert.doesNotMatch(JSON.stringify({ validated, finalized }), /mcp-secret-nonce|payload|signature/);
+});
+test('records approved learning once and treats an exact replay as a no-op', () => {
+    const root = mkdtempSync(join(tmpdir(), 'holdyourvoice-mcp-approved-'));
+    const previousHome = process.env.HYV_HOME;
+    process.env.HYV_HOME = root;
+    try {
+        const source = 'I leverage the answer with useful detail and clear mechanism.';
+        const candidate = 'I use the answer with useful detail and clear mechanism.';
+        const rewriteTask = prepareRewriteForMcp(source, profileJson);
+        const evaluation = applyRewriteForMcp(JSON.stringify(rewriteTask), JSON.stringify({
+            version: '1', taskFingerprint: rewriteTask.fingerprint, replacements: [{ sentenceId: 1, text: candidate }],
+        }), profileJson);
+        assert.equal(evaluation.status, 'needs_semantic_review');
+        const prepared = prepareLifecycleForMcp(JSON.stringify(evaluation.deterministicArtifact), JSON.stringify(evaluation.lifecycleBinding), JSON.stringify(evaluation.receipt), 'normal', []);
+        const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+        const trustStore = { version: '1', audience: '@holdyourvoice/hyv', maxCapabilityLifetimeSeconds: 300, keys: [{ issuer: 'host', keyId: 'k1', publicKeySpki: publicKey.export({ type: 'spki', format: 'der' }).toString('base64url'), status: 'active' }] };
+        const context = { now: 150, trustStore, authorizedSemanticEvaluatorIds: { normal: ['reviewer-1'], highAssurance: [] }, authorizedHumanFinalizerIds: ['human-1'] };
+        const submitted = submitSemanticVerdictForMcp(JSON.stringify(prepared.artifact), JSON.stringify(prepared.task), 'reviewer-1', JSON.stringify({ approved: true, violations: [] }), context);
+        assert.equal(submitted.ok, true);
+        if (!submitted.ok)
+            return;
+        const binding = submitted.artifact.binding;
+        const claims = { version: '1', purpose: 'hyv.final-approval', issuer: 'host', audience: '@holdyourvoice/hyv', subjectArtifactFingerprint: submitted.artifact.artifactFingerprint, sourceHash: binding.sourceHash, candidateHash: binding.candidateHash, profileId: binding.profileId, profileRevisionDigest: binding.profileRevisionDigest, keyId: 'k1', issuedAt: 100, notBefore: 100, expiresAt: 200, nonce: 'approved-learning-secret' };
+        const payload = Buffer.from(canonicalJson(claims));
+        const capability = canonicalJson({ payload: payload.toString('base64url'), signature: sign(null, payload, privateKey).toString('base64url') });
+        const decision = JSON.stringify({ evaluatorId: 'human-1', decision: 'approve' });
+        const finalized = finalizeLifecycleForMcp(JSON.stringify(submitted.artifact), decision, context, capability);
+        assert.equal(finalized.ok, true);
+        if (!finalized.ok)
+            return;
+        const request = { readyJson: JSON.stringify(submitted.artifact), approvedJson: JSON.stringify(finalized.artifact), source, candidate, profileJson, decisionJson: decision, capabilityJson: capability, context };
+        assert.equal(recordApprovedLearningForMcp(request), 'recorded');
+        assert.equal(recordApprovedLearningForMcp(request), 'nothing_to_learn');
+        const stored = JSON.stringify(inspectLearningForMcp(profileJson, { root }));
+        assert.equal(JSON.parse(stored).length, 1);
+        assert.doesNotMatch(stored, /approved-learning-secret|payload|signature|I leverage|I use/);
+    }
+    finally {
+        if (previousHome === undefined)
+            delete process.env.HYV_HOME;
+        else
+            process.env.HYV_HOME = previousHome;
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('exposes text-free learning inspection and explicit mutations through MCP helpers', () => {
+    const root = mkdtempSync(join(tmpdir(), 'holdyourvoice-mcp-learning-'));
+    const unsigned = { ...profile, version: '3', id: 'founder.test', revision: 1, provenance: { source: 'test', rights: 'test', createdAt: '2026-08-13T00:00:00.000Z' }, rulePolicy: {}, fingerprint: { contractionRate: 0, sentenceLengthDistribution: { short: 1, medium: 0, long: 0 }, bulletRate: 0, enDashRate: 0 }, tolerances: { contractionRate: { absolute: 0.1, calibrated: false }, sentenceLengthDistribution: { absolute: 0.1, calibrated: false }, bulletRate: { absolute: 0.1, calibrated: false }, enDashRate: { absolute: 0.1, calibrated: false } }, metricFixtures: { contractionRate: ['test'], sentenceLengthDistribution: ['test'], bulletRate: ['test'], enDashRate: ['test'] } };
+    const canonical = (value) => Array.isArray(value) ? `[${value.map(canonical).join(',')}]` : value && typeof value === 'object' ? `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}` : JSON.stringify(value);
+    const profileV3 = { ...unsigned, revisionDigest: createHash('sha256').update(canonical(unsigned)).digest('hex') };
+    const v3Json = JSON.stringify(profileV3);
+    try {
+        const recorded = recordLearningForMcp(v3Json, 'Keep the mechanism concrete.', { root, mutationId: 'm1', authority: 'founder', provenance: 'editor-review', weight: 2, compatibility: 'exact' });
+        assert.equal(recorded.status, 'recorded');
+        assert.equal(recordLearningForMcp(v3Json, 'Different instruction.', { root, mutationId: 'm1' }).status, 'conflict');
+        const inspection = inspectLearningForMcp(v3Json, { root });
+        assert.equal(inspection[0]?.eventType, 'instruction');
+        assert.equal(JSON.stringify(inspection).includes('Keep the mechanism concrete.'), false);
+        assert.equal(ratifyLearningForMcp(v3Json, recorded.eventId, { root, mutationId: 'm2', authority: 'founder' }).status, 'recorded');
+        assert.equal(supersedeLearningForMcp(v3Json, recorded.eventId, { root, mutationId: 'm3', authority: 'founder' }).status, 'recorded');
+        assert.equal(clearLearningForMcp(v3Json, { root }).cleared, true);
     }
     finally {
         rmSync(root, { recursive: true, force: true });
     }
 });
 test('exposes the executable pattern IDs through MCP tools', () => {
-    assert.ok(patternsForMcp().rules.some((rule) => rule.id === 'ai.leverage'));
+    const catalog = patternsForMcp();
+    assert.ok(catalog.rules.some((rule) => rule.id === 'ai.leverage'));
 });
 test('fails closed on changed CopySpec claims through MCP tools', () => {
     const result = verifyCopySpecForMcp('The launch is on 14 August.', 'The launch is next month.', profileJson, JSON.stringify({
@@ -46,7 +169,17 @@ test('fails closed on changed CopySpec claims through MCP tools', () => {
     }));
     assert.equal(result.passed, false);
     assert.equal(result.claims.failures[0]?.code, 'missing_immutable_claim');
-    assert.equal(result.learning, 'nothing_to_learn');
+    assert.equal('learning' in result, false);
+});
+test('allows declared CopySpec atoms to survive a split MCP rewrite', () => {
+    const spec = JSON.stringify({
+        version: '1', audience: 'operators', intent: 'explain', channel: 'email',
+        claims: [{ id: 'model-size', text: 'Kimi K2.6 has 600 GB of INT4 weights.', atoms: ['Kimi K2.6 uses INT4 weights', 'payload is 600 GB'], evidence: 'Technical report.' }],
+    });
+    const preserved = verifyCopySpecForMcp('Kimi K2.6 has 600 GB of INT4 weights.', 'Kimi K2.6 uses INT4 weights. The payload is 600 GB.', profileJson, spec);
+    assert.equal(preserved.claims.passed, true);
+    const missing = verifyCopySpecForMcp('Kimi K2.6 has 600 GB of INT4 weights.', 'Kimi K2.6 uses INT4 weights.', profileJson, spec);
+    assert.deepEqual(missing.claims.failures.map((failure) => failure.code), ['missing_immutable_atom']);
 });
 test('prepares and applies the rewrite task through MCP helpers', () => {
     const task = prepareRewriteForMcp('I leverage the answer with useful detail and clear mechanism.', profileJson);
@@ -56,3 +189,48 @@ test('prepares and applies the rewrite task through MCP helpers', () => {
     assert.equal(result.status, 'needs_semantic_review');
     assert.equal(result.candidate, 'I use the answer with useful detail and clear mechanism.');
 });
+test('prepares and reduces judgment envelopes through MCP helpers', () => {
+    const draft = 'I leverage the answer.';
+    const envelopes = ['triage', 'argument', 'form'].map((kind) => {
+        const task = prepareJudgmentForMcp('pre-edit', kind, draft, profileJson);
+        return {
+            version: '1', stage: 'pre-edit', judgmentType: kind, taskFingerprint: task.taskFingerprint,
+            bindings: { ...task.bindings, evaluatorId: 'writer.1' }, findings: [], decision: 'SHIP',
+        };
+    });
+    assert.equal(reduceJudgmentForMcp(JSON.stringify(envelopes)).decision, 'SHIP');
+});
+test('prepares and evaluates authorized rebuild through MCP helpers', () => {
+    const draft = 'I leverage the answer. The launch is on 14 August.';
+    const envelopes = ['triage', 'argument', 'form'].map((kind) => {
+        const task = prepareJudgmentForMcp('pre-edit', kind, draft, profileJson);
+        return {
+            version: '1', stage: 'pre-edit', judgmentType: kind, taskFingerprint: task.taskFingerprint,
+            bindings: { ...task.bindings, evaluatorId: 'writer.1' }, findings: kind === 'argument' ? [] : [], decision: kind === 'argument' ? 'REBUILD' : 'SHIP',
+        };
+    });
+    const reduction = reduceJudgmentForMcp(JSON.stringify(envelopes));
+    assert.equal(reduction.decision, 'REBUILD');
+    if (!('recommendationFingerprint' in reduction))
+        throw new Error('expected a pre-edit rebuild recommendation');
+    const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+    const trustStore = { version: '1', audience: '@holdyourvoice/hyv', maxCapabilityLifetimeSeconds: 300, keys: [{ issuer: 'host.example', keyId: 'key-1', publicKeySpki: publicKey.export({ format: 'der', type: 'spki' }).toString('base64url'), status: 'active' }] };
+    const sourceHash = createHash('sha256').update(draft).digest('hex');
+    const identity = `legacy-v2:${createHash('sha256').update(canonicalJson(profile)).digest('hex')}`;
+    const claims = {
+        version: '1', purpose: 'hyv.rebuild-authorization', issuer: 'host.example', audience: '@holdyourvoice/hyv',
+        subjectArtifactFingerprint: reduction.recommendationFingerprint, sourceHash, candidateHash: sourceHash,
+        profileId: identity, profileRevisionDigest: identity, keyId: 'key-1', issuedAt: 100, notBefore: 100, expiresAt: 200, nonce: 'mcp-rebuild',
+    };
+    const payload = Buffer.from(canonicalJson(claims));
+    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 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');
+});

package/dist/mcp.js

@@ -1,20 +1,41 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
-import { analyzeBatchForMcp, analyzeForMcp, applyRewriteForMcp, buildProfileForMcp, patternsForMcp, prepareRewriteForMcp, rewritePromptForMcp, verifyCopySpecForMcp, verifyForMcp } from './mcp-tools.js';
+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 { HYV_VERSION } from './version.js';
+import { loadApprovalContext } from './approval-context.js';
 const writing = z.string().min(1).max(100_000);
+const hygieneText = z.string().max(100_000);
 const profileJson = z.string().min(1).max(50_000);
 const copySpecJson = z.string().min(1).max(250_000);
 const writingBriefJson = z.string().min(1).max(50_000);
 const samples = z.array(writing).min(2).max(20);
 const avoid = z.array(z.string().min(1).max(200)).max(50).optional();
+const lifecycleJson = z.string().min(1).max(1_048_576);
+const approvedLearningText = z.string().min(1).max(1_048_576);
+const evaluatorId = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/);
+const semanticViolation = z.enum(['action_change', 'dropped_object', 'unsupported_claim', 'constraint_weakened', 'clarity_regression']);
+const redactsSensitiveInputs = process.env.HYV_MCP_SENSITIVE_INPUT_REDACTION === '1';
+const learningOptions = {
+    mutation_id: z.string().min(1).max(200).optional(),
+    authority: z.enum(['founder', 'team', 'system']).optional(),
+    provenance: z.string().min(1).max(500).optional(),
+    weight: z.number().positive().finite().optional(),
+    compatibility: z.enum(['same-or-newer', 'exact']).optional(),
+};
+function learningArgs(value) {
+    return { mutationId: value.mutation_id, authority: value.authority, provenance: value.provenance, weight: value.weight, compatibility: value.compatibility };
+}
 function json(value) {
     return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
 }
 function failure(error) {
     return { content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }], isError: true };
 }
-const server = new McpServer({ name: 'hold-your-voice', version: '3.1.1' });
+function lifecycleResult(result) {
+    return json(result.ok ? result.artifact : { error: result.error });
+}
+const server = new McpServer({ name: 'hold-your-voice', version: HYV_VERSION });
 server.registerTool('hyv_build_profile', {
     description: 'Build a portable VoiceDNA profile from at least two writing samples. The samples stay in memory and are not saved.',
     inputSchema: { samples, avoid },
@@ -28,7 +49,7 @@ server.registerTool('hyv_build_profile', {
     }
 });
 server.registerTool('hyv_analyze', {
-    description: 'Run the separate VoiceDNA and AI Editor checks against a draft using a portable profile JSON string.',
+    description: 'Run separate VoiceDNA and AI Editor checks plus a non-scoring Unicode hygiene inspection against a draft using a portable profile JSON string.',
     inputSchema: { draft: writing, profile_json: profileJson, writing_brief_json: writingBriefJson.optional() },
     annotations: { readOnlyHint: true },
 }, async ({ draft, profile_json, writing_brief_json }) => {
@@ -39,6 +60,16 @@ server.registerTool('hyv_analyze', {
         return failure(error);
     }
 });
+server.registerTool('hyv_hygiene', {
+    description: 'Inspect text for zero-width characters, bidirectional controls, Unicode tag characters, and unusual spaces without changing it or requiring a voice profile.',
+    inputSchema: { draft: hygieneText },
+    annotations: { readOnlyHint: true },
+}, async ({ draft }) => json(inspectHygieneForMcp(draft)));
+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 },
+    annotations: { readOnlyHint: true },
+}, async ({ text }) => json(finalOutputCheckForMcp(text)));
 server.registerTool('hyv_rewrite_prompt', {
     description: 'Create a constrained editing brief. It does not rewrite the draft or call a model.',
     inputSchema: { draft: writing, profile_json: profileJson, writing_brief_json: writingBriefJson.optional() },
@@ -75,25 +106,55 @@ server.registerTool('hyv_apply_rewrite', {
         return failure(error);
     }
 });
+server.registerTool('hyv_prepare_judgment', {
+    description: 'Prepare a versioned pre-edit or post-candidate judgment task. It does not call a model.',
+    inputSchema: {
+        stage: z.enum(['pre-edit', 'post-candidate']),
+        kind: z.enum(['triage', 'argument', 'form', 'polarity', 'flatness', 'semantic']),
+        draft: writing,
+        profile_json: profileJson,
+        candidate: writing.optional(),
+    },
+    annotations: { readOnlyHint: true },
+}, async ({ stage, kind, draft, profile_json, candidate }) => {
+    try {
+        return json(prepareJudgmentForMcp(stage, kind, draft, profile_json, candidate));
+    }
+    catch (error) {
+        return failure(error);
+    }
+});
+server.registerTool('hyv_reduce_judgment', {
+    description: 'Reduce bound judgment envelopes into SHIP, EDIT, REBUILD, CLEAR, or ESCALATE. It does not call a model.',
+    inputSchema: { envelopes_json: z.string().min(1).max(250_000) },
+    annotations: { readOnlyHint: true },
+}, async ({ envelopes_json }) => {
+    try {
+        return json(reduceJudgmentForMcp(envelopes_json));
+    }
+    catch (error) {
+        return failure(error);
+    }
+});
 server.registerTool('hyv_verify', {
-    description: 'Verify a revised candidate against an original draft and portable profile. On a successful check, it stores only resolved finding IDs in local profile-scoped learning state; it never retains either text.',
+    description: 'Verify a revised candidate against an original draft and portable profile without changing learning state.',
     inputSchema: { original: writing, candidate: writing, profile_json: profileJson, writing_brief_json: writingBriefJson.optional() },
-    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
 }, async ({ original, candidate, profile_json, writing_brief_json }) => {
     try {
-        return json(verifyForMcp(original, candidate, profile_json, {}, writing_brief_json));
+        return json(verifyForMcp(original, candidate, profile_json, writing_brief_json));
     }
     catch (error) {
         return failure(error);
     }
 });
 server.registerTool('hyv_verify_copy_spec', {
-    description: 'Verify a candidate against the existing voice gates and a local CopySpec. Immutable claims must remain verbatim and each carries local evidence; prohibited claims fail closed.',
+    description: 'Verify a candidate against the existing voice gates and a local CopySpec. Immutable claims remain verbatim unless atoms are supplied; then each declared atom must remain. Prohibited claims fail closed.',
     inputSchema: { original: writing, candidate: writing, profile_json: profileJson, copy_spec_json: copySpecJson, writing_brief_json: writingBriefJson.optional() },
-    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
 }, async ({ original, candidate, profile_json, copy_spec_json, writing_brief_json }) => {
     try {
-        return json(verifyCopySpecForMcp(original, candidate, profile_json, copy_spec_json, {}, writing_brief_json));
+        return json(verifyCopySpecForMcp(original, candidate, profile_json, copy_spec_json, writing_brief_json));
     }
     catch (error) {
         return failure(error);
@@ -116,4 +177,162 @@ server.registerTool('hyv_patterns', {
     inputSchema: {},
     annotations: { readOnlyHint: true },
 }, async () => json(patternsForMcp()));
+server.registerTool('hyv_learning_inspect', {
+    description: 'Inspect profile-scoped learning receipts without returning stored instruction or draft text.',
+    inputSchema: { profile_json: profileJson }, annotations: { readOnlyHint: true },
+}, async ({ profile_json }) => { try {
+    return json(inspectLearningForMcp(profile_json));
+}
+catch (error) {
+    return failure(error);
+} });
+server.registerTool('hyv_learning_record', {
+    description: 'Record an explicit profile-scoped learning instruction with authority and provenance metadata.',
+    inputSchema: { profile_json: profileJson, instruction: z.string().min(1).max(240), ...learningOptions }, annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+}, async (args) => { try {
+    return json(recordLearningForMcp(args.profile_json, args.instruction, learningArgs(args)));
+}
+catch (error) {
+    return failure(error);
+} });
+server.registerTool('hyv_learning_ratify', {
+    description: 'Ratify a learning event for a Profile v3 revision.',
+    inputSchema: { profile_json: profileJson, event_id: z.string().min(1).max(200), ...learningOptions }, annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+}, async (args) => { try {
+    return json(ratifyLearningForMcp(args.profile_json, args.event_id, learningArgs(args)));
+}
+catch (error) {
+    return failure(error);
+} });
+server.registerTool('hyv_learning_supersede', {
+    description: 'Supersede a learning event for a Profile v3 revision.',
+    inputSchema: { profile_json: profileJson, event_id: z.string().min(1).max(200), ...learningOptions }, annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+}, async (args) => { try {
+    return json(supersedeLearningForMcp(args.profile_json, args.event_id, learningArgs(args)));
+}
+catch (error) {
+    return failure(error);
+} });
+server.registerTool('hyv_learning_migrate', {
+    description: 'Migrate Profile v2 learning into a Profile v3 identity.',
+    inputSchema: { source_profile_json: profileJson, target_profile_json: profileJson, ...learningOptions }, annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+}, async (args) => { try {
+    return json(migrateLearningForMcp(args.source_profile_json, args.target_profile_json, learningArgs(args)));
+}
+catch (error) {
+    return failure(error);
+} });
+server.registerTool('hyv_learning_clear', {
+    description: 'Delete all local learning state for a profile.',
+    inputSchema: { profile_json: profileJson }, annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+}, async ({ profile_json }) => { try {
+    return json(clearLearningForMcp(profile_json));
+}
+catch (error) {
+    return failure(error);
+} });
+server.registerTool('hyv_lifecycle_prepare_semantic', {
+    description: 'Prepare a normal semantic-review task and its initial immutable lifecycle artifact.',
+    inputSchema: { deterministic_json: lifecycleJson, binding_json: lifecycleJson, receipt_json: lifecycleJson, policy: z.literal('normal'), allowed_violations: z.array(semanticViolation).max(5) },
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+}, async (args) => { try {
+    return json(prepareLifecycleForMcp(args.deterministic_json, args.binding_json, args.receipt_json, args.policy, args.allowed_violations));
+}
+catch (error) {
+    return failure(error);
+} });
+server.registerTool('hyv_lifecycle_submit_verdict', {
+    description: 'Submit one normal-policy semantic verdict using the server-installed evaluator authorization context.',
+    inputSchema: { artifact_json: lifecycleJson, task_json: lifecycleJson, evaluator_id: evaluatorId, verdict_json: lifecycleJson },
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+}, async (args) => { try {
+    return lifecycleResult(submitSemanticVerdictForMcp(args.artifact_json, args.task_json, args.evaluator_id, args.verdict_json, loadApprovalContext()));
+}
+catch (error) {
+    return failure(error);
+} });
+server.registerTool('hyv_lifecycle_inspect', {
+    description: 'Validate and inspect an immutable lifecycle artifact without exposing bound source or candidate hashes.',
+    inputSchema: { artifact_json: lifecycleJson }, annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+}, async ({ artifact_json }) => { try {
+    return json(inspectLifecycleForMcp(artifact_json));
+}
+catch (error) {
+    return failure(error);
+} });
+if (redactsSensitiveInputs) {
+    server.registerTool('hyv_lifecycle_finalize', {
+        description: 'Finalize an authorized human approval or rejection. Capability input requires host-guaranteed sensitive-input redaction.',
+        inputSchema: { artifact_json: lifecycleJson, decision_json: lifecycleJson, capability_json: lifecycleJson.optional() },
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+    }, async (args) => { try {
+        return lifecycleResult(finalizeLifecycleForMcp(args.artifact_json, args.decision_json, loadApprovalContext(), args.capability_json));
+    }
+    catch {
+        return failure(new Error('Lifecycle finalization failed.'));
+    } });
+    server.registerTool('hyv_lifecycle_validate_final_approval', {
+        description: 'Validate a final-approval capability against the server-installed trust context.',
+        inputSchema: { artifact_json: lifecycleJson, capability_json: lifecycleJson }, annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+    }, async (args) => { try {
+        return json(validateFinalApprovalForMcp(args.artifact_json, args.capability_json, loadApprovalContext()));
+    }
+    catch {
+        return failure(new Error('Capability validation failed.'));
+    } });
+    server.registerTool('hyv_learning_record_approved', {
+        description: 'Record one approval-revalidated, deterministic, text-free learning event.',
+        inputSchema: { ready_json: lifecycleJson, approved_json: lifecycleJson, original: approvedLearningText, candidate: approvedLearningText, profile_json: profileJson, decision_json: lifecycleJson, capability_json: lifecycleJson, copy_spec_json: copySpecJson.optional(), writing_brief_json: writingBriefJson.optional() },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    }, async (args) => { try {
+        return json({ status: recordApprovedLearningForMcp({ readyJson: args.ready_json, approvedJson: args.approved_json, source: args.original, candidate: args.candidate, profileJson: args.profile_json, decisionJson: args.decision_json, capabilityJson: args.capability_json, context: loadApprovalContext(), copySpecJson: args.copy_spec_json, writingBriefJson: args.writing_brief_json }) });
+    }
+    catch {
+        return failure(new Error('Approved learning was not authorized.'));
+    } });
+    server.registerTool('hyv_prepare_rebuild', {
+        description: 'Prepare a rebuild task only after an upstream REBUILD recommendation, CopySpec, and signed rebuild-authorization capability. Capability input requires host-guaranteed sensitive-input redaction.',
+        inputSchema: {
+            draft: writing,
+            profile_json: profileJson,
+            reduction_json: lifecycleJson,
+            copy_spec_json: copySpecJson,
+            capability_json: lifecycleJson,
+            writing_brief_json: writingBriefJson.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));
+        }
+        catch {
+            return failure(new Error('Rebuild preparation failed.'));
+        }
+    });
+    server.registerTool('hyv_apply_rebuild', {
+        description: 'Validate and evaluate a whole-document rebuild response against a prepared authorized rebuild task. Capability input requires host-guaranteed sensitive-input redaction. It never calls a provider.',
+        inputSchema: { task_json: lifecycleJson, response_json: z.string().min(1).max(100_000), profile_json: profileJson, capability_json: lifecycleJson },
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+    }, async (args) => {
+        try {
+            return json(applyRebuildForMcp(args.task_json, args.response_json, args.profile_json, args.capability_json, loadApprovalContext()));
+        }
+        catch {
+            return failure(new Error('Rebuild application failed.'));
+        }
+    });
+}
+else {
+    server.registerTool('hyv_lifecycle_finalize', {
+        description: 'Record an authorized human rejection. Approval is unavailable because this host does not guarantee sensitive-input redaction.',
+        inputSchema: { artifact_json: lifecycleJson, decision_json: lifecycleJson }, annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+    }, async (args) => {
+        try {
+            return lifecycleResult(finalizeRejectionForMcp(args.artifact_json, args.decision_json, loadApprovalContext()));
+        }
+        catch {
+            return failure(new Error('Only rejection is available without sensitive-input redaction.'));
+        }
+    });
+}
 await server.connect(new StdioServerTransport());