404-solution / includes / DataAccessTrait_MutationWatermarkSeam.php

DataAccessTrait_MutationWatermarkSeam.php in 404 Solution 4.1.19, at includes/DataAccessTrait_MutationWatermarkSeam.php

68 lines 3.1 KB

Raw Download Zip

1	<?php
2
3	if (!defined('ABSPATH')) {
4	exit;
5	}
6
7	/**
8	* Source-mutation seam wrapping ABJ_404_Solution_MutationWatermark::bump().
9	*
10	* Every admin / REST / CLI / AJAX mutation that changes the redirects (or
11	* logs) source data calls $this->dao->bumpMutationWatermark() so the
12	* staged-build runner sees a higher counter than active_build_started_
13	* watermark at the next stage boundary and aborts cleanly. This is the
14	* single seam external callers reach into; the bump primitive itself
15	* lives on the static ABJ_404_Solution_MutationWatermark class
16	* (includes/MutationWatermark.php) so its atomic-INSERT contract stays
17	* decoupled from the DAO's connection-aware retry harness.
18	*
19	* Phase 3 Cluster A (queue t_260516_131217_769) wires the 14 admin call
20	* sites in PluginLogicTrait_AdminActions.php to this seam, paired with
21	* the existing markViewDoneInvalidatedByAdminMutation() admin-visibility
22	* seam. Phase 4 (queue c570) rewrites markViewDoneInvalidatedByAdmin
23	* Mutation() to record mutation_watermark_observed_by_admin_action
24	* against the watermark value rather than the unix-timestamp gate; until
25	* then both signals fire and the admin-visibility contract stays pinned
26	* by PostMutationViewDoneVisibilityTest.
27	*
28	* Why route through the DAO instead of calling the static method
29	* directly. Unit-test DAO stubs (the anonymous classes in
30	* AdminRedirectFormValidationTest, RegexAutoPromoteAdminSaveTest, and
31	* siblings) don't initialize a real $wpdb; the static bump() would
32	* fatal on its INSERT. The DAO seam lets every such stub provide a
33	* one-line no-op override, mirroring the existing markViewDone
34	* InvalidatedByAdminMutation stub pattern. The integration suite
35	* (LocalMariaDBServer-backed AdminMutationEndToEndCharacterizationTest)
36	* keeps the real bump in scope via the inherited DataAccess class.
37	*
38	* Lives in its own tiny trait, not on DataAccessTrait_ViewQueriesStaged,
39	* so the staged-queries trait stays under the 1500-line ModularityTest
40	* cap; the seam is conceptually the source-mutation counterpart to
41	* DataAccessTrait_ViewBuildForceRestart.php (runner-owned) so a parallel
42	* dedicated file is the right shape.
43	*
44	* @see docs/refactor-staged-view-build-watermark.md Phase 3.
45	* @see includes/MutationWatermark.php for the atomic-INSERT body.
46	*/
47	trait ABJ_404_Solution_DataAccess_MutationWatermarkSeamTrait {
48
49	/**
50	* Bump the per-blog mutation watermark to signal "source redirect /
51	* logs data changed". Returns the post-increment counter value (the
52	* caller's own contribution, surfaced via $wpdb->insert_id per the
53	* LAST_INSERT_ID(expr) trick in MutationWatermark::bump()), or 0
54	* when the watermark class is not yet loaded (defensive guard for
55	* cold-bootstrap paths that could hit this seam before the
56	* autoloader has resolved MutationWatermark.php).
57	*
58	* @return int Post-increment counter value, or 0 if the primitive
59	* is unavailable.
60	*/
61	public function bumpMutationWatermark(): int {
62	if (!class_exists('ABJ_404_Solution_MutationWatermark')) {
63	return 0;
64	}
65	return ABJ_404_Solution_MutationWatermark::bump();
66	}
67	}
68