@holdyourvoice/hyv 3.1.1 → 3.3.0

package/dist/hygiene.test.js

@@ -0,0 +1,73 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+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);
+    assert.equal(report.suspiciousCount, 4);
+    assert.equal(report.fixableCount, 0);
+    assert.deepEqual(report.hits.map((hit) => [hit.codepoint, hit.kind, hit.count]), [
+        ['U+00A0', 'unusual_space', 1],
+        ['U+200B', 'zero_width', 1],
+        ['U+202E', 'bidi', 1],
+        ['U+E0001', 'tag', 1],
+    ]);
+    assert.deepEqual(report.hits.find((hit) => hit.codepoint === 'U+E0001')?.offsets, [13]);
+});
+test('removes only a leading byte-order mark and preserves language, spacing, bidi, and tag controls', () => {
+    const text = `\uFEFFa\u200Bb\uFEFFc\u00A0d\u200Ce\u200Df\u202Eg\u{E0001}`;
+    const result = cleanHygiene(text);
+    assert.equal(result.cleaned, `a\u200Bb\uFEFFc\u00A0d\u200Ce\u200Df\u202Eg\u{E0001}`);
+    assert.equal(result.changed, true);
+    assert.deepEqual(result.changes.map((change) => [change.codepoint, change.action]), [['U+FEFF', 'removed']]);
+    assert.equal(result.report.suspiciousCount, 8);
+    assert.equal(result.report.fixableCount, 1);
+});
+test('leaves clean text byte-for-byte unchanged', () => {
+    const text = 'plain text\nwith normal spaces.';
+    const result = cleanHygiene(text);
+    assert.equal(result.cleaned, text);
+    assert.equal(result.changed, false);
+    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);
+    assert.equal(result.cleaned, text);
+    assert.equal(result.report.suspiciousCount, 2);
+    assert.equal(result.report.hits.length, 1);
+    assert.equal(result.report.hits[0]?.count, 2);
+    assert.deepEqual(result.report.hits[0]?.offsets, [2, 7]);
+});
+test('preserves multilingual spacing and word-boundary controls byte-for-byte', () => {
+    const text = `ไทย\u200Bภาษา 10\u00A0kg 日本語\u3000本文 ᠮ\u180Eᠣ a\u2060b`;
+    const result = cleanHygiene(text);
+    assert.equal(result.cleaned, text);
+    assert.equal(result.changed, false);
+    assert.equal(result.report.suspiciousCount, 5);
+    assert.equal(result.report.fixableCount, 0);
+});
+test('accepts exact clean output and minimally removes only a leading BOM', () => {
+    const clean = finalOutputCheck('exact output\n');
+    assert.equal(clean.accepted, true);
+    assert.equal(clean.accepted && clean.output, 'exact output\n');
+    assert.equal(clean.changed, false);
+    const bom = finalOutputCheck('\uFEFFexact output');
+    assert.equal(bom.accepted, true);
+    assert.equal(bom.accepted && bom.output, 'exact output');
+    assert.deepEqual(bom.changes, [{ offset: 0, codepoint: 'U+FEFF', action: 'removed' }]);
+});
+test('withholds output when hidden characters remain unresolved', () => {
+    const result = finalOutputCheck('Thai\u200Bboundary 👩\u200D💻');
+    assert.equal(result.accepted, false);
+    assert.equal('output' in result, false);
+    assert.equal(result.changed, false);
+    assert.deepEqual(result.remaining.hits.map((hit) => hit.codepoint), ['U+200B', 'U+200D']);
+});

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');
+});