"""Protocol 023 revision 2: the blind integrity check of one run's export, on the machine that ran the model and on the
Mac; the paired rule; the early stop and the stop with no reading; and the replacement rule with the queue's one record
of it.

  python3 check_instance_023.py server CONTRACT.json K EXPORT OUT.json
        run by run_queue_023.sh right after each attempt that exits 0 with its export (from the run folder's copy of the
        frozen package): the checks below on EXPORT, runs/sK-aN.json.gz; exit 0 passed, 3 refused (OUT,
        runs/sK-aN-server-check.json, written once); any other exit means no check was made (no record)
  python3 check_instance_023.py check CONTRACT.json K-aN FETCHED_DIR OUT.json [--not-frozen]
        on the Mac, the local check of FETCHED_DIR/exports/sK-aN.json.gz as fetch_023.sh saved it (OUT written once)
  python3 check_instance_023.py summary CONTRACT.json FETCHED_DIR CHECKS_DIR OUT.json [--not-frozen]
        every seed's state by the paired rule, from the queue's receipts (FETCHED_DIR/receipts: each attempt's receipts,
        the server check records and the comparison records), and the local check records (CHECKS_DIR/check-sK-aN.json);
        the instances to analyse; S15

Spec: docs/specs/2026-11-08-protocol-023-r2-paired.md ("Integrity checks per instance", "Attempts", "The paired rule",
"The early stop", "The stop with no reading", "The replacement rule", S15). It computes no plaid quantity: it reads
only the 45@30 and 135@30 singles (LGN and layer 4 groups in window G), the LGN lead-in and the export's own records.

Before it reads an export it stops, writing no record: on the Mac unless the running checker and the code it imports
are the frozen manifest's (manifest.json next to CONTRACT.json; --not-frozen only for synthetic tests), and the export
is a regular local file (not an iCloud placeholder) whose SHA-256 is the host's, as fetch_023.sh recorded it in
FETCHED_DIR/data-sha256.txt; on the server unless the running code is the code the contract was made from. A read
failure is never a refusal: only a check of the export's content writes one. An export that cannot be parsed is read
twice, and refused as 'unreadable' only when its bytes read cleanly and still have the checked SHA-256.
Each check is computed twice, each time from its own read of the export, the contract and the lead-in reference, and
its record is written only when both give the same verdict, refusals and kinds; otherwise it stops with no record, as a
check that could not be made (revision 2). Every record is written whole (write_once): a temporary file in its folder,
flushed to disk, linked to its name (which fails if the name exists), the folder flushed, the temporary file removed;
a leftover temporary file is removed when the checker runs again.

Refusals, each of which makes the run's instance invalid, each with its kind (unchanged from protocol 023):
  1. the export is not the declared run ('run'), or the host's bytes cannot be parsed ('unreadable'): its run name must
     be one of m23-sK-intact-a1 to -a9 for the instance's pynn_seed K, its argv the declared command, its resolved
     weights and seeds 017's intact-A entry with pynn_seed K, its NEST kernel rng_seed 42 with 4 threads; the steps
     must be the instance's declared sequence file, with protocol 022's timing, one presentation and one sequence
     segment per sheet, the LGN cache disabled, and well-formed neuron tables and spike trains (protocol 022's checks);
  2. the LGN band ('lgn_band'): the X_ON and X_OFF mean counts per cell in G at 30 % (the 45 and 135 deg singles)
     within 0.90 to 1.10 of protocol 017's 8.06 and 5.73 (plaid_stats.validation, unchanged);
  3. the LGN lead-in identity ('leadin_identity'): every X_ON and X_OFF cell's spike times in the 504 ms lead-in equal
     the pilot intact export's (leadin-reference-023.json), with the same cells.
Reported only, never a refusal: the layer 4 band (the 30 % own singles of the 45 and 135 deg groups against 017's
2.97 and 2.18 counts, band 0.80 to 1.25), the group sizes and the NEST kernel's other records.

Attempts (attempts()): each seed's attempts a1 to a9, each ending, read from its receipts, as completed (exit 0, its
export in data-sha256.txt, the server files unchanged, its server check made), killed for memory (exit 99), a counted
failure (any other non-zero exit, a timeout 124 or a kill 137, exit 0 without an export, a change of the server
files, or an interruption: no exit receipt, or one that is empty or not a number), or stopped at the disk floor (exit
98, not counted).
The paired rule (pair_state()): after each completed run, its server check, then the frozen comparison tool against
each earlier completed run in attempt order until one agrees; the first agreeing pair ends the seed; at most four
completed runs ('no agreeing pair'); two counted failures ('failed twice'); a memory kill ('killed for memory'); a seed
that would need a tenth attempt ('attempts used up'). For an agreeing pair: both server checks passed, the seed is
'agreed aI aJ' and valid once the local check passes the export of aI, the earlier run; both refused with equal kinds
lists (same_checks(); the refusal texts are never compared), the early stop (early_stop()): runs/early-stop.txt, and
NOT INTERPRETABLE once the local check refuses aI's export too (a local pass stops the summary); otherwise the stop with
no reading (checks_disagree(): runs/checks-disagree.txt; the summary stops).
The replacement rule (replacement()): a slot is invalid if its seed ended 'no agreeing pair', 'failed twice', 'killed
for memory' or 'attempts used up', or the local check refused the export of its agreeing pair that the server checks
passed. The one reserve, 14, takes the first invalid slot; at most one replacement. The queue's one record,
runs/replacements.txt, says in time order which reserve filled which slot and why ("reserve R for slot S: CAUSE", or
"no reserve left for slot S: CAUSE"); the summary reads it, checks every line against the rule, the receipts and the
check records, and stops on any disagreement. As soon as more slots need a reserve than are unused, the protocol is NOT
INTERPRETABLE (fewer than six valid instances). The analysed instances are the valid slots and the valid reserve that
filled an invalid slot, in pynn_seed order, each by the export of the earlier run of its agreeing pair.
S15 (s15()): the paired-run record and the fault share, reported only.
Simulation only.
"""
import glob, hashlib, json, os, re, stat, sys, time
sys.dont_write_bytecode = True                  # before any project or frozen import: no __pycache__ beside them
from pathlib import Path

HERE = Path(__file__).resolve().parent
sys.path.insert(0, str(HERE))
import numpy as np                              # noqa: E402
import analyze_plaids as ap                     # noqa: E402  (protocol 022's driver, byte-identical; imports 017's code)
import plaid_stats as ps                        # noqa: E402
import confirm_023 as cf                        # noqa: E402

a = ap.a                                        # protocol 017's analyze_decisions (frozen, unchanged)
RUN_NAME = re.compile(r'^m23-s(\d+)-intact-a([1-9])$')  # the declared names' form; make_contract_023.py checks them
LGN = ('X_ON', 'X_OFF')
LEAD_MS = ap.LEAD_FRAMES * ap.FRAME_MS          # 504 ms
SINGLES_30 = ('45@30', '135@30')
KINDS = ('run', 'unreadable', 'lgn_band', 'leadin_identity')
SF_DATALESS = getattr(stat, 'SF_DATALESS', 0x40000000)   # macOS: an iCloud placeholder whose data is not local
FROZEN_FILES = ('contract.json', 'controller/check_instance_023.py', 'controller/confirm_023.py',
                'controller/plaid_stats.py', 'controller/analyze_plaids.py', 'controller/frozen017.py',
                'leadin-reference-023.json')
RUNNING = {'controller/check_instance_023.py': Path(__file__), 'controller/confirm_023.py': Path(cf.__file__),
           'controller/plaid_stats.py': Path(ps.__file__), 'controller/analyze_plaids.py': Path(ap.__file__),
           'controller/frozen017.py': Path(ap.frozen017.__file__)}
COMPARE_TOOL = 'controller/compare_runs_023.py'
SERVER_PASSED, SERVER_REFUSED = 0, 3            # the server check's exit codes; any other: no check was made
COMPARE_AGREE, COMPARE_DISAGREE, COMPARE_CHECKS_DIFFER = 0, 3, 4    # the comparison tool's exit codes
PEAK_RSS = re.compile(r'Maximum resident set size \(kbytes\): (\d+)')
# the paired rule (spec, "Attempts" and "The paired rule")
COMPLETED_CAP = 4                               # at most four completed runs per seed
COUNTED_FAILURES = 2                            # two counted failures make a seed invalid ('failed twice')
MAX_ATTEMPTS = 9                                # a1 to a9; a seed that would need a tenth is 'attempts used up'
EXIT_MEMORY, EXIT_DISK_FLOOR, EXIT_TIMEOUTS = 99, 98, (124, 137)     # memcap's and GNU timeout's exit codes
SETTLED = ('no agreeing pair', 'failed twice', 'killed for memory', 'attempts used up')   # with 'agreed aI aJ'
AGREED = re.compile(r'^agreed a([1-9]) a([1-9])$')
EXPORT_NAME = re.compile(r'^s(\d+)-a([1-9])\.json\.gz$')
COMPARE_NAME = re.compile(r'^s(\d+)-a([1-9])-a([1-9])-compare\.json$')
LOCAL_NAME = re.compile(r'^check-s(\d+)-a([1-9])\.json$')
# the replacement record's causes ("The replacement rule"): for the slot itself, 'the run failed twice', 'the run killed
# for memory', 'no agreeing pair in four runs', 'the attempts used up' or the local refusal; for the reserve, the same
# after 'reserve 14 ' (without 'the run')
CAUSE_TEXT = {'failed twice': 'failed twice', 'killed for memory': 'killed for memory',
              'no agreeing pair': 'no agreeing pair in four runs', 'attempts used up': 'the attempts used up'}
STATE_OF_CAUSE = {v: k for k, v in CAUSE_TEXT.items()}
REPLACEMENT_LINE = re.compile(r'^(\S+) (?:reserve (\d+)|no reserve left) for slot (\d+): (.+)$')
RUN_CAUSE = re.compile(r'^(?:the run (failed twice|killed for memory)|(no agreeing pair in four runs|the attempts used up)'
                       r'|reserve (\d+) (failed twice|killed for memory|no agreeing pair in four runs|the attempts used '
                       r'up))$')
