PipeWhy local execution contract X1 version1.0 | PW-15.01-.07 | Q1 v1.0
November2,2026 | selected user decision D9

Integration scope
The user selected local worker processes and local snapshots. Use the Python
standard-library process executor and a local filesystem journal; publish C5 via
the existing immutable LocalSnapshotStore. No remote service/authentication,
executor SDK, distributed database or additional dependency is selected. This is
single-host parallel execution, not a multi-machine deployment qualification.
First connector integration is pinned Enron; reference/CPU worker backends share
the existing C2/C3 semantics. Existing sequential CUDA remains available; parallel
GPU scheduling is outside the first worker profile and must never silently fall
back. Public execution APIs and source adapters remain separate from executor
implementation so a future integration can supply the same validated envelopes.

Partition identity (PW-15.02)
Persist a versioned immutable execution plan before dispatch. Its content identity
includes source namespace, full revision, source manifest identity, selected
artifact/scope, schema/profile/algorithm/mode, ordered partition inventory and
execution policy. Cache paths and display labels do not define logical identity.
Each partition identity binds that immutable source/context to its input selector,
logical dataset ID, start and expected count. Attempts do not change partition ID.
The plan/run identity in every receipt prevents mixing results from another plan.
Use the existing canonical JSON/strict manifest decoding and uint64 validation;
reject unknown versions/fields, duplicate keys and noncanonical integer words.

Partition boundaries (PW-15.03)
Initial Enron partitions are physical pinned shards, not new C1 artifacts. Obtain
their exact row counts from verified Parquet metadata; retain the fixed logical
train artifact1. Lexicographic shard/physical row order defines adjacent global
record spans. Validate the complete inventory and sum against the source manifest.
Every planned shard, including an empty shard, requires successful verification.
A shard reader is explicitly a partition API and cannot claim full-dataset scope.
Normalize through the same bounded C2 conversion as the sequential reader.
Ordered C3 workers use the assigned global start; multiset C3 uses its existing
sentinel while the envelope independently retains the assigned span. Counts and
range arithmetic must fit C3's uint64 domain without overlap, gaps or overflow.

Worker envelope (PW-15.04)
Versioned results bind plan ID, partition ID, source revision/manifest/context,
input selector/span, attempt number and resolved backend. COMPLETE requires a
validated C3 state whose count/span/context equal the assignment and successful
source-integrity checks. Failure results contain no comparable state. Preserve
safe reason codes and rows processed separately from successful coverage counts;
never serialize email values or parser tracebacks as routine diagnostics.
Workers read only explicitly prepared local source data and return small states;
they do not mutate accepted-result journals or published snapshots.

Retry/terminal policy (PW-15.05)
Persist attempt reservation before dispatch. Bound attempts and in-flight tasks;
record worker deadlines explicitly as an operational policy, not a workload SLA.
Source identity/schema/integrity/permission and invalid-result failures are
permanent for that run. Lost worker/transport/timeout failures may retry only while
the persisted budget permits, under the same plan/partition identity. An exhausted
or permanent failure remains explicit. No retry may substitute another revision,
change normalization/backend, erase a failure or turn missing work into empty data.
Use monotonic clocks for live deadlines; after restart, interrupted reservations
are lost attempts rather than interpreting another process's monotonic timestamp.

Merge/receipt acceptance (PW-15.06)
Validate a result against the immutable plan before writing or contributing it.
Reject mismatched versions, source/scope/context/ranges, unexpected partitions,
invalid attempt numbers, counts, statuses or state words. Persist each accepted
partition exactly once. Exact retransmission is idempotent; conflicting duplicate
or late/mixed-plan results are rejected without changing accepted/published state.
Merge accepted states in manifest order, not completion order; ordered ranges must
be adjacent. C3 arithmetic and the independent reference define the result.
Reconcile every planned partition as complete, failed or missing. Partial accepted
counts are progress, not a complete dataset fingerprint. A dataset lacking any
required partition has no comparable complete state. Final C5 publication must
retain that distinction and the existing explicit UNKNOWN Enron lineage.

Restart/recovery (PW-15.07)
Use owned per-run directories, immutable plan/accepted-result files, staged atomic
publication and an OS-owned coordinator lock released on process death. Refuse a
second live coordinator. No unverified partial file is an accepted receipt.
Resume validates all persisted identities/checksums and reuses accepted results
without recounting. Attempt history survives restart; interrupted attempts consume
their reservation. A crash between accepted-result persistence and final merge
must not duplicate contribution. Worker processes cannot publish late results
directly into the journal; the coordinator validates them first. Completed output
is immutable, with exact duplicate acknowledgement allowed and mutation rejected.
Missing/corrupt/conflicting journal state is explicit failure, not a fresh run
silently replacing the old one. Any retry of permanent failure needs a new run or
an explicitly defined future recovery policy.

