Semantic Singleflight Dedup Runtime

It collapses repeated runs of the same command into one, deciding sameness by a content key over the state the command depends on and reusing a completed run. This component collapses repeated runs of the same command into one. It decides whether two runs are "the same" by building a content key from the state the command actually depends on, then reusing a completed run instead of executing it again.

Real subprocess exercises through singleflight

It drives the command_run_singleflight bundle over fixture exercises that run real subprocesses, so a counter incremented twice stays at 1 when the duplicate run reuses the finished result. It surfaces one public bundle, command_run_singleflight, and drives it over a small set of fixture exercises. Each exercise runs a real subprocess in a temporary working directory, so the reader can watch a duplicate run reuse a finished result rather than take the claim on trust. The counter exercise makes this visible: a side-effecting command that increments a file runs once, and the counter stays at 1 even though the command is issued twice.

The result is metadata-only records of status, per-case rows, and a card, with no captured output, environment values, or absolute paths written in. The result is a set of metadata-only result records: a status, per-case rows, and a short card. No captured command output, no environment values, and no absolute paths are written into the records.

Purpose

The hard part is deciding sameness

Re-running wastes work but reusing a stale result is worse, and a loose key that reads only the command words reuses answers after the tree has changed. Re-running an identical command wastes work. Reusing a stale result is worse, because the second caller gets an answer computed under different state. The hard part is deciding when two runs count as the same run. A loose key that reads only the command words will happily reuse a result after the working tree has changed underneath it.

An explicit content key over repo state

It answers with an explicit content key that folds in repo state, so a meaningful change changes the key and a follower never reuses a result from unshared state. This component answers with an explicit content key rather than a guess. The key folds in repo state, so a change that matters to the command changes the key, and a follower never reuses a result computed under state it did not share.

How it works

build_result tallies positive and negative rows

build_result runs each fixture case through _evaluate_case and passes only when at least one positive and one negative case are present and every case behaves as required. build_result is the pipeline entry. It loads the fixture cases from the input directory, runs each one in a fresh temporary scratch directory through _evaluate_case, then tallies the rows. It marks the whole run pass only when there is at least one positive case and one negative case, every positive case was observed to pass, every negative case fired its guard, and both declared negative case ids in EXPECTED_NEGATIVE_CASES are present. Otherwise the status is fail. run calls build_result and writes the result record, the card from result_card, and a validation record.

_evaluate_case dispatches on the case's exercise field and calls into the bundle. Two bundle functions carry the mechanism. _evaluate_case dispatches on the case's exercise field and calls into the bundle. Two bundle functions carry the mechanism.

The content key from argv, cwd, and dirty tree

build_command_key hashes argv and cwd, folds in git HEAD and scoped diffs or scoped file contents, adds a bounded env fingerprint, and carries only hashes and labels. build_command_key computes the content key. It hashes the argv, hashes the resolved working directory, and records the resource class and scope paths. For the dirty-tree part it looks for a git root: inside git it folds in HEAD, the porcelain status, the working diff, and the staged diff for the scoped paths; outside git it falls back to hashing the scoped file contents. It also records an environment fingerprint limited to PYTHONPATH and PYTEST_ADDOPTS. The key carries hashes and labels, not absolute paths, so records stay public-safe.

Per-key lock assigns leader, follower, or reused

run_command_singleflight rejects empty argv, takes an exclusive per-key lock, and assigns the caller as leader, follower, or reused, running the subprocess only once. run_command_singleflight performs the collapse. It rejects an empty argv before doing anything else. It builds the key, hashes it into a short key hash, and takes an exclusive file lock keyed by that hash. Under the lock it reads the active state for the key and chooses a role. If a run is active and its process is alive, this caller becomes a follower, waits, and replays the leader's captured output. If a run is already completed and the caller passed reuse_completed, it returns the reused record without executing. Otherwise it becomes the leader, runs the subprocess once, and captures the output for later followers. The returned record names the role: leader, follower, reused, or a stale-or-timeout record if an active run never completed.

flowchart TD Argv["argv + cwd + scope"] Key["build_command_key content key + key hash"] Lock["run_command_singleflight exclusive per-key lock"] Leader["new key leader runs once"] Reused["completed key reuse captured result"] Reject["empty argv rejected"] Argv --> Key Key --> Lock Lock --> Leader Lock --> Reused Argv --> Reject

Negative cases

Two positive exercises: leader and reuse

The two positive exercises are single_leader, where a first run leads and returns its output, and completed_reuse, where the counter stays at 1 as a second run reuses it. The fixtures include two positive exercises and two negative ones. The positive exercises are single_leader, where a first run becomes the leader and returns its captured output, and completed_reuse, where a second run reuses the completed run and the side-effecting counter stays at 1.

Scope mutation and empty argv fail closed

The negative exercises confirm that rewriting a scoped file changes the dirty fingerprint and an empty command is refused, both firing their guards or the run fails. The negative exercises are the point of the check. scope_mutation_changes_key builds the key for a scoped file holding "before", rewrites the file to "after", builds the key again, and confirms the dirty fingerprint changed. A stale working tree cannot answer for a different run, so its guard SINGLEFLIGHT_STALE_STATE_CANNOT_DEDUP is expected to fire. missing_command_rejected passes an empty command and confirms it is refused before any run starts, firing SINGLEFLIGHT_EMPTY_ARGV_REJECTED. Both fail closed: the run reports fail if either guard does not fire.

Prior Art Grounding

Request coalescing plus content-addressed caching

The lineage is request coalescing and content-addressed caching, with repo state added to the key so a working-tree change invalidates reuse. The engineering lineage is request coalescing, the pattern where concurrent callers for the same key share one computation and the rest wait for its result, combined with content-addressed caching, where the cache key is a hash of the inputs rather than a name a caller chose. The bundle adds repo state to that key so that a change to the working tree invalidates reuse. The local prior art is the Plectis paper-module coverage contract: a reader page states which source row or public fixture can be checked, which generated projections are navigation aids, and which claims stay outside the evidence boundary.

Validation Result record Path

Run the component over its bounded fixtures and its test:

Coverage and corpus-parity validation

From the repository root, rerun the public coverage contract and the corpus parity check: From the repository root, rerun the public coverage contract and the corpus parity check:

PYTHONPATH=src ./repo-pytest tests/test_plectis_paper_module_coverage_contract.py -q --tb=short
PYTHONPATH=src ./repo-python scripts/build_doctrine_projection.py --check-paper-module-corpus

What a pass over the fixtures means

A pass means the content key deduplicated the fixture commands, the counter fired once, and both negative guards fired, and any source change means refreshing and rerunning. A pass means the content key deduplicated the bounded fixture commands, the counter side effect happened once, and both negative guards fired. If a later pass changes the bundle source, fixture manifest, runtime locus, or record authority, refresh this page and rerun these commands.