REFUSED_CAUSE = re.compile(r'^(?:reserve (\d+) )?refused by the blind checker \(check record SHA-256 ([0-9a-f]{64})\)$')
EARLY_STOP_LINE = re.compile(r'^(\S+) early stop: pynn_seed (\d+), runs a([1-9]) and a([1-9]) agree and the server check '
                             r'refused both \(record SHA-256 ([0-9a-f]{64}) and ([0-9a-f]{64})\)$')
CHECKS_DISAGREE_LINE = re.compile(r'^(\S+) pynn_seed (\d+): runs a([1-9]) and a([1-9]) agree, but the server checks of '
                                  r'them differ \(record SHA-256 ([0-9a-f]{64}) and ([0-9a-f]{64})\)$')
UTC = re.compile(r'\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z')


class Refusal(Exception):
    """The export is not the declared one, or fails a declared band: the instance is invalid."""

    def __init__(self, message, kind='run'):
        super().__init__(message)
        self.kind = kind


def refuse(message, kind='run'):
    raise Refusal(message, kind)


def stop(message):
    """Not an integrity refusal: nothing is written, and the check can be made again correctly."""
    raise SystemExit(f'refused: {message}')


def sha256(path):
    h = hashlib.sha256()
    with open(path, 'rb') as fh:
        for block in iter(lambda: fh.read(1 << 20), b''):
            h.update(block)
    return h.hexdigest()


def dataless(path):
    """True for an iCloud placeholder (macOS SF_DATALESS): reading it would start a download and can stall."""
    try:
        return bool(os.lstat(path).st_flags & SF_DATALESS)
    except (AttributeError, OSError):
        return False


# ---------------------------------------------------------------- the frozen code and the fetched files

def check_frozen(base, contract, allow_unfrozen=False):
    """In the frozen package (manifest.json next to the contract): the contract, the lead-in reference, every declared
    sequence file and this checker's code are the manifest's, the running code is that code, the manifest records
    that every test passed at the freeze, and protocol 017's package and pins match. Returns the record."""
    manifest = base / 'manifest.json'
    if not manifest.exists():
        if not allow_unfrozen:
            stop('no manifest.json next to the contract (use --not-frozen only for synthetic tests)')
        return {'manifest': False}
    try:
        m = json.loads(manifest.read_text())
        listed = {f['path']: f['sha256'] for f in m['files']}
        tests = m.get('tests_at_freeze') or {}
    except (OSError, ValueError, KeyError, TypeError) as exc:
        stop(f'manifest.json cannot be read ({type(exc).__name__}: {exc})')
    if tests.get('run') is not True or tests.get('all_passed') is not True:
        stop('the frozen manifest does not record that every test passed at the freeze (a --skip-tests freeze is for '
             'tests only)')
    sequences = sorted(rel for rel in listed if rel.startswith('sequences/'))
    for rel in FROZEN_FILES + tuple(sequences):
        if rel not in listed or not (base / rel).is_file() or sha256(base / rel) != listed[rel]:
            stop(f'{rel} differs from the frozen manifest')
    for rel, path in RUNNING.items():
        if sha256(path) != listed[rel]:
            stop(f'the running {rel} is not the frozen one')
    _, _, p017 = ap.check_017(contract)
    return {'manifest': True, 'manifest_sha256': sha256(manifest), 'files_checked': list(FROZEN_FILES) + sequences,
            'protocol_017': p017}


def host_hashes(fetched):
    """{export file name: SHA-256} from FETCHED_DIR/data-sha256.txt, the host's hashes of every completed attempt's
    export (sK-aN.json.gz), as fetch_023.sh recorded them."""
    path = Path(fetched) / 'data-sha256.txt'
    if not path.is_file() or dataless(path):
        stop(f'{path} is missing or an iCloud placeholder (fetch_023.sh writes it)')
    out = {}
    for line in path.read_text().splitlines():
        if not line.strip():
            continue
        parts = line.split()
        if len(parts) != 3 or not re.fullmatch(r'[0-9a-f]{64}', parts[0]) or not EXPORT_NAME.match(parts[2]):
            stop(f'{path} holds a line that is not "SHA-256  bytes  sK-aN.json.gz": {line!r}')
        if parts[2] in out:
            stop(f'{path} gives {parts[2]} twice')
        out[parts[2]] = parts[0]
    return out


def local_export(fetched, k, n, hosts):
    """The fetched export of attempt aN of pynn_seed K: a regular local file, not a placeholder, whose SHA-256 is the
    host's."""
    name = f's{k}-a{n}.json.gz'
    path = Path(fetched) / 'exports' / name
    try:
        st = os.lstat(path)
    except OSError as exc:
        stop(f'no fetched export at {path} ({type(exc).__name__}); fetch it with fetch_023.sh')
    if not stat.S_ISREG(st.st_mode):
        stop(f'{path} is not a regular file')
    if dataless(path):
        stop(f'{path} is an iCloud placeholder; download it first')
    if name not in hosts:
        stop(f'{name} has no host SHA-256 in data-sha256.txt')
    try:
        digest = sha256(path)
    except OSError as exc:
        stop(f'{path} cannot be read on this Mac ({type(exc).__name__}: {exc})')
    if digest != hosts[name]:
        stop(f"{path} is not the host's file (SHA-256 {digest}, the host's {hosts[name]}); fetch it again")
    return path, digest


# ---------------------------------------------------------------- the declared run

def declaration(contract, k):
    """The contract's entry for instance K, or a refusal."""
    entry = (contract.get('instances') or {}).get(str(k))
    if not isinstance(entry, dict) or entry.get('pynn_seed') != k:
        refuse(f'pynn_seed {k!r} is not a declared instance of the contract')
    return entry


def check_identity(ex, decl, contract):
    """The run is the declared one: run name, command line, resolved weights and seeds, NEST kernel. Returns the run
    name."""
    k = decl['pynn_seed']
    argv = ex.get('argv') if isinstance(ex.get('argv'), list) else []
    run_name = argv[-1] if argv else None
    if not isinstance(run_name, str) or run_name not in decl['run_names']:      # the contract's names are the authority
        refuse(f'run name {run_name!r} is not one of the declared {decl["run_names"]}')
    if argv != decl['argv'][run_name]:
        refuse(f'command line {argv} is not the declared {decl["argv"][run_name]}')
    if ex.get('resolved') != decl['resolved']:
        refuse(f"resolved weights or seeds {ex.get('resolved')} differ from the declared entry for pynn_seed {k}")
    nest = ex.get('nest') if isinstance(ex.get('nest'), dict) else {}
    want = contract['engine']['nest_kernel']
    got = {key: nest.get(key) for key in want}
    if got != want:
        refuse(f'the NEST kernel recorded {got}, not the declared {want}')
    return run_name


def check_structure(name, ex, chunks, shown):
    """Protocol 022's checks of the step period and layout (analyze_plaids.check_run_plaids without its run-identity
    part, which check_identity replaces): no separate warm-up, the LGN cache disabled, steps of 30 + 21 frames of 7 ms,
    one presentation with one sequence segment per sheet and well-formed tables and trains, a 72-frame lead-in, 0.8 cpd
    and 2 Hz, the declared steps, and the presentation's duration. Returns (period, layout)."""
    if any(s['stimulus']['name'] == 'InternalStimulus' for s in ex['segments']):
        refuse(f'{name}: a separate warm-up (InternalStimulus) was run; the declared design has none')
    cache = ex.get('lgn_cache')
    if not isinstance(cache, dict) or cache.get('enabled') is not False:
        refuse(f'{name}: the LGN cache is not recorded as disabled ({cache!r})')
    if [ex.get('step_frames'), ex.get('gap_frames')] != [ap.STEP_FRAMES, ap.GAP_FRAMES]:
        refuse(f"{name}: step and gap frames {ex.get('step_frames')}, {ex.get('gap_frames')} are not {ap.STEP_FRAMES}, "
               f'{ap.GAP_FRAMES}')
    if len(chunks) != 1:
        refuse(f'{name}: {len(chunks)} presentations; the declared design has one')
    chunk = chunks[0]
    missing = [sh for sh in ap.SHEETS if sh not in chunk]
    if missing:
        refuse(f'{name}: no sequence segment for {missing}')
    per_sheet = {sh: sum(1 for s in ex['segments'] if s.get('sheet') == sh and s['stimulus']['name'] == a.SEQUENCE_STIMULUS)
                 for sh in ap.SHEETS}
    if any(n != 1 for n in per_sheet.values()):
        refuse(f'{name}: sequence segments per sheet {per_sheet}; the declared export has one per sheet')
    try:
        ap.check_tables(name, ex)
        ap.check_segments(name, ex, chunk)
    except ap.Refusal as exc:
        refuse(str(exc))
    stims = [chunk[sh]['stimulus'] for sh in ap.SHEETS]
    if any(st != stims[0] for st in stims):
        refuse(f"{name}: the sheets' stimulus records differ")
    st = stims[0]
    if [st.get('step_frames'), st.get('gap_frames'), st.get('frame_duration')] != [ap.STEP_FRAMES, ap.GAP_FRAMES, ap.FRAME_MS]:
        refuse(f'{name}: step timing differs from the declared {ap.STEP_FRAMES}, {ap.GAP_FRAMES} and {ap.FRAME_MS} ms frames')
    if st.get('lead_frames') != ap.LEAD_FRAMES:
        refuse(f"{name}: lead-in of {st.get('lead_frames')} frames, not the declared {ap.LEAD_FRAMES}")
    if st.get('first_step', 0) != 0:
        refuse(f"{name}: the presentation starts at step {st.get('first_step')}, not 0")
    if [st.get('spatial_frequency'), st.get('temporal_frequency')] != [ap.SPATIAL_FREQUENCY_CPD, ap.TEMPORAL_FREQUENCY_HZ]:
        refuse(f"{name}: gratings of {st.get('spatial_frequency')} cpd and {st.get('temporal_frequency')} Hz, not the "
               f'declared {ap.SPATIAL_FREQUENCY_CPD} cpd and {ap.TEMPORAL_FREQUENCY_HZ} Hz')
    try:
        presented = json.loads(st['sequence']) if isinstance(st.get('sequence'), str) else None
    except ValueError:
        presented = None
    if presented != shown:
        refuse(f'{name}: presented sequence differs from the declared sequence')
    expected = a.chunk_bounds(len(shown), 0, ap.LEAD_FRAMES)
    found = [(int(st.get('first_step', 0)), len(presented), st.get('lead_frames', 0.0))]
    if found != [(f, last - f, float(lead)) for f, last, lead in expected]:
        refuse(f'{name}: presentation {found} is not the declared {expected}')
    period = (ap.STEP_FRAMES + ap.GAP_FRAMES) * ap.FRAME_MS
    layout = [(f, last - f, lead * ap.FRAME_MS) for f, last, lead in expected]
    duration = layout[0][2] + len(shown) * period
    if st.get('duration_ms') != duration:
        refuse(f"{name}: presentation of {st.get('duration_ms')} ms, not the declared {duration}")
    for sh in ap.SHEETS:
        t = chunk[sh].get('t_stop_ms')
        if not (isinstance(t, (int, float)) and not isinstance(t, bool) and abs(t - duration) < 1.0):
            refuse(f"{name}: the {sh} sequence segment ends at {t!r} ms, not at the presentation's {duration} ms")
    return period, layout