Qualification and budgets
Meaningful units/95% Coverage.py, Black,ty,deptry, distribution/source checks and
small issue-linked commits apply to every component. Test duplicate/out-of-order
delivery, wrong versions/ranges/counts, empty shards, lost worker, interrupted
reservation/receipt/publication and restart. Compare controlled Enron execution
against sequential reference in both C3 modes/profiles and the actual corpus.
Prove no incomplete/mixed-version result can become a complete C5 observation.
Runtime/memory/workload acceptance budgets remain D8; local timeout/worker/retry
defaults must be explicit implementation policies, not invented user SLAs.

This is a specification, not a claim that the executor or its qualifications are
implemented. Q1 documentation-only review applies here; no new Python coverage
pass is claimed by this planning change.

PW-15.08 planning component evidence
ExecutionPlan/Partition and prepare_enron_execution now validate and persist the
complete source/context/range inventory plus source manifest before any dispatch.
Canonical uint64 metadata, immutable identities, bounded documents, source hashes,
conflicting writes, temporary cleanup and offline reopening are enforced. Empty
shards remain explicit partitions. Cache relocation does not change plan identity.
Current operational policy:default4 workers,2 attempts,600000ms timeout,128 Arrow
rows;portable maxima61 workers,10 attempts,86400000ms timeout,65536 Arrow rows.
Plan and source metadata each have a4MiB cap. No new dependency was introduced.
Actual Enron planning verifies3 adjacent172467-row shards,total517401, persists
and reopens plan cb33b0da565a37f5df2048952d3be66deb64e0e745c9fdd89931db186d765745.
No workers were dispatched and no C5 completion is claimed by this component.
Q1 v1.0:3068 units,6391/6418 statements=99.579308%,combined99.361416%,zero
exclusions;all new execution modules100% statement coverage. Black,ty,deptry pass.
Both current wheel forms pass fresh isolated core inventories/pip/entry-point
checks.58 focused plan/footer/persistence tests pass. Evidence:
.tools/execution-planning-quality.log,.tools/execution-planning-targeted.log,
.tools/execution-plan-qualification.log,.tools/execution-planning-distribution.log,
.artifacts/execution/enron-plan-receipt.json,coverage-unit.json/XML.

PW-15.09/.10 single-partition worker and result validation evidence
iter_shard_batches uses the same bounded conversion/verification core as complete
Enron iteration, checks its assigned footer count and never advertises full scope.
execute_partition loads immutable plan/source metadata, enforces the selected
Enron contract/current profile and attempt budget, then reads only its assigned
shard through reference or CPU C3 using the correct global ordered offset.
It does not contact upstream, write journal results or publish C5 observations.
Versioned TaskIdentity/WorkerResult envelopes bind run/plan/partition, source
revision/manifest/context and backend. Validation rejects unsupported fields,
versions, noncanonical words, wrong source/run/context/ranges/counts/attempts and
invalid C3 wire state. Failed results contain safe codes/progress and no state;
only explicit transport/lost-worker/timeout failures can be marked retryable.

Q1 v1.0:3130 units passed,6536/6564 statements=99.573431%,combined99.364592%,zero
exclusions. Black,ty,deptry pass;137 targeted worker/reader/capture regressions pass.
Both current distribution forms pass independent fresh core module/pip/entry-point
checks; no new dependencies. Controlled workers match independent sequential C3
across both modes/profiles/backends, including empty shards and source failures.
Actual3 spawned Windows worker processes consume all517401 Enron rows, complete in
order2,1,0 and return validated compact states. Manifest-order merging exactly
matches the previous full CPU/CUDA state. Observed83.003787s is qualification, not
a release benchmark/SLA; no peak memory or native-instruction coverage is claimed.
No C5 snapshot was published by this worker qualification. Coordinator receipt,
durable attempt authority, retries/resume and final publication remain subsequent.
Artifacts:.tools/execution-workers-quality.log,.tools/execution-workers-targeted.log,
.tools/execution-real-workers.log,.tools/execution-workers-distribution.log,
.artifacts/execution/enron-worker-receipt.json,coverage-unit.json/XML.

