@dzhechkov/p-replicator 1.12.0 → 1.13.1

package/tests/unit/check-source-version.test.js

@@ -0,0 +1,344 @@
+'use strict';
+
+// The deterministic half of «правка объявляет ВЕРСИЮ источника, а не обещает перечитать». There is
+// NO new always-loaded rule: the corpus budget is spent (measured 2026-09-01) and the owner refused
+// to raise the threshold, so the doctrine lives in the checker's header, which is never loaded.
+//
+// WHAT IS ALREADY PRESCRIBED AND IS NOT RE-OPENED. «Take the status from the FILE, not from the
+// worker's narrative» is already required: the coordinator checks each receipt for existence,
+// non-emptiness and mtime freshness before merging. That half stands. This suite covers the one it
+// does not reach.
+//
+// THE UNCOVERED HALF: freshness is checked on the RECEIPT, never on the SOURCE the receipt was
+// derived from. A read copy is a snapshot of the MOMENT OF READING, not of the file, so an edit
+// addressed by a literal string is a race BY CONSTRUCTION. The field case: an edit to Refinement.md
+// died on an assertion because a worker had renumbered the guards between the read and the write.
+// The symmetric case is quieter: three reports saying «the defect is still there» were written from
+// stale copies — and each report was itself perfectly FRESH, so a freshness check on the receipt
+// answered a neighbouring question and handed the answer over as the asked one.
+//
+// WHY A HASH AND NOT AN INSTRUCTION, asserted here rather than merely argued: a rule «re-read
+// immediately before editing» cannot be checked by inspecting the finished file, so its failure is
+// silent — the weakest layer of this package's own ladder. A declared version is checkable by
+// anyone, later, without trusting anybody. P12 is the test that the tool embodies the other half of
+// the same idea: a refusal does not mutate.
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const { spawnSync } = require('node:child_process');
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const PKG = path.resolve(__dirname, '..', '..');
+const TPL = path.join(PKG, 'templates', '.claude');
+const CHECK = path.join(TPL, 'hooks', 'check-source-version.cjs');
+const DECL = 'docs/source-versions.md';
+
+const read = (rel) => fs.readFileSync(path.join(PKG, rel), 'utf8');
+const sha256 = (s) => crypto.createHash('sha256').update(Buffer.from(s, 'utf8')).digest('hex');
+
+/** Build a throwaway project, run the REAL checker, and return the verdict plus a tree fingerprint. */
+function check(files) {
+  const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'p-rep-srcver-')));
+  const fingerprint = () => {
+    const out = [];
+    const walk = (d, rel) => {
+      for (const e of fs.readdirSync(d).sort()) {
+        const full = path.join(d, e);
+        const r = rel ? rel + '/' + e : e;
+        if (fs.statSync(full).isDirectory()) walk(full, r);
+        else out.push(r + ':' + crypto.createHash('sha256').update(fs.readFileSync(full)).digest('hex'));
+      }
+    };
+    walk(dir, '');
+    return out.join('\n');
+  };
+  try {
+    for (const [rel, body] of Object.entries(files || {})) {
+      const abs = path.join(dir, rel);
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, body);
+    }
+    const before = fingerprint();
+    const r = spawnSync(process.execPath, [CHECK, dir], { encoding: 'utf8' });
+    const after = fingerprint();
+    return { code: r.status, out: (r.stdout || '') + (r.stderr || ''), before, after };
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+}
+
+const REFINEMENT = '# Refinement\n\n1. Страж A\n2. Страж B\n3. Страж C\n';
+
+/**
+ * A declaration in whatever state the case needs.
+ *
+ * Defaults are the HEALTHY ones so that every case stays about the single thing it changes; a case
+ * that wants silence passes `null` for that field, and silence is asserted as its own outcome.
+ */
+function decl({ work = 'да', run = 'ВЫПОЛНЕНА', reason = null, rows } = {}) {
+  const line = (label, value) => (value === null || value === undefined ? '' : '**' + label + ':** ' + value + '\n');
+  const body = rows === undefined
+    ? [['перенумеровать стражей', 'правка', 'docs/Refinement.md', sha256(REFINEMENT)],
+      ['дефект F1 всё ещё жив', 'вывод', 'docs/Refinement.md', sha256(REFINEMENT)]]
+    : rows;
+  return '# Source versions\n\n'
+    + line('Правки и выводы', work)
+    + line('Проверка версий', run)
+    + line('Причина', reason)
+    + '\n## Выводы и правки\n\n'
+    + '| Что | Вид | Источник | Хеш источника |\n|---|---|---|---|\n'
+    + body.map((r) => '| ' + r.join(' | ') + ' |').join('\n') + '\n';
+}
+
+const healthy = (over = {}) => ({ 'docs/Refinement.md': REFINEMENT, [DECL]: decl(over) });
+
+describe('версия источника объявлена — the deterministic half', () => {
+  test('P1 - an edit and a verdict whose source still hashes to the declared value are CLEAN', () => {
+    const r = check(healthy());
+    assert.equal(r.code, 0, r.out);
+    assert.match(r.out, /✅/);
+    assert.match(r.out, /1 правк\(и\), 1 вывод\(ов\)/, r.out);
+    // The boundary is part of the verdict: a matching hash proves the ground did not move, never
+    // that the conclusion standing on it follows.
+    assert.match(r.out, /почва НЕ СДВИНУЛАСЬ/, r.out);
+  });
+
+  test('P2 - no declaration at all is NOT clean', () => {
+    const r = check({ 'docs/Refinement.md': REFINEMENT });
+    assert.equal(r.code, 2, r.out);
+    assert.match(r.out, /нет файла docs\/source-versions\.md/);
+    assert.match(r.out, /НЕ ЗАДАВАЛСЯ/);
+  });
+
+  test('P3 - «no edits and no verdicts» is legitimate, and it is 2 rather than 0', () => {
+    const r = check({ [DECL]: decl({ work: 'нет' }) });
+    assert.equal(r.code, 2, r.out);
+    assert.doesNotMatch(r.out, /✅/);
+  });
+
+  test('P4 - an unrecognised closed value stops the check instead of guessing', () => {
+    const r = check(healthy({ work: 'частично' }));
+    assert.equal(r.code, 2, r.out);
+    assert.match(r.out, /нераспознанное значение/);
+  });
+
+  test('P5 - «НЕ ВЫПОЛНЕНА» needs a reason from the closed list, and then it is honest', () => {
+    const noReason = check(healthy({ run: 'НЕ ВЫПОЛНЕНА' }));
+    assert.equal(noReason.code, 2, noReason.out);
+    assert.match(noReason.out, /без строки `\*\*Причина:\*\*`/);
+
+    const freeText = check(healthy({ run: 'НЕ ВЫПОЛНЕНА', reason: 'позже' }));
+    assert.equal(freeText.code, 2, freeText.out);
+    assert.match(freeText.out, /не из закрытого списка/);
+
+    const named = check(healthy({ run: 'НЕ ВЫПОЛНЕНА', reason: 'решение-отложено' }));
+    assert.equal(named.code, 2, named.out);
+    assert.match(named.out, /решение-отложено/);
+    // The honest refusal names WHY it matters — a fresh receipt over a stale source.
+    assert.match(named.out, /устаревшего источника/);
+    assert.doesNotMatch(named.out, /✅/);
+  });
+
+  test('P6 - an empty table under «да» is a PROVEN gap', () => {
+    const r = check({ 'docs/Refinement.md': REFINEMENT, [DECL]: decl({ rows: [] }) });
+    assert.equal(r.code, 1, r.out);
+    assert.match(r.out, /ни один не назван/);
+  });
+
+  test('P7 - a misspelled Вид is reported, never silently dropped', () => {
+    // A row that falls out of the parser is indistinguishable from a row nobody wrote — the same
+    // substitution the whole file is about, one level down.
+    const r = check({ 'docs/Refinement.md': REFINEMENT, [DECL]: decl({
+      rows: [['перенумеровать', 'правочка', 'docs/Refinement.md', sha256(REFINEMENT)]],
+    }) });
+    assert.equal(r.code, 2, r.out);
+    assert.match(r.out, /нераспознанный `Вид`/);
+  });
+
+  test('P8 - a row with no source, or no hash, is a PROVEN defect', () => {
+    const noSource = check({ 'docs/Refinement.md': REFINEMENT, [DECL]: decl({
+      rows: [['перенумеровать', 'правка', '—', sha256(REFINEMENT)]],
+    }) });
+    assert.equal(noSource.code, 1, noSource.out);
+    assert.match(noSource.out, /источник не назван/);
+
+    const noHash = check({ 'docs/Refinement.md': REFINEMENT, [DECL]: decl({
+      rows: [['перенумеровать', 'правка', 'docs/Refinement.md', '—']],
+    }) });
+    assert.equal(noHash.code, 1, noHash.out);
+    assert.match(noHash.out, /версия источника не записана/);
+    // The load-bearing argument: a promise cannot be checked, a hash can.
+    assert.match(noHash.out, /Обещание перечитать проверить\s+нельзя/);
+  });
+
+  test('P9 - a malformed digest is «could not check», not «mismatch»', () => {
+    // Different repairs: a typo in the digest is not evidence that the source moved.
+    const r = check({ 'docs/Refinement.md': REFINEMENT, [DECL]: decl({
+      rows: [['перенумеровать', 'правка', 'docs/Refinement.md', 'deadbeef']],
+    }) });
+    assert.equal(r.code, 2, r.out);
+    assert.match(r.out, /не похож на sha256/);
+  });
+
+  test('P10 - a source that does not exist pins nothing', () => {
+    const r = check({ [DECL]: decl({
+      rows: [['перенумеровать', 'правка', 'docs/absent.md', sha256(REFINEMENT)]],
+    }) });
+    assert.equal(r.code, 1, r.out);
+    assert.match(r.out, /нет на диске/);
+  });
+
+  test('P11 - THE fixture: declared H1, live H2 — the edit is REFUSED', () => {
+    // The field case, reduced: the guards were renumbered between the read and the write.
+    const renumbered = REFINEMENT.replace('2. Страж B', '2. Страж B2');
+    const r = check({ 'docs/Refinement.md': renumbered, [DECL]: decl() });
+    assert.equal(r.code, 1, r.out);
+    assert.match(r.out, /источник изменился после чтения — правка ОТКЛОНЕНА, мутации нет/);
+    assert.match(r.out, /перенумеровать стражей/, 'the edit must be NAMED');
+    // Both halves of the mechanism must appear: the literal-string race AND the fresh report over a
+    // stale source, which is the one a receipt check cannot see.
+    assert.match(r.out, /снимок МОМЕНТА ЧТЕНИЯ/);
+    assert.match(r.out, /отвечает не на тот вопрос/);
+  });
+
+  test('P12 - the refusal does NOT mutate: the tree is byte-identical after the run', () => {
+    // «Отказ без мутации» is a property of the TOOL here, not an instruction to its user. Asserted
+    // over the whole tree rather than the named source, because a checker that repaired the
+    // declaration — or wrote a report beside it — would also be mutating on a refusal.
+    const renumbered = REFINEMENT.replace('2. Страж B', '2. Страж B2');
+    const r = check({ 'docs/Refinement.md': renumbered, [DECL]: decl() });
+    assert.equal(r.code, 1, r.out);
+    assert.equal(r.after, r.before, 'the checker changed the tree while refusing');
+
+    // And the same on the clean path, so the property is not accidentally about failure only.
+    const ok = check(healthy());
+    assert.equal(ok.code, 0, ok.out);
+    assert.equal(ok.after, ok.before, 'the checker changed the tree while passing');
+  });
+
+  test('P13 - and the SAME declaration, re-pinned to the live file, is accepted', () => {
+    const renumbered = REFINEMENT.replace('2. Страж B', '2. Страж B2');
+    const r = check({ 'docs/Refinement.md': renumbered, [DECL]: decl({
+      rows: [['перенумеровать стражей', 'правка', 'docs/Refinement.md', sha256(renumbered)]],
+    }) });
+    assert.equal(r.code, 0, r.out);
+  });
+
+  test('P14 - a VERDICT built on a stale source is refused exactly like an edit', () => {
+    // The symmetric half, and the quieter one: the report is fresh, its ground is not.
+    const renumbered = REFINEMENT.replace('3. Страж C', '3. Страж C — исправлен');
+    const r = check({ 'docs/Refinement.md': renumbered, [DECL]: decl({
+      rows: [['дефект F1 всё ещё жив', 'вывод', 'docs/Refinement.md', sha256(REFINEMENT)]],
+    }) });
+    assert.equal(r.code, 1, r.out);
+    assert.match(r.out, /\(verdict\)/, 'the report must say WHICH kind was refused');
+  });
+
+  test('P15 - no non-zero exit ever prints the clean marker', () => {
+    const cases = [
+      {},
+      { [DECL]: decl({ work: 'нет' }) },
+      { [DECL]: decl({ rows: [] }) },
+      { 'docs/Refinement.md': REFINEMENT + 'x', [DECL]: decl() },
+      { 'docs/Refinement.md': REFINEMENT, [DECL]: decl({ rows: [['a', 'правка', 'docs/Refinement.md', 'zz']] }) },
+    ];
+    for (const files of cases) {
+      const r = check(files);
+      assert.notEqual(r.code, 0, JSON.stringify(Object.keys(files)));
+      assert.doesNotMatch(r.out, /✅/, r.out);
+    }
+  });
+});
+
+/** The seam's FORCE, separately from its vocabulary. */
+function seamForceProblems(text) {
+  const problems = [];
+  if (!/Every EDIT and every VERDICT MUST declare the sha256 of the source it was built on/.test(text)) {
+    problems.push('the version precondition is advisory, not imperative');
+  }
+  if (!/refusal WITHOUT mutation/.test(text)) {
+    problems.push('a mismatch no longer refuses — applying the edit to the newer text is the defect');
+  }
+  if (!/snapshot of the moment\s*\n?\s*of reading, not of the file/.test(text)) {
+    problems.push('the mechanism is gone — without it the duty reads as bookkeeping');
+  }
+  if (!/node \.claude\/hooks\/check-source-version\.cjs \./.test(text)) {
+    problems.push('the deterministic half is not invoked at the seam');
+  }
+  return problems;
+}
+
+describe('the seam still mandates, and every counter agrees', () => {
+  const SEAMS = ['templates/.claude/commands/start.md', 'templates/.claude/commands/feature.md'];
+
+  test('P16 - both WRITING dispatchers carry the obligation, and softening it fires', () => {
+    for (const rel of SEAMS) {
+      const source = read(rel);
+      assert.deepEqual(seamForceProblems(source), [], rel);
+
+      // The exact softening the backlog record forbids: a promise to re-read instead of a declared
+      // version. It is unverifiable by inspection, which is why it must not be able to ship.
+      const promise = source.replace(
+        'Every EDIT and every VERDICT MUST declare the sha256 of the source it was built on',
+        'Re-read the source immediately before editing it');
+      assert.notEqual(promise, source, rel + ': mutation fixture did not apply — the sentence moved');
+      assert.deepEqual(seamForceProblems(promise),
+        ['the version precondition is advisory, not imperative'],
+        rel + ': replacing the version with a promise must fire EXACTLY the precondition predicate');
+
+      // Keep the declaration, drop the refusal: the edit gets applied to the newer text anyway,
+      // which is the defect with an extra field written next to it.
+      const applied = source.replace('refusal WITHOUT mutation', 'a warning worth noting');
+      assert.ok(seamForceProblems(applied).some((p) => p.includes('no longer refuses')), rel);
+    }
+  });
+
+  test('P17 - it is a hooks component wired to NO event, and every counter agrees', () => {
+    const { COMPONENTS } = require(path.join(PKG, 'src', 'utils.js'));
+    assert.ok(COMPONENTS.hooks.items['check-source-version'],
+      'it must be registered, or init/doctor/verify will not know it');
+    const settings = read('templates/.claude/settings.json');
+    assert.ok(!settings.includes('check-source-version'),
+      'it must not be wired to an event: this package\'s hooks are non-blocking by contract');
+
+    const statusline = read('templates/.claude/hooks/statusline.cjs');
+    const hooks = statusline.match(/hooksExpected:\s*(\d+)/);
+    assert.ok(hooks, 'statusline must declare hooksExpected');
+    const onDisk = fs.readdirSync(path.join(TPL, 'hooks')).filter((f) => f.endsWith('.cjs'));
+    assert.equal(Number(hooks[1]), Object.keys(COMPONENTS.hooks.items).length,
+      'the status line would report a phantom missing hook: ' + hooks[1]);
+    assert.equal(onDisk.length, Object.keys(COMPONENTS.hooks.items).length,
+      'the shipped directory and the declared contract disagree: ' + onDisk.join(', '));
+
+    const rule = read('templates/.claude/rules/replicate-pipeline.md');
+    assert.match(rule, /check-source-version\.cjs/, 'the hook inventory must list it');
+    const inventory = rule.match(/\*\*Hooks \((\d+) files/);
+    assert.ok(inventory, 'the rule must state the hook count it is inventorying');
+    assert.equal(Number(inventory[1]), onDisk.length,
+      'the rule prose and the shipped directory disagree — the exact split this family exists for');
+  });
+
+  test('P18 - the mutation registry carries this feature\'s guards', () => {
+    const registry = JSON.parse(read('test/mutation-registry.json'));
+    const expected = {
+      'source-version-cannot-check-is-not-clean': 'templates/.claude/hooks/check-source-version.cjs',
+      'source-version-pin-must-still-match': 'templates/.claude/hooks/check-source-version.cjs',
+      'source-version-verdicts-age-like-edits': 'templates/.claude/hooks/check-source-version.cjs',
+      'source-version-seam-declares-not-promises': 'templates/.claude/commands/feature.md',
+    };
+    for (const [id, file] of Object.entries(expected)) {
+      const entry = registry.entries.find((e) => e.id === id);
+      assert.ok(entry, 'missing targeted mutation id ' + id);
+      assert.equal(entry.file, file, id + ' mutates the wrong surface');
+      assert.ok(entry.property && entry.property.length > 40,
+        id + ' needs a behavioral property, not a cosmetic label');
+      assert.ok(entry.mutation && entry.mutation.find && entry.mutation.replace,
+        id + ' needs a real source mutation');
+      assert.ok(Number.isInteger(entry.minFailing) && entry.minFailing >= 1,
+        id + ' must require at least one failing test');
+      assert.equal(read(entry.file).split(entry.mutation.find).length - 1, 1,
+        id + ': mutation anchor must occur exactly once');
+    }
+  });
+});

package/tests/unit/check-swarm-receipts.test.js

@@ -0,0 +1,231 @@
+'use strict';
+
+// The deterministic half of the swarm contract. The rule text is prose a model reads — layer 2,
+// violated in silence. This is layer 1, and only for whoever runs it.
+//
+// The load-bearing property is the THIRD exit code, for the same reason it is in check-ports and
+// check-growth-trace: a checker that answers "clean" when it could not look converts an unknown
+// into a reassurance. Here the unknown has a specific and very common cause — a worker whose PID is
+// still alive and whose trace has not appeared yet. That is not delivery and it is not failure; it
+// is "not yet", and reading it as either would be a lie in a different direction each time.
+//
+// These are BEHAVIOUR tests: the real utility, real files, real exit codes.
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const PKG = path.resolve(__dirname, '..', '..');
+const TPL = path.join(PKG, 'templates', '.claude');
+const CHECK = path.join(TPL, 'hooks', 'check-swarm-receipts.cjs');
+
+/**
+ * Build a throwaway run directory, write the traces described, and run the real checker.
+ *
+ * `traces` maps a unit id to a body, or to `null` for "this unit never wrote anything". The
+ * manifest's `launchMs` defaults to one second in the PAST, so a file written by this helper is
+ * legitimately post-launch — the freshness boundary is exercised explicitly by its own case.
+ */
+function check({ units, traces = {}, launchMs, manifest: override, raw }) {
+  const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'p-rep-receipts-')));
+  try {
+    const resolved = (units || []).map((u) => ({
+      ...u,
+      tracePath: u.tracePath === undefined ? path.join(dir, u.workUnitId + '.md') : u.tracePath,
+    }));
+    for (const unit of resolved) {
+      const body = traces[unit.workUnitId];
+      if (body === undefined || body === null) continue;
+      fs.writeFileSync(unit.tracePath, body);
+    }
+    const file = path.join(dir, 'receipts.json');
+    if (raw !== undefined) fs.writeFileSync(file, raw);
+    else {
+      const m = override || { runId: 'r1', launchMs: launchMs ?? Date.now() - 1000, units: resolved };
+      fs.writeFileSync(file, JSON.stringify(m));
+    }
+    const r = spawnSync(process.execPath, [CHECK, file], { encoding: 'utf8' });
+    return { code: r.status, out: (r.stdout || '') + (r.stderr || ''), dir };
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+}
+
+const DONE = 'Implemented the parser and its two tests.\nStatus: completed';
+const FAILED = 'Could not build: the fixture is missing.\nStatus: failed';
+
+describe('the swarm-receipt checker answers three questions, and never confuses two of them', () => {
+  test('P1 - every unit delivered a terminal completed receipt: exit 0', () => {
+    const r = check({
+      units: [{ workUnitId: 'api' }, { workUnitId: 'docs' }],
+      traces: { api: DONE, docs: DONE },
+    });
+    assert.equal(r.code, 0, 'two good receipts must pass: ' + r.out);
+    assert.match(r.out, /все 2 квитанций/, r.out);
+    assert.match(r.out, /ДОСТАВЛЕНА, а не что она верна/,
+      'the receipt proves delivery, never correctness — the limit must be stated');
+  });
+
+  test('P2 - a missing trace from a worker with no liveness claim: exit 1, unit named', () => {
+    const r = check({
+      units: [{ workUnitId: 'api' }, { workUnitId: 'docs' }],
+      traces: { api: DONE },
+    });
+    assert.equal(r.code, 1, 'a missing receipt must refuse aggregation: ' + r.out);
+    assert.match(r.out, /docs \[undelivered\/missing\]/, r.out);
+    assert.match(r.out, /ЗАПРЕЩЕНЫ/, 'the refusal must be stated, not implied: ' + r.out);
+  });
+
+  test('P3 - a live PID with no trace is exit 2, a dead PID with no trace is exit 1', () => {
+    // The asymmetry is the whole rule: liveness may only EXTEND waiting; it can never deliver.
+    const live = check({ units: [{ workUnitId: 'api', pid: process.pid }] });
+    assert.equal(live.code, 2, 'a live worker is "not yet", never "clean": ' + live.out);
+    assert.match(live.out, /positive-liveness-only/, live.out);
+
+    // A pid that is certainly gone: spawn a child, wait for it, then reuse its pid.
+    const gone = spawnSync(process.execPath, ['-e', 'process.exit(0)']);
+    const dead = check({ units: [{ workUnitId: 'api', pid: gone.pid }] });
+    assert.equal(dead.code, 1, 'a dead worker with no trace is a delivered failure: ' + dead.out);
+    assert.match(dead.out, /dead-worker/, dead.out);
+  });
+
+  test('P4 - empty, whitespace-only, and marker-only bodies are all undelivered', () => {
+    for (const [label, body, reason] of [
+      ['empty', '', 'empty'],
+      ['whitespace', '   \n\t\n', 'empty'],
+      ['marker with no work above it', 'Status: completed', 'empty-payload'],
+    ]) {
+      const r = check({ units: [{ workUnitId: 'api' }], traces: { api: body } });
+      assert.equal(r.code, 1, label + ' must not pass: ' + r.out);
+      assert.match(r.out, new RegExp(reason), label + ': ' + r.out);
+    }
+  });
+
+  test('P5 - a body without the terminal line is PARTIAL, not success', () => {
+    const r = check({
+      units: [{ workUnitId: 'api' }],
+      traces: { api: 'I am half way through writing this file.' },
+    });
+    assert.equal(r.code, 1, 'a partial write must not read as delivery: ' + r.out);
+    assert.match(r.out, /non-terminal/, r.out);
+  });
+
+  test('P6 - a delivered Status: failed blocks the aggregate exactly like a missing one', () => {
+    const r = check({ units: [{ workUnitId: 'api' }], traces: { api: FAILED } });
+    assert.equal(r.code, 1, 'a delivered failure is still a refusal: ' + r.out);
+    assert.match(r.out, /delivered-failure/, r.out);
+  });
+
+  test('P7 - a file that predates the launch is STALE, however good it looks', () => {
+    // The single case a naive checker gets wrong: last run's trace, still on disk, fully terminal.
+    const r = check({
+      units: [{ workUnitId: 'api' }],
+      traces: { api: DONE },
+      launchMs: Date.now() + 60_000,   // launch is in the future relative to the file
+    });
+    assert.equal(r.code, 1, 'a pre-launch file is not this run\'s evidence: ' + r.out);
+    assert.match(r.out, /stale/, r.out);
+  });
+
+  test('P8 - a symlink is not a regular file, even when its target is perfect', () => {
+    const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'p-rep-link-')));
+    try {
+      const real = path.join(dir, 'real.md');
+      const link = path.join(dir, 'api.md');
+      fs.writeFileSync(real, DONE);
+      fs.symlinkSync(real, link);
+      const file = path.join(dir, 'receipts.json');
+      fs.writeFileSync(file, JSON.stringify({
+        runId: 'r1', launchMs: Date.now() - 1000,
+        units: [{ workUnitId: 'api', tracePath: link }],
+      }));
+      const r = spawnSync(process.execPath, [CHECK, file], { encoding: 'utf8' });
+      assert.equal(r.status, 1, 'a symlinked trace must be refused: ' + r.stdout);
+      assert.match(r.stdout, /not-regular/, r.stdout);
+    } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+  });
+
+  test('P9 - a malformed ASSIGNMENT is exit 2, because the dispatch was wrong, not the delivery', () => {
+    const cases = [
+      [{ units: [{ workUnitId: 'api', tracePath: 'relative/path.md' }] }, /assignment/,
+        'a relative TRACE_PATH cannot be verified'],
+      [{ units: [{ workUnitId: 'api' }, { workUnitId: 'api' }] }, /WORK_UNIT_ID повторяется/,
+        'one id for two units would let one receipt clear both'],
+      [{ manifest: { launchMs: 1, units: [] } }, /ноль рабочих единиц/,
+        'an empty swarm has nothing to prove'],
+      [{ manifest: { units: [{ workUnitId: 'a', tracePath: '/tmp/a.md' }] } }, /launchMs/,
+        'without a launch instant, freshness is unknowable'],
+      [{ raw: 'not json at all' }, /не разбирается как JSON/, 'a broken manifest is an unknown'],
+      [{ raw: '[1,2,3]' }, /не является объектом/, 'an array is not a manifest'],
+    ];
+    for (const [input, pattern, why] of cases) {
+      const r = check(input);
+      assert.equal(r.code, 2, why + ' — got ' + r.code + ': ' + r.out);
+      assert.match(r.out, /проверка НЕ выполнена/, why + ': ' + r.out);
+      assert.match(r.out, pattern, why + ': ' + r.out);
+    }
+  });
+
+  test('P9b - two units sharing one TRACE_PATH is exit 2, not a lucky pass', () => {
+    // The second writer overwrites the first and BOTH report success — the silent lost update.
+    const r = check({
+      units: [{ workUnitId: 'a', tracePath: '/tmp/shared-trace.md' },
+        { workUnitId: 'b', tracePath: '/tmp/shared-trace.md' }],
+    });
+    assert.equal(r.code, 2, 'a shared path is a malformed dispatch: ' + r.out);
+    assert.match(r.out, /TRACE_PATH повторяется/, r.out);
+  });
+
+  test('P10 - a proven violation OUTRANKS an unresolved unit', () => {
+    // One unit is definitively undelivered while another is still live. Exit 1 is the actionable
+    // truth: aggregation is already forbidden, and saying "could not check" would be softer than
+    // the facts allow.
+    const r = check({
+      units: [{ workUnitId: 'dead' }, { workUnitId: 'busy', pid: process.pid }],
+      traces: {},
+    });
+    assert.equal(r.code, 1, 'a proven miss must not be downgraded to inconclusive: ' + r.out);
+    assert.match(r.out, /dead \[undelivered\/missing\]/, r.out);
+    assert.match(r.out, /busy \[waiting\/positive-liveness-only\]/,
+      'the unresolved unit must still be NAMED, not swallowed: ' + r.out);
+  });
+
+  test('P11 - no manifest argument, and a manifest that does not exist, are both exit 2', () => {
+    const bare = spawnSync(process.execPath, [CHECK], { encoding: 'utf8' });
+    assert.equal(bare.status, 2, 'no argument is not a clean bill: ' + bare.stdout);
+    assert.match(bare.stdout, /не передан путь/, bare.stdout);
+
+    const absent = spawnSync(process.execPath, [CHECK, '/nonexistent/receipts.json'],
+      { encoding: 'utf8' });
+    assert.equal(absent.status, 2, 'an unreadable manifest is an unknown: ' + absent.stdout);
+    assert.match(absent.stdout, /не читается манифест/, absent.stdout);
+  });
+
+  test('P12 - it is a hooks component wired to NO event, and the three counters agree', () => {
+    const { COMPONENTS } = require(path.join(PKG, 'src', 'utils.js'));
+    assert.ok(COMPONENTS.hooks.items['check-swarm-receipts'],
+      'it must be registered, or init/doctor/verify will not know it');
+    const settings = fs.readFileSync(path.join(TPL, 'settings.json'), 'utf-8');
+    assert.ok(!settings.includes('check-swarm-receipts'),
+      'it must not be wired to an event: this package\'s hooks are non-blocking by contract, so a '
+      + 'hook could only print — it could never refuse anything');
+    const statusline = fs.readFileSync(path.join(TPL, 'hooks', 'statusline.cjs'), 'utf-8');
+    const m = statusline.match(/hooksExpected:\s*(\d+)/);
+    assert.ok(m, 'statusline must declare hooksExpected');
+    assert.equal(Number(m[1]), Object.keys(COMPONENTS.hooks.items).length,
+      'the status line would report a phantom missing hook: ' + m[1]);
+    assert.equal(Number(m[1]), fs.readdirSync(path.join(TPL, 'hooks')).filter((f) => f.endsWith('.cjs')).length,
+      'the shipped hook FILES must match the declared count — the counter drifted twice before');
+  });
+
+  test('P13 - MUTATION: turning the third exit code into a pass is caught', () => {
+    // The registered mutation in test/mutation-registry.json flips cannotCheck's exit(2) to exit(0).
+    // Assert here that at least one real input DEPENDS on that distinction, so the mutant has a
+    // killer: without this, the registry entry would name a property nothing proves.
+    const source = fs.readFileSync(CHECK, 'utf-8');
+    assert.match(source, /process\.exit\(2\);/, 'cannotCheck must exit 2');
+    const live = check({ units: [{ workUnitId: 'api', pid: process.pid }] });
+    assert.equal(live.code, 2, 'the live-worker case is the killer input for that mutant');
+  });
+});