def read_sequence(base, decl):
    """The instance's declared steps and conditions: its sequence file must match the contract's SHA-256 and pass
    protocol 022's sequence check (analyze_plaids.check_sequence)."""
    seq_file = base / decl['sequence']['file']
    if not seq_file.is_file():
        refuse(f'the sequence file {decl["sequence"]["file"]} is not in the package')
    if sha256(seq_file) != decl['sequence']['sha256']:
        refuse(f'{seq_file.name} does not match its SHA-256 in the contract')
    try:
        return ap.check_sequence(json.loads(seq_file.read_text()))
    except ValueError as exc:
        refuse(f'{seq_file.name} cannot be read ({type(exc).__name__}: {exc})')
    except ap.Refusal as exc:
        refuse(f'{seq_file.name}: {exc}')


# ---------------------------------------------------------------- the bands and the lead-in

def single_means(ex, chunks, layout, period, cond):
    """plaid_stats.Means of the four summaries the bands read (the 45 and 135 deg layer 4 excitatory groups and all
    X_ON and X_OFF cells, in window G), filled only for the 45@30 and 135@30 singles; every other condition is nan.
    017's counting returns every step's counts; only the rows of those two singles' steps are read."""
    names = ['G|L4E|45', 'G|L4E|135', 'G|X_ON|all', 'G|X_OFF|all']
    M = np.full((ps.N_CONDITIONS, len(names)), np.nan)
    rows = {lab: np.where(cond == ps.INDEX[lab])[0] + 1 for lab in SINGLES_30}     # + 1: the warm-up is step 0
    win = list(ps.WINDOWS_MS['G'])
    prefs = np.asarray(ex['neurons']['V1_Exc_L4']['orientation_pref'], float)
    l4 = [('V1_Exc_L4', i) for i in ex['neurons']['V1_Exc_L4']['ids']]
    c4 = a.counts_searchsorted(chunks, layout, l4, period, win)
    cells = {}
    for col, g in enumerate((45, 135)):
        mask = ps.group_mask(prefs, g)
        cells[str(g)] = int(mask.sum())
        for lab, r in rows.items():
            M[ps.INDEX[lab], col] = float(c4[r][:, mask].mean(axis=1).mean())
    for col, sh in enumerate(LGN, 2):
        c = a.counts_searchsorted(chunks, layout, [(sh, i) for i in ex['neurons'][sh]['ids']], period, win)
        for lab, r in rows.items():
            M[ps.INDEX[lab], col] = float(c[r].mean(axis=1).mean())
    cells['90'] = int(ps.group_mask(prefs, 90).sum())
    return ps.Means(M, np.zeros((ps.N_CONDITIONS, 0), complex), names, []), cells


def bands(m):
    """plaid_stats.validation (022's 30 % check, unchanged), split: its LGN checks are refusals here, its layer 4
    checks are reported only."""
    v = ps.validation(m, 'intact', lgn=True)
    lgn = [c for c in v['checks'] if c['what'].startswith('X_')]
    l4 = [c for c in v['checks'] if c['what'].startswith('L4E')]
    return {'lgn': {'checks': lgn, 'passes': all(c['passes'] for c in lgn), 'band': list(ps.VALIDATION['lgn_ratio']),
                    'role': 'refusal'},
            'layer4': {'checks': l4, 'inside_band': all(c['passes'] for c in l4), 'band': list(ps.VALIDATION['ratio']),
                       'role': 'reported only, never a refusal or a replacement'}}


def leadin_trains(chunk, lead_ms=LEAD_MS):
    """{sheet: {id: [spike times before lead_ms]}}, as make_leadin_reference_023.py extracts them."""
    out = {}
    for sh in LGN:
        spikes = chunk[sh]['spikes']
        out[sh] = {i: [float(t) for t in spikes[i] if float(t) < lead_ms] for i in sorted(spikes, key=int)}
    return out


def leadin_identity(trains, reference):
    """Per LGN sheet: the cells compared, how many lead-in trains are identical, and the first ten that differ."""
    out = {}
    for sh in LGN:
        mine, ref = trains[sh], reference['trains'][sh]
        same_cells = set(mine) == set(ref)
        common = sorted(set(mine) & set(ref), key=int)
        differ = [i for i in common if mine[i] != ref[i]]
        out[sh] = {'cells': len(mine), 'reference_cells': len(ref), 'same_cells': same_cells,
                   'identical': len(common) - len(differ), 'differing': len(differ), 'first_differing': differ[:10],
                   'passes': same_cells and not differ}
    out['passes'] = all(out[sh]['passes'] for sh in LGN)
    return out


# ---------------------------------------------------------------- one export

def check_loaded(contract, base, k, ex, chunks, reference, rec):
    """Every check of a loaded export (ex, chunks from 017's load_run) into the record rec; raises Refusal for the
    first identity or structure fault, and records band and lead-in failures as refusals with their kinds."""
    decl = declaration(contract, k)
    rec['role'] = decl['role']
    shown, cond = read_sequence(base, decl)
    try:
        rec['run_name'] = check_identity(ex, decl, contract)
        period, layout = check_structure(f'instance {k}', ex, chunks, shown)
    except (OverflowError, RecursionError, ValueError, TypeError, KeyError, AttributeError) as exc:
        refuse(f'the export is malformed ({type(exc).__name__}: {exc})')
    rec['checks']['run'] = {'passes': True, 'run_name': rec['run_name'], 'argv': ex['argv'], 'resolved': ex['resolved'],
                            'nest': ex.get('nest'), 'presentations': layout, 'step_period_ms': period}
    m, cells = single_means(ex, chunks, layout, period, cond)
    b = bands(m)
    rec['checks']['lgn_band'] = b['lgn']
    rec['report']['layer4_band'] = b['layer4']
    rec['report']['group_cells_L4E'] = cells
    ident = leadin_identity(leadin_trains(chunks[0]), reference)
    rec['checks']['leadin_identity'] = ident
    rec['report']['run_seconds'] = ex.get('run_seconds')
    rec['report']['nest_kernel'] = ex.get('nest')
    if not b['lgn']['passes']:
        rec['refusals'].append('the LGN band: ' + '; '.join(
            f"{c['what']} is {c['value']:.3f} counts per cell, {c['ratio']:.3f} of {c['reference']:.2f}, outside "
            f"{c['band'][0]:.2f} to {c['band'][1]:.2f}" for c in b['lgn']['checks'] if not c['passes']))
        rec['kinds'].append('lgn_band')
    if not ident['passes']:
        rec['refusals'].append('the LGN lead-in identity: ' + '; '.join(
            f"{sh} {ident[sh]['identical']} of {ident[sh]['reference_cells']} trains identical"
            f"{'' if ident[sh]['same_cells'] else ', other cells'}" for sh in LGN if not ident[sh]['passes']))
        rec['kinds'].append('leadin_identity')


def new_record(k, export):
    return {'scope': 'protocol 023: blind integrity check of one instance export; it computes no plaid quantity; '
                     'simulation only',
            'pynn_seed': k, 'export': Path(export).name, 'refusals': [], 'kinds': [], 'checks': {}, 'report': {}}


def check_export(contract, base, k, export, reference, digest=None):
    """The blind check of instance K's export: a record with 'valid', the refusals, their kinds and the reported
    values. digest: the SHA-256 the caller verified (local_export, or the server check's own); the export must still
    have it after the check, or the check stops (the file changed: not a property of the run). A read failure here is
    never a refusal: an export 017's loader cannot read is read a second time, and refused as 'unreadable' only if it
    fails again while its bytes read without an error and still have the checked SHA-256, so that the fault lies in the
    export's content (the host's bytes), not in reading them here."""
    rec = new_record(k, export)
    rec['export_sha256'] = digest if digest is not None else sha256(export)
    try:
        declaration(contract, k)
        try:
            ex, chunks = ap.load(f'instance {k}', export)
        except ap.Refusal:
            same_bytes(export, rec['export_sha256'])
            try:                                # a second read: a fault of the content fails the same way twice
                ex, chunks = ap.load(f'instance {k}', export)
            except ap.Refusal as exc:
                same_bytes(export, rec['export_sha256'])
                refuse(str(exc), 'unreadable')
        check_loaded(contract, base, k, ex, chunks, reference, rec)
        del ex, chunks
    except Refusal as exc:
        rec['refusals'].append(str(exc))
        rec['kinds'].append(exc.kind)
    same_bytes(export, rec['export_sha256'])
    rec['valid'] = not rec['refusals']
    return rec


def same_bytes(export, digest):
    """Stop, writing nothing, unless the export's bytes read without an error and have the checked SHA-256: a read
    fault here, or a file that changed while it was checked, is never an integrity refusal."""
    try:
        now = sha256(export)
    except OSError as exc:
        stop(f'{export} cannot be read here ({type(exc).__name__}: {exc}); nothing is written')
    if now != digest:
        stop(f'{export} changed while it was checked; nothing is written')


