feat: transactional fingerprint finalization via FingerprintTransaction (#1926)

[prompt-driven-github]

Summary

Implements the runtime fix for #1926: one FingerprintTransaction now owns fingerprint hash calculation, validation, serialization, and atomic persistence for every mutating PDD path.

Closes #1926

What changed

• Added pdd/fingerprint_transaction.py with canonical payload construction, complete existing-path hash validation, explicit skip semantics, typed diagnostics, and shared crash-safe atomic JSON persistence.
• Routed save_fingerprint, sync atomic state, one-session sync, generate/example/fix logging, update, auto-deps, metadata sync, CI heal, continuous sync, and the legacy pin-example path through the transaction.
• Made required finalization fail closed: path resolution, stale run-report cleanup, hashing, buffering, or persistence failures now prevent a green command outcome.
• Added complete path-set resolution so untouched example/test hashes are preserved and nested projects write metadata under the correct .pddrc root.
• Added a CI-collected post-command freshness harness for sync, generate, example, update, update --all, auto-deps, fix, and CI heal.
• Added combined regressions for CI auto-heal can loop forever because example writes null fingerprints and heal_update keeps regenerating examples #1305 null hashes and pdd fix from a parent dir writes orphan files to run cwd instead of the subproject #1211/Follow-up to #1211: save_fingerprint doesn't thread project_root, e2e tests don't catch the bug #1290 wrong-root writes.
• Updated prompts, architecture dependencies, README, runnable example, fingerprints, and legacy tests to the enforced contract.
• Reconciled and retained the concurrent automation commit without overwriting branch history.

Acceptance criteria

• One shared finalization implementation; legacy helpers delegate to it.
• Atomic same-filesystem persistence; no partially written JSON replacement.
• Required fingerprint failure prevents command success.
• Post-command freshness property harness is collected by normal pytest CI.
• CI auto-heal can loop forever because example writes null fingerprints and heal_update keeps regenerating examples #1305 null-hash loop regression passes.
• pdd fix from a parent dir writes orphan files to run cwd instead of the subproject #1211/Follow-up to #1211: save_fingerprint doesn't thread project_root, e2e tests don't catch the bug #1290 wrong-root regression passes.

Verification

• Full GitHub Actions-equivalent unit matrix: 12,906 passed, 31 skipped, 1 expected failure.
• Focused fingerprint/sync/update/auto-deps/metadata/CI-heal regressions: 777 passed.
• Post-reconciliation maintenance, architecture, transaction, and invariant batch: 85 passed.
• Repository and fixture architecture/include validation: pass.
• The real drift classifier reports nothing for the new fingerprint source set.
• Python bytecode compilation, JSON parsing, and git diff --check: pass.

Stack

This is the base PR for the #1939 schema/mock contract follow-up. That implementation will target change/issue-1926 so the stack remains explicit until this base lands.

[Serhan-Asad]

Verification update for commit 3295ac99:

• Repaired the previous prompt-only PR with the actual runtime module, runnable example, caller migrations, fail-closed Click behavior, and CI-collected invariant tests.
• Deterministic affected/contract suite: 783 passed, 1 skipped.
• Sync orchestration/main/pin suite: 308 passed. The remaining 6 local cases launch nested pytest and exit -11 with empty output on this macOS host; the same failures reproduce on untouched origin/main, so they are documented as a host baseline rather than PR regressions.
• New transaction/invariant/example pylint: 10.00/10.
• Compile check, example execution, architecture JSON parse, prompt/architecture contract gates, and git diff --check: pass.
• Branch includes current main; GitHub reports the PR MERGEABLE.

Acceptance evidence:

• tests/test_fingerprint_transaction.py: atomic same-directory replace, no partial overwrite, null-hash hard failure, eager root resolution, skip/exception behavior, dependency override.
• tests/test_fingerprint_invariant.py: all seven mutating workflows route through the transaction and converge through sync_determine_operation(log_mode=True).
• Existing update/auto-deps/metadata/CI-heal tests now assert finalization failure is non-zero, not a warning followed by success.

Remote Linux unit tests, CodeQL, and auto-heal are currently running.

[Serhan-Asad]

Final verification is complete for this campaign fix.

GitHub CI

• Head: 5bd2d6c1b13ad66532c35cf808b753adc1ce28e2
• 11/11 checks passed; 0 pending; 0 failing
• Full Run Unit Tests job passed (25m16s)
• Public CLI Regression, Story Regression, Package Preprocess Smoke, Repo Bloat Docker E2E, all CodeQL analyses, and both auto-heal/heal checks passed
• PR is ready, mergeable, and reports a clean merge state

Local verification

• Architecture-vs-prompt include validation: pass
• Public regression target: pass
• Combined issue implementation suite: 931 passed, 15 deselected, 0 failed
• Coverage-validation groups: 332 passed and 249 passed
• Exact CI drift detector: TOTAL=0

The 15 local deselections comprise 9 intentional marker exclusions plus 6 known macOS nested-pytest -11 baseline cases reproduced on untouched main; none is introduced by this PR. No merge to main was performed here. This fix is included in manager bundle PR #1998.

[Serhan-Asad]

Superseded by #1984, which now targets main and contains the complete combined implementation for #1926 and #1939. Closing this PR without merging so the pdd changes have one landing PR.