PW-15.11/.12/.13 receipt, deterministic merge and coverage evidence
RunJournal creates unique runs with checksummed immutable headers and source-bound
plans. Complete/failure receipts are checksummed and atomically admitted without
overwrite. Exact delivery replays return false without adding contribution;
conflicting states, wrong runs/filenames, stale/permanent failures and corrupted
payloads are rejected. Failed results never enter the accepted-state collection.
Reopening validates every receipt and reconciles all planned IDs. Manifest-order
C3 merging is deterministic across arrival order, modes and empty shards. Accepted
row totals are progress; a missing zero-row shard still prevents a complete state.
Conflicting accepted/failure history cannot be hidden by a complete receipt.
Attempt scheduling authority/locking/retry-resume and C5 publication remain next.

Q1 v1.0:3146 units passed,6661/6694 statements=99.507021%,combined99.269603%,zero
exclusions. Black,ty,deptry pass;136 focused execution tests pass. Both current
wheel forms pass independent fresh core inventories/pip/entry-point checks, then
reopen the actual complete journal without Arrow/NumPy. No dependencies added.
Three actual workers return2,0,1; each result is received twice but counted once.
Disk reopening reconstructs all517401 records and the exact full CPU/CUDA state;
intermediate incomplete journals expose no comparable full fingerprint. No C5
observation is published by this receipt qualification. Artifacts:
.tools/execution-journal-quality.log,.tools/execution-journal-targeted.log,
.tools/execution-real-journal.log,.tools/execution-journal-distribution.log,
.tools/execution-journal-installed.log,.artifacts/execution/enron-journal-receipt.json,
coverage-unit.json/XML.

PW-15.14/.15 automatic supervision and restart acceptance
execute_run creates a new explicit run; resume_execution holds its OS lock,
validates the exact persisted plan/source and recovers interrupted reservations.
The spawned process pool has at most the selected number of outstanding tasks.
The per-attempt deadline starts after submission and bounds time until coordinator
observation, including worker startup. Timed-out/lost pools are killed; remaining
unaccepted work is recorded as timeout/lost and retried only while budget remains.
Unexpected process exceptions and malformed/mismatched envelopes become safe
permanent failure codes. Journal/storage errors propagate and leave durable
reservations for explicit recovery. A completed resume dispatches no new work.

Q1 v1.0:3184 units pass;6932/6967 statements=99.497632%,combined99.234667%,
zero exclusions;coordinator100% statements;Black,ty,deptry pass.14 supervisor units
and7 real-process cases qualify both modes/profiles, empty shards, killed/hung
workers, finite attempts and preservation of accepted work. Both fresh wheel forms
pass isolated inventory/pip/entry-point checks and reopen the actual complete run
and attempt authority without Arrow/NumPy. No dependencies were introduced.
Actual Enron run278ba1c441d04f99871b3840fd9d2e64 accepts517401 records in3 attempts
with0 failures, exactly matches full CPU/CUDA C3 and leaves all receipts unchanged
on resume.179.106103s scan/.309401s completed resume are loaded-workstation
qualification observations, not D8 budgets or controlled release measurements.
C5 publication remains PW-15.16. Native source CI follows the pushed revision;
no pending native job is reported as successful. Artifacts:
.tools/execution-supervisor-final-quality.log,
.tools/execution-supervisor-targeted.log,.tools/execution-supervisor-processes.log,
.tools/execution-real-supervisor.log,.tools/execution-supervisor-final-distribution.log,
.artifacts/execution/enron-supervisor-receipt.json,coverage-unit.json/XML.

QA-02/#336: native run143 against0eaf227 exposed an existing wall-clock rollback
in scan_source: finished_at_ns preceded started_at_ns. Commit a0e0d82 anchors
capture/observation timestamps to initial wall time plus monotonic elapsed time;
strict C5 metadata validation is retained. Both clock directions have regressions;
77 capture/bundle checks and the3184-unit quality gate above pass. Build/install
checks include the clock fix. This is not a release duration measurement method
across coordinator restarts. Source CI will verify the combined pushed changes.

Native follow-up verifies unit, integration, failure-gate and installed-package
checks for the supervisor and clock behavior described above.