# ---------------------------------------------------------------- each check twice (revision 2)

def checked_twice(contract_path, k, export, digest):
    """The blind check of an export, computed twice, one computation after the other, each from its own read of the
    export, the contract and the lead-in reference (spec, "Each check twice, and each record whole"). Returns the first
    record when both give the same verdict, refusals and kinds; otherwise it stops with no record, as a check that
    could not be made (the queue stops with exit 2 and resume makes the check again)."""
    recs = []
    for _ in range(2):
        contract, base = load_contract(contract_path)
        reference = load_reference(contract, base)
        recs.append(check_export(contract, base, k, export, reference, digest))
    one, two = ([r['valid'], r['refusals'], r['kinds']] for r in recs)
    if one != two:
        stop(f'the two computations of the check of {Path(export).name} differ (valid {one[0]}, kinds {one[2]}; then '
             f'valid {two[0]}, kinds {two[2]}); nothing is written, and the check is made again')
    rec = recs[0]
    rec['computed'] = ('twice, each from its own read of the export, the contract and the lead-in reference, with the '
                       'same verdict, refusals and kinds')
    return rec


# ---------------------------------------------------------------- the server check

def made_from(contract, rel):
    """The SHA-256 the contract records for a file it was made from, by its path in the package (rel)."""
    hits = [h for key, h in (contract.get('made_from') or {}).items() if key == rel or key.endswith('/' + rel)]
    if len(hits) != 1:
        stop(f'the contract records no single SHA-256 for {rel}')
    return hits[0]


def check_running(contract):
    """On the server: the running checker and the code it imports are the files the contract was made from (the
    frozen ones), and protocol 017's package and pins match (analyze_plaids.check_017). Returns the record."""
    for rel, path in RUNNING.items():
        if sha256(path) != made_from(contract, rel):
            stop(f'the running {rel} is not the one the contract was made from')
    _, _, p017 = ap.check_017(contract)
    return {'checked_against': "the contract's made_from", 'files': sorted(RUNNING), 'protocol_017': p017}


def server_check(contract_path, k, export, out):
    """The server check (run_queue_023.sh, right after each attempt that exits 0 with its export): the blind checker's
    checks of the new export, computed twice, by the run folder's copy of the frozen package. EXPORT is
    runs/sK-aN.json.gz. Writes OUT once and returns SERVER_PASSED or SERVER_REFUSED; it stops (exit 1, no record) when
    the check cannot be made. If OUT already is this checker's record of this export for this contract (the queue was
    stopped after the check), it returns that record's verdict and checks nothing again."""
    if not re.fullmatch(r'\d+', k):
        stop(f'{k!r} is not a pynn_seed')
    k = int(k)
    contract, base = load_contract(contract_path)
    try:
        declaration(contract, k)
    except Refusal as exc:
        stop(str(exc))
    running = check_running(contract)
    path = Path(export)
    m = EXPORT_NAME.match(path.name)
    if not m or int(m.group(1)) != k:
        stop(f'{path} is not the export of an attempt of pynn_seed {k} (s{k}-aN.json.gz, N from 1 to {MAX_ATTEMPTS})')
    n = int(m.group(2))
    try:
        st = os.lstat(path)
    except OSError as exc:
        stop(f'no export at {path} ({type(exc).__name__})')
    if not stat.S_ISREG(st.st_mode):
        stop(f'{path} is not a regular file')
    try:
        digest = sha256(path)
    except OSError as exc:
        stop(f'{path} cannot be read ({type(exc).__name__}: {exc})')
    contract_sha, checker_sha = sha256(contract_path), sha256(__file__)
    leftovers(out)
    if Path(out).exists():
        rec = read_record(Path(out), k, n, contract_sha, checker_sha, {path.name: digest}, where='server')
        print(f"pynn_seed {k}, a{n}: already checked on the server: {'PASSED' if rec['valid'] else 'REFUSED'}")
        return SERVER_PASSED if rec['valid'] else SERVER_REFUSED
    rec = checked_twice(contract_path, k, path, digest)
    rec.update(where='server', attempt=n, checker_sha256=checker_sha, contract_sha256=contract_sha,
               running_code=running, utc=time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime()))
    write_once(out, rec)
    print(f"pynn_seed {k}, a{n}: server check {'PASSED' if rec['valid'] else 'REFUSED'}" +
          ''.join(f'\n  refused ({kd}): {r}' for r, kd in zip(rec['refusals'], rec['kinds'])))
    return SERVER_PASSED if rec['valid'] else SERVER_REFUSED


# ---------------------------------------------------------------- attempts and the paired rule

def same_checks(rec_i, rec_j):
    """The two server checks of an agreeing pair are the same: both passed, or both refused with equal kinds lists
    (spec, "The same refusal kinds"). The refusal texts are never compared: a 'run' refusal quotes the run name, so two
    agreeing runs refused for one reason have different texts. compare_runs_023.same_checks is the same rule, and the
    summary checks every comparison record's server_checks against this one."""
    if rec_i['valid'] or rec_j['valid']:
        return bool(rec_i['valid'] and rec_j['valid'])
    return list(rec_i['kinds']) == list(rec_j['kinds'])


def attempt_numbers(receipts, k):
    """The attempts of pynn_seed K that left a receipt of their own (sK-aN-... or sK-aN.<suffix>; the comparison
    records sK-aI-aJ-compare.json aside), in order."""
    out = set()
    for p in Path(receipts).glob(f's{k}-a*'):
        m = re.match(rf'^s{k}-a(\d+)(?:[-.](.*))?$', p.name)
        if m and not (m.group(2) and re.fullmatch(r'a\d+-compare\.json', m.group(2))):
            out.add(int(m.group(1)))
    return sorted(out)


def attempts(receipts, k, hosts):
    """Each attempt of pynn_seed K in order, read from its receipts (spec, "Attempts"): {'attempt', 'ending', 'kind',
    'exit', 'start_utc', 'peak_rss_kb'}. ending: 'completed' (exit 0, its export in data-sha256.txt, the server files'
    hashes the same at its start and end; whether its server check was made is pair_state's), 'killed for memory'
    (exit 99), 'disk floor' (exit 98, not counted) or 'counted' with its kind: 'files changed', 'timeout (exit 124)',
    'killed (exit 137)' (GNU timeout's own kill after its timeout, or a SIGKILL from outside, which GNU time passes on
    alike; code review of 8 November), 'crash (exit N)', 'no export' (exit 0 without its export) or 'interrupted'
    (no exit receipt, or one that is empty or not a number: a reboot, a power loss, a killed queue). It stops on
    receipts the queue does not write (an exit receipt without the server files' hashes; a completed attempt without
    its start time)."""
    r = Path(receipts)
    out = []
    for n in attempt_numbers(r, k):
        name = f's{k}-a{n}'
        start = r / f'{name}-start-utc.txt'
        t = start.read_text().strip() if start.is_file() else ''
        tv = r / f'{name}-time-v.txt'
        peak = PEAK_RSS.search(tv.read_text()) if tv.is_file() else None
        exit_file = r / f'{name}-exit.txt'
        code = exit_file.read_text().strip() if exit_file.is_file() else None
        row = {'attempt': n, 'exit': code, 'start_utc': t if UTC.fullmatch(t) else None,
               'peak_rss_kb': int(peak.group(1)) if peak else None, 'kind': None}
        out.append(row)
        if code is None or not re.fullmatch(r'\d{1,3}', code):
            row.update(ending='counted', kind='interrupted')
            continue
        code = int(code)
        hs, he = r / f'{name}-sha256-start.txt', r / f'{name}-sha256-end.txt'
        if not (hs.is_file() and he.is_file()) or not hs.read_bytes().strip():
            stop(f'{name} has an exit receipt, but its server-file hashes at start and end are missing')
        changed = hs.read_bytes() != he.read_bytes() or (r / f'{name}-files-changed.txt').exists()
        if code == EXIT_MEMORY:
            row['ending'] = 'killed for memory'
        elif changed:
            row.update(ending='counted', kind='files changed')
        elif code == EXIT_DISK_FLOOR:
            row['ending'] = 'disk floor'
        elif code in EXIT_TIMEOUTS:
            row.update(ending='counted', kind='timeout (exit 124)' if code == 124 else f'killed (exit {code})')
        elif code != 0:
            row.update(ending='counted', kind=f'crash (exit {code})')
        elif f'{name}.json.gz' not in hosts:
            row.update(ending='counted', kind='no export')
        else:
            if row['start_utc'] is None:
                stop(f'{name} completed, but its receipt {name}-start-utc.txt holds no UTC time')
            row['ending'] = 'completed'
    return out


def comparison_problem(k, i, j, c, server):
    """Why a comparison record of runs aI and aJ is not the frozen tool's record for these server records; None if
    it is."""
    where = f'pynn_seed {k}: the comparison record of a{i} and a{j}'
    if c.get('attempts') != [i, j] or c.get('verdict') not in ('agree', 'disagree'):
        return f'{where} is not a comparison of these two runs with a verdict'
    if c.get('server_records') != {f'a{i}': server[i]['sha256'], f'a{j}': server[j]['sha256']}:
        return f'{where} was not made with their server check records'
    if c['verdict'] == 'disagree':
        if c.get('exit') != COMPARE_DISAGREE or c.get('server_checks') is not None:
            return f'{where} says disagree with exit {c.get("exit")} and server checks {c.get("server_checks")!r}'
        return None
    same = same_checks(server[i], server[j])
    if c.get('server_checks') != ('same' if same else 'differ'):
        return (f"{where} says the server checks are {c.get('server_checks')!r}, but by their records they are "
                f"{'the same' if same else 'different'}")
    if c.get('exit') != (COMPARE_AGREE if same else COMPARE_CHECKS_DIFFER):
        return f"{where}: exit {c.get('exit')} is not the tool's for an agreement with server checks {c['server_checks']}"
    return None


