Role: design and implementation of this new public reference system.
Intended user: an engineer reviewing revisions to a technical specification.
Maturity: working local implementation with automated checks. No production customer-use claim.
The problem is omission, not just explanation.
A useful specification review must identify changed requirements and let someone verify them. Asking a model to summarize two whole PDFs makes it difficult to see what it missed. This system computes the change inventory first, then optionally asks a model to explain its significance.
The architecture keeps evidence independent.
- Submit and identify. Bound request size, hash both PDFs, store the pair and an idempotency key.
- Claim a durable job. A worker receives a lease and fencing token in one SQLite transaction.
- Extract and compare. A bounded child process extracts page text. Code creates a complete inventory within explicit size limits.
- Optionally interpret. A model annotates every change. Schema, reference and coverage checks reject unsupported output structures.
- Review and export. Human decisions use version checks and append events. Export the evidence and trace as PDF or JSON.
A real local comparison
The two newly authored fictional specifications change five event-gateway requirements. The values below come from PDF extraction, not a generated account of the documents.
| Earlier revision | Later revision | Source |
|---|---|---|
| Each request may contain up to 100 events. | Each request may contain up to 250 events. | p. 1 |
| Idempotency keys remain valid for 24 hours. | Idempotency keys remain valid for 72 hours. | p. 2 |
| Events are retained for 7 days. | Events are retained for 3 days. | p. 2 |
| Retries use a fixed delay of 5 seconds. | Retries use exponential backoff with a maximum delay of 60 seconds. | p. 3 |
| The legacy status endpoint is /v1/status. | The legacy /v1/status endpoint is removed; use /v2/health. | p. 3 |
Inspect the actual execution trace
These events were written by the local worker. They describe application execution, not a model's private reasoning.
- queued{"old_sha256": "baf9a0e5ba511061f93be7dd56c5c97712ba6d82f5004a118c73a9d35739b522", "new_sha256": "b9facd87f38108f218757b820afc2aae810d3f1523409f3f69db3852233418e6", "mode": "evidence", "pipeline": "pipeline-v1"}
- claimed{"attempt": 1, "fence": 1, "recovered": false}
- extracted{"old_pages": 3, "new_pages": 3, "elapsed_ms": 177}
- diffed{"change_count": 5, "evidence_count": 10}
- review{"error_code": null, "annotation_status": "not_requested"}
Recovery is part of the implementation.
If a worker dies, its lease can expire and another worker can reclaim the job. A stale worker cannot publish over the new owner because completion checks the fencing token. This is at-least-once processing; it is not an exactly-once provider-call guarantee.
Transient model failure gets one retry. If annotation remains unavailable, the source comparison is preserved. Invalid references or incomplete change coverage reject the annotation set. The reviewer never has to mistake an unavailable explanation for “nothing changed.”
What has been tested?
The automated suite covers duplicate submissions, concurrent claims, expired leases, stale publication, reviewer conflicts, unsupported PDFs, citation coverage, provider failure and exports. A separate authored regression corpus covers identical documents, repagination, whitespace, additions, deletions, negation and changed units.
8 of 8 authored extraction/diff regression cases passed in the recorded local run. This is a small regression corpus, not a representative accuracy benchmark. No model was called.
Inspect every regression case and observed resultWhere the system stops
Text extraction does not understand every table, diagram, scan or layout change. Exact source references establish provenance, not the truth of a model's interpretation. The current deployment is local and single-user. Public uploads would require stronger parser isolation, authentication, ownership controls, budgets, monitoring and evaluation on representative documents.
Those are named release requirements, not capabilities inferred from the presence of a database or a test suite.
Read the tradeoffs and readiness boundary →