PW-15.16-.20 publication and end-to-end verification
publish_execution holds the coordinator OS lock, validates the exact plan/source
and attempt ledger, and requires an accepted current result for every partition,
including zero-row shards. It never publishes a complete fingerprint for partial
progress. It seals a source/plan-bound publication intent before C5 writes and
uses the run ID as snapshot ID. Replays compare metadata and all array bytes;
conflicts/corruption are rejected without overwriting an existing snapshot.
Interruptions before or after store publication replay the same frozen intent.
The gate uses existing LocalSnapshotStore staging/checksum/atomic publication and
the shared capture serializer. Ordinary/parallel scans produce the same C5 format;
no alternative snapshot format, third-party dependency or email retention is added.
Stored captures retain UNKNOWN lineage and the explicit missing-lineage reason.
Run creation/publication wall times form a nonnegative metadata interval, bounded
below by run creation when a restarted host clock moves backward. They are not
benchmark durations. Publication does not reread source files and remains usable
with core-only installs; workers independently verified pinned source bytes.

Q1 v1.0:3205 units pass;7017/7052 statements=99.503687%,combined99.242889%,zero
exclusions;publication and shared serializer100% statements. Black,ty,deptry pass.
21 publication units test empty/missing/failed work, wrong plan/source, late wrong
version results, conflicting same-ID metadata/arrays, corrupt intent, and simulated
interruptions before/after publication.7 real-process cases include4 controlled Enron
comparisons against ordinary sequential source capture across both profiles/modes,
plus killed worker, timeout and resume. Earlier exact duplicate/out-of-order and
strict envelope/range/version tests remain in the complete unit gate.
Both current wheel forms pass fresh isolated inventory/pip/entry-point checks,
then replay the actual publication and reopen C5 without Arrow/NumPy/source reads.
Actual complete Enron run278ba1c441d04f99871b3840fd9d2e64 publishes517401 rows with
the exact full CPU/CUDA C3. Repeated publication leaves every C5 file hash unchanged.
30 installed core-only read/export commands pass JSON/text/CSV/DOT validation,
CSV companion checksums and explicit UNKNOWN-lineage behavior. Source CI for this
new publication component remains pending until the pushed revision completes;
PW-15 parent acceptance waits for that native success. Artifacts:
.tools/execution-publication-verified-quality.log,
.tools/execution-publication-unit-current.log,
.tools/execution-publication-processes.log,.tools/execution-publication-distribution.log,
.tools/execution-real-publication.log,.tools/execution-publication-exports.log,
.artifacts/execution/enron-publication-receipt.json,
.artifacts/execution/export-qualification.json,coverage-unit.json/XML.

Final native/parent acceptance: run146 against exact332564eacbfacb6d7b09618e3bab3c0c9e27ab37
is successful.3205 units,7020/7052 native statements,99.27% combined,59 integrations,
7 negative gates and both distribution forms/core/CPU/CUDA/Enron profiles pass.
PW-15 parent is closed after all20 child issues were checked closed. The selected
local backend and C5 publication are complete; D8 numeric limits and PW-16 release
acceptance remain in progress. Artifacts:.tools/execution-publication-native-full.log,
.tools/execution-parent-finalized.log. This parent receipt claims no fresh coverage.

PW-15.14/.15 durable attempt authority and process ownership component
AttemptLedger seals a reservation before dispatch, enforces contiguous attempt
history and finite plan budgets, and admits outcomes only for the latest reserved
attempt. Accepted results survive reopening; interrupted attempts consume a slot
and become explicit WORKER_LOST failures. Permanent failures are not eligible for
retry. Missing/corrupt authority is rejected rather than silently initialized.
coordinator_lock uses OS file ownership on Windows/POSIX and keeps the lock inode;
normal exit and process death release ownership without deleting history.
These supported APIs are implemented; automatic pool dispatch/deadlines and C5
publication remain pending. PW-15.14/.15 are in progress, not completed here.
Q1 v1.0:3168 units pass;6825/6860 statements=99.489796%,combined99.244808%,
zero exclusions;Black,ty,deptry pass. Both fresh wheel forms pass isolated core
inventory,pip and entry-point checks; no new dependency. An actual second process
is excluded while the owner lives; killing the owner releases the lock; a fresh
interpreter preserves one accepted synthetic record, consumes the interrupted
attempt and exhausts its next timeout without creating a complete fingerprint.
Artifacts:.tools/execution-resume-quality.log,
.tools/execution-resume-distribution.log,.tools/execution-real-resume.log,
.artifacts/execution/resume-probes/665b8a52b35f45a3983af7952cbc4fd0,
coverage-unit.json/XML. D8 baseline-derived numeric limits are authorized but not
yet measured or frozen; this qualification does not establish release budgets.