def pair_state(k, runs, server, comparisons):
    """The paired rule for one seed (spec, "Attempts", "The paired rule" and every row of "Every combination for one
    seed"), from its attempts in order (attempts()), its server check records by attempt and its comparison records by
    (I, J). After each completed run, once its server check is made, it is compared with each earlier completed run in
    attempt order until one agrees; the first agreeing pair ends the seed; the failure rules (killed for memory, failed
    twice, attempts used up) end it before the next attempt. Returns {'state', 'status', 'pair', 'completed',
    'counted_failures', 'disk_floor', 'comparisons', 'why', 'problems'}: state is 'not run', 'pending' (an attempt, a
    server check or a comparison still to come; why says which), 'agreed' (an agreeing pair whose server checks both
    passed), 'early stop' (an agreeing pair both refused with the same kinds), 'checks disagree' (an agreeing pair
    whose server checks differ), 'no agreeing pair', 'failed twice', 'killed for memory' or 'attempts used up'; status is
    the line the queue writes into sK-status.txt for it ('agreed aI aJ' for an agreeing pair), None while the seed is
    not settled. problems: what the queue's records hold that the rule does not give."""
    out = {'pynn_seed': k, 'state': 'not run', 'status': None, 'pair': None, 'completed': [], 'counted_failures': [],
           'disk_floor': [], 'killed_for_memory': None, 'comparisons': [], 'why': None, 'problems': []}
    problems = out['problems']
    numbers = [x['attempt'] for x in runs]
    if numbers != list(range(1, len(numbers) + 1)):
        problems.append(f'pynn_seed {k}: attempts {numbers} are not numbered a1, a2, ... in the order they start')
    called, ended, waiting = set(), None, None
    for x in runs:
        n = x['attempt']
        if ended or waiting:
            problems.append(f'pynn_seed {k}: attempt a{n} started after ' +
                            (f'the seed ended ({ended})' if ended else f'{waiting} was made'))
            continue
        if n > MAX_ATTEMPTS:
            problems.append(f'pynn_seed {k}: attempt a{n}, but a seed has at most {MAX_ATTEMPTS} attempts')
            continue
        if x['ending'] != 'completed' and n in server:
            problems.append(f'pynn_seed {k}: a{n} has a server check record, but it did not complete '
                            f"({x['ending']}{', ' + x['kind'] if x.get('kind') else ''})")
        if x['ending'] == 'killed for memory':
            out['killed_for_memory'] = n
            ended = 'killed for memory'
        elif x['ending'] == 'counted':
            out['counted_failures'].append({'attempt': n, 'kind': x['kind']})
            if len(out['counted_failures']) >= COUNTED_FAILURES:
                ended = 'failed twice'
        elif x['ending'] == 'disk floor':
            out['disk_floor'].append(n)
        elif n not in server:
            waiting = f'the server check of a{n}'
            continue
        else:
            for i in out['completed']:
                called.add((i, n))
                c = comparisons.get((i, n))
                if c is None:
                    waiting = f'the comparison of a{i} and a{n}'
                    break
                why = comparison_problem(k, i, n, c, server)
                if why:
                    problems.append(why)
                out['comparisons'].append({'attempts': [i, n], 'verdict': c.get('verdict')})
                if c.get('verdict') == 'agree':
                    out['pair'] = [i, n]
                    if server[i]['valid'] and server[n]['valid']:
                        ended = 'agreed'
                    elif same_checks(server[i], server[n]):
                        ended = 'early stop'
                    else:
                        ended = 'checks disagree'
                    break
            out['completed'].append(n)
            if not ended and not waiting and len(out['completed']) >= COMPLETED_CAP:
                ended = 'no agreeing pair'
        if not ended and not waiting and n >= MAX_ATTEMPTS:
            ended = 'attempts used up'
    for i, j in sorted(set(comparisons) - called):
        problems.append(f'pynn_seed {k}: a comparison of a{i} and a{j} that the paired rule does not call for')
    for n in sorted(set(server) - set(numbers)):
        problems.append(f'pynn_seed {k}: a server check record of a{n}, an attempt that never started')
    if ended:
        out['state'] = ended
        out['status'] = f"agreed a{out['pair'][0]} a{out['pair'][1]}" if out['pair'] else ended
    elif runs:
        out['state'] = 'pending'
        out['why'] = (f'{waiting}, which has not been made' if waiting else
                      f'the next attempt of pynn_seed {k} (a{len(runs) + 1})')
    return out


def queue_status(receipts, k):
    """The line the queue wrote into sK-status.txt when the seed settled, or None."""
    f = Path(receipts) / f's{k}-status.txt'
    if not f.is_file():
        return None
    s = f.read_text().strip()
    m = AGREED.match(s)
    if not (s in SETTLED or (m and int(m.group(1)) < int(m.group(2)))):
        stop(f"{f} holds {s!r}, not 'agreed aI aJ' or one of {SETTLED}")
    return s


# ---------------------------------------------------------------- the replacement rule and its one record

def cause_text(state, seed, slot, sha=None):
    """The cause the queue writes for replacing SEED (SLOT itself, or the reserve standing for it)."""
    base = (f'refused by the blind checker (check record SHA-256 {sha})' if state == 'refused'
            else CAUSE_TEXT[state])
    if seed != slot:
        return f'reserve {seed} {base}'
    return f'the run {base}' if state in ('failed twice', 'killed for memory') else base


def statuses(pairs, records, seeds=None):
    """Each seed's status for the replacement rule: 'valid' (an agreeing pair, both server checks passed, and the local
    check passed the export of its earlier run), 'invalid: <cause>', 'pending' (not settled, its status not yet
    written by the queue, or its export to analyse not checked locally yet) or 'not run'."""
    out = {}
    for k in seeds or list(cf.SLOTS) + list(cf.RESERVES):
        p = pairs[k]
        st = p['state']
        if st == 'not run':
            out[k] = 'not run'
        elif st == 'pending' or not p.get('recorded', True):
            out[k] = 'pending'
        elif p['pair'] is not None:
            rec = records.get(k)
            if rec is None:
                out[k] = 'pending'
            elif rec['valid']:
                out[k] = 'valid'
            else:
                out[k] = 'invalid: refused by the blind check (' + '; '.join(rec['refusals']) + ')'
        else:
            out[k] = 'invalid: ' + cause_text(st, k, k)
    return out


def parse_lines(text, pattern, name):
    """The lines of one of the queue's records, each matched to its declared form; and the lines that are not."""
    out, problems = [], []
    for x in text.splitlines():
        if not x.strip():
            continue
        m = pattern.match(x)
        if m:
            out.append(m.groups())
        else:
            problems.append(f'{name}: a line the queue does not write: {x!r}')
    return out, problems


def replacement_lines(text):
    """The queue's one replacement record (replacements.txt), in time order: [{'utc', 'reserve' (None for 'no reserve
    left'), 'slot', 'cause'}], and the lines that are not of its form."""
    rows, problems = parse_lines(text, REPLACEMENT_LINE, 'replacements.txt')
    return [{'utc': u, 'reserve': int(r) if r else None, 'slot': int(s), 'cause': c} for u, r, s, c in rows], problems


def cause_problem(who, slot, cause, queue, records):
    """Why a replacement line's cause is not what made `who` (the slot itself, or the reserve last given to it)
    invalid; None if it is. queue: each seed's state by the paired rule."""
    m, r = RUN_CAUSE.match(cause), REFUSED_CAUSE.match(cause)
    if not m and not r:
        return f'a cause the queue does not write: {cause!r}'
    named = (m.group(3) if m else r.group(1))
    named = int(named) if named else None
    if (named if named is not None else slot) != who or (named is None) != (who == slot):
        return (f"the cause is about {'the slot' if named is None else 'reserve ' + str(named)}, but the seed it "
                f'replaces is {who}')
    if m:
        want = STATE_OF_CAUSE[m.group(1) or m.group(2) or m.group(4)]
        if queue.get(who) != want:
            return f'pynn_seed {who} is {queue.get(who)}, not {want}'
        return None
    rec = records.get(who)
    if rec is None or rec['valid'] or rec['sha256'] != r.group(2):
        return f'the check record {r.group(2)} of pynn_seed {who} is not a refusal among the check records'
    return None


def replacement(status, queue, records, lines, slots=None, reserves=None):
    """The declared replacement rule, read with the queue's one record of it (lines: replacements.txt, in time order).
    A slot is invalid if its seed ended 'no agreeing pair', 'failed twice', 'killed for memory' or 'attempts used up',
    or the local check refused the export of its agreeing pair. Each invalid slot gets the next unused reserve (one,
    14, in revision 2); at most one replacement. Each line must be the rule's: the next unused reserve (so no reserve
    fills two slots), for a slot whose own seed, or whose reserve, is invalid for the cause the line gives ('no
    reserve left' only once the reserve is used); every reserve that ran is in the record. Returns the state: 'six
    valid instances' (with the analysed instances in pynn_seed order and the slot the reserve filled), 'fewer than six
    valid instances' (as soon as more slots need a reserve than are unused), or 'pending'; and the record's problems,
    on which the summary stops."""
    slots = list(cf.SLOTS if slots is None else slots)
    reserves = list(cf.RESERVES if reserves is None else reserves)
    problems, used, chain, exhausted = [], [], {s: [] for s in slots}, []
    for i, ln in enumerate(lines, 1):
        s, r, cause = ln['slot'], ln['reserve'], ln['cause']
        where = f"replacements.txt line {i} ({'reserve ' + str(r) if r is not None else 'no reserve left'} for slot {s})"
        if s not in chain:
            problems.append(f'{where}: {s} is not a slot')
            continue
        if s in exhausted:
            problems.append(f'{where}: slot {s} already had no reserve left')
            continue
        who = chain[s][-1] if chain[s] else s
        why = cause_problem(who, s, cause, queue, records)
        if why:
            problems.append(f'{where}: {why}')
        if r is None:
            if len(used) < len(reserves):
                problems.append(f'{where}: reserve {reserves[len(used)]} was still unused')
            exhausted.append(s)
            continue
        nxt = reserves[len(used)] if len(used) < len(reserves) else None
        if r != nxt:
            problems.append(f"{where}: {r} is not the next unused reserve ({nxt if nxt else 'none was left'})")
            continue
        used.append(r)
        chain[s].append(r)
    for r in reserves:
        if queue.get(r, 'not run') != 'not run' and r not in used:
            problems.append(f'reserve {r} ran, but replacements.txt gives it to no slot')
    analysed, filled_by, need, pending = [], {}, [], []
    for s in slots:
        who = chain[s][-1] if chain[s] else s
        st = status.get(who, 'not run')
        if st == 'valid':
            analysed.append(who)
            if who != s:
                filled_by[str(s)] = who
        elif st in ('pending', 'not run'):
            pending.append(who)
        else:
            need.append(s)
    unused = [r for r in reserves if r not in used]
    out = {'analysed': None, 'filled_by': filled_by,
           'invalid_slots': [s for s in slots if str(status.get(s)).startswith('invalid')],
           'reserves_used': [{'reserve': r, 'slot': s, 'status': status.get(r, 'not run')}
                             for s in slots for r in chain[s]],
           'pending': sorted(pending), 'needing_a_reserve': need, 'unused_reserves': unused, 'problems': problems}
    if len(need) > len(unused):
        out['state'] = 'fewer than six valid instances'
        out['why'] = (f'fewer than six valid instances after the declared replacements: '
                      f'{count(len(need), "slot")} without a valid instance and {count(len(unused), "unused reserve")} ('
                      + '; '.join(f'slot {s}: ' + '; '.join(f'{x} {status.get(x)}' for x in [s] + chain[s]) for s in need)
                      + ')')
    elif pending or need:
        out['state'] = 'pending'
        out['why'] = 'waiting for ' + '; '.join(
            [f'pynn_seed {x} (not run, not settled or not checked)' for x in sorted(pending)] +
            [f'the next reserve for slot {s} (its queue or launch_023.sh reserve)' for s in need])
    else:
        out['state'] = 'six valid instances'
        out['analysed'] = sorted(analysed)
    return out


