@holdyourvoice/hyv 3.2.0 → 3.3.1

package/dist/profile.js

@@ -1,3 +1,25 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson } from './canonical-json.js';
+const METRICS_KEYS = ['sentenceLength', 'sentenceVariation', 'sentenceStructure', 'rhythm', 'paragraphLength', 'openingMoves', 'vocabulary', 'lexicalDensity', 'pointOfView', 'punctuation', 'caseStyle', 'questionRate', 'transitions'];
+const PROFILE_V3_KEYS = ['version', 'id', 'revision', 'revisionDigest', 'sampleCount', 'metrics', 'avoid', 'provenance', 'rulePolicy', 'fingerprint', 'tolerances', 'metricFixtures'];
+const FINGERPRINT_METRICS = ['contractionRate', 'sentenceLengthDistribution', 'bulletRate', 'enDashRate'];
+const STABLE_ID = /^[a-z0-9](?:[a-z0-9._-]{0,127})$/;
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
+}
+function hasKnownKeys(value, keys) {
+    return Object.keys(value).every((key) => keys.includes(key)) && keys.every((key) => key in value);
+}
+function isBoundedString(value, maximum = 256) {
+    return typeof value === 'string' && value.trim().length > 0 && value.length <= maximum;
+}
+function isRate(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1;
+}
+function isBoundedStringArray(value, minimum = 0) {
+    return Array.isArray(value) && value.length >= minimum && value.length <= 64
+        && value.every((item) => isBoundedString(item)) && new Set(value).size === value.length;
+}
 function isNumberRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype
         && Object.values(value).every((item) => typeof item === 'number' && Number.isFinite(item));
@@ -20,10 +42,75 @@ function isMetrics(value) {
         && stringArrays.every((items) => Array.isArray(items) && items.every((item) => typeof item === 'string'))
         && isPunctuation(metrics.punctuation);
 }
