Writing a large maker journal required more than collecting many files. I needed to know which version of a source had been read, how far the review extended and whether it covered the detail required by the next article. I turned part of that bookkeeping into a small Python module testable without customer material.
An indexed file and a reviewed range are different values
The source input declares the current ID, version, SHA-256 and line count. The review input declares the corresponding snapshot metadata and reviewed ranges. Calling the function does not read a file. Computing real file hashes and line counts and retaining immutable copies remain responsibilities of the integrating tool.
I deliberately narrowed this scope. A file being present or appearing in search results does not establish that a required section was read. False input makes the conclusion unreliable. The module compares review declarations; it cannot authenticate the act of reading or certify comprehension.
Fix the meaning of a line range first
Ranges start at one and include their end line. They must be ordered and non-overlapping. Ranges 3–8 and 9–12 jointly cover a requirement for 4–10, while a gap at line 9 does not. Every required interval must be covered before the result becomes eligible as a note for this source detail.
Collapsing ranges to a minimum and maximum would erase unread lines between them. The implementation advances a cursor through actual contiguous coverage. Overlapping inputs are rejected rather than double-counted. A larger arithmetic total must not become an invented claim of broader review.
Do not inherit old line coverage after a change
Any difference in version, digest or line count makes freshness stale. Even a declared full review of an older snapshot cannot become a full review of the current file. This example conservatively requires attention when the version differs despite an equal hash. A different source ID fails with SOURCE_MISMATCH.
The old snapshot's reviewed line count remains explicitly labelled as such. Historical work is retained without being promoted into current-source coverage. An editor must inspect the change to decide whether a small reread is enough. Merely replacing an old digest with the new one cannot update the review.
Explore the implementation
Complete independent synthetic implementation
"""Compare declared source metadata and reviewed line ranges; no file access."""
import re
class ReviewError(ValueError):
pass
def _keys(value, fields):
if not isinstance(value, dict) or set(value) != set(fields):
raise ReviewError('INVALID_FIELDS')
def _text(value):
if not isinstance(value, str) or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9._-]{0,79}', value):
raise ReviewError('INVALID_LABEL')
return value
def _count(value):
if type(value) is not int or value < 1 or value > 10000000:
raise ReviewError('INVALID_LINE_COUNT')
return value
def _hash(value):
if not isinstance(value, str) or not re.fullmatch(r'[a-f0-9]{64}', value):
raise ReviewError('INVALID_HASH')
return value
def _ranges(value, total):
if not isinstance(value, list) or len(value) > 10000:
raise ReviewError('INVALID_RANGES')
out = []
last = 0
for pair in value:
if not isinstance(pair, list) or len(pair) != 2:
raise ReviewError('INVALID_RANGE')
start, end = pair
if type(start) is not int or type(end) is not int or not 1 <= start <= end <= total or start <= last:
raise ReviewError('INVALID_RANGE_ORDER_OR_BOUNDS')
out.append((start, end))
last = end
return out
def _covers(known, required):
for start, end in required:
cursor = start
for left, right in known:
if right < cursor:
continue
if left > cursor:
break
cursor = max(cursor, right + 1)
if cursor > end:
break
if cursor <= end:
return False
return True
def review_snapshot(source, review, required):
"""Inputs are caller assertions, not authenticated evidence or proof of reading.
Line numbers are one-based and inclusive. Hash equality compares metadata;
it does not read/hash files or validate their semantic content.
"""
_keys(source, ['id', 'version', 'sha256', 'line_count'])
_keys(review, ['source_id', 'version', 'sha256', 'line_count', 'ranges'])
source_id = _text(source['id'])
if _text(review['source_id']) != source_id:
raise ReviewError('SOURCE_MISMATCH')
version, reviewed_version = _text(source['version']), _text(review['version'])
digest, reviewed_digest = _hash(source['sha256']), _hash(review['sha256'])
total, reviewed_total = _count(source['line_count']), _count(review['line_count'])
ranges = _ranges(review['ranges'], reviewed_total)
needed = _ranges(required, total)
if not needed:
raise ReviewError('REQUIRED_RANGE_EMPTY')
current = (version, digest, total) == (reviewed_version, reviewed_digest, reviewed_total)
covered = current and _covers(ranges, needed)
return {
'source_id': source_id,
'freshness': 'current' if current else 'stale',
'requested_coverage': 'covered' if covered else ('missing' if current else 'unresolved_after_change'),
'reviewed_lines_in_snapshot': sum(end - start + 1 for start, end in ranges),
'whole_current_source_declared_reviewed': current and _covers(ranges, [(1, total)]),
'eligible_as_current_source_note': covered,
'proves_execution': False,
'proves_semantic_truth': False,
'publishes_content': False,
}
State precisely what a passing result does not establish
Eligibility means that the required intervals are declared reviewed in the same source version. The execution-proof, semantic-truth and publication fields always remain false. A record of reading code cannot substitute for a successful program run, verified interpretation or actual website publication.
Twenty-one tests cover adjacent coverage, emptiness, gaps, multiple requirements, full coverage, changed hashes, versions, line counts and wrong sources. They also reject overlap, reverse order, booleans as line numbers, out-of-bounds ranges and unknown fields. Separate assertions check unchanged inputs and the absence of an execution certificate.
The displayed records come from actual synthetic execution
Five records show current partial coverage, unread required lines, changed source, a declared whole-file review and rejection of another source ID. Local Python generated them. The selector only displays their JSON; it reads no visitor files and runs no Python in the page.
After the source-folder tests, the package procedure compares each ZIP entry hash, extracts into a separate test folder and runs the same twenty-one tests. The actual inline selector code for both languages is checked against records with DOM stubs. This is verification of the independent synthetic module, not rendered-browser review or complete inspection of another program.
What a real editorial ledger still needs
The public ZIP contains the implementation, tests, record generator and README, using only the standard library and permitting modification and reuse. A real collector must retain snapshots and compute actual hashes; an editor selects required intervals before this function compares them. Internal IDs can connect private evidence without putting file paths or customer text in public input.
The module cannot select relevant lines or detect semantic overlap with an existing article. Historical tests, current implementation and publication evidence need separate records. I share it as a small tool for remembering the scope of a review, not a claim that automation replaces editorial judgment. Collection, interpretation and publication must retain distinct responsibilities when real evidence is connected.