@holdyourvoice/hyv 3.2.0 → 3.3.0

package/dist/learning.test.js

@@ -3,7 +3,7 @@ import { appendFileSync, existsSync, mkdtempSync, readFileSync, rmSync } from 'n
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import test from 'node:test';
-import { addLearningInstruction, clearLearning, composeLearning, profileFingerprint, recordVerifiedCandidate } from './learning.js';
+import { addLearningInstruction, clearLearning, composeLearning, inspectLearning, migrateLearningV2ToV3, profileFingerprint, ratifyLearningEvent, recordLearningInstruction, recordVerifiedCandidate, supersedeLearningEvent } from './learning.js';
 import { verify } from './pipeline.js';
 import { buildProfile } from './voice-dna.js';
 const profile = buildProfile([
@@ -13,6 +13,206 @@ const profile = buildProfile([
 function directory() {
     return mkdtempSync(join(tmpdir(), 'holdyourvoice-learning-'));
 }
+function version3(id, revision) {
+    return {
+        ...profile,
+        version: '3', id, revision, revisionDigest: String(revision).padStart(64, '0'),
+        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'] },
+    };
+}
+test('keeps compatible learning across Profile v3 revisions by stable identity', () => {
+    const root = directory();
+    try {
+        assert.equal(addLearningInstruction(version3('founder.jane', 1), 'Keep the mechanism.', { root }), true);
+        assert.deepEqual(composeLearning(version3('founder.jane', 2), { root }), [{ text: 'Keep the mechanism.', count: 1 }]);
+        assert.deepEqual(composeLearning(version3('founder.other', 2), { root }), []);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('migrates v2 learning explicitly and idempotently without crossing identities', () => {
+    const root = directory();
+    try {
+        addLearningInstruction(profile, 'Keep it direct.', { root });
+        const first = migrateLearningV2ToV3(profile, version3('founder.jane', 1), { root, mutationId: 'migration-1' });
+        const replay = migrateLearningV2ToV3(profile, version3('founder.jane', 1), { root, mutationId: 'migration-1' });
+        assert.equal(first.status, 'recorded');
+        assert.equal(replay.status, 'already_recorded');
+        assert.deepEqual(composeLearning(version3('founder.jane', 1), { root }), [{ text: 'Keep it direct.', count: 1 }]);
+        assert.deepEqual(composeLearning(version3('founder.other', 1), { root }), []);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('imports legacy v1 JSONL and makes default migration replay idempotent', () => {
+    const root = directory();
+    try {
+        const legacyFile = join(root, 'learning', `${profileFingerprint(profile)}.jsonl`);
+        addLearningInstruction(profile, 'bootstrap', { root });
+        const legacy = { version: '1', timestamp: '2026-08-13T00:00:00.000Z', kind: 'instruction', instruction: 'Keep the legacy cadence.' };
+        appendFileSync(legacyFile, `${JSON.stringify(legacy)}\n`);
+        const target = version3('founder.jane', 1);
+        const first = migrateLearningV2ToV3(profile, target, { root });
+        const replay = migrateLearningV2ToV3(profile, target, { root });
+        assert.equal(first.status, 'recorded');
+        assert.equal(replay.status, 'already_recorded');
+        assert.ok(composeLearning(target, { root }).some((item) => item.text === 'Keep the legacy cadence.'));
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('inspects bounded learning metadata without leaking prose', () => {
+    const root = directory();
+    try {
+        const current = version3('founder.jane', 1);
+        recordLearningInstruction(current, 'Never expose this instruction.', { root, mutationId: 'inspect-1', authority: 'founder', provenance: 'author-interview' });
+        const inspection = inspectLearning(current, { root });
+        assert.equal(inspection.length, 1);
+        assert.equal(inspection[0]?.status, 'active');
+        assert.equal(inspection[0]?.authority, 'founder');
+        const serialized = JSON.stringify(inspection);
+        assert.doesNotMatch(serialized, /Never expose this instruction|candidate text|source text/);
+        assert.ok(inspection.every((item) => !('text' in item) && !('instruction' in item) && !('candidate' in item)));
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('makes mutation replay atomic and returns a text-free receipt', () => {
+    const root = directory();
+    try {
+        const first = recordLearningInstruction(version3('founder.jane', 1), 'Keep it direct.', { root, mutationId: 'instruction-1', authority: 'founder' });
+        const replay = recordLearningInstruction(version3('founder.jane', 1), 'Keep it direct.', { root, mutationId: 'instruction-1', authority: 'founder' });
+        assert.equal(first.status, 'recorded');
+        assert.equal(replay.status, 'already_recorded');
+        assert.equal(JSON.stringify(first).includes('Keep it direct.'), false);
+        assert.deepEqual(composeLearning(version3('founder.jane', 1), { root }), [{ text: 'Keep it direct.', count: 1 }]);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('rejects conflicting mutation-id reuse without changing stored learning', () => {
+    const root = directory();
+    try {
+        const current = version3('founder.jane', 1);
+        assert.equal(recordLearningInstruction(current, 'First instruction.', { root, mutationId: 'same' }).status, 'recorded');
+        assert.equal(recordLearningInstruction(current, 'Conflicting instruction.', { root, mutationId: 'same' }).status, 'conflict');
+        assert.deepEqual(composeLearning(current, { root }), [{ text: 'First instruction.', count: 1 }]);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('fails closed on corrupt learning without rewriting the original', () => {
+    const root = directory();
+    try {
+        const current = version3('founder.jane', 1);
+        recordLearningInstruction(current, 'Valid.', { root, mutationId: 'valid' });
+        const file = join(root, 'learning', 'founder.jane.jsonl');
+        appendFileSync(file, '{corrupt}\n');
+        const before = readFileSync(file, 'utf8');
+        assert.throws(() => composeLearning(current, { root }), /corrupt/i);
+        assert.equal(recordLearningInstruction(current, 'Must not write.', { root, mutationId: 'blocked' }).status, 'corrupt');
+        assert.equal(readFileSync(file, 'utf8'), before);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('rejects lower-authority ratification and supersession', () => {
+    const root = directory();
+    try {
+        const current = version3('founder.jane', 1);
+        const founder = recordLearningInstruction(current, 'Founder ruling.', { root, mutationId: 'founder-rule', authority: 'founder' });
+        assert.equal(ratifyLearningEvent(current, founder.eventId, { root, mutationId: 'team-ratify', authority: 'team' }).status, 'unauthorized');
+        assert.equal(supersedeLearningEvent(current, founder.eventId, { root, mutationId: 'team-supersede', authority: 'team' }).status, 'unauthorized');
+        assert.deepEqual(composeLearning(current, { root }), [{ text: 'Founder ruling.', count: 1 }]);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('inspection identifiers and digests do not depend on secret prose or provenance', () => {
+    const firstRoot = directory();
+    const secondRoot = directory();
+    try {
+        const current = version3('founder.jane', 1);
+        recordLearningInstruction(current, 'Secret alpha.', { root: firstRoot, mutationId: 'public-id', provenance: 'secret provenance alpha' });
+        recordLearningInstruction(current, 'Secret beta.', { root: secondRoot, mutationId: 'public-id', provenance: 'secret provenance beta' });
+        const publicFields = (root) => inspectLearning(current, { root }).map(({ timestamp: _timestamp, ...item }) => item);
+        assert.deepEqual(publicFields(firstRoot), publicFields(secondRoot));
+    }
+    finally {
+        rmSync(firstRoot, { recursive: true, force: true });
+        rmSync(secondRoot, { recursive: true, force: true });
+    }
+});
+test('migration fails atomically when all intended imports cannot fit', () => {
+    const root = directory();
+    try {
+        for (let index = 0; index < 40; index += 1)
+            recordLearningInstruction(profile, `Legacy ${index}.`, { root, mutationId: `legacy-${index}` });
+        const target = version3('founder.capacity', 1);
+        assert.equal(migrateLearningV2ToV3(profile, target, { root }).status, 'capacity_exceeded');
+        assert.deepEqual(composeLearning(target, { root }), []);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('ratifies incompatible events and supersedes them without deleting audit history', () => {
+    const root = directory();
+    try {
+        const recorded = recordLearningInstruction(version3('founder.jane', 1), 'Keep the old cadence.', { root, mutationId: 'old', compatibility: 'exact' });
+        assert.deepEqual(composeLearning(version3('founder.jane', 2), { root }), []);
+        assert.equal(ratifyLearningEvent(version3('founder.jane', 2), recorded.eventId, { root, mutationId: 'ratify-old' }).status, 'recorded');
+        assert.deepEqual(composeLearning(version3('founder.jane', 2), { root }), [{ text: 'Keep the old cadence.', count: 1 }]);
+        assert.equal(supersedeLearningEvent(version3('founder.jane', 2), recorded.eventId, { root, mutationId: 'supersede-old' }).status, 'recorded');
+        assert.deepEqual(composeLearning(version3('founder.jane', 2), { root }), []);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('compaction retains higher-authority learning before lower-authority observations', () => {
+    const root = directory();
+    try {
+        const current = version3('founder.jane', 1);
+        recordLearningInstruction(current, 'Founder ruling.', { root, mutationId: 'founder', authority: 'founder', weight: 1 });
+        for (let index = 0; index < 45; index += 1)
+            recordLearningInstruction(current, `Team observation ${index}.`, { root, mutationId: `team-${index}`, authority: 'team', weight: 100 });
+        assert.ok(composeLearning(current, { root }).some((item) => item.text === 'Founder ruling.'));
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('compaction preserves a retained target with its ratification control', () => {
+    const root = directory();
+    try {
+        const first = version3('founder.controls', 1);
+        const second = version3('founder.controls', 2);
+        const old = recordLearningInstruction(first, 'Ratified founder ruling.', { root, mutationId: 'old-founder', authority: 'founder', compatibility: 'exact' });
+        ratifyLearningEvent(second, old.eventId, { root, mutationId: 'ratify-founder', authority: 'founder' });
+        for (let index = 0; index < 45; index += 1)
+            recordLearningInstruction(second, `Team churn ${index}.`, { root, mutationId: `churn-${index}`, authority: 'team' });
+        assert.ok(composeLearning(second, { root }).some((item) => item.text === 'Ratified founder ruling.'));
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
 test('records only resolved findings from successful verification without draft text', () => {
     const root = directory();
     try {
@@ -75,12 +275,12 @@ test('bounds retained events and local instruction size', () => {
         rmSync(root, { recursive: true, force: true });
     }
 });
-test('skips malformed local events without breaking composition', () => {
+test('fails closed on malformed local events', () => {
     const root = directory();
     try {
         addLearningInstruction(profile, 'Keep it direct.', { root });
         appendFileSync(join(root, 'learning', `${profileFingerprint(profile)}.jsonl`), '{"version":"1","timestamp":"now","kind":"verified_candidate","resolved":{}}\n');
-        assert.deepEqual(composeLearning(profile, { root }), [{ text: 'Keep it direct.', count: 1 }]);
+        assert.throws(() => composeLearning(profile, { root }), /corrupt/);
     }
     finally {
         rmSync(root, { recursive: true, force: true });

package/dist/lifecycle-adapter.js

@@ -0,0 +1,75 @@
+import { canonicalJson } from './canonical-json.js';
+import { verifyApprovalCapability } from './approval-capability.js';
+import { createInitialLifecycleArtifact, isValidLifecycleArtifact, parseSemanticVerdict, prepareSemanticReviewTask, reduceRewriteLifecycle } from './semantic-review.js';
+import { verifyDeterministically } from './pipeline.js';
+import { recordVerifiedCandidate } from './learning.js';
+export function prepareLifecycle(deterministic, binding, receipt, policy, allowedViolations) {
+    const task = prepareSemanticReviewTask(binding, policy, receipt, allowedViolations);
+    return { task, artifact: createInitialLifecycleArtifact(task, deterministic) };
+}
+export function submitSemanticVerdict(artifact, task, evaluatorId, verdict, context) {
+    try {
+        inspectLifecycle(artifact);
+    }
+    catch {
+        return { ok: false, error: 'invalid_action' };
+    }
+    const parsed = parseSemanticVerdict(task, evaluatorId, verdict);
+    return reduceRewriteLifecycle(artifact, {
+        version: '1', type: 'semantic_submission', parentArtifactFingerprint: artifact.artifactFingerprint,
+        taskFingerprint: task.taskFingerprint, verdicts: [parsed],
+    }, context);
+}
+export function inspectLifecycle(artifact) {
+    if (!artifact || artifact.version !== '1' || !isValidLifecycleArtifact(artifact))
+        throw new Error('Invalid lifecycle artifact.');
+    return {
+        version: '1', status: artifact.status, artifactFingerprint: artifact.artifactFingerprint,
+        ...(artifact.parentArtifactFingerprint ? { parentArtifactFingerprint: artifact.parentArtifactFingerprint } : {}),
+        transitionFingerprint: artifact.transitionFingerprint, semanticPolicy: artifact.semanticPolicy,
+        semanticTaskFingerprint: artifact.semanticTaskFingerprint,
+        semanticEvidenceScopeFingerprint: artifact.semanticEvidenceScopeFingerprint,
+        verdictFingerprints: [...artifact.verdictFingerprints],
+        ...(artifact.capabilityFingerprint ? { capabilityFingerprint: artifact.capabilityFingerprint } : {}),
+        ...(artifact.reason ? { reason: artifact.reason } : {}),
+    };
+}
+export function validateFinalApproval(artifact, capability, context) {
+    try {
+        inspectLifecycle(artifact);
+        const result = verifyApprovalCapability(capability, context.trustStore, { now: context.now, expectedSubjectArtifactFingerprint: artifact.artifactFingerprint, binding: artifact.binding, expectedPurpose: 'hyv.final-approval' });
+        return result.ok ? result : { ok: false, error: 'capability_invalid' };
+    }
+    catch {
+        return { ok: false, error: 'capability_invalid' };
+    }
+}
+export function finalizeLifecycle(artifact, decision, context, capability) {
+    try {
+        inspectLifecycle(artifact);
+    }
+    catch {
+        return { ok: false, error: 'invalid_action' };
+    }
+    return reduceRewriteLifecycle(artifact, {
+        version: '1', type: 'human_finalization', parentArtifactFingerprint: artifact.artifactFingerprint,
+        finalization: { version: '1', judgmentType: 'human_finalization', parentArtifactFingerprint: artifact.artifactFingerprint, binding: artifact.binding, evaluatorId: decision.evaluatorId, evidenceScope: { kind: 'candidate' }, decision: decision.decision, ...(capability ? { capability } : {}) },
+    }, context);
+}
+export function recordApprovedLearning(request) {
+    const { ready, approved, decision, capability, source, candidate, profile, context, copySpec, writingBrief } = request;
+    if (Buffer.byteLength(source, 'utf8') > 1024 * 1024 || Buffer.byteLength(candidate, 'utf8') > 1024 * 1024)
+        throw new Error('Approved learning text exceeds the byte limit.');
+    inspectLifecycle(ready);
+    inspectLifecycle(approved);
+    const replay = finalizeLifecycle(ready, decision, context, capability);
+    if (!replay.ok || canonicalJson(replay.artifact) !== canonicalJson(approved) || approved.status !== 'approved')
+        throw new Error('Approved learning is not authorized.');
+    const deterministic = verifyDeterministically(source, candidate, profile, copySpec, writingBrief);
+    if (!deterministic.verification.passed || deterministic.artifact.artifactFingerprint !== approved.binding.deterministicArtifactFingerprint
+        || deterministic.artifact.sourceHash !== approved.binding.sourceHash || deterministic.artifact.candidateHash !== approved.binding.candidateHash
+        || deterministic.artifact.profileId !== approved.binding.profileId || deterministic.artifact.profileRevisionDigest !== approved.binding.profileRevisionDigest
+        || deterministic.artifact.rulesetVersion !== approved.binding.rulesetVersion)
+        throw new Error('Approved learning binding does not match deterministic verification.');
+    return recordVerifiedCandidate(profile, deterministic.verification, candidate, { mutationId: `approved:${approved.artifactFingerprint}`, authority: 'team', provenance: `approved:${approved.capabilityFingerprint}`, compatibility: 'exact' });
+}

package/dist/lifecycle-adapter.test.js

@@ -0,0 +1,56 @@
+import assert from 'node:assert/strict';
+import { createHash, generateKeyPairSync, sign } from 'node:crypto';
+import test from 'node:test';
+import { canonicalJson, canonicalJsonBytes } from './canonical-json.js';
+import { finalizeLifecycle, inspectLifecycle, prepareLifecycle, submitSemanticVerdict, validateFinalApproval } from './lifecycle-adapter.js';
+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 deterministicFingerprint = createHash('sha256').update(`hyv:deterministic-verification:v1\0${canonicalJson(deterministicBase)}`).digest('hex');
+const deterministic = { ...deterministicBase, artifactFingerprint: deterministicFingerprint };
+const binding = { rewriteTaskFingerprint: '1'.repeat(64), rewriteResponseFingerprint: '2'.repeat(64), deterministicArtifactFingerprint: deterministicFingerprint, 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 emptyTrust = { version: '1', audience: '@holdyourvoice/hyv', maxCapabilityLifetimeSeconds: 300, keys: [] };
+const context = { now: 150, trustStore: emptyTrust, authorizedSemanticEvaluatorIds: { normal: ['reviewer-1'], highAssurance: [] }, authorizedHumanFinalizerIds: ['human-1'] };
+test('prepares and submits a normal semantic verdict through the shared adapter', () => {
+    const prepared = prepareLifecycle(deterministic, binding, receipt, 'normal', ['action_change']);
+    assert.equal(prepared.task.policy, 'normal');
+    assert.equal(prepared.artifact.status, 'needs_semantic_review');
+    const submitted = submitSemanticVerdict(prepared.artifact, prepared.task, 'reviewer-1', { approved: true, violations: [] }, context);
+    assert.equal(submitted.ok && submitted.artifact.status, 'ready_for_human_review');
+    const forged = submitSemanticVerdict({ ...prepared.artifact, artifactFingerprint: '9'.repeat(64) }, prepared.task, 'reviewer-1', { approved: true, violations: [] }, context);
+    assert.deepEqual(forged, { ok: false, error: 'invalid_action' });
+});
+test('inspection validates the artifact fingerprint and returns metadata only', () => {
+    const { artifact } = prepareLifecycle(deterministic, binding, receipt, 'normal', ['action_change']);
+    const inspected = inspectLifecycle(artifact);
+    assert.equal(inspected.status, 'needs_semantic_review');
+    assert.equal(inspected.artifactFingerprint, artifact.artifactFingerprint);
+    assert.doesNotMatch(JSON.stringify(inspected), /sourceHash|candidateHash|capability|signature|nonce|verdicts/);
+    assert.throws(() => inspectLifecycle({ ...artifact, artifactFingerprint: '9'.repeat(64) }), /invalid lifecycle artifact/i);
+    const { artifactFingerprint: _fingerprint, ...base } = artifact;
+    const malformedBase = { ...base, status: 'ready_for_human_review', parentArtifactFingerprint: artifact.artifactFingerprint };
+    const malformed = { ...malformedBase, artifactFingerprint: createHash('sha256').update(`hyv:lifecycle-artifact:v1\0${canonicalJson(malformedBase)}`).digest('hex') };
+    assert.throws(() => inspectLifecycle(malformed), /invalid lifecycle artifact/i);
+    for (const invalid of [{ ...base, status: 'garbage' }, { ...base, status: 'needs_escalation', parentArtifactFingerprint: artifact.artifactFingerprint, reason: 'garbage' }]) {
+        const recomputed = { ...invalid, artifactFingerprint: createHash('sha256').update(`hyv:lifecycle-artifact:v1\0${canonicalJson(invalid)}`).digest('hex') };
+        assert.throws(() => inspectLifecycle(recomputed), /invalid lifecycle artifact/i);
+    }
+});
+test('capability validation collapses verifier details and finalization stays reducer-backed', () => {
+    const prepared = prepareLifecycle(deterministic, binding, receipt, 'normal', ['action_change']);
+    const submitted = submitSemanticVerdict(prepared.artifact, prepared.task, 'reviewer-1', { approved: true, violations: [] }, context);
+    assert.equal(submitted.ok, true);
+    if (!submitted.ok)
+        return;
+    assert.deepEqual(validateFinalApproval(submitted.artifact, { payload: 'bad', signature: 'bad' }, context), { ok: false, error: 'capability_invalid' });
+    const rejected = finalizeLifecycle(submitted.artifact, { evaluatorId: 'human-1', decision: 'reject' }, context);
+    assert.equal(rejected.ok && rejected.artifact.status, 'needs_escalation');
+    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 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: 'secret-nonce' };
+    const payload = canonicalJsonBytes(claims);
+    const capability = { payload: payload.toString('base64url'), signature: sign(null, payload, privateKey).toString('base64url') };
+    assert.equal(validateFinalApproval(submitted.artifact, capability, { ...context, trustStore }).ok, true);
+    const approved = finalizeLifecycle(submitted.artifact, { evaluatorId: 'human-1', decision: 'approve' }, { ...context, trustStore }, capability);
+    assert.equal(approved.ok && approved.artifact.status, 'approved');
+    assert.doesNotMatch(JSON.stringify(approved), /secret-nonce|payload|signature/);
+});

package/dist/mcp-tools.js

@@ -1,12 +1,15 @@
 import { RULESET_VERSION, serializedRules } from './ai-editor.js';
 import { parseCopySpec } from './copy-spec.js';
 import { analyzeBatch, parseWritingBrief } from './editorial-packs.js';
-import { composeLearning, recordVerifiedCandidate } from './learning.js';
+import { clearLearning, composeLearning, inspectLearning, migrateLearningV2ToV3, ratifyLearningEvent, recordLearningInstruction, supersedeLearningEvent } from './learning.js';
 import { analyze, rewritePrompt, verify, verifyWithCopySpec } from './pipeline.js';
 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 { buildProfile } from './voice-dna.js';
 import { finalOutputCheck, inspectHygiene } from './hygiene.js';
+import { finalizeLifecycle, inspectLifecycle, prepareLifecycle, recordApprovedLearning, submitSemanticVerdict, validateFinalApproval } from './lifecycle-adapter.js';
 function profileFromJson(profileJson) {
     try {
         return parseProfile(JSON.parse(profileJson));
@@ -15,6 +18,12 @@ function profileFromJson(profileJson) {
         throw new Error(error instanceof Error ? error.message : 'Profile is not valid JSON.');
     }
 }
+function profileV3FromJson(profileJson) {
+    const profile = profileFromJson(profileJson);
+    if (profile.version !== '3')
+        throw new Error('This learning operation requires a Profile v3.');
+    return profile;
+}
 function copySpecFromJson(copySpecJson) {
     try {
         return parseCopySpec(JSON.parse(copySpecJson));
@@ -55,15 +64,79 @@ export function prepareRewriteForMcp(draft, profileJson, copySpecJson, writingBr
 export function applyRewriteForMcp(taskJson, responseJson, profileJson) {
     return evaluateRewriteResponse(parseRewriteTask(JSON.parse(taskJson)), responseJson, profileFromJson(profileJson));
 }
-export function verifyForMcp(original, candidate, profileJson, options = {}, writingBriefJson) {
+export function prepareJudgmentForMcp(stage, kind, draft, profileJson, candidate) {
+    const profile = profileFromJson(profileJson);
+    return stage === 'pre-edit'
+        ? preparePreEditJudgment(draft, profile, kind)
+        : preparePostCandidateJudgment(draft, candidate ?? '', profile, kind);
+}
+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 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 verifyForMcp(original, candidate, profileJson, writingBriefJson) {
     const profile = profileFromJson(profileJson);
-    const result = verify(original, candidate, profile, writingBriefFromJson(writingBriefJson));
-    return { ...result, learning: recordVerifiedCandidate(profile, result, candidate, options) };
+    return verify(original, candidate, profile, writingBriefFromJson(writingBriefJson));
 }
-export function verifyCopySpecForMcp(original, candidate, profileJson, copySpecJson, options = {}, writingBriefJson) {
+export function verifyCopySpecForMcp(original, candidate, profileJson, copySpecJson, writingBriefJson) {
     const profile = profileFromJson(profileJson);
-    const result = verifyWithCopySpec(original, candidate, profile, copySpecFromJson(copySpecJson), writingBriefFromJson(writingBriefJson));
-    return { ...result, learning: result.passed ? recordVerifiedCandidate(profile, result, candidate, options) : 'nothing_to_learn' };
+    return verifyWithCopySpec(original, candidate, profile, copySpecFromJson(copySpecJson), writingBriefFromJson(writingBriefJson));
+}
+function parsed(json, label) {
+    if (Buffer.byteLength(json, 'utf8') > 1024 * 1024)
+        throw new Error(`${label} exceeds the byte limit.`);
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        throw new Error(`${label} is not valid JSON.`);
+    }
+}
+export function prepareLifecycleForMcp(deterministicJson, bindingJson, receiptJson, policy, allowedViolations) {
+    if (policy !== 'normal')
+        throw new Error('High-assurance semantic review requires a trusted embedding.');
+    return prepareLifecycle(parsed(deterministicJson, 'Deterministic artifact'), parsed(bindingJson, 'Lifecycle binding'), parsed(receiptJson, 'Rewrite receipt'), policy, allowedViolations);
+}
+export function submitSemanticVerdictForMcp(artifactJson, taskJson, evaluatorId, verdictJson, context) {
+    const task = parsed(taskJson, 'Semantic task');
+    if (task.policy !== 'normal')
+        throw new Error('High-assurance semantic review requires a trusted embedding.');
+    return submitSemanticVerdict(parsed(artifactJson, 'Lifecycle artifact'), task, evaluatorId, parsed(verdictJson, 'Semantic verdict'), context);
+}
+export function inspectLifecycleForMcp(artifactJson) {
+    return inspectLifecycle(parsed(artifactJson, 'Lifecycle artifact'));
+}
+export function validateFinalApprovalForMcp(artifactJson, capabilityJson, context) {
+    return validateFinalApproval(parsed(artifactJson, 'Lifecycle artifact'), parsed(capabilityJson, 'Approval capability'), context);
+}
+export function finalizeLifecycleForMcp(artifactJson, decisionJson, context, capabilityJson) {
+    const decision = parsed(decisionJson, 'Finalization decision');
+    if (decision.decision === 'approve' && !capabilityJson)
+        throw new Error('Approval requires a capability.');
+    if (decision.decision === 'reject' && capabilityJson)
+        throw new Error('Rejection does not accept a capability.');
+    return finalizeLifecycle(parsed(artifactJson, 'Lifecycle artifact'), decision, context, capabilityJson ? parsed(capabilityJson, 'Approval capability') : undefined);
+}
+export function finalizeRejectionForMcp(artifactJson, decisionJson, context) {
+    const decision = parsed(decisionJson, 'Finalization decision');
+    if (decision.decision !== 'reject')
+        throw new Error('Only rejection is available.');
+    return finalizeLifecycle(parsed(artifactJson, 'Lifecycle artifact'), decision, context);
+}
+export function recordApprovedLearningForMcp(request) {
+    const { readyJson, approvedJson, source, candidate, profileJson, decisionJson, capabilityJson, context, copySpecJson, writingBriefJson } = request;
+    return recordApprovedLearning({
+        ready: parsed(readyJson, 'Ready artifact'), approved: parsed(approvedJson, 'Approved artifact'),
+        decision: parsed(decisionJson, 'Finalization decision'), capability: parsed(capabilityJson, 'Approval capability'),
+        source, candidate, profile: profileFromJson(profileJson), context,
+        copySpec: copySpecJson ? copySpecFromJson(copySpecJson) : undefined, writingBrief: writingBriefFromJson(writingBriefJson),
+    });
 }
 export function patternsForMcp() {
     return { version: RULESET_VERSION, rules: serializedRules() };
@@ -71,3 +144,24 @@ export function patternsForMcp() {
 export function analyzeBatchForMcp(drafts) {
     return analyzeBatch(drafts);
 }
+export function inspectLearningForMcp(profileJson, options = {}) {
+    return inspectLearning(profileFromJson(profileJson), options);
+}
+export function recordLearningForMcp(profileJson, instruction, options = {}) {
+    return recordLearningInstruction(profileFromJson(profileJson), instruction, options);
+}
+export function ratifyLearningForMcp(profileJson, eventId, options = {}) {
+    return ratifyLearningEvent(profileV3FromJson(profileJson), eventId, options);
+}
+export function supersedeLearningForMcp(profileJson, eventId, options = {}) {
+    return supersedeLearningEvent(profileV3FromJson(profileJson), eventId, options);
+}
+export function migrateLearningForMcp(sourceProfileJson, targetProfileJson, options = {}) {
+    const source = profileFromJson(sourceProfileJson);
+    if (source.version !== '2')
+        throw new Error('Learning migration requires a Profile v2 source.');
+    return migrateLearningV2ToV3(source, profileV3FromJson(targetProfileJson), options);
+}
+export function clearLearningForMcp(profileJson, options = {}) {
+    return { cleared: clearLearning(profileFromJson(profileJson), options) };
+}