+function isStrictMetrics(value) {
+    return isPlainObject(value) && hasKnownKeys(value, METRICS_KEYS) && isMetrics(value)
+        && [value.sentenceStructure, value.openingMoves, value.vocabulary, value.transitions].every((items) => isBoundedStringArray(items));
+}
+function isProvenance(value) {
+    if (!isPlainObject(value) || !hasKnownKeys(value, ['source', 'rights', 'createdAt']))
+        return false;
+    if (!isBoundedString(value.source) || !isBoundedString(value.rights) || !isBoundedString(value.createdAt, 64))
+        return false;
+    const parsed = new Date(value.createdAt);
+    return !Number.isNaN(parsed.valueOf()) && parsed.toISOString() === value.createdAt;
+}
+function isRulePolicy(value) {
+    if (!isPlainObject(value) || Object.keys(value).length > 512)
+        return false;
+    const states = ['blocking', 'advisory', 'judgment-required', 'disabled'];
+    return Object.entries(value).every(([id, state]) => STABLE_ID.test(id) && states.includes(state));
+}
+function isFingerprint(value) {
+    if (!isPlainObject(value) || !hasKnownKeys(value, FINGERPRINT_METRICS))
+        return false;
+    const distribution = value.sentenceLengthDistribution;
+    if (!isPlainObject(distribution) || !hasKnownKeys(distribution, ['short', 'medium', 'long']))
+        return false;
+    const parts = [distribution.short, distribution.medium, distribution.long];
+    return isRate(value.contractionRate) && isRate(value.bulletRate) && isRate(value.enDashRate)
+        && parts.every(isRate) && Math.abs(parts.reduce((sum, item) => sum + item, 0) - 1) < 1e-9;
+}
+function isTolerances(value) {
+    return isPlainObject(value) && hasKnownKeys(value, FINGERPRINT_METRICS) && FINGERPRINT_METRICS.every((key) => {
+        const tolerance = value[key];
+        return isPlainObject(tolerance) && hasKnownKeys(tolerance, ['absolute', 'calibrated'])
+            && isRate(tolerance.absolute) && typeof tolerance.calibrated === 'boolean';
+    });
+}
+function isMetricFixtures(value) {
+    return isPlainObject(value) && hasKnownKeys(value, FINGERPRINT_METRICS)
+        && FINGERPRINT_METRICS.every((key) => isBoundedStringArray(value[key], 1) && value[key].every((id) => STABLE_ID.test(id)));
+}
+function hasValidRevisionDigest(profile) {
+    if (typeof profile.revisionDigest !== 'string' || !/^[a-f0-9]{64}$/.test(profile.revisionDigest))
+        return false;
+    const { revisionDigest, ...unsigned } = profile;
+    return createHash('sha256').update(canonicalJson(unsigned)).digest('hex') === revisionDigest;
+}
+function parseProfileV3(value) {
+    const valid = isPlainObject(value) && hasKnownKeys(value, PROFILE_V3_KEYS)
+        && typeof value.id === 'string' && STABLE_ID.test(value.id)
+        && typeof value.revision === 'number' && Number.isSafeInteger(value.revision) && value.revision > 0
+        && typeof value.sampleCount === 'number' && Number.isInteger(value.sampleCount) && value.sampleCount >= 2
+        && isStrictMetrics(value.metrics)
+        && isBoundedStringArray(value.avoid)
+        && isProvenance(value.provenance)
+        && isRulePolicy(value.rulePolicy)
+        && isFingerprint(value.fingerprint)
+        && isTolerances(value.tolerances)
+        && isMetricFixtures(value.metricFixtures);
+    if (!valid)
+        throw new Error('Profile is not a valid Hold Your Voice version 3 profile. Rebuild it from fixture-backed metrics.');
+    if (!hasValidRevisionDigest(value))
+        throw new Error('Profile version 3 revision digest does not match its canonical contents.');
+    return value;
+}
 export function parseProfile(value) {
     if (!value || typeof value !== 'object')
         throw new Error('Profile must be a JSON object.');
     const profile = value;
+    if (profile.version === '3')
+        return parseProfileV3(profile);
     if (profile.version !== '2' || typeof profile.sampleCount !== 'number' || !Number.isInteger(profile.sampleCount) || profile.sampleCount < 2 || !isMetrics(profile.metrics) || !Array.isArray(profile.avoid) || !profile.avoid.every((item) => typeof item === 'string' && item.trim().length > 0)) {
         throw new Error('Profile is not a valid Hold Your Voice version 2 profile. Rebuild it with the profile command.');
     }

package/dist/profile.test.js

@@ -0,0 +1,114 @@
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import test from 'node:test';
+import { parseProfile } from './profile.js';
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    if (value !== null && typeof value === 'object') {
+        return `{${Object.entries(value).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function profileV3() {
+    const unsigned = {
+        version: '3',
+        id: 'founder.primary',
+        revision: 1,
+        sampleCount: 2,
+        metrics: {
+            sentenceLength: 7,
+            sentenceVariation: 2,
+            sentenceStructure: ['i name the'],
+            rhythm: 2,
+            paragraphLength: 2,
+            openingMoves: ['i'],
+            vocabulary: ['mechanism'],
+            lexicalDensity: 0.5,
+            pointOfView: 'first_person',
+            punctuation: { '!': 0, '?': 0, ';': 0, ':': 0, '—': 0 },
+            caseStyle: 'lowercase',
+            questionRate: 0,
+            transitions: ['but'],
+        },
+        avoid: ['unlock'],
+        provenance: { source: 'local-author-owned-samples', rights: 'author-owned', createdAt: '2026-08-13T00:00:00.000Z' },
+        rulePolicy: {
+            'ai.antithesis': 'advisory',
+            'ai.staccato': 'judgment-required',
+            'ai.generic': 'blocking',
+            'ai.question-hook': 'disabled',
+        },
+        fingerprint: {
+            contractionRate: 0.3,
+            sentenceLengthDistribution: { short: 0.2, medium: 0.5, long: 0.3 },
+            bulletRate: 0.1,
+            enDashRate: 0.05,
+        },
+        tolerances: {
+            contractionRate: { absolute: 0.1, calibrated: true },
+            sentenceLengthDistribution: { absolute: 0.15, calibrated: false },
+            bulletRate: { absolute: 0.1, calibrated: false },
+            enDashRate: { absolute: 0.05, calibrated: false },
+        },
+        metricFixtures: {
+            contractionRate: ['fixture.contractions'],
+            sentenceLengthDistribution: ['fixture.sentences'],
+            bulletRate: ['fixture.bullets'],
+            enDashRate: ['fixture.en-dashes'],
+        },
+    };
+    return {
+        ...unsigned,
+        revisionDigest: createHash('sha256').update(canonicalJson(unsigned)).digest('hex'),
+    };
+}
+test('keeps Profile v2 parsing and runtime shape byte-for-byte compatible', () => {
+    const profile = {
+        version: '2', sampleCount: 2,
+        metrics: {
+            sentenceLength: 4, sentenceVariation: 1, sentenceStructure: [], rhythm: 1, paragraphLength: 1,
+            openingMoves: [], vocabulary: [], lexicalDensity: 0.5, pointOfView: 'mixed',
+            punctuation: { '!': 0, '?': 0, ';': 0, ':': 0, '—': 0 }, caseStyle: 'mixed', questionRate: 0, transitions: [],
+        },
+        avoid: [],
+        legacyExtension: true,
+    };
+    assert.strictEqual(parseProfile(profile), profile);
+});
+test('parses a strict Profile v3 with all four rule policy states and fixture-backed metrics', () => {
+    const profile = profileV3();
+    assert.strictEqual(parseProfile(profile), profile);
+});
+test('rejects a changed Profile v3 revision digest', () => {
+    const profile = profileV3();
+    profile.fingerprint.bulletRate = 0.2;
+    assert.throws(() => parseProfile(profile), /revision digest/);
+});
+test('rejects malformed Profile v3 identity, policy, provenance, and unknown keys', () => {
+    for (const mutate of [
+        (profile) => { profile.id = '../founder'; },
+        (profile) => { profile.revision = 0; },
+        (profile) => { profile.rulePolicy['ai.generic'] = 'warn'; },
+        (profile) => { profile.provenance.source = ''; },
+        (profile) => { profile.extra = true; },
+    ]) {
+        const profile = profileV3();
+        mutate(profile);
+        assert.throws(() => parseProfile(profile), /version 3 profile/);
+    }
+});
+test('rejects unbounded or invalid Profile v3 metrics and tolerances', () => {
+    for (const mutate of [
+        (profile) => { profile.fingerprint.contractionRate = Number.NaN; },
+        (profile) => { profile.fingerprint.sentenceLengthDistribution = { short: 0.2, medium: 0.2, long: 0.2 }; },
+        (profile) => { profile.tolerances.bulletRate.absolute = 1.1; },
+        (profile) => { profile.tolerances.enDashRate.calibrated = 'yes'; },
+        (profile) => { profile.metricFixtures.enDashRate = []; },
+        (profile) => { profile.metricFixtures.bulletRate = Array.from({ length: 65 }, (_, index) => `fixture.${index}`); },
+    ]) {
+        const profile = profileV3();
+        mutate(profile);
+        assert.throws(() => parseProfile(profile), /version 3 profile/);
+    }
+});

package/dist/rebuild-task.js

@@ -0,0 +1,226 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson } from './canonical-json.js';
+import { parseCopySpec } from './copy-spec.js';
+import { parseWritingBrief } from './editorial-packs.js';
+import { verifyApprovalCapability } from './approval-capability.js';
+import { fingerprintPreEditReduction } from './judgment-task.js';
+import { verifyRebuildDeterministically } from './pipeline.js';
+import { sentences } from './text.js';
+import { HYV_VERSION } from './version.js';
+const MAX_RESPONSE_BYTES = 100_000;
+const MAX_CANDIDATE_CHARACTERS = 100_000;
+function fingerprint(value) {
+    return createHash('sha256').update(typeof value === 'string' ? value : canonicalJson(value)).digest('hex');
+}
+function digest(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function digestCanonical(value) {
+    return digest(canonicalJson(value));
+}
+function failure(code, message, path) {
+    return { code, message, ...(path ? { path } : {}) };
+}
+function isFailure(value) {
+    return typeof value === 'object' && value !== null && 'code' in value && 'message' in value;
+}
+function profileIdentity(profile) {
+    if (profile.version === '3')
+        return { profileId: profile.id, profileRevisionDigest: profile.revisionDigest };
+    const legacy = `legacy-v2:${digestCanonical(profile)}`;
+    return { profileId: legacy, profileRevisionDigest: legacy };
+}
+function parseJson(value) {
+    if (Buffer.byteLength(value) > MAX_RESPONSE_BYTES)
+        return failure('response_too_large', `Response exceeds ${MAX_RESPONSE_BYTES} bytes.`);
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return failure('invalid_json', 'Response must be valid JSON.');
+    }
+}
+function parseRebuildResponse(value) {
+    const raw = typeof value === 'string' ? parseJson(value) : value;
+    if (isFailure(raw))
+        return raw;
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return failure('invalid_response_shape', 'Response must be an object.');
+    const response = raw;
+    if ('replacements' in response || 'operations' in response) {
+        return failure('edit_response_on_rebuild_task', 'Edit responses cannot satisfy rebuild tasks.');
+    }
+    if (response.mode === 'SHIP')
+        return failure('edit_response_on_rebuild_task', 'Edit responses cannot satisfy rebuild tasks.', 'mode');
+    if (response.version !== '1')
+        return failure('invalid_response_version', 'Rebuild response version must be "1".', 'version');
+    if (response.mode !== 'REBUILD')
+        return failure('invalid_response_shape', 'Rebuild responses require mode REBUILD.', 'mode');
+    if (typeof response.taskFingerprint !== 'string' || response.taskFingerprint.length !== 64) {
+        return failure('invalid_response_shape', 'Response must include the task fingerprint.', 'taskFingerprint');
+    }
+    if (typeof response.candidate !== 'string')
+        return failure('invalid_candidate_text', 'Rebuild candidate must be a string.', 'candidate');
+    if (!response.candidate.trim() || response.candidate.length > MAX_CANDIDATE_CHARACTERS) {
+        return failure('invalid_candidate_text', `Rebuild candidate must contain at most ${MAX_CANDIDATE_CHARACTERS} characters.`, 'candidate');
+    }
+    return response;
+}
+function renderRebuildPrompt(draft, copySpec, writingBrief) {
+    return [
+        '# Rebuild contract',
+        'Return a whole-document candidate. Do not emit sentence replacements or range operations.',
+        'Keep every immutable CopySpec claim and atom. Do not add prohibited claims.',
+        'Claim, polarity, hygiene, fingerprint, and semantic gates remain blocking. Lexical survival is not required.',
+        '',
+        '# CopySpec',
+        canonicalJson({ audience: copySpec.audience, intent: copySpec.intent, channel: copySpec.channel, claims: copySpec.claims, ...(copySpec.prohibitedClaims ? { prohibitedClaims: copySpec.prohibitedClaims } : {}) }),
+        ...(writingBrief ? ['', '# WritingBrief', canonicalJson(writingBrief)] : []),
+        '',
+        '# Draft',
+        draft,
+    ].join('\n');
+}
+function authorizationBinding(draft, profile, recommendationFingerprint) {
+    const identity = profileIdentity(profile);
+    const sourceHash = digest(draft);
+    return {
+        rewriteTaskFingerprint: recommendationFingerprint,
+        rewriteResponseFingerprint: recommendationFingerprint,
+        deterministicArtifactFingerprint: recommendationFingerprint,
+        sourceHash,
+        candidateHash: sourceHash,
+        profileId: identity.profileId,
+        profileRevisionDigest: identity.profileRevisionDigest,
+        rulesetVersion: HYV_VERSION,
+        schemaVersion: '1',
+    };
+}
+function verifyRebuildAuthorization(draft, profile, recommendationFingerprint, capability, trustStore, now) {
+    const authorized = verifyApprovalCapability(capability, trustStore, {
+        now,
+        expectedSubjectArtifactFingerprint: recommendationFingerprint,
+        binding: authorizationBinding(draft, profile, recommendationFingerprint),
+        expectedPurpose: 'hyv.rebuild-authorization',
+    });
+    if (!authorized.ok)
+        throw new Error('Rebuild authorization is invalid.');
+    return authorized;
+}
+export function prepareRebuildTask(draft, profile, reduction, copySpec, capability, trustStore, now, writingBrief) {
+    if (reduction.decision !== 'REBUILD')
+        throw new Error('Rebuild requires an upstream REBUILD recommendation.');
+    if (fingerprintPreEditReduction(reduction) !== reduction.recommendationFingerprint || reduction.recommendationFingerprint.length !== 64) {
+        throw new Error('Rebuild requires an upstream REBUILD recommendation.');
+    }
+    const spec = parseCopySpec(copySpec);
+    const identity = profileIdentity(profile);
+    const authorized = verifyRebuildAuthorization(draft, profile, reduction.recommendationFingerprint, capability, trustStore, now);
+    if (writingBrief)
+        parseWritingBrief(writingBrief);
+    const taskBase = {
+        version: '1',
+        draft,
+        prompt: renderRebuildPrompt(draft, spec, writingBrief),
+        copySpec: spec,
+        recommendationFingerprint: reduction.recommendationFingerprint,
+        authorizationFingerprint: authorized.capabilityFingerprint,
+        profileId: identity.profileId,
+        profileRevisionDigest: identity.profileRevisionDigest,
+        ...(writingBrief ? { writingBrief } : {}),
+    };
+    return { ...taskBase, fingerprint: fingerprint(taskBase) };
+}
+export function parseRebuildTask(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Rebuild task must be an object.');
+    const task = value;
+    if (task.version !== '1' || typeof task.fingerprint !== 'string' || typeof task.draft !== 'string' || typeof task.prompt !== 'string'
+        || typeof task.recommendationFingerprint !== 'string' || typeof task.authorizationFingerprint !== 'string'
+        || typeof task.profileId !== 'string' || typeof task.profileRevisionDigest !== 'string' || !task.copySpec) {
+        throw new Error('Rebuild task does not match version 1.');
+    }
+    parseCopySpec(task.copySpec);
+    if (task.writingBrief !== undefined)
+        parseWritingBrief(task.writingBrief);
+    const { fingerprint: suppliedFingerprint, ...base } = task;
+    if (fingerprint(base) !== suppliedFingerprint)
+        throw new Error('Rebuild task fingerprint does not match its contents.');
+    return task;
+}
+function rejected(task, raw, failures) {
+    return {
+        status: 'repairable',
+        failures,
+        receipt: {
+            version: '1',
+            taskFingerprint: task.fingerprint,
+            responseFingerprint: fingerprint(raw),
+            adapterIds: [],
+            replacementSentenceIds: [],
+            mode: 'REBUILD',
+            recommendationFingerprint: task.recommendationFingerprint,
+        },
+    };
+}
+export function applyRebuildResponse(task, raw) {
+    const response = parseRebuildResponse(typeof raw === 'string' ? parseJson(raw) : raw);
+    if (isFailure(response))
+        return rejected(task, raw, [response]);
+    if (response.taskFingerprint !== task.fingerprint) {
+        return rejected(task, raw, [failure('task_fingerprint_mismatch', 'Response task fingerprint does not match this task.', 'taskFingerprint')]);
+    }
+    return {
+        status: 'accepted',
+        candidate: response.candidate,
+        failures: [],
+        receipt: {
+            version: '1',
+            taskFingerprint: task.fingerprint,
+            responseFingerprint: fingerprint(raw),
+            adapterIds: [],
+            replacementSentenceIds: sentences(response.candidate).map((sentence) => sentence.index),
+            mode: 'REBUILD',
+            recommendationFingerprint: task.recommendationFingerprint,
+        },
+    };
+}
+export function evaluateRebuildResponse(task, raw, profile, capability, trustStore, now) {
+    const identity = profileIdentity(profile);
+    if (identity.profileId !== task.profileId || identity.profileRevisionDigest !== task.profileRevisionDigest) {
+        throw new Error('Rebuild profile binding does not match this task.');
+    }
+    const authorized = verifyRebuildAuthorization(task.draft, profile, task.recommendationFingerprint, capability, trustStore, now);
+    if (authorized.capabilityFingerprint !== task.authorizationFingerprint)
+        throw new Error('Rebuild authorization is invalid.');
+    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 receipt = {
+        ...applied.receipt,
+        preservationBypass: true,
+        authorizationFingerprint: authorized.capabilityFingerprint,
+        preservationScore: verification.preservationScore,
+    };
+    if (!verification.passed)
+        return { ...applied, receipt, status: 'needs_escalation', verification, deterministicArtifact };
+    const lifecycleBinding = createRebuildLifecycleBinding(task, receipt, deterministicArtifact);
+    return { ...applied, receipt, status: 'needs_semantic_review', verification, deterministicArtifact, lifecycleBinding };
+}
+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.');
+    }
+    return {
+        rewriteTaskFingerprint: task.fingerprint,
+        rewriteResponseFingerprint: receipt.responseFingerprint,
+        deterministicArtifactFingerprint: deterministic.artifactFingerprint,
+        sourceHash: deterministic.sourceHash,
+        candidateHash: deterministic.candidateHash,
+        profileId: deterministic.profileId,
+        profileRevisionDigest: deterministic.profileRevisionDigest,
+        rulesetVersion: deterministic.rulesetVersion,
+        schemaVersion: '1',
+    };
+}

package/dist/rebuild-task.test.js

@@ -0,0 +1,179 @@
+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 { applyRewriteResponse, prepareRewriteTask } from './rewrite-task.js';
+import { applyRebuildResponse, evaluateRebuildResponse, parseRebuildTask, prepareRebuildTask } from './rebuild-task.js';
+import { bindJudgmentEnvelope, preparePreEditJudgment, reducePreEdit } from './judgment-task.js';
+import { verifyDeterministically, verifyRebuildWithCopySpec } from './pipeline.js';
+import { prepareLifecycle, recordApprovedLearning } from './lifecycle-adapter.js';
+import { buildProfile } from './voice-dna.js';
+import { HYV_VERSION } from './version.js';
+const profile = buildProfile([
+    'I write clear notes. I keep the mechanism visible.',
+    'I name the trade-off. Then I make the next step plain.',
+], ['leverage']);
+const draft = 'I leverage the answer. The launch is on 14 August.';
+const rebuilt = '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.';
+const copySpec = {
+    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 { 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' }],
+};
+function envelope(task, decision, extra = {}) {
+    return {
+        version: '1',
+        stage: task.stage,
+        judgmentType: task.judgmentType,
+        taskFingerprint: task.taskFingerprint,
+        bindings: { ...task.bindings, evaluatorId: 'writer.1' },
+        findings: [],
+        decision,
+        ...extra,
+    };
+}
+function rebuildRecommendation(text = draft) {
+    const triage = preparePreEditJudgment(text, profile, 'triage');
+    const argument = preparePreEditJudgment(text, profile, 'argument');
+    const form = preparePreEditJudgment(text, profile, 'form');
+    return reducePreEdit([
+        bindJudgmentEnvelope(triage, envelope(triage, 'SHIP')),
+        bindJudgmentEnvelope(argument, envelope(argument, 'REBUILD')),
+        bindJudgmentEnvelope(form, envelope(form, 'SHIP')),
+    ]);
+}
+function capability(reduction, overrides = {}, source = draft) {
+    const sourceHash = createHash('sha256').update(source).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: 'nonce-rebuild',
+        ...overrides,
+    };
+    const payload = canonicalJsonBytes(claims);
+    return { payload: payload.toString('base64url'), signature: sign(null, payload, privateKey).toString('base64url') };
+}
+function evaluate(task, raw, reduction, boundProfile = profile) {
+    return evaluateRebuildResponse(task, raw, boundProfile, capability(reduction), trustStore, 150);
+}
+test('pre-edit reductions carry a stable recommendation fingerprint', () => {
+    const left = rebuildRecommendation();
+    const right = rebuildRecommendation();
+    assert.equal(left.decision, 'REBUILD');
+    assert.match(left.recommendationFingerprint, /^[a-f0-9]{64}$/);
+    assert.equal(left.recommendationFingerprint, right.recommendationFingerprint);
+});
+test('a caller cannot self-select rebuild or submit a forged authorization', () => {
+    const reduction = rebuildRecommendation();
+    const edit = { ...reduction, decision: 'EDIT' };
+    assert.throws(() => prepareRebuildTask(draft, profile, edit, copySpec, capability(reduction), trustStore, 150), /upstream REBUILD recommendation/);
+    assert.throws(() => prepareRebuildTask(draft, profile, reduction, copySpec, capability(reduction, { purpose: 'hyv.final-approval' }), trustStore, 150), /Rebuild authorization is invalid/);
+    assert.throws(() => prepareRebuildTask(draft, profile, reduction, copySpec, capability(reduction, { nonce: 'stale' }), { ...trustStore, keys: [{ ...trustStore.keys[0], status: 'revoked' }] }, 150), /Rebuild authorization is invalid/);
+    assert.throws(() => prepareRebuildTask(draft, profile, reduction, copySpec, capability(reduction, { sourceHash: '8'.repeat(64) }), trustStore, 150), /Rebuild authorization is invalid/);
+    assert.throws(() => prepareRebuildTask(draft, profile, { ...reduction, recommendationFingerprint: 'a'.repeat(64) }, copySpec, capability(reduction), trustStore, 150), /upstream REBUILD recommendation/);
+});
+test('missing CopySpec blocks rebuild before a candidate is evaluated', () => {
+    const reduction = rebuildRecommendation();
+    assert.throws(() => prepareRebuildTask(draft, profile, reduction, { ...copySpec, claims: [] }, capability(reduction), trustStore, 150), /CopySpec/);
+});
+test('edit and rebuild responses are mutually incompatible', () => {
+    const reduction = rebuildRecommendation();
+    const rebuildTask = prepareRebuildTask(draft, profile, reduction, copySpec, capability(reduction), trustStore, 150);
+    const editTask = prepareRewriteTask(draft, profile);
+    const rebuildOnEdit = applyRewriteResponse(editTask, { version: '1', mode: 'REBUILD', taskFingerprint: editTask.fingerprint, candidate: rebuilt });
+    assert.equal(rebuildOnEdit.status, 'repairable');
+    assert.equal(rebuildOnEdit.failures[0]?.code, 'rebuild_response_on_edit_task');
+    const replacementsOnRebuild = applyRebuildResponse(rebuildTask, { version: '1', taskFingerprint: rebuildTask.fingerprint, replacements: [{ sentenceId: 1, text: 'I use the answer.' }] });
+    assert.equal(replacementsOnRebuild.status, 'repairable');
+    assert.equal(replacementsOnRebuild.failures[0]?.code, 'edit_response_on_rebuild_task');
+    const unsigned = applyRebuildResponse(rebuildTask, { version: '1', mode: 'REBUILD', taskFingerprint: rebuildTask.fingerprint, candidate: rebuilt });
+    assert.equal(unsigned.status, 'accepted');
+    assert.equal(unsigned.receipt.authorizationFingerprint, undefined);
+    assert.equal(unsigned.receipt.preservationBypass, undefined);
+});
+test('authorized rebuild allows low lexical survival while claims and hygiene still block', () => {
+    const reduction = rebuildRecommendation();
+    const task = prepareRebuildTask(draft, profile, reduction, copySpec, capability(reduction), trustStore, 150);
+    const passed = evaluate(task, { version: '1', mode: 'REBUILD', taskFingerprint: task.fingerprint, candidate: rebuilt }, reduction);
+    assert.equal(passed.status, 'needs_semantic_review');
+    assert.ok((passed.verification?.preservationScore ?? 100) < 70);
+    assert.equal(passed.receipt.mode, 'REBUILD');
+    assert.equal(passed.receipt.preservationBypass, true);
+    assert.ok(Array.isArray(passed.receipt.replacementSentenceIds));
+    assert.ok((passed.receipt.replacementSentenceIds?.length ?? 0) > 0);
+    assert.equal(passed.deterministicArtifact?.verificationKind, 'rebuild');
+    assert.equal(prepareLifecycle(passed.deterministicArtifact, passed.lifecycleBinding, passed.receipt, 'normal', ['action_change']).artifact.status, 'needs_semantic_review');
+    assert.equal(verifyRebuildWithCopySpec(draft, rebuilt, profile, copySpec).passed, true);
+    const missingClaim = evaluate(task, { version: '1', mode: 'REBUILD', taskFingerprint: task.fingerprint, candidate: 'Operators should delay the launch indefinitely.' }, reduction);
+    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');
+});
+test('rebuild disagreement cannot record accepted learning', () => {
+    const reduction = rebuildRecommendation();
+    const task = prepareRebuildTask(draft, profile, reduction, copySpec, capability(reduction), trustStore, 150);
+    const failed = evaluate(task, { version: '1', mode: 'REBUILD', taskFingerprint: task.fingerprint, candidate: 'Operators should delay the launch indefinitely.' }, reduction);
+    assert.equal(failed.status, 'needs_escalation');
+    const evaluated = evaluate(task, { version: '1', mode: 'REBUILD', taskFingerprint: task.fingerprint, candidate: rebuilt }, reduction);
+    assert.equal(evaluated.status, 'needs_semantic_review');
+    const standard = verifyDeterministically(draft, rebuilt, profile, copySpec);
+    assert.notEqual(standard.artifact.artifactFingerprint, evaluated.deterministicArtifact?.artifactFingerprint);
+    assert.throws(() => recordApprovedLearning({
+        ready: { version: '1', status: 'ready_for_human_review', artifactFingerprint: '1'.repeat(64), transitionFingerprint: '2'.repeat(64), binding: evaluated.lifecycleBinding, semanticPolicy: 'normal', semanticTaskFingerprint: '3'.repeat(64), semanticEvidenceScopeFingerprint: '4'.repeat(64), verdictFingerprints: [] },
+        approved: { version: '1', status: 'approved', artifactFingerprint: '5'.repeat(64), transitionFingerprint: '6'.repeat(64), binding: evaluated.lifecycleBinding, semanticPolicy: 'normal', semanticTaskFingerprint: '3'.repeat(64), semanticEvidenceScopeFingerprint: '4'.repeat(64), verdictFingerprints: [] },
+        decision: { evaluatorId: 'human.1', decision: 'approve' },
+        capability: capability(reduction),
+        source: draft,
+        candidate: rebuilt,
+        profile,
+        context: { now: 150, trustStore, authorizedSemanticEvaluatorIds: { normal: [], highAssurance: [] }, authorizedHumanFinalizerIds: ['human.1'] },
+        copySpec,
+    }), /Invalid lifecycle artifact|Approved learning is not authorized|does not match deterministic verification/);
+});
+test('CLI and MCP rebuild helpers share fingerprints', () => {
+    const reduction = rebuildRecommendation();
+    const task = prepareRebuildTask(draft, profile, reduction, copySpec, capability(reduction), trustStore, 150);
+    const parsed = parseRebuildTask(JSON.parse(JSON.stringify(task)));
+    assert.equal(parsed.fingerprint, task.fingerprint);
+    assert.equal(parsed.authorizationFingerprint, task.authorizationFingerprint);
+    assert.match(task.prompt, /whole-document candidate/);
+    const briefTask = prepareRebuildTask(draft, profile, reduction, copySpec, capability(reduction, { nonce: 'nonce-brief' }), trustStore, 150, {
+        version: '1', audience: 'operators', intent: 'explain', format: 'outreach',
+    });
+    assert.match(briefTask.prompt, /# WritingBrief/);
+    assert.equal(HYV_VERSION, '3.3.1');
+});
+test('apply rejects forged tasks, missing capability, and substituted profiles', () => {
+    const reduction = rebuildRecommendation();
+    const task = prepareRebuildTask(draft, profile, reduction, copySpec, capability(reduction), trustStore, 150);
+    const response = { version: '1', mode: 'REBUILD', taskFingerprint: task.fingerprint, candidate: rebuilt };
+    const { fingerprint: _ignored, ...base } = task;
+    const forgedBase = { ...base, authorizationFingerprint: 'a'.repeat(64) };
+    const forged = { ...forgedBase, fingerprint: createHash('sha256').update(canonicalJson(forgedBase)).digest('hex') };
+    assert.equal(parseRebuildTask(forged).fingerprint, forged.fingerprint);
+    assert.throws(() => evaluateRebuildResponse(forged, { ...response, taskFingerprint: forged.fingerprint }, profile, capability(reduction), trustStore, 150), /Rebuild authorization is invalid/);
+    assert.throws(() => evaluateRebuildResponse(task, response, profile, {}, trustStore, 150), /Rebuild authorization is invalid/);
+    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/);
+});