def count(n, noun):
    return f'{n} {noun}' + ('' if n == 1 else 's')


# ---------------------------------------------------------------- the early stop and the stop with no reading

def early_stop(lines, pairs, records, server, starts):
    """The early stop (spec, "The early stop"), from the queue's early-stop.txt (lines), each seed's state by the
    paired rule, the local check records, the server check records and every attempt's start time. At an agreeing
    pair that both server checks refused with the same refusal kinds the queue stops; the protocol is NOT
    INTERPRETABLE once the local check of the earlier run's export refuses it too. Returns {'state': 'none' |
    'stopped' | 'pending', ...} with the problems, on which the summary stops: such a pair without the stop, a stop the
    rule does not give, a second such pair, an attempt started after the stop, and a local check that passed what both
    server checks refused. A refusal of a run that disagrees with its seed's other runs is a one-off fault and stops
    nothing."""
    problems = []
    found = sorted(k for k, p in pairs.items() if p['state'] == 'early stop')
    if not lines:
        for k in found:
            i, j = pairs[k]['pair']
            problems.append(f'runs a{i} and a{j} of pynn_seed {k} agree and the server check refused both with the same '
                            'kinds, but the queue did not stop (no early-stop.txt)')
        return {'state': 'none', 'problems': problems}
    if len(lines) > 1:
        problems.append(f'early-stop.txt holds {len(lines)} lines; the queue writes one')
    utc, seed, i, j, sha_i, sha_j = lines[0]
    seed, i, j = int(seed), int(i), int(j)
    p, srv = pairs.get(seed), server.get(seed, {})
    out = {'state': 'stopped', 'utc': utc, 'pynn_seed': seed, 'attempts': [i, j], 'server_record_sha256': [sha_i, sha_j],
           'problems': problems}
    if (p is None or p['state'] != 'early stop' or p['pair'] != [i, j] or i not in srv or j not in srv
            or srv[i]['sha256'] != sha_i or srv[j]['sha256'] != sha_j):
        problems.append(f'early-stop.txt: the queue stopped for runs a{i} and a{j} of pynn_seed {seed} with records '
                        f'{sha_i} and {sha_j}, which are not an agreeing pair refused by both server checks with the same '
                        'kinds')
        return out
    out.update(refusals=list(srv[i]['refusals']), kinds=list(srv[i]['kinds']))
    for k in found:
        if k != seed:
            problems.append(f'pynn_seed {k} also reached the early stop: the queue stops at the first')
    for (k, n), t in sorted(starts.items()):
        if t is not None and t > utc:
            problems.append(f'a{n} of pynn_seed {k} started at {t}, after the early stop at {utc}')
    local = records.get(seed)
    if local is None:
        out['state'] = 'pending'
        out['why'] = (f'the local check of the export of a{i} of pynn_seed {seed}, which both server checks refused, has '
                      'not been made')
    elif local['valid']:
        problems.append(f'the local check passed the export of a{i} of pynn_seed {seed}, which both server checks '
                        'refused: the two checks of the same export disagree')
    return out


def checks_disagree(lines, pairs, server):
    """The stop with no reading (spec, "The stop with no reading"), from the queue's checks-disagree.txt (lines): the
    server checks of an agreeing pair differ (one passed and one refused, or both refused with different kinds).
    Returns {'state': 'none' | 'stopped', ...} with the problems; the summary stops on any state but 'none'."""
    problems = []
    found = sorted(k for k, p in pairs.items() if p['state'] == 'checks disagree')
    if not lines and not found:
        return {'state': 'none', 'problems': problems}
    out = {'state': 'stopped', 'problems': problems}
    if not lines:
        for k in found:
            i, j = pairs[k]['pair']
            problems.append(f'runs a{i} and a{j} of pynn_seed {k} agree and their server checks differ, but the queue '
                            'did not stop (no checks-disagree.txt)')
        out.update(pynn_seed=found[0], attempts=pairs[found[0]]['pair'])
        return out
    if len(lines) > 1:
        problems.append(f'checks-disagree.txt holds {len(lines)} lines; the queue writes one')
    utc, seed, i, j, sha_i, sha_j = lines[0]
    seed, i, j = int(seed), int(i), int(j)
    out.update(utc=utc, pynn_seed=seed, attempts=[i, j], server_record_sha256=[sha_i, sha_j])
    p, srv = pairs.get(seed), server.get(seed, {})
    if (p is None or p['state'] != 'checks disagree' or p['pair'] != [i, j] or i not in srv or j not in srv
            or srv[i]['sha256'] != sha_i or srv[j]['sha256'] != sha_j):
        problems.append(f'checks-disagree.txt: runs a{i} and a{j} of pynn_seed {seed} with records {sha_i} and {sha_j} '
                        'are not an agreeing pair whose server checks differ')
    for k in found:
        if k != seed:
            problems.append(f'the server checks of an agreeing pair of pynn_seed {k} differ too: the queue stops at the '
                            'first')
    return out


def decide(status, queue, records, lines, early):
    """The early stop first, then the replacement rule (whose record is checked either way)."""
    rule = replacement(status, queue, records, lines)
    if early['state'] == 'stopped':
        i, j = early['attempts']
        rule.update(state='stopped by the early check', analysed=None,
                    why=(f"the early stop: runs a{i} and a{j} of pynn_seed {early['pynn_seed']} agree, and the server "
                         f"check refused both with the same refusal kinds ({', '.join(early.get('kinds') or [])}), for a "
                         'fault taken to be shared by every instance; the local check refused the export of '
                         f"a{i} too (" + '; '.join(early.get('refusals') or []) + ')'))
    elif early['state'] == 'pending':
        rule.update(state='pending', analysed=None, why=early['why'])
    return rule


# ---------------------------------------------------------------- S15, the paired-run record (reported only)

def clopper_pearson(x, n, level=0.95):
    """The two-sided Clopper-Pearson interval of x successes in n trials (None for n = 0)."""
    if n == 0:
        return None
    from scipy import stats                     # the venv's and the Mac's scipy, as plaid_stats uses it
    tail = (1 - level) / 2
    lo = 0.0 if x == 0 else float(stats.beta.ppf(tail, x, n - x + 1))
    hi = 1.0 if x == n else float(stats.beta.ppf(1 - tail, x + 1, n - x))
    return [lo, hi]


