@holdyourvoice/hyv 3.1.1 → 3.3.0

package/dist/rewrite-task.test.js

@@ -1,8 +1,10 @@
 import assert from 'node:assert/strict';
 import { createHash } from 'node:crypto';
 import test from 'node:test';
-import { applyRewriteResponse, parseRewriteTask, prepareRewriteTask } from './rewrite-task.js';
+import { applyRewriteResponse, createRewriteLifecycleBinding, evaluateRewriteResponse, parseRewriteTask, prepareRewriteTask } from './rewrite-task.js';
 import { parseWritingBrief } from './editorial-packs.js';
+import { canonicalJson } from './canonical-json.js';
+import { verifyDeterministically } from './pipeline.js';
 import { buildProfile } from './voice-dna.js';
 const profile = buildProfile([
     'I write clear notes. I keep the mechanism visible.',
@@ -19,24 +21,64 @@ test('applies only eligible numbered replacements and preserves all clean bytes'
     assert.equal(result.candidate, 'I use the answer. The launch is on 14 August.');
     assert.deepEqual(result.receipt.adapterIds, []);
 });
+test('does not make an advisory broad catalog match eligible', () => {
+    const task = prepareRewriteTask('I write clear notes. This work is meaningful. I keep the mechanism visible.', profile);
+    assert.deepEqual(task.eligibleSentenceIds, []);
+    assert.deepEqual(task.sentences.map((sentence) => sentence.eligible), [false, false, false]);
+});
+test('grants edit scope only to blocking findings and keeps pending judgment separate', () => {
+    const advisory = prepareRewriteTask('Firstly, check the invoice.', profile);
+    assert.deepEqual(advisory.eligibleSentenceIds, []);
+    const neutralProfile = buildProfile(['I write plainly.', 'I name the mechanism.']);
+    const pending = prepareRewriteTask('We leverage the scheduler.', neutralProfile);
+    assert.deepEqual(pending.eligibleSentenceIds, []);
+    assert.match(pending.prompt, /pending judgment/i);
+    const blocking = prepareRewriteTask('The scheduler failed — twice. The owner checked it.', profile);
+    assert.deepEqual(blocking.eligibleSentenceIds, [1]);
+});
+test('keeps blocking VoiceDNA avoid findings eligible', () => {
+    const task = prepareRewriteTask('The plan uses leverage.', profile);
+    assert.deepEqual(task.eligibleSentenceIds, [1]);
+});
+test('preserves founder reframes that reconciled policy makes advisory', () => {
+    const task = prepareRewriteTask("This isn't positioning. This is proof.", profile);
+    assert.deepEqual(task.eligibleSentenceIds, []);
+});
+test('preserves a clean draft byte-for-byte when the rewrite response is empty', () => {
+    const draft = 'I write clear notes.\n\nI keep the mechanism visible.\n';
+    const task = prepareRewriteTask(draft, profile);
+    assert.deepEqual(task.eligibleSentenceIds, []);
+    const result = applyRewriteResponse(task, { version: '1', taskFingerprint: task.fingerprint, replacements: [] });
+    assert.equal(result.status, 'accepted');
+    assert.equal(result.candidate, draft);
+});
+test('rejects an attempted edit to a clean sentence without changing any source bytes', () => {
+    const draft = 'I leverage the answer.\n\nThe launch starts Tuesday.\n';
+    const task = prepareRewriteTask(draft, profile);
+    const result = applyRewriteResponse(task, { version: '1', taskFingerprint: task.fingerprint, replacements: [{ sentenceId: 2, text: 'The launch starts Wednesday.' }] });
+    assert.equal(result.status, 'repairable');
+    assert.equal(result.candidate, undefined);
+    assert.equal(result.failures[0]?.code, 'ineligible_sentence_id');
+    assert.equal(task.draft, draft);
+});
 test('carries WritingBrief context into a fingerprinted rewrite task', () => {
     const brief = parseWritingBrief({ version: '1', audience: 'founders', intent: 'start a discussion', format: 'social' });
     const task = prepareRewriteTask('A pattern I keep seeing in founder posts is vague advice.', profile, undefined, brief);
     assert.equal(task.writingBrief?.format, 'social');
-    assert.ok(task.eligibleSentenceIds.includes(1));
+    assert.deepEqual(task.eligibleSentenceIds, []);
 });
 test('rejects a fingerprint-valid rewrite task with malformed WritingBrief data', () => {
     const task = prepareRewriteTask('I leverage the answer.', profile);
     const { fingerprint: _fingerprint, ...taskBase } = task;
     const base = { ...taskBase, writingBrief: { version: '1', audience: 'operators', intent: 'write', format: 'general', prohibitedTerms: [42] } };
-    const malformed = { ...base, fingerprint: createHash('sha256').update(JSON.stringify(base)).digest('hex') };
+    const malformed = { ...base, fingerprint: createHash('sha256').update(canonicalJson(base)).digest('hex') };
     assert.throws(() => parseRewriteTask(malformed), /WritingBrief/);
 });
 test('rejects a fingerprint-valid rewrite task with a null WritingBrief', () => {
     const task = prepareRewriteTask('I leverage the answer.', profile);
     const { fingerprint: _fingerprint, ...taskBase } = task;
     const base = { ...taskBase, writingBrief: null };
-    const malformed = { ...base, fingerprint: createHash('sha256').update(JSON.stringify(base)).digest('hex') };
+    const malformed = { ...base, fingerprint: createHash('sha256').update(canonicalJson(base)).digest('hex') };
     assert.throws(() => parseRewriteTask(malformed), /WritingBrief/);
 });
 test('rejects a duplicate, unknown, or clean sentence replacement before it creates a candidate', () => {
@@ -72,6 +114,32 @@ test('keeps a valid response byte-for-byte unchanged by repair adapters', () =>
     assert.equal(result.status, 'accepted');
     assert.equal(result.receipt.responseFingerprint.length, 64);
     assert.deepEqual(result.receipt.adapterIds, []);
+    assert.deepEqual(result.receipt.replacementSentenceIds, [1]);
+});
+test('binds the task, response, deterministic artifact, text hashes, and profile revision', () => {
+    const draft = 'I write clear notes.';
+    const task = prepareRewriteTask(draft, profile);
+    const applied = applyRewriteResponse(task, { version: '1', taskFingerprint: task.fingerprint, replacements: [] });
+    assert.equal(applied.status, 'accepted');
+    const artifact = verifyDeterministically(draft, applied.candidate, profile).artifact;
+    const binding = createRewriteLifecycleBinding(task, applied.receipt, artifact);
+    assert.equal(binding.rewriteTaskFingerprint, task.fingerprint);
+    assert.equal(binding.rewriteResponseFingerprint, applied.receipt.responseFingerprint);
+    assert.equal(binding.deterministicArtifactFingerprint, artifact.artifactFingerprint);
+    assert.match(binding.sourceHash, /^[a-f0-9]{64}$/);
+});
+test('returns the deterministic artifact and lifecycle binding at the semantic gate', () => {
+    const task = prepareRewriteTask('I write clear notes.', profile);
+    const result = evaluateRewriteResponse(task, { version: '1', taskFingerprint: task.fingerprint, replacements: [] }, profile);
+    assert.equal(result.status, 'needs_semantic_review');
+    assert.equal(result.deterministicArtifact?.passed, true);
+    assert.equal(result.lifecycleBinding?.deterministicArtifactFingerprint, result.deterministicArtifact?.artifactFingerprint);
+});
+test('keeps object response fingerprints stable across property order', () => {
+    const task = prepareRewriteTask('I leverage the answer.', profile);
+    const first = applyRewriteResponse(task, { version: '1', taskFingerprint: task.fingerprint, replacements: [{ sentenceId: 1, text: 'I use the answer.' }] });
+    const second = applyRewriteResponse(task, { replacements: [{ text: 'I use the answer.', sentenceId: 1 }], taskFingerprint: task.fingerprint, version: '1' });
+    assert.equal(first.receipt.responseFingerprint, second.receipt.responseFingerprint);
 });
 test('repairs only an exact outer JSON code fence after JSON parsing fails', () => {
     const task = prepareRewriteTask('I leverage the answer with useful detail and clear mechanism.', profile);

package/dist/rule-reconciliation.test.js

@@ -0,0 +1,50 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { rules } from './ai-editor-rules.js';
+function rule(id) {
+    const match = rules.find((candidate) => candidate.id === id);
+    assert.ok(match, `missing rule ${id}`);
+    return match;
+}
+test('struct.not-x-y only detects an explicit two-beat contrast', () => {
+    const matcher = rule('struct.not-x-y').expression;
+    assert.equal(matcher.test('Not speed. Reliability.'), true);
+    assert.equal(matcher.test('This does not include the standard onboarding steps every team runs.'), false);
+});
+test('keeps the explicit this-isnt reframe matcher available to policy', () => {
+    const matcher = rule('struct.this-isnt-x-this-is-y').expression;
+    assert.equal(matcher.test("This isn't positioning. This is proof."), true);
+    assert.equal(matcher.test('This positioning claim has proof.'), false);
+});
+test('treats both long dash characters as red findings', () => {
+    const emDash = rule('punct.em-dash');
+    const enDash = rule('punct.en-dash');
+    assert.equal(emDash.severity, 'red');
+    assert.equal(enDash.severity, 'red');
+    assert.equal(emDash.expression.test('The job failed — retry it.'), true);
+    assert.equal(enDash.expression.test('Use pages 6–11.'), true);
+    assert.equal(emDash.expression.test('The job failed; retry it.'), false);
+    assert.equal(enDash.expression.test('Use pages 6-11.'), false);
+});
+test('detects clear performative-sincerity phrases as red', () => {
+    const matcher = rule('formula.performative-sincerity');
+    assert.equal(matcher.severity, 'red');
+    for (const text of ['To be honest, the launch failed.', 'In all honesty, the launch failed.']) {
+        assert.equal(matcher.expression.test(text), true, text);
+    }
+    assert.equal(matcher.expression.test('The honest report says the launch failed.'), false);
+});
+test('detects performative-sincerity adverbs as yellow', () => {
+    const matcher = rule('hedge.performative-sincerity-adverb');
+    assert.equal(matcher.severity, 'yellow');
+    for (const text of [
+        'Honestly, the launch failed.',
+        'Genuinely, the launch failed.',
+        'Truly, the launch failed.',
+        'Frankly, the launch failed.',
+        'Actually, the launch failed.',
+    ]) {
+        assert.equal(matcher.expression.test(text), true, text);
+    }
+    assert.equal(matcher.expression.test('The genuine invoice arrived.'), false);
+});

package/dist/semantic-review.js

@@ -1,12 +1,61 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson } from './canonical-json.js';
+import { verifyApprovalCapability } from './approval-capability.js';
 const violations = new Set(['action_change', 'dropped_object', 'unsupported_claim', 'constraint_weakened', 'clarity_regression']);
-export function parseSemanticVerdict(evaluatorId, value) {
-    if (!value || typeof value !== 'object' || Array.isArray(value))
-        throw new Error('Semantic evaluator response must be an object.');
-    const verdict = value;
-    if (typeof verdict.approved !== 'boolean' || !Array.isArray(verdict.violations) || !verdict.violations.every((item) => typeof item === 'string' && violations.has(item))) {
-        throw new Error('Semantic evaluator response must include approved and known violations.');
+const HEX = /^[a-f0-9]{64}$/;
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+function hash(domain, value) { return createHash('sha256').update(`${domain}\0`).update(canonicalJson(value)).digest('hex'); }
+function same(left, right) { return canonicalJson(left) === canonicalJson(right); }
+function exact(value, required, optional = []) { return required.every((key) => key in value) && Object.keys(value).every((key) => required.includes(key) || optional.includes(key)); }
+function plain(value) { return value !== null && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype; }
+function bindingValid(binding) {
+    return binding.schemaVersion === '1' && [binding.rewriteTaskFingerprint, binding.rewriteResponseFingerprint, binding.deterministicArtifactFingerprint, binding.sourceHash, binding.candidateHash].every((item) => HEX.test(item))
+        && ID.test(binding.profileId) && ID.test(binding.profileRevisionDigest) && ID.test(binding.rulesetVersion);
+}
+export function prepareSemanticReviewTask(binding, policy, receipt, allowedViolations) {
+    if (!bindingValid(binding) || !['normal', 'high_assurance'].includes(policy))
+        throw new Error('Semantic review task has an invalid binding or policy.');
+    if (receipt.taskFingerprint !== binding.rewriteTaskFingerprint || receipt.responseFingerprint !== binding.rewriteResponseFingerprint || !Array.isArray(receipt.replacementSentenceIds))
+        throw new Error('Semantic review task requires its bound rewrite receipt.');
+    const evidenceScope = { sentenceIds: [...new Set(receipt.replacementSentenceIds)].sort((left, right) => left - right) };
+    if (evidenceScope.sentenceIds.some((id) => !Number.isSafeInteger(id) || id < 1) || new Set(allowedViolations).size !== allowedViolations.length || allowedViolations.some((item) => !violations.has(item)))
+        throw new Error('Semantic review task has invalid evidence scope or violations.');
+    const base = { version: '1', judgmentType: 'semantic', binding, policy, evidenceScope, allowedViolations: [...allowedViolations].sort() };
+    return { ...base, taskFingerprint: hash('hyv:semantic-task:v1', base) };
+}
+export function isValidSemanticReviewTask(task) {
+    try {
+        if (!plain(task) || !exact(task, ['version', 'judgmentType', 'binding', 'policy', 'evidenceScope', 'allowedViolations', 'taskFingerprint'])
+            || task.version !== '1' || task.judgmentType !== 'semantic' || !bindingValid(task.binding) || !['normal', 'high_assurance'].includes(task.policy)
+            || !plain(task.evidenceScope) || !exact(task.evidenceScope, ['sentenceIds']) || !Array.isArray(task.evidenceScope.sentenceIds)
+            || task.evidenceScope.sentenceIds.some((id) => !Number.isSafeInteger(id) || id < 1) || new Set(task.evidenceScope.sentenceIds).size !== task.evidenceScope.sentenceIds.length
+            || !Array.isArray(task.allowedViolations) || task.allowedViolations.some((item) => !violations.has(item)) || new Set(task.allowedViolations).size !== task.allowedViolations.length)
+            return false;
+        const { taskFingerprint, ...base } = task;
+        return taskFingerprint === hash('hyv:semantic-task:v1', base);
+    }
+    catch {
+        return false;
+    }
+}
+export function parseSemanticVerdict(taskOrEvaluatorId, evaluatorIdOrValue, maybeValue) {
+    if (typeof taskOrEvaluatorId === 'string') {
+        const raw = evaluatorIdOrValue;
+        if (!plain(raw) || typeof raw.approved !== 'boolean' || !Array.isArray(raw.violations) || raw.violations.some((item) => typeof item !== 'string' || !violations.has(item)))
+            throw new Error('Semantic evaluator response must include approved and known violations.');
+        return { evaluatorId: taskOrEvaluatorId, approved: raw.approved, violations: raw.violations };
     }
-    return { evaluatorId, approved: verdict.approved, violations: verdict.violations };
+    const task = taskOrEvaluatorId;
+    const evaluatorId = evaluatorIdOrValue;
+    const value = maybeValue;
+    if (!isValidSemanticReviewTask(task) || !ID.test(evaluatorId) || !value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Semantic evaluator response must be a bounded object.');
+    const raw = value;
+    if (Object.keys(raw).some((key) => !['approved', 'violations'].includes(key)) || typeof raw.approved !== 'boolean' || !Array.isArray(raw.violations)
+        || raw.violations.some((item) => typeof item !== 'string' || !violations.has(item) || !task.allowedViolations.includes(item)) || new Set(raw.violations).size !== raw.violations.length
+        || (raw.approved && raw.violations.length !== 0) || (!raw.approved && raw.violations.length === 0))
+        throw new Error('Semantic evaluator response contradicts its known violations.');
+    return { version: '1', judgmentType: 'semantic', taskFingerprint: task.taskFingerprint, binding: task.binding, evidenceScope: task.evidenceScope, evaluatorId, approved: raw.approved, violations: raw.violations };
 }
 export function reviewSemanticVerdicts(verdicts) {
     const ids = new Set(verdicts.map((verdict) => verdict.evaluatorId));
@@ -18,3 +67,123 @@ export function reviewSemanticVerdicts(verdicts) {
         return { status: 'needs_escalation', verdicts, reason: 'evaluator_disagreement' };
     return { status: 'needs_escalation', verdicts, reason: 'semantic_violation' };
 }
+function artifact(base) {
+    return { ...base, artifactFingerprint: hash('hyv:lifecycle-artifact:v1', base) };
+}
+export function isValidLifecycleArtifact(value) {
+    if (!plain(value) || value.version !== '1' || !['needs_semantic_review', 'ready_for_human_review', 'approved', 'needs_escalation'].includes(value.status) || !bindingValid(value.binding) || !['normal', 'high_assurance'].includes(value.semanticPolicy)
+        || !HEX.test(value.transitionFingerprint) || !HEX.test(value.semanticTaskFingerprint) || !HEX.test(value.semanticEvidenceScopeFingerprint)
+        || !Array.isArray(value.verdictFingerprints) || value.verdictFingerprints.some((item) => !HEX.test(item)) || new Set(value.verdictFingerprints).size !== value.verdictFingerprints.length)
+        return false;
+    const requiredKeys = ['version', 'status', 'artifactFingerprint', 'transitionFingerprint', 'binding', 'semanticPolicy', 'semanticTaskFingerprint', 'semanticEvidenceScopeFingerprint', 'verdictFingerprints'];
+    const optionalKeys = ['parentArtifactFingerprint', 'capabilityFingerprint', 'reason'];
+    if (!exact(value, requiredKeys, optionalKeys))
+        return false;
+    const requiredVerdicts = value.semanticPolicy === 'normal' ? 1 : 3;
+    if (value.status === 'needs_semantic_review' && (value.parentArtifactFingerprint !== undefined || value.verdictFingerprints.length !== 0 || value.capabilityFingerprint !== undefined || value.reason !== undefined))
+        return false;
+    if (value.status === 'ready_for_human_review' && (!value.parentArtifactFingerprint || !HEX.test(value.parentArtifactFingerprint) || value.verdictFingerprints.length !== requiredVerdicts || value.capabilityFingerprint !== undefined || value.reason !== undefined))
+        return false;
+    if (value.status === 'approved' && (!value.parentArtifactFingerprint || !HEX.test(value.parentArtifactFingerprint) || value.verdictFingerprints.length !== requiredVerdicts || !value.capabilityFingerprint || !HEX.test(value.capabilityFingerprint) || value.reason !== undefined))
+        return false;
+    if (value.status === 'needs_escalation' && (!value.parentArtifactFingerprint || !HEX.test(value.parentArtifactFingerprint) || !value.reason || !['semantic_rejection', 'semantic_disagreement', 'human_rejection'].includes(value.reason) || value.verdictFingerprints.length !== requiredVerdicts || value.capabilityFingerprint !== undefined))
+        return false;
+    const { artifactFingerprint, ...base } = value;
+    return HEX.test(artifactFingerprint) && artifactFingerprint === hash('hyv:lifecycle-artifact:v1', base);
+}
+export function createInitialLifecycleArtifact(task, deterministic) {
+    const { taskFingerprint, ...taskBase } = task;
+    const { artifactFingerprint, ...deterministicBase } = deterministic;
+    const expectedDeterministicFingerprint = createHash('sha256').update(`hyv:deterministic-verification:v1\0${canonicalJson(deterministicBase)}`).digest('hex');
+    if (taskFingerprint !== hash('hyv:semantic-task:v1', taskBase) || !deterministic.passed || artifactFingerprint !== expectedDeterministicFingerprint || deterministic.artifactFingerprint !== task.binding.deterministicArtifactFingerprint || deterministic.sourceHash !== task.binding.sourceHash || deterministic.candidateHash !== task.binding.candidateHash || deterministic.profileId !== task.binding.profileId || deterministic.profileRevisionDigest !== task.binding.profileRevisionDigest || deterministic.rulesetVersion !== task.binding.rulesetVersion)
+        throw new Error('Lifecycle creation requires its bound passed deterministic verification artifact.');
+    return artifact({ version: '1', status: 'needs_semantic_review', transitionFingerprint: hash('hyv:lifecycle-initial:v1', { binding: task.binding, semanticPolicy: task.policy }), binding: task.binding, semanticPolicy: task.policy, semanticTaskFingerprint: task.taskFingerprint, semanticEvidenceScopeFingerprint: hash('hyv:semantic-evidence-scope:v1', task.evidenceScope), verdictFingerprints: [] });
+}
+function fail(error) { return { ok: false, error }; }
+function normalizeAction(value) {
+    if (!plain(value) || value.version !== '1' || typeof value.parentArtifactFingerprint !== 'string' || !HEX.test(value.parentArtifactFingerprint))
+        return undefined;
+    const action = value;
+    if (action.type === 'semantic_submission') {
+        if (!exact(value, ['version', 'type', 'parentArtifactFingerprint', 'taskFingerprint', 'verdicts']) || !HEX.test(action.taskFingerprint) || !Array.isArray(action.verdicts) || action.verdicts.length < 1 || action.verdicts.length > 3)
+            return undefined;
+        for (const verdict of action.verdicts) {
+            if (!verdict || typeof verdict !== 'object' || !exact(verdict, ['version', 'judgmentType', 'taskFingerprint', 'binding', 'evidenceScope', 'evaluatorId', 'approved', 'violations']) || verdict.version !== '1' || verdict.judgmentType !== 'semantic' || !ID.test(verdict.evaluatorId) || typeof verdict.approved !== 'boolean' || !Array.isArray(verdict.violations) || verdict.violations.some((item) => !violations.has(item)) || new Set(verdict.violations).size !== verdict.violations.length)
+                return undefined;
+        }
+        return { ...action, verdicts: [...action.verdicts].map((verdict) => ({ ...verdict, violations: [...verdict.violations].sort() })).sort((left, right) => left.evaluatorId < right.evaluatorId ? -1 : left.evaluatorId > right.evaluatorId ? 1 : 0) };
+    }
+    if (action.type === 'human_finalization' && exact(action, ['version', 'type', 'parentArtifactFingerprint', 'finalization']) && action.finalization?.version === '1') {
+        const finalization = action.finalization;
+        if (!plain(finalization) || !exact(finalization, ['version', 'judgmentType', 'parentArtifactFingerprint', 'binding', 'evaluatorId', 'evidenceScope', 'decision'], ['capability']) || action.finalization.judgmentType !== 'human_finalization' || !ID.test(action.finalization.evaluatorId) || !HEX.test(action.finalization.parentArtifactFingerprint) || !bindingValid(action.finalization.binding) || !plain(action.finalization.evidenceScope) || !exact(action.finalization.evidenceScope, ['kind']) || action.finalization.evidenceScope.kind !== 'candidate' || !['approve', 'reject'].includes(action.finalization.decision))
+            return undefined;
+        return action;
+    }
+    return undefined;
+}
+export function reduceRewriteLifecycle(current, rawAction, context) {
+    let action;
+    let transitionFingerprint;
+    try {
+        action = normalizeAction(rawAction);
+        if (!action)
+            return fail('invalid_action');
+        transitionFingerprint = hash('hyv:lifecycle-transition:v1', action);
+    }
+    catch {
+        return fail('invalid_action');
+    }
+    if (current.transitionFingerprint === transitionFingerprint)
+        return { ok: true, artifact: current };
+    if (action.parentArtifactFingerprint === current.parentArtifactFingerprint)
+        return fail('conflicting_replay');
+    if (action.parentArtifactFingerprint !== current.artifactFingerprint)
+        return fail('stale_parent');
+    if (current.status === 'approved' || current.status === 'needs_escalation')
+        return fail('terminal_state');
+    if (action.type === 'semantic_submission') {
+        if (current.status !== 'needs_semantic_review')
+            return fail('out_of_order_transition');
+        const required = current.semanticPolicy === 'normal' ? 1 : 3;
+        if (action.verdicts.length !== required)
+            return fail('invalid_verdict_count');
+        const ids = action.verdicts.map((verdict) => verdict.evaluatorId);
+        if (new Set(ids).size !== ids.length)
+            return fail('duplicate_evaluator');
+        const authorized = current.semanticPolicy === 'normal' ? context.authorizedSemanticEvaluatorIds.normal : context.authorizedSemanticEvaluatorIds.highAssurance;
+        if (current.semanticPolicy === 'high_assurance' && new Set(authorized).size < 3)
+            return fail('invalid_verdict_count');
+        if (ids.some((id) => !authorized.includes(id)))
+            return fail('evaluator_not_authorized');
+        for (const verdict of action.verdicts) {
+            if (action.taskFingerprint !== current.semanticTaskFingerprint || verdict.taskFingerprint !== action.taskFingerprint)
+                return fail('task_fingerprint_mismatch');
+            if (!same(verdict.binding, current.binding))
+                return fail('invalid_binding');
+            if (verdict.judgmentType !== 'semantic' || hash('hyv:semantic-evidence-scope:v1', verdict.evidenceScope) !== current.semanticEvidenceScopeFingerprint)
+                return fail('evidence_scope_mismatch');
+            if ((verdict.approved && verdict.violations.length) || (!verdict.approved && !verdict.violations.length))
+                return fail('contradictory_verdict');
+        }
+        const verdictFingerprints = action.verdicts.map((verdict) => hash('hyv:semantic-verdict:v1', verdict));
+        const approvals = action.verdicts.filter((verdict) => verdict.approved).length;
+        const status = approvals === required ? 'ready_for_human_review' : 'needs_escalation';
+        const reason = status === 'needs_escalation' ? (approvals === 0 ? 'semantic_rejection' : 'semantic_disagreement') : undefined;
+        return { ok: true, artifact: artifact({ version: '1', status, parentArtifactFingerprint: current.artifactFingerprint, transitionFingerprint, binding: current.binding, semanticPolicy: current.semanticPolicy, semanticTaskFingerprint: current.semanticTaskFingerprint, semanticEvidenceScopeFingerprint: current.semanticEvidenceScopeFingerprint, verdictFingerprints, ...(reason ? { reason } : {}) }) };
+    }
+    if (current.status !== 'ready_for_human_review')
+        return fail('out_of_order_transition');
+    const finalization = action.finalization;
+    if (finalization.parentArtifactFingerprint !== current.artifactFingerprint || !same(finalization.binding, current.binding) || finalization.judgmentType !== 'human_finalization' || finalization.evidenceScope.kind !== 'candidate')
+        return fail('invalid_binding');
+    if (!context.authorizedHumanFinalizerIds.includes(finalization.evaluatorId))
+        return fail('human_finalizer_not_authorized');
+    if (finalization.decision === 'reject')
+        return { ok: true, artifact: artifact({ version: '1', status: 'needs_escalation', parentArtifactFingerprint: current.artifactFingerprint, transitionFingerprint, binding: current.binding, semanticPolicy: current.semanticPolicy, semanticTaskFingerprint: current.semanticTaskFingerprint, semanticEvidenceScopeFingerprint: current.semanticEvidenceScopeFingerprint, verdictFingerprints: current.verdictFingerprints, reason: 'human_rejection' }) };
+    if (!finalization.capability)
+        return fail('capability_required');
+    const capability = verifyApprovalCapability(finalization.capability, context.trustStore, { now: context.now, expectedSubjectArtifactFingerprint: current.artifactFingerprint, binding: current.binding, expectedPurpose: 'hyv.final-approval' });
+    if (!capability.ok)
+        return fail('capability_invalid');
+    return { ok: true, artifact: artifact({ version: '1', status: 'approved', parentArtifactFingerprint: current.artifactFingerprint, transitionFingerprint, binding: current.binding, semanticPolicy: current.semanticPolicy, semanticTaskFingerprint: current.semanticTaskFingerprint, semanticEvidenceScopeFingerprint: current.semanticEvidenceScopeFingerprint, verdictFingerprints: current.verdictFingerprints, capabilityFingerprint: capability.capabilityFingerprint }) };
+}

package/dist/semantic-review.test.js

@@ -1,17 +1,101 @@
 import assert from 'node:assert/strict';
+import { createHash, generateKeyPairSync, sign } from 'node:crypto';
 import test from 'node:test';
-import { parseSemanticVerdict, reviewSemanticVerdicts } from './semantic-review.js';
-test('accepts only three independent clean semantic verdicts', () => {
-    const result = reviewSemanticVerdicts(['deepseek', 'kimi', 'sonnet'].map((evaluatorId) => parseSemanticVerdict(evaluatorId, { approved: true, violations: [] })));
-    assert.equal(result.status, 'accepted');
-});
-test('escalates disagreement and action drift', () => {
-    const disagreement = reviewSemanticVerdicts([
-        parseSemanticVerdict('deepseek', { approved: true, violations: [] }),
-        parseSemanticVerdict('kimi', { approved: false, violations: ['action_change'] }),
-        parseSemanticVerdict('sonnet', { approved: false, violations: ['action_change'] }),
-    ]);
-    assert.equal(disagreement.reason, 'evaluator_disagreement');
-    const rejected = reviewSemanticVerdicts(['deepseek', 'kimi', 'sonnet'].map((evaluatorId) => parseSemanticVerdict(evaluatorId, { approved: false, violations: ['action_change'] })));
-    assert.equal(rejected.reason, 'semantic_violation');
+import { canonicalJson, canonicalJsonBytes } from './canonical-json.js';
+import { createInitialLifecycleArtifact, parseSemanticVerdict, prepareSemanticReviewTask, reduceRewriteLifecycle, reviewSemanticVerdicts } from './semantic-review.js';
+const deterministicBase = { version: '1', verificationKind: 'standard', passed: true, analysisVersion: '2', rulesetVersion: '3.2.0', preservationMetricVersion: 'legacy-set-v1', preservationScore: 100, sourceHash: '4'.repeat(64), candidateHash: '5'.repeat(64), profileId: 'founder.primary', profileRevisionDigest: '6'.repeat(64), regressionKeys: [] };
+const deterministicFingerprint = createHash('sha256').update(`hyv:deterministic-verification:v1\0${canonicalJson(deterministicBase)}`).digest('hex');
+const binding = { rewriteTaskFingerprint: '1'.repeat(64), rewriteResponseFingerprint: '2'.repeat(64), deterministicArtifactFingerprint: deterministicFingerprint, sourceHash: deterministicBase.sourceHash, candidateHash: deterministicBase.candidateHash, profileId: deterministicBase.profileId, profileRevisionDigest: deterministicBase.profileRevisionDigest, rulesetVersion: deterministicBase.rulesetVersion, schemaVersion: '1' };
+const receipt = { version: '1', taskFingerprint: binding.rewriteTaskFingerprint, responseFingerprint: binding.rewriteResponseFingerprint, adapterIds: [], replacementSentenceIds: [3, 1] };
+function task(policy = 'normal') { return prepareSemanticReviewTask(binding, policy, receipt, ['action_change']); }
+function deterministic(passed = true) { const base = { ...deterministicBase, passed }; return { ...base, artifactFingerprint: createHash('sha256').update(`hyv:deterministic-verification:v1\0${canonicalJson(base)}`).digest('hex') }; }
+const emptyTrust = { version: '1', audience: '@holdyourvoice/hyv', maxCapabilityLifetimeSeconds: 300, keys: [] };
+const context = { now: 150, trustStore: emptyTrust, authorizedSemanticEvaluatorIds: { normal: ['one'], highAssurance: ['one', 'two', 'three'] }, authorizedHumanFinalizerIds: ['human-1'] };
+test('preserves the version 3.2 semantic aggregation API', () => {
+    const verdicts = ['one', 'two', 'three'].map((id) => parseSemanticVerdict(id, { approved: true, violations: [] }));
+    assert.equal(reviewSemanticVerdicts(verdicts).status, 'accepted');
+});
+test('normal review clears with one clean authorized verdict and rejection escalates', () => {
+    const reviewTask = task();
+    const initial = createInitialLifecycleArtifact(reviewTask, deterministic());
+    const clean = parseSemanticVerdict(reviewTask, 'one', { approved: true, violations: [] });
+    const cleared = reduceRewriteLifecycle(initial, { version: '1', type: 'semantic_submission', parentArtifactFingerprint: initial.artifactFingerprint, taskFingerprint: reviewTask.taskFingerprint, verdicts: [clean] }, context);
+    assert.equal(cleared.ok && cleared.artifact.status, 'ready_for_human_review');
+    const rejected = parseSemanticVerdict(reviewTask, 'one', { approved: false, violations: ['action_change'] });
+    const escalated = reduceRewriteLifecycle(initial, { version: '1', type: 'semantic_submission', parentArtifactFingerprint: initial.artifactFingerprint, taskFingerprint: reviewTask.taskFingerprint, verdicts: [rejected] }, context);
+    assert.equal(escalated.ok && escalated.artifact.status, 'needs_escalation');
+});
+test('high assurance is permutation-stable and requires three configured evaluators', () => {
+    const reviewTask = task('high_assurance');
+    const initial = createInitialLifecycleArtifact(reviewTask, deterministic());
+    const verdicts = ['three', 'one', 'two'].map((id) => parseSemanticVerdict(reviewTask, id, { approved: true, violations: [] }));
+    const action = { version: '1', type: 'semantic_submission', parentArtifactFingerprint: initial.artifactFingerprint, taskFingerprint: reviewTask.taskFingerprint, verdicts };
+    const left = reduceRewriteLifecycle(initial, action, context);
+    const right = reduceRewriteLifecycle(initial, { ...action, verdicts: [...verdicts].reverse() }, context);
+    assert.deepEqual(left, right);
+    assert.deepEqual(reduceRewriteLifecycle(initial, { ...action, verdicts: verdicts.slice(0, 2) }, context), { ok: false, error: 'invalid_verdict_count' });
+});
+test('enforces replay, parent order, terminal states, bindings, and evaluator authority', () => {
+    const reviewTask = task();
+    const initial = createInitialLifecycleArtifact(reviewTask, deterministic());
+    const action = { version: '1', type: 'semantic_submission', parentArtifactFingerprint: initial.artifactFingerprint, taskFingerprint: reviewTask.taskFingerprint, verdicts: [parseSemanticVerdict(reviewTask, 'one', { approved: true, violations: [] })] };
+    const next = reduceRewriteLifecycle(initial, action, context);
+    assert.equal(next.ok, true);
+    if (!next.ok)
+        return;
+    assert.strictEqual(reduceRewriteLifecycle(next.artifact, action, context).ok, true);
+    assert.deepEqual(reduceRewriteLifecycle(next.artifact, { ...action, verdicts: [parseSemanticVerdict(reviewTask, 'one', { approved: false, violations: ['action_change'] })] }, context), { ok: false, error: 'conflicting_replay' });
+    assert.deepEqual(reduceRewriteLifecycle(initial, { ...action, parentArtifactFingerprint: '9'.repeat(64) }, context), { ok: false, error: 'stale_parent' });
+    assert.deepEqual(reduceRewriteLifecycle(initial, { ...action, verdicts: [parseSemanticVerdict(reviewTask, 'unknown', { approved: true, violations: [] })] }, context), { ok: false, error: 'evaluator_not_authorized' });
+    const terminal = reduceRewriteLifecycle(createInitialLifecycleArtifact(reviewTask, deterministic()), { ...action, verdicts: [parseSemanticVerdict(reviewTask, 'one', { approved: false, violations: ['action_change'] })] }, context);
+    if (terminal.ok)
+        assert.deepEqual(reduceRewriteLifecycle(terminal.artifact, { ...action, parentArtifactFingerprint: terminal.artifact.artifactFingerprint }, context), { ok: false, error: 'terminal_state' });
+});
+test('authorized human rejection escalates; approval requires a valid external capability', () => {
+    const reviewTask = task();
+    const initial = createInitialLifecycleArtifact(reviewTask, deterministic());
+    const semantic = reduceRewriteLifecycle(initial, { version: '1', type: 'semantic_submission', parentArtifactFingerprint: initial.artifactFingerprint, taskFingerprint: reviewTask.taskFingerprint, verdicts: [parseSemanticVerdict(reviewTask, 'one', { approved: true, violations: [] })] }, context);
+    assert.equal(semantic.ok, true);
+    if (!semantic.ok)
+        return;
+    const approvalBase = { version: '1', judgmentType: 'human_finalization', parentArtifactFingerprint: semantic.artifact.artifactFingerprint, binding, evaluatorId: 'human-1', evidenceScope: { kind: 'candidate' }, decision: 'approve' };
+    assert.deepEqual(reduceRewriteLifecycle(semantic.artifact, { version: '1', type: 'human_finalization', parentArtifactFingerprint: semantic.artifact.artifactFingerprint, finalization: approvalBase }, context), { ok: false, error: 'capability_required' });
+    assert.deepEqual(reduceRewriteLifecycle(semantic.artifact, { version: '1', type: 'human_finalization', parentArtifactFingerprint: semantic.artifact.artifactFingerprint, finalization: { ...approvalBase, capability: { payload: 'bad', signature: 'bad' } } }, context), { ok: false, error: 'capability_invalid' });
+    const rejection = reduceRewriteLifecycle(semantic.artifact, { version: '1', type: 'human_finalization', parentArtifactFingerprint: semantic.artifact.artifactFingerprint, finalization: { version: '1', judgmentType: 'human_finalization', parentArtifactFingerprint: semantic.artifact.artifactFingerprint, binding, evaluatorId: 'human-1', evidenceScope: { kind: 'candidate' }, decision: 'reject' } }, context);
+    assert.equal(rejection.ok && rejection.artifact.status, 'needs_escalation');
+    const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+    const trustStore = { version: '1', audience: '@holdyourvoice/hyv', maxCapabilityLifetimeSeconds: 300, keys: [{ issuer: 'host', keyId: 'k1', publicKeySpki: publicKey.export({ type: 'spki', format: 'der' }).toString('base64url'), status: 'active' }] };
+    const claims = { version: '1', purpose: 'hyv.final-approval', issuer: 'host', audience: '@holdyourvoice/hyv', subjectArtifactFingerprint: semantic.artifact.artifactFingerprint, sourceHash: binding.sourceHash, candidateHash: binding.candidateHash, profileId: binding.profileId, profileRevisionDigest: binding.profileRevisionDigest, keyId: 'k1', issuedAt: 100, notBefore: 100, expiresAt: 200, nonce: 'nonce' };
+    const payload = canonicalJsonBytes(claims);
+    const capability = { payload: payload.toString('base64url'), signature: sign(null, payload, privateKey).toString('base64url') };
+    const approved = reduceRewriteLifecycle(semantic.artifact, { version: '1', type: 'human_finalization', parentArtifactFingerprint: semantic.artifact.artifactFingerprint, finalization: { version: '1', judgmentType: 'human_finalization', parentArtifactFingerprint: semantic.artifact.artifactFingerprint, binding, evaluatorId: 'human-1', evidenceScope: { kind: 'candidate' }, decision: 'approve', capability } }, { ...context, trustStore });
+    assert.equal(approved.ok && approved.artifact.status, 'approved');
+    assert.doesNotMatch(JSON.stringify(approved), /nonce|payload|signature/);
+});
+test('failed deterministic verification cannot create an initial lifecycle artifact', () => {
+    assert.throws(() => createInitialLifecycleArtifact(task(), deterministic(false)), /passed deterministic verification/);
+    const reviewTask = task();
+    assert.throws(() => createInitialLifecycleArtifact({ ...reviewTask, evidenceScope: { sentenceIds: [99] } }, deterministic()), /passed deterministic verification/);
+});
+test('rejects oversized or deeply nested actions as invalid without throwing', () => {
+    const reviewTask = task();
+    const initial = createInitialLifecycleArtifact(reviewTask, deterministic());
+    const verdict = parseSemanticVerdict(reviewTask, 'one', { approved: true, violations: [] });
+    const oversized = { version: '1', type: 'semantic_submission', parentArtifactFingerprint: initial.artifactFingerprint, taskFingerprint: reviewTask.taskFingerprint, verdicts: Array.from({ length: 1000 }, () => verdict) };
+    assert.deepEqual(reduceRewriteLifecycle(initial, oversized, context), { ok: false, error: 'invalid_action' });
+    let nested = 'x';
+    for (let index = 0; index < 70; index += 1)
+        nested = [nested];
+    assert.deepEqual(reduceRewriteLifecycle(initial, { ...oversized, verdicts: [{ ...verdict, binding: nested }] }, context), { ok: false, error: 'invalid_action' });
+    const malformedFinalization = { version: '1', type: 'human_finalization', parentArtifactFingerprint: initial.artifactFingerprint, finalization: { version: '1', judgmentType: 'human_finalization', parentArtifactFingerprint: initial.artifactFingerprint, binding, evaluatorId: 'human-1', evidenceScope: null, decision: 'reject' } };
+    assert.deepEqual(reduceRewriteLifecycle(initial, malformedFinalization, context), { ok: false, error: 'invalid_action' });
+});
+test('semantic submissions reject changed task, binding, and evidence scope', () => {
+    const reviewTask = task();
+    const initial = createInitialLifecycleArtifact(reviewTask, deterministic());
+    const verdict = parseSemanticVerdict(reviewTask, 'one', { approved: true, violations: [] });
+    const base = { version: '1', type: 'semantic_submission', parentArtifactFingerprint: initial.artifactFingerprint, taskFingerprint: reviewTask.taskFingerprint, verdicts: [verdict] };
+    assert.deepEqual(reduceRewriteLifecycle(initial, { ...base, taskFingerprint: '9'.repeat(64) }, context), { ok: false, error: 'task_fingerprint_mismatch' });
+    assert.deepEqual(reduceRewriteLifecycle(initial, { ...base, verdicts: [{ ...verdict, binding: { ...binding, candidateHash: '9'.repeat(64) } }] }, context), { ok: false, error: 'invalid_binding' });
+    assert.deepEqual(reduceRewriteLifecycle(initial, { ...base, verdicts: [{ ...verdict, evidenceScope: { sentenceIds: [99] } }] }, context), { ok: false, error: 'evidence_scope_mismatch' });
 });

package/dist/stage1-dry-run.test.js

@@ -0,0 +1,39 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, symlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+test('synthetic Stage 1 packet executes outside the repository and remains blocked', () => {
+    const parent = mkdtempSync(join(tmpdir(), 'hyv-stage1-dry-run-test-'));
+    const outputRoot = join(parent, 'packet');
+    try {
+        const output = JSON.parse(execFileSync(process.execPath, ['scripts/run-stage1-dry-run.mjs', '--out', outputRoot], { encoding: 'utf8' }));
+        assert.equal(output.decision, 'BLOCKED');
+        assert.equal(output.promotable, false);
+        assert.deepEqual(output.blockers, ['human_writer_evidence_deferred', 'synthetic_fixture_evidence', 'locked_human_evidence_required']);
+        const report = JSON.parse(readFileSync(join(outputRoot, 'report.json'), 'utf8'));
+        assert.equal(report.decision, 'BLOCKED');
+        assert.equal(report.promotable, false);
+        assert.match(report.reportDigest, /^[a-f0-9]{64}$/);
+    }
+    finally {
+        rmSync(parent, { recursive: true, force: true });
+    }
+});
+test('synthetic Stage 1 packet refuses repository output', () => {
+    assert.throws(() => execFileSync(process.execPath, ['scripts/run-stage1-dry-run.mjs', '--out', join(process.cwd(), 'stage1-output')], { stdio: 'pipe' }), /Dry-run output must stay outside the repository/);
+});
+test('synthetic Stage 1 packet refuses a symlinked ancestor into the repository', () => {
+    const parent = mkdtempSync(join(tmpdir(), 'hyv-stage1-symlink-test-'));
+    const repositoryTarget = join(process.cwd(), 'stage1-symlink-target');
+    mkdirSync(repositoryTarget);
+    symlinkSync(repositoryTarget, join(parent, 'redirect'));
+    try {
+        assert.throws(() => execFileSync(process.execPath, ['scripts/run-stage1-dry-run.mjs', '--out', join(parent, 'redirect', 'packet')], { stdio: 'pipe' }), /Dry-run output must stay outside the repository/);
+    }
+    finally {
+        rmSync(parent, { recursive: true, force: true });
+        rmSync(repositoryTarget, { recursive: true, force: true });
+    }
+});