@holdyourvoice/hyv 3.2.0 → 3.3.1

package/dist/cli.test.js

@@ -1,14 +1,31 @@
 import assert from 'node:assert/strict';
-import { mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { createHash, generateKeyPairSync, sign } from 'node:crypto';
 import test from 'node:test';
 import { patternsForMcp } from './mcp-tools.js';
+import { canonicalJson } from './canonical-json.js';
 const cli = new URL('./cli.js', import.meta.url).pathname;
 function run(args, env = process.env, input) {
     return spawnSync(process.execPath, [cli, ...args], { encoding: 'utf8', env, input });
 }
+function installedContextEnvironment(root, context) {
+    const home = join(root, 'home');
+    const config = join(home, '.config', 'holdyourvoice');
+    mkdirSync(config, { recursive: true, mode: 0o700 });
+    const contextPath = join(config, 'approval-context.json');
+    writeFileSync(contextPath, canonicalJson(context), { mode: 0o600 });
+    chmodSync(contextPath, 0o600);
+    const fakeOs = join(root, 'fake-os.mjs');
+    const hooks = join(root, 'hooks.mjs');
+    const register = join(root, 'register.mjs');
+    writeFileSync(fakeOs, `import * as actual from 'node:os'; export const userInfo = () => ({ ...actual.userInfo(), homedir: process.env.HYV_TEST_HOME });\n`);
+    writeFileSync(hooks, `export async function resolve(specifier, context, nextResolve) { if (specifier === 'node:os' && context.parentURL?.endsWith('/approval-context.js')) return { url: new URL('./fake-os.mjs', import.meta.url).href, shortCircuit: true }; return nextResolve(specifier, context); }\n`);
+    writeFileSync(register, `import { register } from 'node:module'; register(new URL('./hooks.mjs', import.meta.url));\n`);
+    return { ...process.env, NODE_NO_WARNINGS: '1', NODE_OPTIONS: `--import=${register}`, HYV_TEST_HOME: home };
+}
 test('creates an explicit local avoid list and exposes the ruleset', () => {
     const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-'));
     try {
@@ -28,13 +45,13 @@ test('creates an explicit local avoid list and exposes the ruleset', () => {
         rmSync(directory, { recursive: true, force: true });
     }
 });
-test('publishes the same normalized 145-rule catalog and version through CLI and MCP', () => {
+test('publishes the same normalized reconciled catalog and version through CLI and MCP', () => {
     const result = run(['patterns']);
     assert.equal(result.status, 0, result.stderr);
     const cliCatalog = JSON.parse(result.stdout);
     const mcpCatalog = patternsForMcp();
-    assert.equal(cliCatalog.version, '2.9.24-static.2');
-    assert.equal(cliCatalog.rules.length, 145);
+    assert.equal(cliCatalog.version, '3.2.0-reconciled.1');
+    assert.equal(cliCatalog.rules.length, 148);
     assert.deepEqual(cliCatalog, mcpCatalog);
 });
 test('runs contextual analysis and batch analysis without changing the profile contract', () => {
@@ -197,6 +214,96 @@ test('prepares and applies the same constrained rewrite task without a provider
         rmSync(directory, { recursive: true, force: true });
     }
 });
+test('prepares and reduces pre-edit judgment envelopes through CLI', () => {
+    const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-judgment-'));
+    try {
+        const first = join(directory, 'first.md');
+        const second = join(directory, 'second.md');
+        const profile = join(directory, 'profile.json');
+        const draft = join(directory, 'draft.md');
+        writeFileSync(first, 'I write plainly. I name the work.');
+        writeFileSync(second, 'I keep the mechanism clear. I avoid filler.');
+        writeFileSync(draft, 'I leverage the answer.');
+        assert.equal(run(['profile', profile, first, second, '--avoid=leverage']).status, 0);
+        const envelopes = ['triage', 'argument', 'form'].map((kind) => {
+            const taskPath = join(directory, `${kind}.json`);
+            assert.equal(run(['prepare-judgment', 'pre-edit', kind, draft, profile, taskPath]).status, 0);
+            const task = JSON.parse(readFileSync(taskPath, 'utf8'));
+            const envelopePath = join(directory, `${kind}-envelope.json`);
+            writeFileSync(envelopePath, JSON.stringify({
+                version: '1', stage: 'pre-edit', judgmentType: kind, taskFingerprint: task.taskFingerprint,
+                bindings: { ...task.bindings, evaluatorId: 'writer.1' }, findings: [], decision: 'SHIP',
+            }));
+            return envelopePath;
+        });
+        const result = run(['reduce-judgment', ...envelopes]);
+        assert.equal(result.status, 0, result.stderr);
+        assert.equal(JSON.parse(result.stdout).decision, 'SHIP');
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});
+test('prepares, submits, and inspects a normal lifecycle through CLI canonical envelopes', () => {
+    const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-lifecycle-'));
+    try {
+        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 paths = Object.fromEntries(['deterministic', 'binding', 'receipt', 'violations', 'output', 'artifact', 'task', 'verdict'].map((name) => [name, join(directory, `${name}.json`)]));
+        writeFileSync(paths.deterministic, JSON.stringify(deterministic));
+        writeFileSync(paths.binding, JSON.stringify(binding));
+        writeFileSync(paths.receipt, JSON.stringify(receipt));
+        writeFileSync(paths.violations, JSON.stringify(['action_change']));
+        const prepared = run(['lifecycle', 'prepare-semantic', paths.deterministic, paths.binding, paths.receipt, 'normal', paths.violations, paths.output]);
+        assert.equal(prepared.status, 0, prepared.stderr);
+        const envelope = JSON.parse(prepared.stdout);
+        assert.equal(envelope.artifact.status, 'needs_semantic_review');
+        assert.deepEqual(JSON.parse(readFileSync(paths.output, 'utf8')), envelope);
+        writeFileSync(paths.artifact, JSON.stringify(envelope.artifact));
+        writeFileSync(paths.task, JSON.stringify(envelope.task));
+        writeFileSync(paths.verdict, JSON.stringify({ approved: true, violations: [] }));
+        const context = { now: 0, trustStore: { version: '1', audience: '@holdyourvoice/hyv', maxCapabilityLifetimeSeconds: 300, keys: [] }, authorizedSemanticEvaluatorIds: { normal: ['reviewer-1'], highAssurance: [] }, authorizedHumanFinalizerIds: ['human-1'] };
+        const submitted = run(['lifecycle', 'submit-verdict', paths.artifact, paths.task, 'reviewer-1', paths.verdict], installedContextEnvironment(directory, context));
+        assert.equal(submitted.status, 0, submitted.stderr);
+        assert.equal(JSON.parse(submitted.stdout).status, 'ready_for_human_review');
+        const inspected = run(['lifecycle', 'inspect', paths.artifact]);
+        assert.equal(inspected.status, 0, inspected.stderr);
+        assert.equal(JSON.parse(inspected.stdout).status, 'needs_semantic_review');
+        assert.doesNotMatch(inspected.stdout, /sourceHash|candidateHash|verdicts/);
+        assert.equal(run(['lifecycle', 'prepare-semantic', paths.deterministic, paths.binding, paths.receipt, 'high_assurance', paths.violations, join(directory, 'high.json')]).status, 1);
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});
+test('accepts only one bounded capability transport and treats a file named stdin literally', () => {
+    const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-capability-'));
+    try {
+        const capability = JSON.stringify({ payload: 'secret-payload', signature: 'secret-signature' });
+        const literal = join(directory, 'stdin');
+        writeFileSync(literal, capability, { mode: 0o600 });
+        const literalResult = spawnSync(process.execPath, [cli, 'lifecycle', 'validate-final-approval', 'missing.json', '--capability-file', 'stdin'], { cwd: directory, encoding: 'utf8' });
+        assert.equal(literalResult.status, 1);
+        assert.doesNotMatch(literalResult.stderr, /Capability file is unavailable or unsafe|secret-payload|secret-signature/);
+        chmodSync(literal, 0o644);
+        const unsafe = spawnSync(process.execPath, [cli, 'lifecycle', 'validate-final-approval', 'missing.json', '--capability-file', 'stdin'], { cwd: directory, encoding: 'utf8' });
+        assert.equal(unsafe.status, 1);
+        assert.match(unsafe.stderr, /Capability file is unavailable or unsafe/);
+        assert.doesNotMatch(unsafe.stderr, /secret-payload|secret-signature/);
+        const duplicate = run(['lifecycle', 'validate-final-approval', 'missing.json', '--capability-stdin', '--capability-file', literal], process.env, capability);
+        assert.equal(duplicate.status, 1);
+        assert.match(duplicate.stderr, /Choose one capability source/);
+        assert.doesNotMatch(duplicate.stderr, /secret-payload|secret-signature/);
+        const oversized = run(['lifecycle', 'validate-final-approval', 'missing.json', '--capability-stdin'], process.env, 'x'.repeat(1024 * 1024 + 1));
+        assert.equal(oversized.status, 1);
+        assert.match(oversized.stderr, /exceeds the byte limit/);
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});
 test('rejects a malformed hand-edited profile before analysis', () => {
     const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-'));
     try {
@@ -265,7 +372,7 @@ test('rejects hand-edited metrics outside their semantic bounds', () => {
         rmSync(directory, { recursive: true, force: true });
     }
 });
-test('learns from a successful local verification by default and exposes local controls', () => {
+test('keeps verification read-only and exposes learning only through explicit controls', () => {
     const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-'));
     try {
         const first = join(directory, 'first.md');
@@ -282,11 +389,10 @@ test('learns from a successful local verification by default and exposes local c
         assert.equal(run(['verify', original, candidate, profile], env).status, 0);
         const brief = run(['rewrite-prompt', candidate, profile], env);
         assert.equal(brief.status, 0, brief.stderr);
-        assert.match(brief.stdout, /Learned local preferences/);
-        assert.match(brief.stdout, /ai\\_editor\/ai\.leverage/);
+        assert.doesNotMatch(brief.stdout, /Learned local preferences/);
         const learned = run(['learning', 'show', profile], env);
         assert.equal(learned.status, 0, learned.stderr);
-        assert.ok(JSON.parse(learned.stdout).preferences.some((item) => item.text.includes('ai_editor/ai.leverage')));
+        assert.deepEqual(JSON.parse(learned.stdout).preferences, []);
         assert.equal(run(['learning', 'clear', profile], env).status, 0);
         assert.deepEqual(JSON.parse(run(['learning', 'show', profile], env).stdout).preferences, []);
     }
@@ -294,3 +400,94 @@ test('learns from a successful local verification by default and exposes local c
         rmSync(directory, { recursive: true, force: true });
     }
 });
+test('records and inspects text-free learning metadata through the CLI', () => {
+    const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-learning-'));
+    try {
+        const first = join(directory, 'first.md');
+        const second = join(directory, 'second.md');
+        const profile = join(directory, 'profile.json');
+        const env = { ...process.env, HYV_HOME: join(directory, 'state') };
+        writeFileSync(first, 'I write plainly. I name the work.');
+        writeFileSync(second, 'I keep the mechanism clear. I avoid filler.');
+        assert.equal(run(['profile', profile, first, second]).status, 0);
+        const recorded = run(['learning', 'record', profile, 'Keep the mechanism concrete.', '--authority=founder', '--provenance=editor-review', '--weight=2', '--compatibility=exact', '--mutation-id=cli-1'], env);
+        assert.equal(recorded.status, 0, recorded.stderr);
+        assert.equal(JSON.parse(recorded.stdout).mutationId, 'cli-1');
+        assert.equal(JSON.parse(run(['learning', 'record', profile, 'Different instruction.', '--mutation-id=cli-1'], env).stdout).status, 'conflict');
+        const inspected = run(['learning', 'inspect', profile], env);
+        assert.equal(inspected.status, 0, inspected.stderr);
+        assert.equal(JSON.parse(inspected.stdout)[0].authority, 'founder');
+        assert.doesNotMatch(inspected.stdout, /Keep the mechanism concrete/);
+        assert.equal(run(['learning', 'ratify', profile, JSON.parse(recorded.stdout).eventId], env).status, 1);
+        assert.equal(run(['learning', 'record', profile, 'Boundary.', `--mutation-id=${'m'.repeat(200)}`, `--provenance=${'p'.repeat(500)}`], env).status, 0);
+        assert.equal(run(['learning', 'record', profile, 'Too long.', `--mutation-id=${'m'.repeat(201)}`], env).status, 1);
+        assert.equal(run(['learning', 'record', profile, 'Too long.', `--provenance=${'p'.repeat(501)}`], env).status, 1);
+        assert.equal(run(['learning', 'inspect', profile, '--mutation-id=nope'], env).status, 1);
+        assert.equal(run(['learning', 'clear', profile, '--authority=team'], env).status, 1);
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});
+test('prepares and applies an authorized rebuild through CLI', () => {
+    const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-rebuild-'));
+    try {
+        const first = join(directory, 'first.md');
+        const second = join(directory, 'second.md');
+        const profile = join(directory, 'profile.json');
+        const draft = join(directory, 'draft.md');
+        const spec = join(directory, 'copy-spec.json');
+        const reduction = join(directory, 'reduction.json');
+        const task = join(directory, 'rebuild-task.json');
+        const response = join(directory, 'response.json');
+        const capability = join(directory, 'capability.json');
+        writeFileSync(first, 'I write plainly. I name the work.');
+        writeFileSync(second, 'I keep the mechanism clear. I avoid filler.');
+        writeFileSync(draft, 'I leverage the answer. The launch is on 14 August.');
+        writeFileSync(spec, 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.' }] }));
+        assert.equal(run(['profile', profile, first, second, '--avoid=leverage']).status, 0);
+        const envelopes = ['triage', 'argument', 'form'].map((kind) => {
+            const taskPath = join(directory, `${kind}.json`);
+            assert.equal(run(['prepare-judgment', 'pre-edit', kind, draft, profile, taskPath]).status, 0);
+            const prepared = JSON.parse(readFileSync(taskPath, 'utf8'));
+            const envelopePath = join(directory, `${kind}-envelope.json`);
+            writeFileSync(envelopePath, JSON.stringify({
+                version: '1', stage: 'pre-edit', judgmentType: kind, taskFingerprint: prepared.taskFingerprint,
+                bindings: { ...prepared.bindings, evaluatorId: 'writer.1' }, findings: [], decision: kind === 'argument' ? 'REBUILD' : 'SHIP',
+            }));
+            return envelopePath;
+        });
+        const reduced = run(['reduce-judgment', ...envelopes]);
+        assert.equal(reduced.status, 0, reduced.stderr);
+        writeFileSync(reduction, reduced.stdout);
+        const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+        const trustStore = { version: '1', audience: '@holdyourvoice/hyv', maxCapabilityLifetimeSeconds: 300, keys: [{ issuer: 'host.example', keyId: 'key-1', publicKeySpki: publicKey.export({ type: 'spki', format: 'der' }).toString('base64url'), status: 'active' }] };
+        const context = { now: 0, trustStore, authorizedSemanticEvaluatorIds: { normal: [], highAssurance: [] }, authorizedHumanFinalizerIds: [] };
+        const env = installedContextEnvironment(directory, context);
+        const sourceHash = createHash('sha256').update(readFileSync(draft)).digest('hex');
+        const profileValue = JSON.parse(readFileSync(profile, 'utf8'));
+        const identity = `legacy-v2:${createHash('sha256').update(canonicalJson(profileValue)).digest('hex')}`;
+        const claims = {
+            version: '1', purpose: 'hyv.rebuild-authorization', issuer: 'host.example', audience: '@holdyourvoice/hyv',
+            subjectArtifactFingerprint: JSON.parse(reduced.stdout).recommendationFingerprint, sourceHash, candidateHash: sourceHash,
+            profileId: identity, profileRevisionDigest: identity, keyId: 'key-1', issuedAt: Math.floor(Date.now() / 1000) - 1,
+            notBefore: Math.floor(Date.now() / 1000) - 1, expiresAt: Math.floor(Date.now() / 1000) + 120, nonce: 'cli-rebuild',
+        };
+        const payload = Buffer.from(canonicalJson(claims));
+        writeFileSync(capability, canonicalJson({ payload: payload.toString('base64url'), signature: sign(null, payload, privateKey).toString('base64url') }));
+        chmodSync(capability, 0o600);
+        const prepared = run(['prepare-rebuild', draft, profile, reduction, spec, task, '--capability-file', capability], env);
+        assert.equal(prepared.status, 0, prepared.stderr);
+        writeFileSync(response, JSON.stringify({
+            version: '1', mode: 'REBUILD', taskFingerprint: JSON.parse(readFileSync(task, 'utf8')).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.',
+        }));
+        const applied = run(['apply-rebuild', task, response, profile, '--capability-file', capability], env);
+        assert.equal(applied.status, 2, applied.stderr);
+        assert.equal(JSON.parse(applied.stdout).status, 'needs_semantic_review');
+        assert.equal(run(['apply-rebuild', task, response, profile], env).status, 1);
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});

package/dist/hygiene.js

@@ -73,6 +73,12 @@ function scanHygiene(text, clean) {
 export function inspectHygiene(text) {
     return scanHygiene(text, false).report;
 }
+export function hygieneSourceFindings(text) {
+    return inspectHygiene(text).hits.flatMap((hit) => hit.offsets.map((start) => {
+        const character = String.fromCodePoint(text.codePointAt(start));
+        return { kind: 'hygiene', start, end: start + character.length, codepoint: hit.codepoint, eligible: hit.fix === 'remove' };
+    }));
+}
 export function cleanHygiene(text) {
     const result = scanHygiene(text, true);
     return { ...result, changed: result.changes.length > 0 };

package/dist/hygiene.test.js

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { cleanHygiene, finalOutputCheck, inspectHygiene } from './hygiene.js';
+import { cleanHygiene, finalOutputCheck, hygieneSourceFindings, inspectHygiene } from './hygiene.js';
 test('reports zero-width, bidi, tag, and unusual-space characters with exact offsets', () => {
     const text = `one\u200Btwo\u202Ethree\u{E0001}\u00A0four`;
     const report = inspectHygiene(text);
@@ -31,6 +31,12 @@ test('leaves clean text byte-for-byte unchanged', () => {
     assert.deepEqual(result.changes, []);
     assert.deepEqual(result.report.hits, []);
 });
+test('projects eligible hygiene hits as source-offset findings', () => {
+    const findings = hygieneSourceFindings('\uFEFFplain');
+    assert.equal(findings.length, 1);
+    assert.equal(findings[0]?.start, 0);
+    assert.equal(findings[0]?.eligible, true);
+});
 test('groups repeated report-only hits and preserves supplementary characters', () => {
     const text = `😀\u200Bword\u200B`;
     const result = cleanHygiene(text);

package/dist/judgment-task.js

@@ -0,0 +1,171 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson } from './canonical-json.js';
+import { sentences } from './text.js';
+import { HYV_VERSION } from './version.js';
+const PRE_EDIT_KINDS = ['triage', 'argument', 'form'];
+const POST_CANDIDATE_KINDS = ['argument', 'polarity', 'form', 'flatness', 'semantic'];
+function digest(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function digestCanonical(value) {
+    return digest(canonicalJson(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 fingerprintTask(task) {
+    return digest(`hyv:judgment-task:v1\0${canonicalJson(task)}`);
+}
+function sentenceIds(text) {
+    return sentences(text).map((sentence) => sentence.index);
+}
+function isRange(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+        && Number.isInteger(value.startSentenceId)
+        && Number.isInteger(value.endSentenceId)
+        && value.startSentenceId >= 1
+        && value.endSentenceId >= value.startSentenceId;
+}
+function rangesContiguous(ranges) {
+    return ranges.every((range) => range.endSentenceId >= range.startSentenceId);
+}
+export function parseJudgmentEnvelope(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Judgment envelope must be an object.');
+    const envelope = value;
+    if (envelope.version !== '1')
+        throw new Error('Judgment envelope version must be "1".');
+    if (envelope.stage !== 'pre-edit' && envelope.stage !== 'post-candidate')
+        throw new Error('Judgment stage is invalid.');
+    if (typeof envelope.judgmentType !== 'string' || typeof envelope.taskFingerprint !== 'string' || envelope.taskFingerprint.length !== 64) {
+        throw new Error('Judgment envelope is missing a bound task.');
+    }
+    if (!envelope.bindings || typeof envelope.bindings !== 'object' || typeof envelope.bindings.sourceHash !== 'string' || typeof envelope.bindings.evaluatorId !== 'string') {
+        throw new Error('Judgment envelope is missing bindings.');
+    }
+    if (!Array.isArray(envelope.findings) || typeof envelope.decision !== 'string')
+        throw new Error('Judgment envelope is missing findings or a decision.');
+    for (const [index, finding] of envelope.findings.entries()) {
+        if (!finding || typeof finding !== 'object' || typeof finding.kind !== 'string')
+            throw new Error(`Finding ${index} is invalid.`);
+        if (finding.ranges && (!Array.isArray(finding.ranges) || !finding.ranges.every(isRange)))
+            throw new Error(`Finding ${index} ranges are invalid.`);
+    }
+    if (envelope.editScope && (!Array.isArray(envelope.editScope.ranges) || !envelope.editScope.ranges.every(isRange))) {
+        throw new Error('Edit scope ranges are invalid.');
+    }
+    return envelope;
+}
+function prepareTask(stage, judgmentType, draft, profile, candidate) {
+    const identity = profileIdentity(profile);
+    const allowedDecisions = stage === 'pre-edit' ? ['SHIP', 'EDIT', 'REBUILD'] : ['CLEAR', 'ESCALATE', 'REBUILD'];
+    const base = {
+        version: '1',
+        stage,
+        judgmentType,
+        ...(stage === 'pre-edit' ? { draft } : { draft, candidate }),
+        bindings: {
+            sourceHash: digest(draft),
+            ...(candidate !== undefined ? { candidateHash: digest(candidate) } : {}),
+            ...identity,
+            rulesetVersion: HYV_VERSION,
+            evidenceScope: { sentenceIds: sentenceIds(candidate ?? draft) },
+        },
+        allowedDecisions,
+    };
+    return { ...base, taskFingerprint: fingerprintTask(base) };
+}
+export function preparePreEditJudgment(draft, profile, kind) {
+    return prepareTask('pre-edit', kind, draft, profile);
+}
+export function preparePostCandidateJudgment(draft, candidate, profile, kind) {
+    return prepareTask('post-candidate', kind, draft, profile, candidate);
+}
+export function bindJudgmentEnvelope(task, envelope) {
+    const parsed = parseJudgmentEnvelope(envelope);
+    if (parsed.taskFingerprint !== task.taskFingerprint)
+        throw new Error('Judgment envelope task fingerprint does not match.');
+    if (parsed.stage !== task.stage || parsed.judgmentType !== task.judgmentType)
+        throw new Error('Judgment envelope type does not match the task.');
+    if (parsed.bindings.sourceHash !== task.bindings.sourceHash)
+        throw new Error('Judgment envelope source hash does not match.');
+    if (task.bindings.candidateHash && parsed.bindings.candidateHash !== task.bindings.candidateHash)
+        throw new Error('Judgment envelope candidate hash does not match.');
+    if (parsed.bindings.profileId !== task.bindings.profileId || parsed.bindings.profileRevisionDigest !== task.bindings.profileRevisionDigest) {
+        throw new Error('Judgment envelope profile binding does not match.');
+    }
+    if (parsed.bindings.rulesetVersion !== task.bindings.rulesetVersion)
+        throw new Error('Judgment envelope ruleset does not match.');
+    if (canonicalJson(parsed.bindings.evidenceScope) !== canonicalJson(task.bindings.evidenceScope))
+        throw new Error('Judgment envelope evidence scope does not match.');
+    if (!task.allowedDecisions.includes(parsed.decision))
+        throw new Error('Judgment decision is not allowed at this stage.');
+    return parsed;
+}
+function namedRanges(findings) {
+    return findings.flatMap((finding) => finding.ranges ?? []);
+}
+function fingerprintReduction(decision, editScope, reason) {
+    return digest(`hyv:pre-edit-reduction:v1\0${canonicalJson({ decision, editScope, ...(reason ? { reason } : {}) })}`);
+}
+export function fingerprintPreEditReduction(reduction) {
+    return fingerprintReduction(reduction.decision, reduction.editScope, reduction.reason);
+}
+function reduced(decision, editScope, reason) {
+    return { decision, editScope, ...(reason ? { reason } : {}), recommendationFingerprint: fingerprintReduction(decision, editScope, reason) };
+}
+export function reducePreEdit(envelopes) {
+    if (envelopes.length !== PRE_EDIT_KINDS.length)
+        throw new Error('Pre-edit reduction requires triage, argument, and form envelopes.');
+    const kinds = new Set(envelopes.map((envelope) => envelope.judgmentType));
+    if (PRE_EDIT_KINDS.some((kind) => !kinds.has(kind)))
+        throw new Error('Pre-edit reduction requires triage, argument, and form envelopes.');
+    if (envelopes.some((envelope) => envelope.stage !== 'pre-edit'))
+        throw new Error('Pre-edit reduction rejects post-candidate envelopes.');
+    const argument = envelopes.find((envelope) => envelope.judgmentType === 'argument');
+    if (argument.findings.some((finding) => finding.unbounded) || argument.decision === 'REBUILD') {
+        return reduced('REBUILD', { ranges: [] }, argument.findings.some((finding) => finding.unbounded) ? 'unbounded_argument_failure' : undefined);
+    }
+    if (envelopes.some((envelope) => envelope.decision === 'REBUILD')) {
+        return reduced('REBUILD', { ranges: [] });
+    }
+    const ranges = envelopes.flatMap((envelope) => envelope.editScope?.ranges ?? namedRanges(envelope.findings));
+    if (!rangesContiguous(ranges) || ranges.some((range) => range.endSentenceId < range.startSentenceId)) {
+        throw new Error('Edit scope must name contiguous sentence ranges.');
+    }
+    if (envelopes.every((envelope) => envelope.decision === 'SHIP') && ranges.length === 0) {
+        return reduced('SHIP', { ranges: [] });
+    }
+    if (ranges.length === 0)
+        throw new Error('Paragraph-level findings cannot unlock text unless they name contiguous sentence ranges.');
+    return reduced('EDIT', { ranges });
+}
+export function reducePostCandidate(envelopes) {
+    if (envelopes.length !== POST_CANDIDATE_KINDS.length)
+        throw new Error('Post-candidate reduction requires argument, polarity, form, flatness, and semantic envelopes.');
+    const kinds = new Set(envelopes.map((envelope) => envelope.judgmentType));
+    if (POST_CANDIDATE_KINDS.some((kind) => !kinds.has(kind)))
+        throw new Error('Post-candidate reduction requires argument, polarity, form, flatness, and semantic envelopes.');
+    if (envelopes.some((envelope) => envelope.stage !== 'post-candidate'))
+        throw new Error('Post-candidate reduction rejects pre-edit envelopes.');
+    if (envelopes.some((envelope) => envelope.decision === 'REBUILD'))
+        return { decision: 'REBUILD' };
+    if (envelopes.some((envelope) => envelope.decision === 'ESCALATE'))
+        return { decision: 'ESCALATE' };
+    if (!envelopes.every((envelope) => envelope.decision === 'CLEAR'))
+        throw new Error('Post-candidate envelopes must CLEAR, ESCALATE, or REBUILD.');
+    return { decision: 'CLEAR' };
+}
+export function authorizedSentenceIds(reduction) {
+    if (reduction.decision !== 'EDIT')
+        return [];
+    const ids = new Set();
+    for (const range of reduction.editScope.ranges) {
+        for (let id = range.startSentenceId; id <= range.endSentenceId; id += 1)
+            ids.add(id);
+    }
+    return [...ids].sort((left, right) => left - right);
+}

package/dist/judgment-task.test.js

@@ -0,0 +1,162 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { bindJudgmentEnvelope, preparePostCandidateJudgment, preparePreEditJudgment, reducePostCandidate, reducePreEdit } from './judgment-task.js';
+import { applyRewriteResponse, applyShip, prepareRewriteTask } from './rewrite-task.js';
+import { hygieneSourceFindings } from './hygiene.js';
+import { buildProfile } from './voice-dna.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']);
+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,
+    };
+}
+test('pre-edit findings select SHIP, bounded EDIT, or REBUILD', () => {
+    const draft = 'I leverage the answer. The launch is on 14 August.';
+    const triage = preparePreEditJudgment(draft, profile, 'triage');
+    const argument = preparePreEditJudgment(draft, profile, 'argument');
+    const form = preparePreEditJudgment(draft, profile, 'form');
+    const ship = reducePreEdit([
+        bindJudgmentEnvelope(triage, envelope(triage, 'SHIP')),
+        bindJudgmentEnvelope(argument, envelope(argument, 'SHIP')),
+        bindJudgmentEnvelope(form, envelope(form, 'SHIP')),
+    ]);
+    assert.equal(ship.decision, 'SHIP');
+    const edit = reducePreEdit([
+        bindJudgmentEnvelope(triage, envelope(triage, 'EDIT', { editScope: { ranges: [{ startSentenceId: 1, endSentenceId: 1 }] } })),
+        bindJudgmentEnvelope(argument, envelope(argument, 'SHIP')),
+        bindJudgmentEnvelope(form, envelope(form, 'SHIP')),
+    ]);
+    assert.equal(edit.decision, 'EDIT');
+    assert.deepEqual(edit.editScope.ranges, [{ startSentenceId: 1, endSentenceId: 1 }]);
+    const rebuild = reducePreEdit([
+        bindJudgmentEnvelope(triage, envelope(triage, 'SHIP')),
+        bindJudgmentEnvelope(argument, envelope(argument, 'REBUILD')),
+        bindJudgmentEnvelope(form, envelope(form, 'SHIP')),
+    ]);
+    assert.equal(rebuild.decision, 'REBUILD');
+    assert.match(rebuild.recommendationFingerprint, /^[a-f0-9]{64}$/);
+});
+test('unbounded argument failure can recommend only rebuild', () => {
+    const draft = 'I leverage the answer. The launch is on 14 August.';
+    const triage = preparePreEditJudgment(draft, profile, 'triage');
+    const argument = preparePreEditJudgment(draft, profile, 'argument');
+    const form = preparePreEditJudgment(draft, profile, 'form');
+    const reduced = reducePreEdit([
+        bindJudgmentEnvelope(triage, envelope(triage, 'EDIT', { editScope: { ranges: [{ startSentenceId: 1, endSentenceId: 1 }] } })),
+        bindJudgmentEnvelope(argument, envelope(argument, 'EDIT', { findings: [{ kind: 'argument', unbounded: true }] })),
+        bindJudgmentEnvelope(form, envelope(form, 'SHIP')),
+    ]);
+    assert.equal(reduced.decision, 'REBUILD');
+    assert.equal(reduced.reason, 'unbounded_argument_failure');
+});
+test('paragraph-level findings cannot unlock text without named ranges', () => {
+    const draft = 'I leverage the answer. The launch is on 14 August.';
+    const triage = preparePreEditJudgment(draft, profile, 'triage');
+    const argument = preparePreEditJudgment(draft, profile, 'argument');
+    const form = preparePreEditJudgment(draft, profile, 'form');
+    assert.throws(() => reducePreEdit([
+        bindJudgmentEnvelope(triage, envelope(triage, 'EDIT')),
+        bindJudgmentEnvelope(argument, envelope(argument, 'SHIP')),
+        bindJudgmentEnvelope(form, envelope(form, 'SHIP')),
+    ]), /contiguous sentence ranges/);
+});
+test('deleting one eligible sentence or merging two adjacent sentences succeeds', () => {
+    const draft = 'I leverage the answer. I leverage the second point. The launch is on 14 August.';
+    const task = prepareRewriteTask(draft, profile, undefined, undefined, [1, 2]);
+    const deleted = applyRewriteResponse(task, {
+        version: '2',
+        taskFingerprint: task.fingerprint,
+        operations: [{ startSentenceId: 1, endSentenceId: 1, text: '' }],
+    });
+    assert.equal(deleted.status, 'accepted');
+    assert.equal(deleted.candidate, ' I leverage the second point. The launch is on 14 August.');
+    const merged = applyRewriteResponse(task, {
+        version: '2',
+        taskFingerprint: task.fingerprint,
+        operations: [{ startSentenceId: 1, endSentenceId: 2, text: 'I use both points.' }],
+    });
+    assert.equal(merged.status, 'accepted');
+    assert.equal(merged.candidate, 'I use both points. The launch is on 14 August.');
+});
+test('overlapping, noncontiguous, out-of-order, or partly locked ranges fail before candidate construction', () => {
+    const draft = 'I leverage the answer. The launch is on 14 August. I keep the mechanism visible.';
+    const task = prepareRewriteTask(draft, profile);
+    const overlap = applyRewriteResponse(task, {
+        version: '2',
+        taskFingerprint: task.fingerprint,
+        operations: [
+            { startSentenceId: 1, endSentenceId: 1, text: 'I use the answer.' },
+            { startSentenceId: 1, endSentenceId: 1, text: 'I choose the answer.' },
+        ],
+    });
+    assert.equal(overlap.status, 'repairable');
+    assert.equal(overlap.candidate, undefined);
+    assert.equal(overlap.failures[0]?.code, 'overlapping_range');
+    const locked = applyRewriteResponse(task, {
+        version: '2',
+        taskFingerprint: task.fingerprint,
+        operations: [{ startSentenceId: 1, endSentenceId: 2, text: 'I use the answer. The launch is on 14 August.' }],
+    });
+    assert.equal(locked.status, 'repairable');
+    assert.equal(locked.failures[0]?.code, 'partly_locked_range');
+});
+test('SHIP returns original bytes without a model response body', () => {
+    const draft = 'I leverage the answer. The launch is on 14 August.';
+    const task = prepareRewriteTask(draft, profile);
+    const shipped = applyShip(task);
+    assert.equal(shipped.status, 'accepted');
+    assert.equal(shipped.candidate, draft);
+    assert.equal(shipped.receipt.mode, 'SHIP');
+    const viaResponse = applyRewriteResponse(task, { version: '1', mode: 'SHIP', taskFingerprint: task.fingerprint });
+    assert.equal(viaResponse.candidate, draft);
+});
+test('hygiene changes occur only through eligible source-offset findings', () => {
+    const draft = `\uFEFFI leverage the answer.`;
+    const findings = hygieneSourceFindings(draft);
+    assert.equal(findings[0]?.eligible, true);
+    const task = prepareRewriteTask(draft, profile);
+    const rejected = applyRewriteResponse(task, {
+        version: '2',
+        taskFingerprint: task.fingerprint,
+        operations: [],
+        hygieneOperations: [{ start: 1, end: 2, text: '' }],
+    });
+    assert.equal(rejected.status, 'repairable');
+    assert.equal(rejected.failures[0]?.code, 'ineligible_hygiene_offset');
+    const cleaned = applyRewriteResponse(task, {
+        version: '2',
+        taskFingerprint: task.fingerprint,
+        operations: [{ startSentenceId: 1, endSentenceId: 1, text: 'I use the answer.' }],
+        hygieneOperations: [{ start: findings[0].start, end: findings[0].end, text: '' }],
+    });
+    assert.equal(cleaned.status, 'accepted');
+    assert.equal(cleaned.candidate, 'I use the answer.');
+});
+test('post-candidate reduction requires the full judgment set', () => {
+    const draft = 'I write clear notes.';
+    const candidate = 'I write clear notes.';
+    const kinds = ['argument', 'polarity', 'form', 'flatness', 'semantic'];
+    const envelopes = kinds.map((kind) => {
+        const task = preparePostCandidateJudgment(draft, candidate, profile, kind);
+        return bindJudgmentEnvelope(task, {
+            version: '1',
+            stage: 'post-candidate',
+            judgmentType: kind,
+            taskFingerprint: task.taskFingerprint,
+            bindings: { ...task.bindings, evaluatorId: 'writer.1' },
+            findings: [],
+            decision: 'CLEAR',
+        });
+    });
+    assert.equal(reducePostCandidate(envelopes).decision, 'CLEAR');
+});