def s15(pairs, runs, server, comparisons, disk_waits):
    """S15 (spec, "Secondary measures"): for every seed that ran, its attempts with their endings, each completed run's
    server verdict and kinds, each comparison with its verdict and differences, and its agreeing pair; the fault share
    (the completed runs that disagree with their seed's agreeing pair, over the completed runs of the seeds that have
    one) with its 95 % Clopper-Pearson interval and how many of those runs the server check refused or passed; the
    completed runs of the seeds that never reached a pair, counted apart, with each one's kinds; the bound that counts
    each seed that ended 'no agreeing pair' as at least three faulty runs of four; the note when every completed run of
    those seeds was refused with one kind, or was unreadable; the failed attempts by kind; and the queue's waits for
    free disk. Reported only: it decides nothing and sizes nothing."""
    seeds, faulty, refused, passed, total = [], 0, 0, 0, 0
    nopair_seeds, nopair = 0, []
    failed = {'killed for memory': 0, 'counted failure': {}, 'disk floor': 0}
    for k in sorted(pairs):
        p = pairs[k]
        if p['state'] == 'not run':
            continue
        srv = server.get(k, {})
        unreadable = {int(name[1:]) for c in comparisons.get(k, {}).values() for name in (c.get('unreadable') or [])}
        entry = {'pynn_seed': k, 'state': p['state'], 'agreeing_pair': p['pair'], 'attempts': [], 'comparisons': []}
        for x in runs.get(k, []):
            row = {'attempt': x['attempt'], 'ending': x['ending']}
            if x['ending'] == 'counted':
                row['kind'] = x['kind']
                failed['counted failure'][x['kind']] = failed['counted failure'].get(x['kind'], 0) + 1
            elif x['ending'] in ('killed for memory', 'disk floor'):
                failed[x['ending']] += 1
            if x['attempt'] in srv:
                row['server_check'] = {'valid': srv[x['attempt']]['valid'], 'kinds': list(srv[x['attempt']]['kinds'])}
            if x['attempt'] in unreadable:
                row['unreadable_in_a_comparison'] = True
            entry['attempts'].append(row)
        for (i, j), c in sorted(comparisons.get(k, {}).items()):
            entry['comparisons'].append({'attempts': [i, j], 'verdict': c.get('verdict'),
                                         'unreadable': list(c.get('unreadable') or []),
                                         'differences': c.get('differences')})
        if p['pair']:
            others = [n for n in p['completed'] if n not in p['pair']]
            entry['one_off_faults'] = others
            total += len(p['completed'])
            faulty += len(others)
            refused += sum(1 for n in others if not srv[n]['valid'])
            passed += sum(1 for n in others if srv[n]['valid'])
        elif p['state'] == 'no agreeing pair':
            nopair_seeds += 1
            for n in p['completed']:
                nopair.append({'pynn_seed': k, 'attempt': n, 'server_valid': srv[n]['valid'],
                               'kinds': list(srv[n]['kinds']),
                               'unreadable': n in unreadable or list(srv[n]['kinds']) == ['unreadable']})
        seeds.append(entry)
    note = None
    if nopair:
        if all(not r['server_valid'] for r in nopair) and len({tuple(r['kinds']) for r in nopair}) == 1:
            note = (f"every completed run of the seeds without an agreeing pair was refused by the server check with "
                    f"the same kinds ({', '.join(nopair[0]['kinds'])}): a systematic fault whose details vary from run "
                    'to run looks the same (risk 14), so these runs are not called one-off faults')
        elif all(r['unreadable'] for r in nopair):
            note = ('every completed run of the seeds without an agreeing pair was unreadable: an exporter that writes '
                    'bytes that can never be parsed looks the same (risk 14), so these runs are not called one-off '
                    'faults')
    bx, bn = faulty + 3 * nopair_seeds, total + 4 * nopair_seeds
    return {'scope': ('S15, the paired-run record: reported only, it decides nothing and sizes nothing; protocol 023\'s '
                      "run, the diagnosis's runs and the rehearsal's runs are not in it"),
            'seeds': seeds,
            'fault_share': {'faulty_runs': faulty, 'completed_runs_of_seeds_with_a_pair': total,
                            'share': faulty / total if total else None, 'ci95_clopper_pearson': clopper_pearson(faulty, total),
                            'refused_by_the_server_check': refused, 'passed_by_the_server_check': passed,
                            'note': ('an estimate of the one-off fault rate that runs low: a seed stops at its second '
                                     'clean run and the seeds without a pair are left out (about 0.21 at a true rate of '
                                     '0.25 with a cap of four), and the Clopper-Pearson interval assumes a fixed number '
                                     'of runs, which the paired rule does not have')},
            'seeds_without_a_pair': {'seeds': nopair_seeds, 'completed_runs': len(nopair), 'runs': nopair,
                                     'note': note},
            'bound': {'faulty_runs_at_least': bx, 'runs': bn, 'share': bx / bn if bn else None,
                      'ci95_clopper_pearson': clopper_pearson(bx, bn),
                      'rule': "each seed that ended 'no agreeing pair' counted as at least three faulty runs of four"},
            'failed_attempts': failed, 'disk_waits': list(disk_waits)}


# ---------------------------------------------------------------- the rule from the recorded inputs

def rule_state(inputs, slots=None, reserves=None):
    """Every seed's state by the paired rule, the statuses, the early stop, the stop with no reading, the replacement
    rule and S15, from the inputs the summary records (each seed's attempts, server check records by attempt,
    comparison records by pair, the queue's status lines, the local check records, the replacement, early-stop and
    checks-disagree records and the disk waits): the one computation the summary makes and the analysis driver makes
    again. Returns them with 'problems', on which both stop."""
    slots = list(cf.SLOTS if slots is None else slots)
    reserves = list(cf.RESERVES if reserves is None else reserves)
    seeds = slots + reserves
    problems = []
    for key in ('attempts', 'server_checks', 'comparisons', 'queue_status', 'check_records'):
        extra = sorted(set(inputs[key]) - {str(k) for k in seeds})
        if extra:
            problems.append(f'{key} holds seeds that are not slots or reserves: {extra}')
    runs = {k: list(inputs['attempts'].get(str(k)) or []) for k in seeds}
    server = {k: {int(n[1:]): rec for n, rec in (inputs['server_checks'].get(str(k)) or {}).items()} for k in seeds}
    comps = {k: {tuple(int(x[1:]) for x in key.split('-')): c
                 for key, c in (inputs['comparisons'].get(str(k)) or {}).items()} for k in seeds}
    pairs = {}
    for k in seeds:
        p = pair_state(k, runs[k], server[k], comps[k])
        problems += p['problems']
        q = inputs['queue_status'].get(str(k))
        if q is not None and q != p['status']:
            problems.append(f'pynn_seed {k}: s{k}-status.txt holds {q!r}, but by the paired rule the seed is '
                            + (repr(p['status']) if p['status'] else f"not settled ({p['why']})"))
        p['recorded'] = q is not None or p['state'] in ('early stop', 'checks disagree')
        if p['status'] and not p['recorded']:
            p['why'] = f's{k}-status.txt, which the queue writes when the seed settles ({p["status"]!r})'
        pairs[k] = p
    records = {}
    for key, rec in sorted(inputs['check_records'].items()):
        k = int(key)
        p = pairs.get(k)
        if p is None or p['pair'] is None:
            problems.append(f"check-s{k}-a{rec.get('attempt')}.json exists, but pynn_seed {k} has no agreeing pair")
        elif rec.get('attempt') != p['pair'][0]:
            problems.append(f"check-s{k}-a{rec.get('attempt')}.json is not the check of the export to analyse of "
                            f"pynn_seed {k} (a{p['pair'][0]}, the earlier run of its agreeing pair)")
        else:
            records[k] = rec
    status = statuses(pairs, records, seeds)
    queue = {k: p['state'] for k, p in pairs.items()}
    starts = {(k, x['attempt']): x.get('start_utc') for k in seeds for x in runs[k]}
    early = early_stop([tuple(x) for x in inputs['early_stop_record']], pairs, records, server, starts)
    disagree = checks_disagree([tuple(x) for x in inputs['checks_disagree_record']], pairs, server)
    lines = [{'utc': x['utc'], 'reserve': x['reserve'], 'slot': int(x['slot']), 'cause': x['cause']}
             for x in inputs['replacement_record']]
    rule = decide(status, queue, records, lines, early)
    problems += early['problems'] + disagree['problems'] + rule['problems']
    return {'pairs': {str(k): p for k, p in pairs.items()}, 'status': {str(k): v for k, v in status.items()},
            'early_stop': early, 'checks_disagree': disagree, 'rule': rule,
            's15': s15(pairs, runs, server, comps, inputs.get('disk_waits') or []), 'problems': problems}


# ---------------------------------------------------------------- the summary

def read_record(path, k, n, contract_sha, checker_sha, hosts, where='local'):
    """A check record of the export of attempt aN of pynn_seed K (where: 'local', made on the Mac, or 'server', made by
    the queue), or a stop unless it is the frozen checker's record of that host export for this contract."""
    try:
        rec = json.loads(Path(path).read_text())
    except (OSError, ValueError) as exc:
        stop(f'{path} cannot be read ({type(exc).__name__}: {exc})')
    problems = []
    if not isinstance(rec, dict):
        stop(f'{path} is not a check record')
    name = f's{k}-a{n}.json.gz'
    if rec.get('where') != where:
        problems.append(f"it is a {rec.get('where')!r} record, not a {where!r} one")
    if rec.get('pynn_seed') != k:
        problems.append(f"it is the check of pynn_seed {rec.get('pynn_seed')!r}")
    if rec.get('contract_sha256') != contract_sha:
        problems.append('it was made for another contract')
    if rec.get('checker_sha256') != checker_sha:
        problems.append('it was made by another checker than this frozen one')
    if rec.get('export') != name or rec.get('export_sha256') != hosts.get(name):
        problems.append(f"its export is not the host's file {name} in data-sha256.txt")
    refusals, kinds = rec.get('refusals'), rec.get('kinds')
    if (not isinstance(rec.get('valid'), bool) or not isinstance(refusals, list) or not isinstance(kinds, list)
            or len(refusals) != len(kinds) or any(kd not in KINDS for kd in kinds) or rec['valid'] != (not refusals)):
        problems.append('its verdict, refusals and kinds are not a check record\'s')
    if problems:
        stop(f'{path}: ' + '; '.join(problems))
    return {'file': Path(path).name, 'sha256': sha256(path), 'where': where, 'attempt': n, 'valid': rec['valid'],
            'refusals': refusals, 'kinds': kinds, 'export': rec['export'], 'export_sha256': rec['export_sha256'],
            'contract_sha256': rec['contract_sha256'], 'checker_sha256': rec['checker_sha256']}


def read_comparison(path, k, i, j, contract_sha, tool_sha, hosts):
    """A comparison record (runs/sK-aI-aJ-compare.json), or a stop unless it is the frozen comparison tool's record,
    for this contract, of the host's exports of aI and aJ (data-sha256.txt). Returns what the paired rule and S15 read
    of it, with the SHA-256s of the server check records it was made with (pair_state checks them against the fetched
    records)."""
    try:
        rec = json.loads(Path(path).read_text())
    except (OSError, ValueError) as exc:
        stop(f'{path} cannot be read ({type(exc).__name__}: {exc})')
    if not isinstance(rec, dict):
        stop(f'{path} is not a comparison record')
    names = (f'a{i}', f'a{j}')
    problems = []
    if rec.get('tool_sha256') != tool_sha:
        problems.append("it was made by another comparison tool than the contract's")
    if rec.get('contract_sha256') != contract_sha:
        problems.append('it was made for another contract')
    if rec.get('pynn_seed') != k or rec.get('attempts') != [i, j]:
        problems.append(f'it is not the comparison of a{i} and a{j} of pynn_seed {k}')
    exports = rec.get('exports') if isinstance(rec.get('exports'), dict) else {}
    want = {n: {'file': f's{k}-{n}.json.gz', 'sha256': hosts.get(f's{k}-{n}.json.gz')} for n in names}
    if exports != want or None in [w['sha256'] for w in want.values()]:
        problems.append("its exports are not the host's files in data-sha256.txt")
    records = rec.get('server_records') if isinstance(rec.get('server_records'), dict) else {}
    shas = {n: (records.get(n) or {}).get('sha256') if isinstance(records.get(n), dict) else None for n in names}
    if problems:
        stop(f'{path}: ' + '; '.join(problems))
    diff = rec.get('differences') if isinstance(rec.get('differences'), dict) else None
    compact = None
    if diff is not None:
        compact = {'fields': diff.get('fields'),
                   'sheets': [{key: seg.get(key) for key in ('sheet', 'stimulus', 'differing_trains',
                                                             'first_differing_time_ms')}
                              for seg in diff.get('segments') or [] if isinstance(seg, dict)]}
    return {'file': Path(path).name, 'sha256': sha256(path), 'attempts': rec.get('attempts'),
            'verdict': rec.get('verdict'), 'exit': rec.get('exit'), 'server_checks': rec.get('server_checks'),
            'server_records': shas, 'exports': {n: want[n]['sha256'] for n in names},
            'tool_sha256': rec.get('tool_sha256'), 'contract_sha256': rec.get('contract_sha256'),
            'unreadable': list(rec.get('unreadable') or []), 'differences': compact}


def read_text(path):
    return Path(path).read_text() if Path(path).is_file() else ''


def summary(contract_path, fetched, checks):
    """Every seed's state by the paired rule from the fetched receipts (each attempt's receipts, the server check
    records and the comparison records), the local check records and the queue's records; the early stop, the stop
    with no reading, the replacement rule and S15. Stops, writing nothing, on any record that is not the declared
    procedure's, and at the stop with no reading."""
    receipts = Path(fetched) / 'receipts'
    if not receipts.is_dir():
        stop(f'{receipts} does not exist (fetch_023.sh writes it)')
    hosts = host_hashes(fetched)
    contract, _ = load_contract(contract_path)
    contract_sha, checker_sha = sha256(contract_path), sha256(__file__)
    tool_sha = made_from(contract, COMPARE_TOOL)
    seeds = list(cf.SLOTS) + list(cf.RESERVES)
    inputs = {'seeds': seeds, 'attempts': {}, 'server_checks': {}, 'comparisons': {}, 'queue_status': {},
              'check_records': {}}
    problems = []
    for k in seeds:
        inputs['attempts'][str(k)] = attempts(receipts, k, hosts)
        srv = {}
        for p in sorted(receipts.glob(f's{k}-a*-server-check.json')):
            m = re.fullmatch(rf's{k}-a([1-9])-server-check\.json', p.name)
            if not m:
                problems.append(f'{p.name} is not a server check record the queue names so')
                continue
            srv[f'a{m.group(1)}'] = read_record(p, k, int(m.group(1)), contract_sha, checker_sha, hosts, where='server')
        comps = {}
        for p in sorted(receipts.glob(f's{k}-a*-compare.json')):
            m = COMPARE_NAME.match(p.name)
            if not m or int(m.group(1)) != k or not int(m.group(2)) < int(m.group(3)):
                problems.append(f'{p.name} is not a comparison record the queue names so')
                continue
            i, j = int(m.group(2)), int(m.group(3))
            comps[f'a{i}-a{j}'] = read_comparison(p, k, i, j, contract_sha, tool_sha, hosts)
        inputs['server_checks'][str(k)] = srv
        inputs['comparisons'][str(k)] = comps
        inputs['queue_status'][str(k)] = queue_status(receipts, k)
    for p in sorted(Path(checks).glob('check-*.json')):
        m = LOCAL_NAME.match(p.name)
        if not m or int(m.group(1)) not in seeds:
            problems.append(f'{p.name} is not the local check record of an attempt of a slot or reserve '
                            '(check-sK-aN.json)')
            continue
        k, n = int(m.group(1)), int(m.group(2))
        if str(k) in inputs['check_records']:
            problems.append(f'pynn_seed {k} has two local check records; the export to analyse is checked once')
            continue
        inputs['check_records'][str(k)] = read_record(p, k, n, contract_sha, checker_sha, hosts)
    lines, more = replacement_lines(read_text(receipts / 'replacements.txt'))
    problems += more
    stops_, more = parse_lines(read_text(receipts / 'early-stop.txt'), EARLY_STOP_LINE, 'early-stop.txt')
    problems += more
    disagree, more = parse_lines(read_text(receipts / 'checks-disagree.txt'), CHECKS_DISAGREE_LINE,
                                 'checks-disagree.txt')
    problems += more
    inputs.update(replacement_record=lines, early_stop_record=[list(x) for x in stops_],
                  checks_disagree_record=[list(x) for x in disagree],
                  disk_waits=[x for x in read_text(receipts / 'disk-waits.txt').splitlines() if x.strip()])
    state = rule_state(inputs)
    problems += state['problems']
    if problems:
        stop("the queue's records do not follow the declared procedure; nothing is written:\n  - " + '\n  - '.join(problems))
    if state['checks_disagree']['state'] != 'none':
        d = state['checks_disagree']
        stop(f"runs a{d['attempts'][0]} and a{d['attempts'][1]} of pynn_seed {d['pynn_seed']} agree, but their server "
             'checks differ: the stop with no reading. No summary is written and no outcome is declared; the protocol '
             'ends without a reading (spec, "No reading")')
    return {'scope': ('protocol 023 revision 2: every seed by the paired rule and the instances to analyse, from the '
                      'queue receipts, the comparisons and the blind checks; simulation only'),
            'inputs': inputs, 'pairs': state['pairs'], 'status': state['status'], 'early_stop': state['early_stop'],
            'checks_disagree': state['checks_disagree'], 'rule': state['rule'], 's15': state['s15'],
            'attempt_peak_rss_kb': {f'{k}-a{x["attempt"]}': x['peak_rss_kb'] for k in seeds
                                    for x in inputs['attempts'][str(k)]},
            'data_sha256': {'file': 'data-sha256.txt', 'sha256': sha256(Path(fetched) / 'data-sha256.txt')},
            'comparison_tool_sha256': tool_sha,
            'utc': time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime())}


# ---------------------------------------------------------------- records written whole

def leftovers(out):
    """Remove the checker's leftover temporary files of OUT (a power loss between the write and the link)."""
    for p in glob.glob(glob.escape(str(out)) + '.tmp-*'):
        try:
            os.unlink(p)
        except FileNotFoundError:
            pass


def write_once(path, obj):
    """Write a record once and whole: a temporary file in its folder, flushed to disk, linked to its name (which fails
    if the name exists, so a record is never overwritten), the folder flushed, the temporary file removed."""
    text = json.dumps(ap.clean(obj), indent=1, allow_nan=False) + '\n'
    path = Path(path)
    tmp = path.with_name(f'{path.name}.tmp-{os.getpid()}')
    fd = os.open(str(tmp), os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644)
    try:
        with os.fdopen(fd, 'w', encoding='utf-8') as fh:
            fh.write(text)
            fh.flush()
            os.fsync(fh.fileno())
        try:
            os.link(str(tmp), str(path))
        except FileExistsError:
            stop(f'{path} exists; a check record is never overwritten')
        dfd = os.open(str(path.parent), os.O_RDONLY)
        try:
            os.fsync(dfd)
        finally:
            os.close(dfd)
    finally:
        try:
            os.unlink(str(tmp))
        except FileNotFoundError:
            pass


def load_contract(path):
    try:
        contract = json.loads(Path(path).read_text())
    except (OSError, ValueError) as exc:
        stop(f'the contract {path} cannot be read ({type(exc).__name__}: {exc})')
    return contract, Path(path).resolve().parent


def load_reference(contract, base):
    ref = contract['integrity']['leadin_identity']
    path = base / ref['file']
    if sha256(path) != ref['sha256']:
        stop(f'{path} does not match its SHA-256 in the contract')
    return json.loads(path.read_text())


def main(args):
    allow_unfrozen = '--not-frozen' in args
    args = [x for x in args if x != '--not-frozen']
    if len(args) == 5 and args[0] == 'check':
        _, contract_path, kn, fetched, out = args
        m = re.fullmatch(r'(\d+)-a([1-9])', kn)
        if not m:
            stop(f'{kn!r} is not K-aN (a pynn_seed and an attempt, such as 8-a1)')
        k, n = int(m.group(1)), int(m.group(2))
        contract, base = load_contract(contract_path)
        leftovers(out)
        if Path(out).exists():
            stop(f'{out} exists; a check record is never overwritten')
        frozen = check_frozen(base, contract, allow_unfrozen)
        load_reference(contract, base)
        try:
            declaration(contract, k)
        except Refusal as exc:
            stop(str(exc))
        export, digest = local_export(fetched, k, n, host_hashes(fetched))
        rec = checked_twice(contract_path, k, export, digest)
        rec.update(where='local', attempt=n, checker_sha256=sha256(__file__), contract_sha256=sha256(contract_path),
                   frozen_check=frozen, utc=time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime()))
        write_once(out, rec)
        print(f"pynn_seed {k}, a{n}: {'VALID' if rec['valid'] else 'REFUSED'}" +
              ''.join(f'\n  refused ({kd}): {r}' for r, kd in zip(rec['refusals'], rec['kinds'])))
        return 0 if rec['valid'] else 1
    if len(args) == 5 and args[0] == 'server' and not allow_unfrozen:
        _, contract_path, k, export, out = args
        return server_check(contract_path, k, export, out)
    if len(args) == 5 and args[0] == 'summary':
        _, contract_path, fetched, checks, out = args
        contract, base = load_contract(contract_path)
        leftovers(out)
        if Path(out).exists():
            stop(f'{out} exists; a summary is never overwritten')
        frozen = check_frozen(base, contract, allow_unfrozen)
        res = summary(contract_path, fetched, checks)
        res.update(checker_sha256=sha256(__file__), contract_sha256=sha256(contract_path), frozen_check=frozen)
        write_once(out, res)
        rule = res['rule']
        print(rule['state'] + (f": {rule.get('why')}" if rule.get('why') else '') +
              (f"; analysed {rule['analysed']}" if rule['analysed'] else ''))
        return 0
    raise SystemExit(__doc__)


if __name__ == '__main__':
    sys.exit(main(sys.argv[1:]))
