From f30ec9d1f937f6485946de53afe15c6db46bd277 Mon Sep 17 00:00:00 2001
From: Tony Hegyes <a.hegyes@proton.me>
Date: Sun, 21 Jun 2026 16:37:17 +0200
Subject: [PATCH 01/21] refactor(framework): relocate WC-order field store out
 of settings; add ObjectField module; group WC SettingsPage
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Pre-Phase-4 hardening. settings shipped WordPressObjectFieldStore — a
WooCommerce-order implementation (OrderUtil, shop_order, wc_get_order,
woocommerce_process_shop_order_meta) — inside a package documented and
deptrac-scoped as WooCommerce-free. deptrac could not catch it: WC symbols
are external, so no framework-layer collector sees them, and the package
would fatal on load when scoped without WooCommerce.

Move the implementation to woocommerce as OrderData/OrderFieldStore (a
rename that also corrects the misleading "WordPress" name on an order
store), and keep only the generic, WP/WC-agnostic contract in settings,
now under an ObjectField/ concept module:
settings/src/ObjectField/{ObjectFieldStoreInterface, ValueObjects/
ObjectMetaBox, Exceptions/InvalidObjectMetaBoxException}. settings drops
its WooCommerce composer "suggest" and php-scoper stub, so it is
WooCommerce-free in code and tooling. The contract stays a single-
implementation interface by design (the impl must live in woocommerce); a
docblock note records why it must not be removed on an impl count.

Also group the WC settings-page trio (WooCommerceSettingsBackend,
WCSettingsBuilder, DescriptorBackedWCSettingsPage) into a SettingsPage/
concept folder, so woocommerce/src reads as peer concept folders
(SettingsPage/, ProductData/, OrderData/).

deptrac unchanged and 0 violations; the existing ruleset already encodes
the correct architecture. PHPStan + Unit (290) green for the changed
packages; integration suite to be run under wp-env.

Assisted-by: Claude Code:claude-opus-4-8
---
 packages/settings/composer.json               |  7 +--
 .../InvalidObjectMetaBoxException.php         |  2 +-
 .../src/ObjectField/Exceptions/index.php      |  1 +
 .../ObjectFieldStoreInterface.php             |  9 +++-
 .../ValueObjects/ObjectMetaBox.php            |  4 +-
 .../src/ObjectField/ValueObjects/index.php    |  1 +
 packages/settings/src/ObjectField/index.php   |  1 +
 .../settings/tests/Unit/ObjectMetaBoxTest.php |  4 +-
 .../src/OrderData/OrderFieldStore.php}        | 16 ++++--
 packages/woocommerce/src/OrderData/index.php  |  1 +
 .../DescriptorBackedWCSettingsPage.php        |  2 +-
 .../{ => SettingsPage}/WCSettingsBuilder.php  |  2 +-
 .../WooCommerceSettingsBackend.php            |  2 +-
 .../woocommerce/src/SettingsPage/index.php    |  1 +
 .../DescriptorBackedWCSettingsPageTest.php    |  2 +-
 .../Fixtures/BarWCSettingsPage.php            |  2 +-
 .../Fixtures/FooWCSettingsPage.php            |  2 +-
 .../Fixtures/LazyBindWCSettingsPage.php       |  2 +-
 .../Fixtures/UnboundWCSettingsPage.php        |  2 +-
 .../OrderData/OrderFieldStoreTest.php}        | 52 +++++++++----------
 .../tests/Integration/OrderData/index.php     |  1 +
 .../WooCommerceSettingsBackendTest.php        |  2 +-
 .../tests/Unit/WCSettingsBuilderTest.php      |  2 +-
 phpstan.dist.neon                             |  4 +-
 tests/Fixtures/consumer-smoke/smoke.php       |  8 +--
 25 files changed, 72 insertions(+), 60 deletions(-)
 rename packages/settings/src/{ => ObjectField}/Exceptions/InvalidObjectMetaBoxException.php (86%)
 create mode 100644 packages/settings/src/ObjectField/Exceptions/index.php
 rename packages/settings/src/{ => ObjectField}/ObjectFieldStoreInterface.php (81%)
 rename packages/settings/src/{ => ObjectField}/ValueObjects/ObjectMetaBox.php (94%)
 create mode 100644 packages/settings/src/ObjectField/ValueObjects/index.php
 create mode 100644 packages/settings/src/ObjectField/index.php
 rename packages/{settings/src/WordPressObjectFieldStore.php => woocommerce/src/OrderData/OrderFieldStore.php} (94%)
 create mode 100644 packages/woocommerce/src/OrderData/index.php
 rename packages/woocommerce/src/{ => SettingsPage}/DescriptorBackedWCSettingsPage.php (98%)
 rename packages/woocommerce/src/{ => SettingsPage}/WCSettingsBuilder.php (99%)
 rename packages/woocommerce/src/{ => SettingsPage}/WooCommerceSettingsBackend.php (99%)
 create mode 100644 packages/woocommerce/src/SettingsPage/index.php
 rename packages/{settings/tests/Integration/WordPressObjectFieldStoreTest.php => woocommerce/tests/Integration/OrderData/OrderFieldStoreTest.php} (92%)
 create mode 100644 packages/woocommerce/tests/Integration/OrderData/index.php

diff --git a/packages/settings/composer.json b/packages/settings/composer.json
index 3a2258f..af56ca0 100644
--- a/packages/settings/composer.json
+++ b/packages/settings/composer.json
@@ -23,10 +23,6 @@
     "psr/log": "^3"
   },
 
-  "suggest": {
-    "wp-plugin/woocommerce": "Required at runtime by WordPressObjectFieldStore, which stores fields as WooCommerce order meta."
-  },
-
   "minimum-stability": "dev",
   "prefer-stable": true,
 
@@ -49,8 +45,7 @@
       "dev-trunk": "2.0.x-dev"
     },
     "scoping-stubs": [
-      "php-stubs/wordpress-stubs",
-      "php-stubs/woocommerce-stubs"
+      "php-stubs/wordpress-stubs"
     ],
     "changelogger": {
       "versioning": "semver",
diff --git a/packages/settings/src/Exceptions/InvalidObjectMetaBoxException.php b/packages/settings/src/ObjectField/Exceptions/InvalidObjectMetaBoxException.php
similarity index 86%
rename from packages/settings/src/Exceptions/InvalidObjectMetaBoxException.php
rename to packages/settings/src/ObjectField/Exceptions/InvalidObjectMetaBoxException.php
index 705dea3..007f649 100644
--- a/packages/settings/src/Exceptions/InvalidObjectMetaBoxException.php
+++ b/packages/settings/src/ObjectField/Exceptions/InvalidObjectMetaBoxException.php
@@ -1,6 +1,6 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Settings\Exceptions;
+namespace DeepWebSolutions\Framework\Settings\ObjectField\Exceptions;
 
 use DeepWebSolutions\Framework\Shared\Exception\AbstractRuntimeException;
 
diff --git a/packages/settings/src/ObjectField/Exceptions/index.php b/packages/settings/src/ObjectField/Exceptions/index.php
new file mode 100644
index 0000000..f767346
--- /dev/null
+++ b/packages/settings/src/ObjectField/Exceptions/index.php
@@ -0,0 +1 @@
+<?php declare( strict_types=1 ); // Silence is golden.
diff --git a/packages/settings/src/ObjectFieldStoreInterface.php b/packages/settings/src/ObjectField/ObjectFieldStoreInterface.php
similarity index 81%
rename from packages/settings/src/ObjectFieldStoreInterface.php
rename to packages/settings/src/ObjectField/ObjectFieldStoreInterface.php
index 50032ad..32ee44c 100644
--- a/packages/settings/src/ObjectFieldStoreInterface.php
+++ b/packages/settings/src/ObjectField/ObjectFieldStoreInterface.php
@@ -1,8 +1,8 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Settings;
+namespace DeepWebSolutions\Framework\Settings\ObjectField;
 
-use DeepWebSolutions\Framework\Settings\ValueObjects\ObjectMetaBox;
+use DeepWebSolutions\Framework\Settings\ObjectField\ValueObjects\ObjectMetaBox;
 
 /**
  * Registers a per-entity meta box and reads/writes its fields as object meta.
@@ -11,6 +11,11 @@
  * explicit meta key. The field id and the storage key are kept distinct, so a
  * consumer can persist under runtime keys the settings id charset forbids.
  *
+ * Contract-only in this package: its sole implementation is the WooCommerce-order
+ * store in the woocommerce package, kept there so this package stays WooCommerce-free.
+ * The cross-package WooCommerce/WC-free split justifies this lone-implementation
+ * interface — do not remove it on a single-implementation count.
+ *
  * @since   2.0.0
  * @version 2.0.0
  */
diff --git a/packages/settings/src/ValueObjects/ObjectMetaBox.php b/packages/settings/src/ObjectField/ValueObjects/ObjectMetaBox.php
similarity index 94%
rename from packages/settings/src/ValueObjects/ObjectMetaBox.php
rename to packages/settings/src/ObjectField/ValueObjects/ObjectMetaBox.php
index f923f2c..736a56e 100644
--- a/packages/settings/src/ValueObjects/ObjectMetaBox.php
+++ b/packages/settings/src/ObjectField/ValueObjects/ObjectMetaBox.php
@@ -1,8 +1,8 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Settings\ValueObjects;
+namespace DeepWebSolutions\Framework\Settings\ObjectField\ValueObjects;
 
-use DeepWebSolutions\Framework\Settings\Exceptions\InvalidObjectMetaBoxException;
+use DeepWebSolutions\Framework\Settings\ObjectField\Exceptions\InvalidObjectMetaBoxException;
 
 /**
  * Declarative description of a per-entity meta box (object fields).
diff --git a/packages/settings/src/ObjectField/ValueObjects/index.php b/packages/settings/src/ObjectField/ValueObjects/index.php
new file mode 100644
index 0000000..f767346
--- /dev/null
+++ b/packages/settings/src/ObjectField/ValueObjects/index.php
@@ -0,0 +1 @@
+<?php declare( strict_types=1 ); // Silence is golden.
diff --git a/packages/settings/src/ObjectField/index.php b/packages/settings/src/ObjectField/index.php
new file mode 100644
index 0000000..f767346
--- /dev/null
+++ b/packages/settings/src/ObjectField/index.php
@@ -0,0 +1 @@
+<?php declare( strict_types=1 ); // Silence is golden.
diff --git a/packages/settings/tests/Unit/ObjectMetaBoxTest.php b/packages/settings/tests/Unit/ObjectMetaBoxTest.php
index d24aa92..01beaa6 100644
--- a/packages/settings/tests/Unit/ObjectMetaBoxTest.php
+++ b/packages/settings/tests/Unit/ObjectMetaBoxTest.php
@@ -2,8 +2,8 @@
 
 namespace DeepWebSolutions\Framework\Settings\Tests\Unit;
 
-use DeepWebSolutions\Framework\Settings\Exceptions\InvalidObjectMetaBoxException;
-use DeepWebSolutions\Framework\Settings\ValueObjects\ObjectMetaBox;
+use DeepWebSolutions\Framework\Settings\ObjectField\Exceptions\InvalidObjectMetaBoxException;
+use DeepWebSolutions\Framework\Settings\ObjectField\ValueObjects\ObjectMetaBox;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\TestCase;
 
diff --git a/packages/settings/src/WordPressObjectFieldStore.php b/packages/woocommerce/src/OrderData/OrderFieldStore.php
similarity index 94%
rename from packages/settings/src/WordPressObjectFieldStore.php
rename to packages/woocommerce/src/OrderData/OrderFieldStore.php
index c5164c7..92f5332 100644
--- a/packages/settings/src/WordPressObjectFieldStore.php
+++ b/packages/woocommerce/src/OrderData/OrderFieldStore.php
@@ -1,16 +1,22 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Settings;
+namespace DeepWebSolutions\Framework\WooCommerce\OrderData;
 
 use Automattic\WooCommerce\Utilities\OrderUtil;
 use DeepWebSolutions\Framework\Settings\Exceptions\DuplicateSettingsFieldException;
-use DeepWebSolutions\Framework\Settings\Exceptions\InvalidObjectMetaBoxException;
-use DeepWebSolutions\Framework\Settings\ValueObjects\ObjectMetaBox;
+use DeepWebSolutions\Framework\Settings\FieldProcessor;
+use DeepWebSolutions\Framework\Settings\FieldRenderer;
+use DeepWebSolutions\Framework\Settings\ObjectField\Exceptions\InvalidObjectMetaBoxException;
+use DeepWebSolutions\Framework\Settings\ObjectField\ObjectFieldStoreInterface;
+use DeepWebSolutions\Framework\Settings\ObjectField\ValueObjects\ObjectMetaBox;
 use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
 
 /**
  * WooCommerce-order object-field store: an order meta box plus per-object meta CRUD.
  *
+ * Accepted scope is WooCommerce order meta, with a post-meta fallback for an object
+ * id that is not an order.
+ *
  * Registers a meta box on the order edit screen — the legacy post screen or the
  * HPOS orders page, resolved at registration so the box renders under either
  * storage mode — and reads/writes its fields as order meta through WC_Order, so
@@ -24,7 +30,7 @@
  * @since   2.0.0
  * @version 2.0.0
  */
-final class WordPressObjectFieldStore implements ObjectFieldStoreInterface {
+final class OrderFieldStore implements ObjectFieldStoreInterface {
 	// region FIELDS AND CONSTANTS
 
 	/**
@@ -186,7 +192,7 @@ public function delete( int $object_id, string $meta_key ): bool {
 	private function resolve_screens( string $screen ): array {
 		if ( self::ORDER_SCREEN !== $screen ) {
 			// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- framework-internal exception; never reaches an HTML output context unescaped.
-			throw new InvalidObjectMetaBoxException( "WordPressObjectFieldStore registers meta boxes on the WooCommerce order screen ('shop_order') only; got '$screen'." );
+			throw new InvalidObjectMetaBoxException( "OrderFieldStore registers meta boxes on the WooCommerce order screen ('shop_order') only; got '$screen'." );
 		}
 		if ( ! OrderUtil::custom_orders_table_usage_is_enabled() ) {
 			return array( self::ORDER_SCREEN );
diff --git a/packages/woocommerce/src/OrderData/index.php b/packages/woocommerce/src/OrderData/index.php
new file mode 100644
index 0000000..f767346
--- /dev/null
+++ b/packages/woocommerce/src/OrderData/index.php
@@ -0,0 +1 @@
+<?php declare( strict_types=1 ); // Silence is golden.
diff --git a/packages/woocommerce/src/DescriptorBackedWCSettingsPage.php b/packages/woocommerce/src/SettingsPage/DescriptorBackedWCSettingsPage.php
similarity index 98%
rename from packages/woocommerce/src/DescriptorBackedWCSettingsPage.php
rename to packages/woocommerce/src/SettingsPage/DescriptorBackedWCSettingsPage.php
index 92128c9..add1b34 100644
--- a/packages/woocommerce/src/DescriptorBackedWCSettingsPage.php
+++ b/packages/woocommerce/src/SettingsPage/DescriptorBackedWCSettingsPage.php
@@ -1,6 +1,6 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\WooCommerce;
+namespace DeepWebSolutions\Framework\WooCommerce\SettingsPage;
 
 use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsPage;
 use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsSection;
diff --git a/packages/woocommerce/src/WCSettingsBuilder.php b/packages/woocommerce/src/SettingsPage/WCSettingsBuilder.php
similarity index 99%
rename from packages/woocommerce/src/WCSettingsBuilder.php
rename to packages/woocommerce/src/SettingsPage/WCSettingsBuilder.php
index 3a3ef6d..b9fac3f 100644
--- a/packages/woocommerce/src/WCSettingsBuilder.php
+++ b/packages/woocommerce/src/SettingsPage/WCSettingsBuilder.php
@@ -1,6 +1,6 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\WooCommerce;
+namespace DeepWebSolutions\Framework\WooCommerce\SettingsPage;
 
 use DeepWebSolutions\Framework\Settings\FieldType;
 use DeepWebSolutions\Framework\Settings\OptionsResolver;
diff --git a/packages/woocommerce/src/WooCommerceSettingsBackend.php b/packages/woocommerce/src/SettingsPage/WooCommerceSettingsBackend.php
similarity index 99%
rename from packages/woocommerce/src/WooCommerceSettingsBackend.php
rename to packages/woocommerce/src/SettingsPage/WooCommerceSettingsBackend.php
index 66478fa..56f282e 100644
--- a/packages/woocommerce/src/WooCommerceSettingsBackend.php
+++ b/packages/woocommerce/src/SettingsPage/WooCommerceSettingsBackend.php
@@ -1,6 +1,6 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\WooCommerce;
+namespace DeepWebSolutions\Framework\WooCommerce\SettingsPage;
 
 use DeepWebSolutions\Framework\Settings\Exceptions\DuplicateSettingsFieldException;
 use DeepWebSolutions\Framework\Settings\Exceptions\InvalidSettingsFieldException;
diff --git a/packages/woocommerce/src/SettingsPage/index.php b/packages/woocommerce/src/SettingsPage/index.php
new file mode 100644
index 0000000..f767346
--- /dev/null
+++ b/packages/woocommerce/src/SettingsPage/index.php
@@ -0,0 +1 @@
+<?php declare( strict_types=1 ); // Silence is golden.
diff --git a/packages/woocommerce/tests/Integration/DescriptorBackedWCSettingsPageTest.php b/packages/woocommerce/tests/Integration/DescriptorBackedWCSettingsPageTest.php
index 4e54676..b1cd1da 100644
--- a/packages/woocommerce/tests/Integration/DescriptorBackedWCSettingsPageTest.php
+++ b/packages/woocommerce/tests/Integration/DescriptorBackedWCSettingsPageTest.php
@@ -5,7 +5,7 @@
 use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
 use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsPage;
 use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsSection;
-use DeepWebSolutions\Framework\WooCommerce\DescriptorBackedWCSettingsPage;
+use DeepWebSolutions\Framework\WooCommerce\SettingsPage\DescriptorBackedWCSettingsPage;
 use DeepWebSolutions\Framework\WooCommerce\Exceptions\UnboundSettingsPageException;
 use DeepWebSolutions\Framework\WooCommerce\Tests\Integration\Fixtures\BarWCSettingsPage;
 use DeepWebSolutions\Framework\WooCommerce\Tests\Integration\Fixtures\FooWCSettingsPage;
diff --git a/packages/woocommerce/tests/Integration/Fixtures/BarWCSettingsPage.php b/packages/woocommerce/tests/Integration/Fixtures/BarWCSettingsPage.php
index 823ef45..bb3e2fc 100644
--- a/packages/woocommerce/tests/Integration/Fixtures/BarWCSettingsPage.php
+++ b/packages/woocommerce/tests/Integration/Fixtures/BarWCSettingsPage.php
@@ -2,7 +2,7 @@
 
 namespace DeepWebSolutions\Framework\WooCommerce\Tests\Integration\Fixtures;
 
-use DeepWebSolutions\Framework\WooCommerce\DescriptorBackedWCSettingsPage;
+use DeepWebSolutions\Framework\WooCommerce\SettingsPage\DescriptorBackedWCSettingsPage;
 
 /**
  * A second distinct settings-page subclass standing in for another plugin's coexisting page.
diff --git a/packages/woocommerce/tests/Integration/Fixtures/FooWCSettingsPage.php b/packages/woocommerce/tests/Integration/Fixtures/FooWCSettingsPage.php
index cfef2f1..5f0ad3e 100644
--- a/packages/woocommerce/tests/Integration/Fixtures/FooWCSettingsPage.php
+++ b/packages/woocommerce/tests/Integration/Fixtures/FooWCSettingsPage.php
@@ -2,7 +2,7 @@
 
 namespace DeepWebSolutions\Framework\WooCommerce\Tests\Integration\Fixtures;
 
-use DeepWebSolutions\Framework\WooCommerce\DescriptorBackedWCSettingsPage;
+use DeepWebSolutions\Framework\WooCommerce\SettingsPage\DescriptorBackedWCSettingsPage;
 
 /**
  * A distinct, REST-safe settings-page subclass standing in for one consumer plugin's page.
diff --git a/packages/woocommerce/tests/Integration/Fixtures/LazyBindWCSettingsPage.php b/packages/woocommerce/tests/Integration/Fixtures/LazyBindWCSettingsPage.php
index 705ce10..dcbc750 100644
--- a/packages/woocommerce/tests/Integration/Fixtures/LazyBindWCSettingsPage.php
+++ b/packages/woocommerce/tests/Integration/Fixtures/LazyBindWCSettingsPage.php
@@ -2,7 +2,7 @@
 
 namespace DeepWebSolutions\Framework\WooCommerce\Tests\Integration\Fixtures;
 
-use DeepWebSolutions\Framework\WooCommerce\DescriptorBackedWCSettingsPage;
+use DeepWebSolutions\Framework\WooCommerce\SettingsPage\DescriptorBackedWCSettingsPage;
 
 /**
  * A subclass bound by no other test, used to prove register_page() defers binding until the filter fires.
diff --git a/packages/woocommerce/tests/Integration/Fixtures/UnboundWCSettingsPage.php b/packages/woocommerce/tests/Integration/Fixtures/UnboundWCSettingsPage.php
index c066ebb..83406d9 100644
--- a/packages/woocommerce/tests/Integration/Fixtures/UnboundWCSettingsPage.php
+++ b/packages/woocommerce/tests/Integration/Fixtures/UnboundWCSettingsPage.php
@@ -2,7 +2,7 @@
 
 namespace DeepWebSolutions\Framework\WooCommerce\Tests\Integration\Fixtures;
 
-use DeepWebSolutions\Framework\WooCommerce\DescriptorBackedWCSettingsPage;
+use DeepWebSolutions\Framework\WooCommerce\SettingsPage\DescriptorBackedWCSettingsPage;
 
 /**
  * A subclass deliberately never bound to a descriptor, to exercise the unbound-instantiation guard.
diff --git a/packages/settings/tests/Integration/WordPressObjectFieldStoreTest.php b/packages/woocommerce/tests/Integration/OrderData/OrderFieldStoreTest.php
similarity index 92%
rename from packages/settings/tests/Integration/WordPressObjectFieldStoreTest.php
rename to packages/woocommerce/tests/Integration/OrderData/OrderFieldStoreTest.php
index d61593a..5b43349 100644
--- a/packages/settings/tests/Integration/WordPressObjectFieldStoreTest.php
+++ b/packages/woocommerce/tests/Integration/OrderData/OrderFieldStoreTest.php
@@ -1,29 +1,29 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Settings\Tests\Integration;
+namespace DeepWebSolutions\Framework\WooCommerce\Tests\Integration\OrderData;
 
 use Automattic\WooCommerce\Utilities\OrderUtil;
 use DeepWebSolutions\Framework\Settings\Exceptions\DuplicateSettingsFieldException;
-use DeepWebSolutions\Framework\Settings\Exceptions\InvalidObjectMetaBoxException;
 use DeepWebSolutions\Framework\Settings\FieldProcessor;
 use DeepWebSolutions\Framework\Settings\FieldRenderer;
 use DeepWebSolutions\Framework\Settings\FieldType;
+use DeepWebSolutions\Framework\Settings\ObjectField\Exceptions\InvalidObjectMetaBoxException;
+use DeepWebSolutions\Framework\Settings\ObjectField\ValueObjects\ObjectMetaBox;
 use DeepWebSolutions\Framework\Settings\OptionsResolver;
-use DeepWebSolutions\Framework\Settings\ValueObjects\ObjectMetaBox;
 use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
-use DeepWebSolutions\Framework\Settings\WordPressObjectFieldStore;
+use DeepWebSolutions\Framework\WooCommerce\OrderData\OrderFieldStore;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\UsesClass;
 use PHPUnit\Framework\TestCase;
 
-#[CoversClass( WordPressObjectFieldStore::class )]
+#[CoversClass( OrderFieldStore::class )]
 #[UsesClass( ObjectMetaBox::class )]
 #[UsesClass( SettingsField::class )]
 #[UsesClass( FieldRenderer::class )]
 #[UsesClass( FieldProcessor::class )]
 #[UsesClass( OptionsResolver::class )]
 #[UsesClass( FieldType::class )]
-final class WordPressObjectFieldStoreTest extends TestCase {
+final class OrderFieldStoreTest extends TestCase {
 	private const BOX_ID       = 'dws_unlock';
 	private const NONCE_NAME   = 'dws_object_field_dws_unlock_nonce';
 	private const NONCE_ACTION = 'dws_object_field_dws_unlock';
@@ -97,7 +97,7 @@ protected function tearDown(): void {
 	}
 
 	public function test_set_and_get_round_trip_on_an_order(): void {
-		$store = new WordPressObjectFieldStore();
+		$store = new OrderFieldStore();
 
 		$store->set( $this->order_id, '_dws_unlocked', 'yes' );
 
@@ -105,13 +105,13 @@ public function test_set_and_get_round_trip_on_an_order(): void {
 	}
 
 	public function test_get_returns_the_default_when_nothing_is_stored(): void {
-		$store = new WordPressObjectFieldStore();
+		$store = new OrderFieldStore();
 
 		self::assertSame( 'fallback', $store->get( $this->order_id, '_dws_absent', 'fallback' ) );
 	}
 
 	public function test_has_reports_presence_and_delete_removes_the_value(): void {
-		$store = new WordPressObjectFieldStore();
+		$store = new OrderFieldStore();
 
 		self::assertFalse( $store->has( $this->order_id, '_dws_flag' ) );
 
@@ -127,7 +127,7 @@ public function test_crud_falls_back_to_post_meta_for_a_non_order_id(): void {
 		$post_id = \wp_insert_post( array( 'post_title' => 'Probe', 'post_status' => 'publish' ) );
 		\assert( \is_int( $post_id ) );
 		self::assertFalse( \wc_get_order( $post_id ) ); // guarantee the non-order fallback branch, not an id collision
-		$store = new WordPressObjectFieldStore();
+		$store = new OrderFieldStore();
 
 		$store->set( $post_id, '_dws_post_key', 'value' );
 
@@ -144,7 +144,7 @@ public function test_register_meta_box_registers_on_the_resolved_order_screen():
 		$screen = OrderUtil::custom_orders_table_usage_is_enabled() ? 'woocommerce_page_wc-orders' : 'shop_order';
 		\set_current_screen( $screen );
 
-		( new WordPressObjectFieldStore() )->register_meta_box( $this->box() );
+		( new OrderFieldStore() )->register_meta_box( $this->box() );
 		\do_action( "add_meta_boxes_$screen" );
 
 		self::assertArrayHasKey( self::BOX_ID, $this->boxes_on( $screen ) );
@@ -162,7 +162,7 @@ public function test_the_registered_box_renders_a_nonce_and_its_field_control():
 		$screen = OrderUtil::custom_orders_table_usage_is_enabled() ? 'woocommerce_page_wc-orders' : 'shop_order';
 		\set_current_screen( $screen );
 
-		( new WordPressObjectFieldStore() )->register_meta_box( $this->box() );
+		( new OrderFieldStore() )->register_meta_box( $this->box() );
 		\do_action( "add_meta_boxes_$screen" );
 
 		$definition = (array) ( $this->boxes_on( $screen )[ self::BOX_ID ] ?? array() );
@@ -194,7 +194,7 @@ public function test_a_bespoke_render_and_save_descriptor_emits_the_nonce_and_sa
 				$saved_for = $object_id;
 			},
 		);
-		$store = new WordPressObjectFieldStore();
+		$store = new OrderFieldStore();
 		$store->register_meta_box( $box );
 		\do_action( "add_meta_boxes_$screen" );
 
@@ -215,7 +215,7 @@ public function test_a_bespoke_render_and_save_descriptor_emits_the_nonce_and_sa
 	}
 
 	public function test_a_truthy_submission_is_stored_and_a_falsy_one_deletes_the_meta(): void {
-		$store = new WordPressObjectFieldStore();
+		$store = new OrderFieldStore();
 		$store->register_meta_box( $this->box() );
 
 		// Checkbox checked → meta stored.
@@ -243,7 +243,7 @@ public function test_a_zero_value_is_stored_not_revoked(): void {
 				new SettingsField( id: 'note', type: 'text', label: 'Note' ),
 			),
 		);
-		$store = new WordPressObjectFieldStore();
+		$store = new OrderFieldStore();
 		$store->register_meta_box( $box );
 
 		// A literal "0" is a real value, not an empty submission, so it must persist rather than revoke.
@@ -258,7 +258,7 @@ public function test_a_zero_value_is_stored_not_revoked(): void {
 	}
 
 	public function test_save_is_skipped_without_a_valid_nonce(): void {
-		$store = new WordPressObjectFieldStore();
+		$store = new OrderFieldStore();
 		$store->register_meta_box( $this->box() );
 
 		$_POST = array( self::BOX_ID => array( 'unlocked' => '1' ) );
@@ -281,7 +281,7 @@ public function test_the_post_meta_fallback_preserves_backslashes(): void {
 		$post_id = \wp_insert_post( array( 'post_title' => 'Probe', 'post_status' => 'publish' ) );
 		\assert( \is_int( $post_id ) );
 		self::assertFalse( \wc_get_order( $post_id ) );
-		$store = new WordPressObjectFieldStore();
+		$store = new OrderFieldStore();
 
 		$store->set( $post_id, '_dws_path', 'C:\\Users\\dev\\file.txt' );
 
@@ -305,7 +305,7 @@ public function test_clearing_a_field_with_a_default_revokes_it_without_restorin
 				new SettingsField( id: 'note', type: 'text', label: 'Note', default: 'preset' ),
 			),
 		);
-		$store = new WordPressObjectFieldStore();
+		$store = new OrderFieldStore();
 		$store->register_meta_box( $box );
 
 		// Store a value, then submit it empty: delete-on-falsy revokes the meta.
@@ -334,7 +334,7 @@ public function test_register_meta_box_also_registers_on_the_restricted_hpos_scr
 		}
 		\set_current_screen( 'admin_page_wc-orders' );
 
-		( new WordPressObjectFieldStore() )->register_meta_box( $this->box() );
+		( new OrderFieldStore() )->register_meta_box( $this->box() );
 		\do_action( 'add_meta_boxes_admin_page_wc-orders' );
 
 		self::assertArrayHasKey( self::BOX_ID, $this->boxes_on( 'admin_page_wc-orders' ) );
@@ -351,7 +351,7 @@ public function test_a_field_meta_key_overrides_the_id_for_storage(): void {
 				new SettingsField( id: 'unlocked', type: 'checkbox', label: 'Unlocked', meta_key: '_lpm_unlocked' ),
 			),
 		);
-		$store = new WordPressObjectFieldStore();
+		$store = new OrderFieldStore();
 		$store->register_meta_box( $box );
 
 		$_POST = array( self::NONCE_NAME => $this->nonce(), self::BOX_ID => array( 'unlocked' => '1' ) );
@@ -369,7 +369,7 @@ public function test_save_is_skipped_for_a_user_without_the_orders_capability():
 		\assert( \is_int( $subscriber ) );
 		\wp_set_current_user( $subscriber );
 
-		$store = new WordPressObjectFieldStore();
+		$store = new OrderFieldStore();
 		$store->register_meta_box( $this->box() );
 
 		// A valid nonce for this user, but the user lacks edit_shop_orders: the save must be refused.
@@ -392,7 +392,7 @@ public function test_a_multi_field_save_persists_the_order_once(): void {
 				new SettingsField( id: 'second', type: 'text', label: 'Second' ),
 			),
 		);
-		$store = new WordPressObjectFieldStore();
+		$store = new OrderFieldStore();
 		$store->register_meta_box( $box );
 
 		$saves = 0;
@@ -416,7 +416,7 @@ static function () use ( &$saves ): void {
 	}
 
 	public function test_a_no_op_save_does_not_persist_the_order(): void {
-		$store = new WordPressObjectFieldStore();
+		$store = new OrderFieldStore();
 		$store->register_meta_box( $this->box() );
 
 		$saves = 0;
@@ -446,7 +446,7 @@ public function test_a_duplicate_field_id_in_a_box_is_rejected(): void {
 				new SettingsField( id: 'flag', type: 'checkbox', label: 'B' ),
 			),
 		);
-		$store = new WordPressObjectFieldStore();
+		$store = new OrderFieldStore();
 		$store->register_meta_box( $box );
 
 		$_POST = array( self::NONCE_NAME => $this->nonce(), self::BOX_ID => array( 'flag' => '1' ) );
@@ -467,7 +467,7 @@ public function test_register_meta_box_rejects_a_non_order_screen(): void {
 
 		$this->expectException( InvalidObjectMetaBoxException::class );
 
-		( new WordPressObjectFieldStore() )->register_meta_box( $box );
+		( new OrderFieldStore() )->register_meta_box( $box );
 	}
 
 	public function test_a_meta_box_title_is_escaped_before_registration(): void {
@@ -482,7 +482,7 @@ public function test_a_meta_box_title_is_escaped_before_registration(): void {
 			priority: 'default',
 			fields_provider: static fn ( int $object_id ): array => array(),
 		);
-		( new WordPressObjectFieldStore() )->register_meta_box( $box );
+		( new OrderFieldStore() )->register_meta_box( $box );
 		\do_action( "add_meta_boxes_$screen" );
 
 		// WordPress echoes the stored title raw in do_meta_boxes(), so the store hands it pre-escaped.
diff --git a/packages/woocommerce/tests/Integration/OrderData/index.php b/packages/woocommerce/tests/Integration/OrderData/index.php
new file mode 100644
index 0000000..f767346
--- /dev/null
+++ b/packages/woocommerce/tests/Integration/OrderData/index.php
@@ -0,0 +1 @@
+<?php declare( strict_types=1 ); // Silence is golden.
diff --git a/packages/woocommerce/tests/Integration/WooCommerceSettingsBackendTest.php b/packages/woocommerce/tests/Integration/WooCommerceSettingsBackendTest.php
index 4ebe9cf..6799538 100644
--- a/packages/woocommerce/tests/Integration/WooCommerceSettingsBackendTest.php
+++ b/packages/woocommerce/tests/Integration/WooCommerceSettingsBackendTest.php
@@ -11,7 +11,7 @@
 use DeepWebSolutions\Framework\WooCommerce\Tests\Integration\Fixtures\BarWCSettingsPage;
 use DeepWebSolutions\Framework\WooCommerce\Tests\Integration\Fixtures\FooWCSettingsPage;
 use DeepWebSolutions\Framework\WooCommerce\Tests\Integration\Fixtures\LazyBindWCSettingsPage;
-use DeepWebSolutions\Framework\WooCommerce\WooCommerceSettingsBackend;
+use DeepWebSolutions\Framework\WooCommerce\SettingsPage\WooCommerceSettingsBackend;
 use PHPUnit\Framework\TestCase;
 
 final class WooCommerceSettingsBackendTest extends TestCase {
diff --git a/packages/woocommerce/tests/Unit/WCSettingsBuilderTest.php b/packages/woocommerce/tests/Unit/WCSettingsBuilderTest.php
index fe19530..d3b4e41 100644
--- a/packages/woocommerce/tests/Unit/WCSettingsBuilderTest.php
+++ b/packages/woocommerce/tests/Unit/WCSettingsBuilderTest.php
@@ -6,7 +6,7 @@
 use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
 use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsPage;
 use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsSection;
-use DeepWebSolutions\Framework\WooCommerce\WCSettingsBuilder;
+use DeepWebSolutions\Framework\WooCommerce\SettingsPage\WCSettingsBuilder;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\UsesClass;
 use PHPUnit\Framework\TestCase;
diff --git a/phpstan.dist.neon b/phpstan.dist.neon
index fec32b3..d964cf8 100644
--- a/phpstan.dist.neon
+++ b/phpstan.dist.neon
@@ -2,8 +2,8 @@ includes:
     - vendor/ahegyes/wordpress-configs/php/quality-assurance/phpstan.dist.neon
 
 parameters:
-    # WooCommerce symbols (OrderUtil, WC_Order, wc_get_order) used by the settings
-    # object-field store; the shared config only wires the WordPress stubs.
+    # WooCommerce symbols (OrderUtil, WC_Order, wc_get_order) used by the woocommerce
+    # package's order-field store and settings page; the shared config only wires the WordPress stubs.
     bootstrapFiles:
         - vendor/php-stubs/woocommerce-stubs/woocommerce-stubs.php
     # PHPStan does not expand globs in `paths`; each package is enumerated literally.
diff --git a/tests/Fixtures/consumer-smoke/smoke.php b/tests/Fixtures/consumer-smoke/smoke.php
index 9c07ad0..599d277 100644
--- a/tests/Fixtures/consumer-smoke/smoke.php
+++ b/tests/Fixtures/consumer-smoke/smoke.php
@@ -51,10 +51,10 @@
 	$failures[] = 'missing scoped class: DeepWebSolutions\\Framework\\Settings\\ValueObjects\\SettingsField';
 }
 
-// Settings WooCommerce-coupled backend: the class that references WooCommerce symbols resolves under
-// the scoped prefix, with those symbols left unprefixed via the fixture's woocommerce-stubs catalog.
-if ( ! class_exists( 'DWS_CONSUMER_SMOKE_Deps\\DeepWebSolutions\\Framework\\Settings\\WordPressObjectFieldStore' ) ) {
-	$failures[] = 'missing scoped class: DeepWebSolutions\\Framework\\Settings\\WordPressObjectFieldStore';
+// WooCommerce order-field store: the class that references WooCommerce symbols resolves under the
+// scoped prefix, with those symbols left unprefixed via the fixture's woocommerce-stubs catalog.
+if ( ! class_exists( 'DWS_CONSUMER_SMOKE_Deps\\DeepWebSolutions\\Framework\\WooCommerce\\OrderData\\OrderFieldStore' ) ) {
+	$failures[] = 'missing scoped class: DeepWebSolutions\\Framework\\WooCommerce\\OrderData\\OrderFieldStore';
 }
 
 // PHP-DI PSR-4 + files-autoloaded factory().

From 4a1b8c99968a576cce324b6634cbf9b031ebf35a Mon Sep 17 00:00:00 2001
From: Tony Hegyes <a.hegyes@proton.me>
Date: Sun, 21 Jun 2026 16:55:37 +0200
Subject: [PATCH 02/21] test(bootstrap): drop redundant always-true const
 assertion in AggregatorTest
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PHPStan flagged assertTrue( defined( '…\Requirements\FRAMEWORK_MIN_PHP' ) )
as staticMethod.alreadyNarrowedType: the namespaced const is resolved
statically, so the assertion is always true. The Requirements concern
file's wiring is already covered by the same-file check_requirements
function_exists assertion, so the const check was redundant. Removing it
restores a PHPStan-green tree and keeps exactly one wiring assertion per
concern file (Environment / Plugin / Requirements / Notice).

Assisted-by: Claude Code:claude-opus-4-8
---
 packages/bootstrap/tests/Unit/AggregatorTest.php | 1 -
 1 file changed, 1 deletion(-)

diff --git a/packages/bootstrap/tests/Unit/AggregatorTest.php b/packages/bootstrap/tests/Unit/AggregatorTest.php
index c9bb263..ca0f761 100644
--- a/packages/bootstrap/tests/Unit/AggregatorTest.php
+++ b/packages/bootstrap/tests/Unit/AggregatorTest.php
@@ -10,6 +10,5 @@ public function test_aggregator_wires_every_concern_file(): void {
 		self::assertTrue( \function_exists( 'DeepWebSolutions\Framework\Bootstrap\Plugin\get_plugin_metadata' ) );
 		self::assertTrue( \function_exists( 'DeepWebSolutions\Framework\Bootstrap\Requirements\check_requirements' ) );
 		self::assertTrue( \function_exists( 'DeepWebSolutions\Framework\Bootstrap\Notice\output_requirements_error' ) );
-		self::assertTrue( \defined( 'DeepWebSolutions\Framework\Bootstrap\Requirements\FRAMEWORK_MIN_PHP' ) );
 	}
 }

From 951183965f8960813525639e4a13fc13f23e3b53 Mon Sep 17 00:00:00 2001
From: Tony Hegyes <a.hegyes@proton.me>
Date: Sun, 21 Jun 2026 17:26:33 +0200
Subject: [PATCH 03/21] refactor(framework): establish component-grammar
 conventions (interface placement + VO/descriptor)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Pre-Phase-4 hardening — codify two grammar rules that replace improvised
conventions, restoring a predictable structure without reintroducing
inheritance.

Interface placement: an interface lives at its concept-folder root; a
single-concept package keeps its contract flat at the package src root
(the locked PluginInterface/PluginKernel pair is the one flat exception);
no generic Contracts/ subfolder. Applied by removing the lone outlier —
Hooks/Contracts/HookHandlerInterface moves to Hooks/HookHandlerInterface
(the only Contracts/ folder in the tree).

Value object vs descriptor: ValueObjects/ folders hold two carrier kinds,
distinguished by base class + docblock, not a marker interface. A value
object extends AbstractValueObject only when structural equals()/JSON is
consumed (PluginHeader, Version; docblock opens "Value object ..."); a
descriptor is a bare final readonly carrier, required when it holds
closures/providers/WP objects (SettingsField, SettingsPage, SettingsSection,
ObjectMetaBox, AdminNotice, DependencyRequirement; docblock opens
"Descriptor for ..."). A marker DescriptorInterface is deferred until a
consumer needs it.

Both rules recorded as decision blocks in AGENTS.md. settings is
multi-concept but under-foldered; its concept-folder reorganization is a
separate follow-up.

Assisted-by: Claude Code:claude-opus-4-8
---
 AGENTS.md                                              |  8 ++++++++
 packages/core/src/ValueObjects/PluginHeader.php        |  2 +-
 .../src/ObjectField/ValueObjects/ObjectMetaBox.php     |  2 +-
 packages/settings/src/ValueObjects/SettingsField.php   |  2 +-
 packages/settings/src/ValueObjects/SettingsPage.php    |  4 ++--
 packages/settings/src/ValueObjects/SettingsSection.php |  2 +-
 packages/shared/src/Version/Version.php                |  2 +-
 .../src/AdminNotices/ValueObjects/AdminNotice.php      |  2 +-
 .../ValueObjects/DependencyRequirement.php             | 10 +++++-----
 packages/utilities/src/Hooks/Contracts/index.php       |  1 -
 .../src/Hooks/Handlers/BufferedHookHandler.php         |  2 +-
 .../utilities/src/Hooks/Handlers/DirectHookHandler.php |  2 +-
 .../utilities/src/Hooks/Handlers/ScopedHookHandler.php |  2 +-
 .../src/Hooks/{Contracts => }/HookHandlerInterface.php |  2 +-
 packages/utilities/src/Hooks/HooksService.php          |  1 -
 .../utilities/tests/Unit/Hooks/HooksServiceTest.php    |  2 +-
 16 files changed, 26 insertions(+), 20 deletions(-)
 delete mode 100644 packages/utilities/src/Hooks/Contracts/index.php
 rename packages/utilities/src/Hooks/{Contracts => }/HookHandlerInterface.php (97%)

diff --git a/AGENTS.md b/AGENTS.md
index 72c08d5..516d950 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -365,3 +365,11 @@ Resolves parity finding A1 (the v1→v2 parity reconciliation — reports archiv
 **Cross-package change:** `SettingsField` gains an optional `description` (additive; the WP-backed `FieldRenderer` now renders it too, so the WP options page + object meta box benefit). `desc_tip` stays WC-only (defaulted true in the product renderer). `php-stubs/woocommerce-stubs` added to the woocommerce package's php-scoper `scoping-stubs` (the product-data + existing WC settings code reference WC symbols a consumer's scoper must leave external).
 
 **deptrac:** unchanged — `WooCommerce: [Core, Shared, Settings]` already covers the reuse of `SettingsField`/`SettingsSection`/`FieldProcessor`/`FieldType`/`OptionsResolver` + the settings exceptions; `Shared` for `InvalidProductDataTabException`'s base. No abstract base (the "intrinsically requires" exception does not fire — a tab registers via filters, with no WC class to subclass) and no new interface (single impl). Gates at landing: Unit 288 · Integration 261 · PHPStan clean · deptrac 0 · Infection 100% covered-code MSI on `woocommerce/src`. Design spec in the project vault (`drafts/2026-06-15-wc-product-settings-tab-mini-spec`).
+
+### Component grammar — interface placement (2026-06-21)
+
+One rule replaces three improvised conventions. An interface lives at the ROOT of the concept folder it names; concrete variants live in plural sub-bags beneath it (`Handlers/`, `Stores/`, `Backends/`, `ValueObjects/`, `Exceptions/`). A package whose ENTIRE content is a single concept keeps its contract flat at the package `src/` root — the package boundary IS the concept boundary (e.g. `storage`: `KeyValueStoreInterface` beside its stores). The locked core entrypoint pair (`PluginInterface` / `PluginKernel`) is the one explicit flat exception; do not generalize it. There is NO generic `Contracts/` subfolder — an interface is the concept's root type, not a nested artifact. Placement test for a new interface: does its concept share the package with other concepts? → concept-folder root. Is the package a single concept (or the locked entrypoint)? → package root. Applied: `Hooks/Contracts/HookHandlerInterface` moved to `Hooks/HookHandlerInterface`. (`settings` is multi-concept but currently under-foldered; its concept-folder reorganization is tracked as a separate item.)
+
+### Component grammar — value object vs descriptor (2026-06-21)
+
+`ValueObjects/` folders hold immutable carriers of two kinds; the folder name is kept, and the kinds are distinguished by base class + docblock, not by a marker interface. **Value object** — extends `Shared\ValueObject\AbstractValueObject`; use ONLY when reflection-driven structural `equals()` / `jsonSerialize()` is actually consumed and every public property can participate safely in structural equality (`PluginHeader`, `Version`); its docblock opens "Value object …". **Descriptor** — a bare `final readonly` class with no base; the default immutable carrier, and REQUIRED when it holds closures/callables, runtime providers, or WordPress/WooCommerce objects (`SettingsField`, `SettingsPage`, `SettingsSection`, `ObjectMetaBox`, `AdminNotice`, `DependencyRequirement`); its docblock opens "Descriptor for …". A marker `DescriptorInterface` is deferred until real code must typehint a polymorphic descriptor collection — a taxonomy-only marker is ceremony (service interfaces only on plurality).
diff --git a/packages/core/src/ValueObjects/PluginHeader.php b/packages/core/src/ValueObjects/PluginHeader.php
index 15cf161..9bd064d 100644
--- a/packages/core/src/ValueObjects/PluginHeader.php
+++ b/packages/core/src/ValueObjects/PluginHeader.php
@@ -7,7 +7,7 @@
 use function DeepWebSolutions\Framework\Bootstrap\Plugin\get_plugin_metadata;
 
 /**
- * Typed read-once value object wrapping the WP plugin file header.
+ * Value object wrapping the WP plugin file header, read once and typed.
  *
  * The single source of truth is the file header comment of the plugin's main
  * file. Consumers must NOT type metadata values manually — pass the file path
diff --git a/packages/settings/src/ObjectField/ValueObjects/ObjectMetaBox.php b/packages/settings/src/ObjectField/ValueObjects/ObjectMetaBox.php
index 736a56e..b696c4f 100644
--- a/packages/settings/src/ObjectField/ValueObjects/ObjectMetaBox.php
+++ b/packages/settings/src/ObjectField/ValueObjects/ObjectMetaBox.php
@@ -5,7 +5,7 @@
 use DeepWebSolutions\Framework\Settings\ObjectField\Exceptions\InvalidObjectMetaBoxException;
 
 /**
- * Declarative description of a per-entity meta box (object fields).
+ * Descriptor for a per-entity meta box (object fields).
  *
  * Drives the object-field backend: the box attaches to an object screen and its
  * fields are built per object at render time by the provider closure — so a box
diff --git a/packages/settings/src/ValueObjects/SettingsField.php b/packages/settings/src/ValueObjects/SettingsField.php
index 432a063..4c2bbb0 100644
--- a/packages/settings/src/ValueObjects/SettingsField.php
+++ b/packages/settings/src/ValueObjects/SettingsField.php
@@ -6,7 +6,7 @@
 use DeepWebSolutions\Framework\Settings\SettingsOptionsProviderInterface;
 
 /**
- * Declarative, storage- and UI-agnostic description of a single settings field.
+ * Descriptor for a single settings field, storage- and UI-agnostic.
  *
  * Immutable carrier of everything a backend needs to register, render, sanitize,
  * and validate one field: identifier, type token, presentation metadata, an
diff --git a/packages/settings/src/ValueObjects/SettingsPage.php b/packages/settings/src/ValueObjects/SettingsPage.php
index 2897e54..921c949 100644
--- a/packages/settings/src/ValueObjects/SettingsPage.php
+++ b/packages/settings/src/ValueObjects/SettingsPage.php
@@ -3,8 +3,8 @@
 namespace DeepWebSolutions\Framework\Settings\ValueObjects;
 
 /**
- * Declarative description of a settings page: a titled, capability-gated screen
- * composed of sections.
+ * Descriptor for a settings page: a titled, capability-gated screen composed
+ * of sections.
  *
  * The location is interpreted by the backend the page is registered with — a
  * WordPress parent slug for the options backend, a tab id for the WooCommerce
diff --git a/packages/settings/src/ValueObjects/SettingsSection.php b/packages/settings/src/ValueObjects/SettingsSection.php
index 3a8b951..e2a6922 100644
--- a/packages/settings/src/ValueObjects/SettingsSection.php
+++ b/packages/settings/src/ValueObjects/SettingsSection.php
@@ -3,7 +3,7 @@
 namespace DeepWebSolutions\Framework\Settings\ValueObjects;
 
 /**
- * Declarative description of a settings section: a titled group of fields.
+ * Descriptor for a settings section: a titled group of fields.
  *
  * A section is the unit of storage for the WordPress options backend — its
  * identifier doubles as the persisted option-group key segment — and the unit of
diff --git a/packages/shared/src/Version/Version.php b/packages/shared/src/Version/Version.php
index 5234110..b1f1d46 100644
--- a/packages/shared/src/Version/Version.php
+++ b/packages/shared/src/Version/Version.php
@@ -6,7 +6,7 @@
 use DeepWebSolutions\Framework\Shared\Version\Exceptions\InvalidVersionException;
 
 /**
- * Immutable representation of a software version. SemVer-shaped:
+ * Value object representing a software version. SemVer-shaped:
  * MAJOR[.MINOR[.PATCH]][-PRERELEASE][+BUILD]. Provides type-safe ordering and
  * equality.
  *
diff --git a/packages/utilities/src/AdminNotices/ValueObjects/AdminNotice.php b/packages/utilities/src/AdminNotices/ValueObjects/AdminNotice.php
index e3be73b..a8dea7a 100644
--- a/packages/utilities/src/AdminNotices/ValueObjects/AdminNotice.php
+++ b/packages/utilities/src/AdminNotices/ValueObjects/AdminNotice.php
@@ -3,7 +3,7 @@
 namespace DeepWebSolutions\Framework\Utilities\AdminNotices\ValueObjects;
 
 /**
- * Value object representing a single WordPress admin notice.
+ * Descriptor for a single WordPress admin notice.
  *
  * The $is_persistent flag governs post-render retention in a persistent store: a non-persistent
  * notice is consumed (removed) after it renders once, a persistent one recurs until dismissed or
diff --git a/packages/utilities/src/AdminNotices/ValueObjects/DependencyRequirement.php b/packages/utilities/src/AdminNotices/ValueObjects/DependencyRequirement.php
index 4a41bb7..76ad015 100644
--- a/packages/utilities/src/AdminNotices/ValueObjects/DependencyRequirement.php
+++ b/packages/utilities/src/AdminNotices/ValueObjects/DependencyRequirement.php
@@ -5,11 +5,11 @@
 use DeepWebSolutions\Framework\Core\Conditional\ConditionalInterface;
 
 /**
- * A dependency a plugin declares for missing-dependency admin notices: the conditional that decides
- * whether it is satisfied, a human-readable label, and whether it is required (blocking) or optional
- * (recommended). The getters derive the notice's identity and presentation purely from those fields,
- * so {@see \DeepWebSolutions\Framework\Utilities\AdminNotices\DependencyAdminNoticeRenderer} owns only
- * the translatable message and the queueing.
+ * Descriptor for a dependency a plugin declares for missing-dependency admin notices: the conditional
+ * that decides whether it is satisfied, a human-readable label, and whether it is required (blocking)
+ * or optional (recommended). The getters derive the notice's identity and presentation purely from
+ * those fields, so {@see \DeepWebSolutions\Framework\Utilities\AdminNotices\DependencyAdminNoticeRenderer}
+ * owns only the translatable message and the queueing.
  *
  * @since   2.0.0
  * @version 2.0.0
diff --git a/packages/utilities/src/Hooks/Contracts/index.php b/packages/utilities/src/Hooks/Contracts/index.php
deleted file mode 100644
index f767346..0000000
--- a/packages/utilities/src/Hooks/Contracts/index.php
+++ /dev/null
@@ -1 +0,0 @@
-<?php declare( strict_types=1 ); // Silence is golden.
diff --git a/packages/utilities/src/Hooks/Handlers/BufferedHookHandler.php b/packages/utilities/src/Hooks/Handlers/BufferedHookHandler.php
index 4b60c13..b3a718a 100644
--- a/packages/utilities/src/Hooks/Handlers/BufferedHookHandler.php
+++ b/packages/utilities/src/Hooks/Handlers/BufferedHookHandler.php
@@ -2,7 +2,7 @@
 
 namespace DeepWebSolutions\Framework\Utilities\Hooks\Handlers;
 
-use DeepWebSolutions\Framework\Utilities\Hooks\Contracts\HookHandlerInterface;
+use DeepWebSolutions\Framework\Utilities\Hooks\HookHandlerInterface;
 use DeepWebSolutions\Framework\Utilities\Hooks\HookRegistry;
 
 /**
diff --git a/packages/utilities/src/Hooks/Handlers/DirectHookHandler.php b/packages/utilities/src/Hooks/Handlers/DirectHookHandler.php
index 8b664f8..a97f95a 100644
--- a/packages/utilities/src/Hooks/Handlers/DirectHookHandler.php
+++ b/packages/utilities/src/Hooks/Handlers/DirectHookHandler.php
@@ -2,7 +2,7 @@
 
 namespace DeepWebSolutions\Framework\Utilities\Hooks\Handlers;
 
-use DeepWebSolutions\Framework\Utilities\Hooks\Contracts\HookHandlerInterface;
+use DeepWebSolutions\Framework\Utilities\Hooks\HookHandlerInterface;
 use DeepWebSolutions\Framework\Utilities\Hooks\HookRegistry;
 
 /**
diff --git a/packages/utilities/src/Hooks/Handlers/ScopedHookHandler.php b/packages/utilities/src/Hooks/Handlers/ScopedHookHandler.php
index 595c33d..3c6a6f6 100644
--- a/packages/utilities/src/Hooks/Handlers/ScopedHookHandler.php
+++ b/packages/utilities/src/Hooks/Handlers/ScopedHookHandler.php
@@ -2,7 +2,7 @@
 
 namespace DeepWebSolutions\Framework\Utilities\Hooks\Handlers;
 
-use DeepWebSolutions\Framework\Utilities\Hooks\Contracts\HookHandlerInterface;
+use DeepWebSolutions\Framework\Utilities\Hooks\HookHandlerInterface;
 use DeepWebSolutions\Framework\Utilities\Hooks\HookRegistry;
 
 /**
diff --git a/packages/utilities/src/Hooks/Contracts/HookHandlerInterface.php b/packages/utilities/src/Hooks/HookHandlerInterface.php
similarity index 97%
rename from packages/utilities/src/Hooks/Contracts/HookHandlerInterface.php
rename to packages/utilities/src/Hooks/HookHandlerInterface.php
index e87b9c1..7089014 100644
--- a/packages/utilities/src/Hooks/Contracts/HookHandlerInterface.php
+++ b/packages/utilities/src/Hooks/HookHandlerInterface.php
@@ -1,6 +1,6 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Utilities\Hooks\Contracts;
+namespace DeepWebSolutions\Framework\Utilities\Hooks;
 
 /**
  * Strategy for registering WordPress hook callbacks.
diff --git a/packages/utilities/src/Hooks/HooksService.php b/packages/utilities/src/Hooks/HooksService.php
index c0a97b6..47cad12 100644
--- a/packages/utilities/src/Hooks/HooksService.php
+++ b/packages/utilities/src/Hooks/HooksService.php
@@ -2,7 +2,6 @@
 
 namespace DeepWebSolutions\Framework\Utilities\Hooks;
 
-use DeepWebSolutions\Framework\Utilities\Hooks\Contracts\HookHandlerInterface;
 use DeepWebSolutions\Framework\Utilities\Hooks\Handlers\DirectHookHandler;
 use OutOfBoundsException;
 
diff --git a/packages/utilities/tests/Unit/Hooks/HooksServiceTest.php b/packages/utilities/tests/Unit/Hooks/HooksServiceTest.php
index 94c6553..1415a01 100644
--- a/packages/utilities/tests/Unit/Hooks/HooksServiceTest.php
+++ b/packages/utilities/tests/Unit/Hooks/HooksServiceTest.php
@@ -2,8 +2,8 @@
 
 namespace DeepWebSolutions\Framework\Utilities\Tests\Unit\Hooks;
 
-use DeepWebSolutions\Framework\Utilities\Hooks\Contracts\HookHandlerInterface;
 use DeepWebSolutions\Framework\Utilities\Hooks\Handlers\DirectHookHandler;
+use DeepWebSolutions\Framework\Utilities\Hooks\HookHandlerInterface;
 use DeepWebSolutions\Framework\Utilities\Hooks\HooksService;
 use OutOfBoundsException;
 use PHPUnit\Framework\Attributes\CoversClass;

From 5c1a3e8eef98ad5a17e37de81ac879699d52fda4 Mon Sep 17 00:00:00 2001
From: Tony Hegyes <a.hegyes@proton.me>
Date: Sun, 21 Jun 2026 17:26:34 +0200
Subject: [PATCH 04/21] fix(shared): make AbstractValueObject::equals() recurse
 arrays like jsonSerialize()

equals() recursed only direct ValueObjectInterface properties and fell back
to strict !== for everything else, so an array of value objects was compared
by identity -- while jsonSerialize() (via convert_to_primitives) recurses
arrays element-by-element. Two value objects holding a structurally-equal
list<VO> of distinct instances therefore reported equals() === false yet
serialized identically.

Compare the canonical primitive projections instead -- the same
convert_to_primitives() traversal jsonSerialize() uses -- so equality and
serialization share one source of truth and can no longer drift. This also
fixes DateTimeInterface equality (equal-but-distinct instances now compare
equal) and drops two property.dynamicName PHPStan ignores plus the now-unused
get_public_property_names import.

Adds an Integration regression: a value object holding list<VO> asserts
equals() agrees with jsonSerialize() across distinct-but-equal instances.

Assisted-by: Claude Code:claude-opus-4-8
---
 .../src/ValueObject/AbstractValueObject.php   | 18 +-------
 .../ValueObject/AbstractValueObjectTest.php   | 44 +++++++++++++++++++
 2 files changed, 45 insertions(+), 17 deletions(-)

diff --git a/packages/shared/src/ValueObject/AbstractValueObject.php b/packages/shared/src/ValueObject/AbstractValueObject.php
index 7004033..c5c8885 100644
--- a/packages/shared/src/ValueObject/AbstractValueObject.php
+++ b/packages/shared/src/ValueObject/AbstractValueObject.php
@@ -3,7 +3,6 @@
 namespace DeepWebSolutions\Framework\Shared\ValueObject;
 
 use function DeepWebSolutions\Framework\Shared\Reflection\convert_to_primitives;
-use function DeepWebSolutions\Framework\Shared\Reflection\get_public_property_names;
 
 /**
  * Base class for value objects. Provides reflection-driven structural equality,
@@ -47,22 +46,7 @@ final public function equals( ValueObjectInterface $other ): bool {
 			return false;
 		}
 
-		foreach ( get_public_property_names( $this ) as $property_name ) {
-			// @phpstan-ignore-next-line property.dynamicName
-			$value_this = $this->{ $property_name };
-			// @phpstan-ignore-next-line property.dynamicName
-			$value_other = $other->{ $property_name };
-
-			if ( $value_this instanceof ValueObjectInterface ) {
-				if ( ! $value_other instanceof ValueObjectInterface || ! $value_this->equals( $value_other ) ) {
-					return false;
-				}
-			} elseif ( $value_this !== $value_other ) {
-				return false;
-			}
-		}
-
-		return true;
+		return convert_to_primitives( $this ) === convert_to_primitives( $other );
 	}
 
 	/**
diff --git a/packages/shared/tests/Integration/ValueObject/AbstractValueObjectTest.php b/packages/shared/tests/Integration/ValueObject/AbstractValueObjectTest.php
index 255ad20..d585cab 100644
--- a/packages/shared/tests/Integration/ValueObject/AbstractValueObjectTest.php
+++ b/packages/shared/tests/Integration/ValueObject/AbstractValueObjectTest.php
@@ -25,6 +25,15 @@ public function __construct(
 	) {}
 }
 
+final readonly class CollectionFixtureValueObject extends AbstractValueObject {
+	/**
+	 * @param list<FixtureValueObject> $items
+	 */
+	public function __construct(
+		public array $items,
+	) {}
+}
+
 #[CoversClass( AbstractValueObject::class )]
 final class AbstractValueObjectTest extends TestCase {
 	public function test_equals_returns_true_for_structurally_identical_objects(): void {
@@ -57,6 +66,41 @@ public function test_equals_returns_false_when_nested_value_objects_differ(): vo
 		self::assertFalse( $a->equals( $b ) );
 	}
 
+	public function test_equals_recurses_into_arrays_of_value_objects(): void {
+		$a = new CollectionFixtureValueObject(
+			array(
+				new FixtureValueObject( 'foo', 1 ),
+				new FixtureValueObject( 'bar', 2 ),
+			),
+		);
+		$b = new CollectionFixtureValueObject(
+			array(
+				new FixtureValueObject( 'foo', 1 ),
+				new FixtureValueObject( 'bar', 2 ),
+			),
+		);
+
+		self::assertTrue( $a->equals( $b ) );
+		self::assertSame( $a->jsonSerialize(), $b->jsonSerialize() );
+	}
+
+	public function test_equals_false_when_value_object_inside_array_differs(): void {
+		$a = new CollectionFixtureValueObject(
+			array(
+				new FixtureValueObject( 'foo', 1 ),
+				new FixtureValueObject( 'bar', 2 ),
+			),
+		);
+		$b = new CollectionFixtureValueObject(
+			array(
+				new FixtureValueObject( 'foo', 1 ),
+				new FixtureValueObject( 'bar', 3 ),
+			),
+		);
+
+		self::assertFalse( $a->equals( $b ) );
+	}
+
 	public function test_json_serialize_returns_public_properties(): void {
 		$vo = new FixtureValueObject( 'foo', 7 );
 		self::assertSame(

From 0182e1be31b8fb8f6ef9655ed858b86a76adf385 Mon Sep 17 00:00:00 2001
From: Tony Hegyes <a.hegyes@proton.me>
Date: Sun, 21 Jun 2026 18:24:05 +0200
Subject: [PATCH 05/21] refactor(settings,woocommerce): reorganize settings
 into Schema/ + Backend/ concept folders; align woocommerce Backend/
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Pre-Phase-4 hardening — resolve settings' under-fragmentation (the
flattest yet most multi-concept package) by folding its flat files into
three peer concept folders, per the codified component grammar:

  Schema/      shared declarative field model + render/process engine
               (FieldType, FieldRenderer, FieldProcessor, OptionsResolver,
                SettingsFieldAggregator, provider interfaces, the
                SettingsField/Page/Section descriptors, field exceptions)
  Backend/     WP options-page surface (SettingsBackendInterface +
               WordPressSettingsBackend)
  ObjectField/ unchanged

Schema/ is the cross-cutting core consumed by every surface (the WP
backend, ObjectField, and the woocommerce package), and is the clean
lift-out point should the field core ever be extracted to its own package.

Also rename woocommerce/SettingsPage/ -> woocommerce/Backend/ so the
settings-page backend surface carries one name in both packages
(settings/Backend + woocommerce/Backend), beside woocommerce's
ProductData/ + OrderData/.

Pure moves + namespace/reference rewrites; no behavior change. deptrac
unchanged (0 violations). PHPStan clean, Unit 290, Integration 274.

Assisted-by: Claude Code:claude-opus-4-8
---
 .../{ => Backend}/SettingsBackendInterface.php |  4 ++--
 .../{ => Backend}/WordPressSettingsBackend.php | 18 ++++++++++--------
 .../src/{Exceptions => Backend}/index.php      |  0
 .../DuplicateSettingsFieldException.php        |  2 +-
 .../DuplicateSettingsSectionException.php      |  2 +-
 .../InvalidSettingsFieldException.php          |  2 +-
 .../InvalidSettingsOptionsException.php        |  2 +-
 .../Exceptions/UnknownFieldTypeException.php   |  2 +-
 .../Exceptions}/index.php                      |  0
 .../src/{ => Schema}/FieldProcessor.php        |  6 +++---
 .../src/{ => Schema}/FieldRenderer.php         |  6 +++---
 .../settings/src/{ => Schema}/FieldType.php    |  2 +-
 .../src/{ => Schema}/OptionsResolver.php       |  4 ++--
 .../{ => Schema}/SettingsFieldAggregator.php   |  6 +++---
 .../SettingsFieldProviderInterface.php         |  4 ++--
 .../SettingsOptionsProviderInterface.php       |  2 +-
 .../ValueObjects/SettingsField.php             |  6 +++---
 .../{ => Schema}/ValueObjects/SettingsPage.php |  2 +-
 .../ValueObjects/SettingsSection.php           |  2 +-
 .../src/Schema/ValueObjects}/index.php         |  0
 packages/settings/src/Schema/index.php         |  1 +
 .../Integration/CrossComponentSettingsTest.php | 14 +++++++-------
 .../tests/Integration/FieldRendererTest.php    |  6 +++---
 .../WordPressSettingsBackendTest.php           | 12 ++++++------
 .../settings/tests/Unit/FieldProcessorTest.php |  8 ++++----
 .../settings/tests/Unit/ObjectMetaBoxTest.php  |  2 +-
 .../tests/Unit/OptionsResolverTest.php         |  6 +++---
 .../tests/Unit/SettingsFieldAggregatorTest.php |  8 ++++----
 .../settings/tests/Unit/SettingsFieldTest.php  |  6 +++---
 .../settings/tests/Unit/SettingsPageTest.php   |  4 ++--
 .../tests/Unit/SettingsSectionTest.php         |  4 ++--
 .../DescriptorBackedWCSettingsPage.php         |  6 +++---
 .../WCSettingsBuilder.php                      | 10 +++++-----
 .../WooCommerceSettingsBackend.php             | 12 ++++++------
 packages/woocommerce/src/Backend/index.php     |  1 +
 .../src/OrderData/OrderFieldStore.php          |  8 ++++----
 .../ProductData/ProductDataFieldRenderer.php   |  8 ++++----
 .../src/ProductData/ProductDataFieldStore.php  | 10 +++++-----
 .../src/ProductData/ProductDataTab.php         |  2 +-
 .../DescriptorBackedWCSettingsPageTest.php     |  8 ++++----
 .../Integration/Fixtures/BarWCSettingsPage.php |  2 +-
 .../Integration/Fixtures/FooWCSettingsPage.php |  2 +-
 .../Fixtures/LazyBindWCSettingsPage.php        |  2 +-
 .../Fixtures/UnboundWCSettingsPage.php         |  2 +-
 .../OrderData/OrderFieldStoreTest.php          | 12 ++++++------
 .../ProductDataFieldRendererTest.php           |  6 +++---
 .../Integration/ProductDataFieldStoreTest.php  |  8 ++++----
 .../WooCommerceSettingsBackendTest.php         | 12 ++++++------
 .../Unit/ProductDataFieldRendererTest.php      |  6 +++---
 .../tests/Unit/ProductDataTabTest.php          |  4 ++--
 .../tests/Unit/WCSettingsBuilderTest.php       | 10 +++++-----
 tests/Fixtures/consumer-smoke/smoke.php        |  4 ++--
 52 files changed, 141 insertions(+), 137 deletions(-)
 rename packages/settings/src/{ => Backend}/SettingsBackendInterface.php (93%)
 rename packages/settings/src/{ => Backend}/WordPressSettingsBackend.php (94%)
 rename packages/settings/src/{Exceptions => Backend}/index.php (100%)
 rename packages/settings/src/{ => Schema}/Exceptions/DuplicateSettingsFieldException.php (82%)
 rename packages/settings/src/{ => Schema}/Exceptions/DuplicateSettingsSectionException.php (82%)
 rename packages/settings/src/{ => Schema}/Exceptions/InvalidSettingsFieldException.php (86%)
 rename packages/settings/src/{ => Schema}/Exceptions/InvalidSettingsOptionsException.php (83%)
 rename packages/settings/src/{ => Schema}/Exceptions/UnknownFieldTypeException.php (82%)
 rename packages/settings/src/{ValueObjects => Schema/Exceptions}/index.php (100%)
 rename packages/settings/src/{ => Schema}/FieldProcessor.php (94%)
 rename packages/settings/src/{ => Schema}/FieldRenderer.php (97%)
 rename packages/settings/src/{ => Schema}/FieldType.php (92%)
 rename packages/settings/src/{ => Schema}/OptionsResolver.php (91%)
 rename packages/settings/src/{ => Schema}/SettingsFieldAggregator.php (88%)
 rename packages/settings/src/{ => Schema}/SettingsFieldProviderInterface.php (82%)
 rename packages/settings/src/{ => Schema}/SettingsOptionsProviderInterface.php (92%)
 rename packages/settings/src/{ => Schema}/ValueObjects/SettingsField.php (95%)
 rename packages/settings/src/{ => Schema}/ValueObjects/SettingsPage.php (95%)
 rename packages/settings/src/{ => Schema}/ValueObjects/SettingsSection.php (93%)
 rename packages/{woocommerce/src/SettingsPage => settings/src/Schema/ValueObjects}/index.php (100%)
 create mode 100644 packages/settings/src/Schema/index.php
 rename packages/woocommerce/src/{SettingsPage => Backend}/DescriptorBackedWCSettingsPage.php (95%)
 rename packages/woocommerce/src/{SettingsPage => Backend}/WCSettingsBuilder.php (95%)
 rename packages/woocommerce/src/{SettingsPage => Backend}/WooCommerceSettingsBackend.php (93%)
 create mode 100644 packages/woocommerce/src/Backend/index.php

diff --git a/packages/settings/src/SettingsBackendInterface.php b/packages/settings/src/Backend/SettingsBackendInterface.php
similarity index 93%
rename from packages/settings/src/SettingsBackendInterface.php
rename to packages/settings/src/Backend/SettingsBackendInterface.php
index 0af5202..788b424 100644
--- a/packages/settings/src/SettingsBackendInterface.php
+++ b/packages/settings/src/Backend/SettingsBackendInterface.php
@@ -1,8 +1,8 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Settings;
+namespace DeepWebSolutions\Framework\Settings\Backend;
 
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsPage;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsPage;
 
 /**
  * Registers and persists one option-scoped settings page.
diff --git a/packages/settings/src/WordPressSettingsBackend.php b/packages/settings/src/Backend/WordPressSettingsBackend.php
similarity index 94%
rename from packages/settings/src/WordPressSettingsBackend.php
rename to packages/settings/src/Backend/WordPressSettingsBackend.php
index 1669ad6..6fa106f 100644
--- a/packages/settings/src/WordPressSettingsBackend.php
+++ b/packages/settings/src/Backend/WordPressSettingsBackend.php
@@ -1,13 +1,15 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Settings;
-
-use DeepWebSolutions\Framework\Settings\Exceptions\DuplicateSettingsFieldException;
-use DeepWebSolutions\Framework\Settings\Exceptions\DuplicateSettingsSectionException;
-use DeepWebSolutions\Framework\Settings\Exceptions\InvalidSettingsFieldException;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsPage;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsSection;
+namespace DeepWebSolutions\Framework\Settings\Backend;
+
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\DuplicateSettingsFieldException;
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\DuplicateSettingsSectionException;
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\InvalidSettingsFieldException;
+use DeepWebSolutions\Framework\Settings\Schema\FieldProcessor;
+use DeepWebSolutions\Framework\Settings\Schema\FieldRenderer;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsPage;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsSection;
 use DeepWebSolutions\Framework\Storage\OptionsStore;
 use Psr\Log\LoggerInterface;
 
diff --git a/packages/settings/src/Exceptions/index.php b/packages/settings/src/Backend/index.php
similarity index 100%
rename from packages/settings/src/Exceptions/index.php
rename to packages/settings/src/Backend/index.php
diff --git a/packages/settings/src/Exceptions/DuplicateSettingsFieldException.php b/packages/settings/src/Schema/Exceptions/DuplicateSettingsFieldException.php
similarity index 82%
rename from packages/settings/src/Exceptions/DuplicateSettingsFieldException.php
rename to packages/settings/src/Schema/Exceptions/DuplicateSettingsFieldException.php
index 9f6581e..3f246f9 100644
--- a/packages/settings/src/Exceptions/DuplicateSettingsFieldException.php
+++ b/packages/settings/src/Schema/Exceptions/DuplicateSettingsFieldException.php
@@ -1,6 +1,6 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Settings\Exceptions;
+namespace DeepWebSolutions\Framework\Settings\Schema\Exceptions;
 
 use DeepWebSolutions\Framework\Shared\Exception\AbstractRuntimeException;
 
diff --git a/packages/settings/src/Exceptions/DuplicateSettingsSectionException.php b/packages/settings/src/Schema/Exceptions/DuplicateSettingsSectionException.php
similarity index 82%
rename from packages/settings/src/Exceptions/DuplicateSettingsSectionException.php
rename to packages/settings/src/Schema/Exceptions/DuplicateSettingsSectionException.php
index 5c6e0c8..ede732d 100644
--- a/packages/settings/src/Exceptions/DuplicateSettingsSectionException.php
+++ b/packages/settings/src/Schema/Exceptions/DuplicateSettingsSectionException.php
@@ -1,6 +1,6 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Settings\Exceptions;
+namespace DeepWebSolutions\Framework\Settings\Schema\Exceptions;
 
 use DeepWebSolutions\Framework\Shared\Exception\AbstractRuntimeException;
 
diff --git a/packages/settings/src/Exceptions/InvalidSettingsFieldException.php b/packages/settings/src/Schema/Exceptions/InvalidSettingsFieldException.php
similarity index 86%
rename from packages/settings/src/Exceptions/InvalidSettingsFieldException.php
rename to packages/settings/src/Schema/Exceptions/InvalidSettingsFieldException.php
index e18b569..50dfed4 100644
--- a/packages/settings/src/Exceptions/InvalidSettingsFieldException.php
+++ b/packages/settings/src/Schema/Exceptions/InvalidSettingsFieldException.php
@@ -1,6 +1,6 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Settings\Exceptions;
+namespace DeepWebSolutions\Framework\Settings\Schema\Exceptions;
 
 use DeepWebSolutions\Framework\Shared\Exception\AbstractInvalidArgumentException;
 
diff --git a/packages/settings/src/Exceptions/InvalidSettingsOptionsException.php b/packages/settings/src/Schema/Exceptions/InvalidSettingsOptionsException.php
similarity index 83%
rename from packages/settings/src/Exceptions/InvalidSettingsOptionsException.php
rename to packages/settings/src/Schema/Exceptions/InvalidSettingsOptionsException.php
index 77dc04c..4be03da 100644
--- a/packages/settings/src/Exceptions/InvalidSettingsOptionsException.php
+++ b/packages/settings/src/Schema/Exceptions/InvalidSettingsOptionsException.php
@@ -1,6 +1,6 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Settings\Exceptions;
+namespace DeepWebSolutions\Framework\Settings\Schema\Exceptions;
 
 use DeepWebSolutions\Framework\Shared\Exception\AbstractRuntimeException;
 
diff --git a/packages/settings/src/Exceptions/UnknownFieldTypeException.php b/packages/settings/src/Schema/Exceptions/UnknownFieldTypeException.php
similarity index 82%
rename from packages/settings/src/Exceptions/UnknownFieldTypeException.php
rename to packages/settings/src/Schema/Exceptions/UnknownFieldTypeException.php
index bfeac7c..acb491b 100644
--- a/packages/settings/src/Exceptions/UnknownFieldTypeException.php
+++ b/packages/settings/src/Schema/Exceptions/UnknownFieldTypeException.php
@@ -1,6 +1,6 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Settings\Exceptions;
+namespace DeepWebSolutions\Framework\Settings\Schema\Exceptions;
 
 use DeepWebSolutions\Framework\Shared\Exception\AbstractRuntimeException;
 
diff --git a/packages/settings/src/ValueObjects/index.php b/packages/settings/src/Schema/Exceptions/index.php
similarity index 100%
rename from packages/settings/src/ValueObjects/index.php
rename to packages/settings/src/Schema/Exceptions/index.php
diff --git a/packages/settings/src/FieldProcessor.php b/packages/settings/src/Schema/FieldProcessor.php
similarity index 94%
rename from packages/settings/src/FieldProcessor.php
rename to packages/settings/src/Schema/FieldProcessor.php
index b69c296..cf9f301 100644
--- a/packages/settings/src/FieldProcessor.php
+++ b/packages/settings/src/Schema/FieldProcessor.php
@@ -1,9 +1,9 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Settings;
+namespace DeepWebSolutions\Framework\Settings\Schema;
 
-use DeepWebSolutions\Framework\Settings\Exceptions\UnknownFieldTypeException;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\UnknownFieldTypeException;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
 
 /**
  * Turns a field's raw submission into the value to persist.
diff --git a/packages/settings/src/FieldRenderer.php b/packages/settings/src/Schema/FieldRenderer.php
similarity index 97%
rename from packages/settings/src/FieldRenderer.php
rename to packages/settings/src/Schema/FieldRenderer.php
index 182d976..cc53fb7 100644
--- a/packages/settings/src/FieldRenderer.php
+++ b/packages/settings/src/Schema/FieldRenderer.php
@@ -1,9 +1,9 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Settings;
+namespace DeepWebSolutions\Framework\Settings\Schema;
 
-use DeepWebSolutions\Framework\Settings\Exceptions\UnknownFieldTypeException;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\UnknownFieldTypeException;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
 
 /**
  * Renders a field descriptor to an escaped HTML control with its value bound.
diff --git a/packages/settings/src/FieldType.php b/packages/settings/src/Schema/FieldType.php
similarity index 92%
rename from packages/settings/src/FieldType.php
rename to packages/settings/src/Schema/FieldType.php
index af60e54..8570a6c 100644
--- a/packages/settings/src/FieldType.php
+++ b/packages/settings/src/Schema/FieldType.php
@@ -1,6 +1,6 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Settings;
+namespace DeepWebSolutions\Framework\Settings\Schema;
 
 /**
  * The framework's settings field-type taxonomy.
diff --git a/packages/settings/src/OptionsResolver.php b/packages/settings/src/Schema/OptionsResolver.php
similarity index 91%
rename from packages/settings/src/OptionsResolver.php
rename to packages/settings/src/Schema/OptionsResolver.php
index a4fb342..0ac0162 100644
--- a/packages/settings/src/OptionsResolver.php
+++ b/packages/settings/src/Schema/OptionsResolver.php
@@ -1,8 +1,8 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Settings;
+namespace DeepWebSolutions\Framework\Settings\Schema;
 
-use DeepWebSolutions\Framework\Settings\Exceptions\InvalidSettingsOptionsException;
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\InvalidSettingsOptionsException;
 
 /**
  * Resolves a field's options source into a concrete value-to-label map.
diff --git a/packages/settings/src/SettingsFieldAggregator.php b/packages/settings/src/Schema/SettingsFieldAggregator.php
similarity index 88%
rename from packages/settings/src/SettingsFieldAggregator.php
rename to packages/settings/src/Schema/SettingsFieldAggregator.php
index 3f7b8ab..594f3e3 100644
--- a/packages/settings/src/SettingsFieldAggregator.php
+++ b/packages/settings/src/Schema/SettingsFieldAggregator.php
@@ -1,9 +1,9 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Settings;
+namespace DeepWebSolutions\Framework\Settings\Schema;
 
-use DeepWebSolutions\Framework\Settings\Exceptions\DuplicateSettingsFieldException;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\DuplicateSettingsFieldException;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
 
 /**
  * Merges field providers into one ordered, duplicate-free field list.
diff --git a/packages/settings/src/SettingsFieldProviderInterface.php b/packages/settings/src/Schema/SettingsFieldProviderInterface.php
similarity index 82%
rename from packages/settings/src/SettingsFieldProviderInterface.php
rename to packages/settings/src/Schema/SettingsFieldProviderInterface.php
index 42e38b6..fcc9b09 100644
--- a/packages/settings/src/SettingsFieldProviderInterface.php
+++ b/packages/settings/src/Schema/SettingsFieldProviderInterface.php
@@ -1,8 +1,8 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Settings;
+namespace DeepWebSolutions\Framework\Settings\Schema;
 
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
 
 /**
  * Contributes settings fields to a page or section from a component.
diff --git a/packages/settings/src/SettingsOptionsProviderInterface.php b/packages/settings/src/Schema/SettingsOptionsProviderInterface.php
similarity index 92%
rename from packages/settings/src/SettingsOptionsProviderInterface.php
rename to packages/settings/src/Schema/SettingsOptionsProviderInterface.php
index 416e8f8..0aa97e3 100644
--- a/packages/settings/src/SettingsOptionsProviderInterface.php
+++ b/packages/settings/src/Schema/SettingsOptionsProviderInterface.php
@@ -1,6 +1,6 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Settings;
+namespace DeepWebSolutions\Framework\Settings\Schema;
 
 /**
  * Supplies the value-to-label option set for a choice-typed settings field.
diff --git a/packages/settings/src/ValueObjects/SettingsField.php b/packages/settings/src/Schema/ValueObjects/SettingsField.php
similarity index 95%
rename from packages/settings/src/ValueObjects/SettingsField.php
rename to packages/settings/src/Schema/ValueObjects/SettingsField.php
index 4c2bbb0..196dfcc 100644
--- a/packages/settings/src/ValueObjects/SettingsField.php
+++ b/packages/settings/src/Schema/ValueObjects/SettingsField.php
@@ -1,9 +1,9 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Settings\ValueObjects;
+namespace DeepWebSolutions\Framework\Settings\Schema\ValueObjects;
 
-use DeepWebSolutions\Framework\Settings\Exceptions\InvalidSettingsFieldException;
-use DeepWebSolutions\Framework\Settings\SettingsOptionsProviderInterface;
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\InvalidSettingsFieldException;
+use DeepWebSolutions\Framework\Settings\Schema\SettingsOptionsProviderInterface;
 
 /**
  * Descriptor for a single settings field, storage- and UI-agnostic.
diff --git a/packages/settings/src/ValueObjects/SettingsPage.php b/packages/settings/src/Schema/ValueObjects/SettingsPage.php
similarity index 95%
rename from packages/settings/src/ValueObjects/SettingsPage.php
rename to packages/settings/src/Schema/ValueObjects/SettingsPage.php
index 921c949..ba58e4b 100644
--- a/packages/settings/src/ValueObjects/SettingsPage.php
+++ b/packages/settings/src/Schema/ValueObjects/SettingsPage.php
@@ -1,6 +1,6 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Settings\ValueObjects;
+namespace DeepWebSolutions\Framework\Settings\Schema\ValueObjects;
 
 /**
  * Descriptor for a settings page: a titled, capability-gated screen composed
diff --git a/packages/settings/src/ValueObjects/SettingsSection.php b/packages/settings/src/Schema/ValueObjects/SettingsSection.php
similarity index 93%
rename from packages/settings/src/ValueObjects/SettingsSection.php
rename to packages/settings/src/Schema/ValueObjects/SettingsSection.php
index e2a6922..8c63f7b 100644
--- a/packages/settings/src/ValueObjects/SettingsSection.php
+++ b/packages/settings/src/Schema/ValueObjects/SettingsSection.php
@@ -1,6 +1,6 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Settings\ValueObjects;
+namespace DeepWebSolutions\Framework\Settings\Schema\ValueObjects;
 
 /**
  * Descriptor for a settings section: a titled group of fields.
diff --git a/packages/woocommerce/src/SettingsPage/index.php b/packages/settings/src/Schema/ValueObjects/index.php
similarity index 100%
rename from packages/woocommerce/src/SettingsPage/index.php
rename to packages/settings/src/Schema/ValueObjects/index.php
diff --git a/packages/settings/src/Schema/index.php b/packages/settings/src/Schema/index.php
new file mode 100644
index 0000000..f767346
--- /dev/null
+++ b/packages/settings/src/Schema/index.php
@@ -0,0 +1 @@
+<?php declare( strict_types=1 ); // Silence is golden.
diff --git a/packages/settings/tests/Integration/CrossComponentSettingsTest.php b/packages/settings/tests/Integration/CrossComponentSettingsTest.php
index c85b1b0..c1cfbc1 100644
--- a/packages/settings/tests/Integration/CrossComponentSettingsTest.php
+++ b/packages/settings/tests/Integration/CrossComponentSettingsTest.php
@@ -2,13 +2,13 @@
 
 namespace DeepWebSolutions\Framework\Settings\Tests\Integration;
 
-use DeepWebSolutions\Framework\Settings\Exceptions\DuplicateSettingsFieldException;
-use DeepWebSolutions\Framework\Settings\SettingsFieldAggregator;
-use DeepWebSolutions\Framework\Settings\SettingsFieldProviderInterface;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsPage;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsSection;
-use DeepWebSolutions\Framework\Settings\WordPressSettingsBackend;
+use DeepWebSolutions\Framework\Settings\Backend\WordPressSettingsBackend;
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\DuplicateSettingsFieldException;
+use DeepWebSolutions\Framework\Settings\Schema\SettingsFieldAggregator;
+use DeepWebSolutions\Framework\Settings\Schema\SettingsFieldProviderInterface;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsPage;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsSection;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\UsesClass;
 use PHPUnit\Framework\TestCase;
diff --git a/packages/settings/tests/Integration/FieldRendererTest.php b/packages/settings/tests/Integration/FieldRendererTest.php
index 4a4e6f0..0fc12a8 100644
--- a/packages/settings/tests/Integration/FieldRendererTest.php
+++ b/packages/settings/tests/Integration/FieldRendererTest.php
@@ -2,9 +2,9 @@
 
 namespace DeepWebSolutions\Framework\Settings\Tests\Integration;
 
-use DeepWebSolutions\Framework\Settings\Exceptions\UnknownFieldTypeException;
-use DeepWebSolutions\Framework\Settings\FieldRenderer;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\UnknownFieldTypeException;
+use DeepWebSolutions\Framework\Settings\Schema\FieldRenderer;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\UsesClass;
 use PHPUnit\Framework\TestCase;
diff --git a/packages/settings/tests/Integration/WordPressSettingsBackendTest.php b/packages/settings/tests/Integration/WordPressSettingsBackendTest.php
index 704601d..0bd8c64 100644
--- a/packages/settings/tests/Integration/WordPressSettingsBackendTest.php
+++ b/packages/settings/tests/Integration/WordPressSettingsBackendTest.php
@@ -2,12 +2,12 @@
 
 namespace DeepWebSolutions\Framework\Settings\Tests\Integration;
 
-use DeepWebSolutions\Framework\Settings\Exceptions\DuplicateSettingsFieldException;
-use DeepWebSolutions\Framework\Settings\Exceptions\DuplicateSettingsSectionException;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsPage;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsSection;
-use DeepWebSolutions\Framework\Settings\WordPressSettingsBackend;
+use DeepWebSolutions\Framework\Settings\Backend\WordPressSettingsBackend;
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\DuplicateSettingsFieldException;
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\DuplicateSettingsSectionException;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsPage;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsSection;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\UsesClass;
 use PHPUnit\Framework\TestCase;
diff --git a/packages/settings/tests/Unit/FieldProcessorTest.php b/packages/settings/tests/Unit/FieldProcessorTest.php
index 3a32038..dc95ef7 100644
--- a/packages/settings/tests/Unit/FieldProcessorTest.php
+++ b/packages/settings/tests/Unit/FieldProcessorTest.php
@@ -2,10 +2,10 @@
 
 namespace DeepWebSolutions\Framework\Settings\Tests\Unit;
 
-use DeepWebSolutions\Framework\Settings\Exceptions\UnknownFieldTypeException;
-use DeepWebSolutions\Framework\Settings\FieldProcessor;
-use DeepWebSolutions\Framework\Settings\OptionsResolver;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\UnknownFieldTypeException;
+use DeepWebSolutions\Framework\Settings\Schema\FieldProcessor;
+use DeepWebSolutions\Framework\Settings\Schema\OptionsResolver;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\UsesClass;
 use PHPUnit\Framework\TestCase;
diff --git a/packages/settings/tests/Unit/ObjectMetaBoxTest.php b/packages/settings/tests/Unit/ObjectMetaBoxTest.php
index 01beaa6..756d3a1 100644
--- a/packages/settings/tests/Unit/ObjectMetaBoxTest.php
+++ b/packages/settings/tests/Unit/ObjectMetaBoxTest.php
@@ -47,7 +47,7 @@ public function test_an_id_outside_the_charset_throws(): void {
 	public function test_array_callable_fields_provider_is_normalized_to_a_closure(): void {
 		$source = new class() {
 			/**
-			 * @return list<\DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField>
+			 * @return list<\DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField>
 			 */
 			public function fields( int $object_id ): array {
 				return array();
diff --git a/packages/settings/tests/Unit/OptionsResolverTest.php b/packages/settings/tests/Unit/OptionsResolverTest.php
index 92c4db4..9be32e3 100644
--- a/packages/settings/tests/Unit/OptionsResolverTest.php
+++ b/packages/settings/tests/Unit/OptionsResolverTest.php
@@ -2,9 +2,9 @@
 
 namespace DeepWebSolutions\Framework\Settings\Tests\Unit;
 
-use DeepWebSolutions\Framework\Settings\Exceptions\InvalidSettingsOptionsException;
-use DeepWebSolutions\Framework\Settings\OptionsResolver;
-use DeepWebSolutions\Framework\Settings\SettingsOptionsProviderInterface;
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\InvalidSettingsOptionsException;
+use DeepWebSolutions\Framework\Settings\Schema\OptionsResolver;
+use DeepWebSolutions\Framework\Settings\Schema\SettingsOptionsProviderInterface;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\TestCase;
 
diff --git a/packages/settings/tests/Unit/SettingsFieldAggregatorTest.php b/packages/settings/tests/Unit/SettingsFieldAggregatorTest.php
index 989d9ca..72c1baa 100644
--- a/packages/settings/tests/Unit/SettingsFieldAggregatorTest.php
+++ b/packages/settings/tests/Unit/SettingsFieldAggregatorTest.php
@@ -2,10 +2,10 @@
 
 namespace DeepWebSolutions\Framework\Settings\Tests\Unit;
 
-use DeepWebSolutions\Framework\Settings\Exceptions\DuplicateSettingsFieldException;
-use DeepWebSolutions\Framework\Settings\SettingsFieldAggregator;
-use DeepWebSolutions\Framework\Settings\SettingsFieldProviderInterface;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\DuplicateSettingsFieldException;
+use DeepWebSolutions\Framework\Settings\Schema\SettingsFieldAggregator;
+use DeepWebSolutions\Framework\Settings\Schema\SettingsFieldProviderInterface;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\UsesClass;
 use PHPUnit\Framework\TestCase;
diff --git a/packages/settings/tests/Unit/SettingsFieldTest.php b/packages/settings/tests/Unit/SettingsFieldTest.php
index 34f576f..8026ce1 100644
--- a/packages/settings/tests/Unit/SettingsFieldTest.php
+++ b/packages/settings/tests/Unit/SettingsFieldTest.php
@@ -2,9 +2,9 @@
 
 namespace DeepWebSolutions\Framework\Settings\Tests\Unit;
 
-use DeepWebSolutions\Framework\Settings\Exceptions\InvalidSettingsFieldException;
-use DeepWebSolutions\Framework\Settings\SettingsOptionsProviderInterface;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\InvalidSettingsFieldException;
+use DeepWebSolutions\Framework\Settings\Schema\SettingsOptionsProviderInterface;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\TestCase;
diff --git a/packages/settings/tests/Unit/SettingsPageTest.php b/packages/settings/tests/Unit/SettingsPageTest.php
index ec4a0b7..0d32afb 100644
--- a/packages/settings/tests/Unit/SettingsPageTest.php
+++ b/packages/settings/tests/Unit/SettingsPageTest.php
@@ -2,8 +2,8 @@
 
 namespace DeepWebSolutions\Framework\Settings\Tests\Unit;
 
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsPage;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsSection;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsPage;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsSection;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\UsesClass;
 use PHPUnit\Framework\TestCase;
diff --git a/packages/settings/tests/Unit/SettingsSectionTest.php b/packages/settings/tests/Unit/SettingsSectionTest.php
index b81917b..0d2000f 100644
--- a/packages/settings/tests/Unit/SettingsSectionTest.php
+++ b/packages/settings/tests/Unit/SettingsSectionTest.php
@@ -2,8 +2,8 @@
 
 namespace DeepWebSolutions\Framework\Settings\Tests\Unit;
 
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsSection;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsSection;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\UsesClass;
 use PHPUnit\Framework\TestCase;
diff --git a/packages/woocommerce/src/SettingsPage/DescriptorBackedWCSettingsPage.php b/packages/woocommerce/src/Backend/DescriptorBackedWCSettingsPage.php
similarity index 95%
rename from packages/woocommerce/src/SettingsPage/DescriptorBackedWCSettingsPage.php
rename to packages/woocommerce/src/Backend/DescriptorBackedWCSettingsPage.php
index add1b34..0404a05 100644
--- a/packages/woocommerce/src/SettingsPage/DescriptorBackedWCSettingsPage.php
+++ b/packages/woocommerce/src/Backend/DescriptorBackedWCSettingsPage.php
@@ -1,9 +1,9 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\WooCommerce\SettingsPage;
+namespace DeepWebSolutions\Framework\WooCommerce\Backend;
 
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsPage;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsSection;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsPage;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsSection;
 use DeepWebSolutions\Framework\WooCommerce\Exceptions\UnboundSettingsPageException;
 
 /**
diff --git a/packages/woocommerce/src/SettingsPage/WCSettingsBuilder.php b/packages/woocommerce/src/Backend/WCSettingsBuilder.php
similarity index 95%
rename from packages/woocommerce/src/SettingsPage/WCSettingsBuilder.php
rename to packages/woocommerce/src/Backend/WCSettingsBuilder.php
index b9fac3f..75e6c39 100644
--- a/packages/woocommerce/src/SettingsPage/WCSettingsBuilder.php
+++ b/packages/woocommerce/src/Backend/WCSettingsBuilder.php
@@ -1,11 +1,11 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\WooCommerce\SettingsPage;
+namespace DeepWebSolutions\Framework\WooCommerce\Backend;
 
-use DeepWebSolutions\Framework\Settings\FieldType;
-use DeepWebSolutions\Framework\Settings\OptionsResolver;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsPage;
+use DeepWebSolutions\Framework\Settings\Schema\FieldType;
+use DeepWebSolutions\Framework\Settings\Schema\OptionsResolver;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsPage;
 
 /**
  * Translates a settings page descriptor into WooCommerce's settings-array format.
diff --git a/packages/woocommerce/src/SettingsPage/WooCommerceSettingsBackend.php b/packages/woocommerce/src/Backend/WooCommerceSettingsBackend.php
similarity index 93%
rename from packages/woocommerce/src/SettingsPage/WooCommerceSettingsBackend.php
rename to packages/woocommerce/src/Backend/WooCommerceSettingsBackend.php
index 56f282e..0067f18 100644
--- a/packages/woocommerce/src/SettingsPage/WooCommerceSettingsBackend.php
+++ b/packages/woocommerce/src/Backend/WooCommerceSettingsBackend.php
@@ -1,12 +1,12 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\WooCommerce\SettingsPage;
+namespace DeepWebSolutions\Framework\WooCommerce\Backend;
 
-use DeepWebSolutions\Framework\Settings\Exceptions\DuplicateSettingsFieldException;
-use DeepWebSolutions\Framework\Settings\Exceptions\InvalidSettingsFieldException;
-use DeepWebSolutions\Framework\Settings\SettingsBackendInterface;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsPage;
+use DeepWebSolutions\Framework\Settings\Backend\SettingsBackendInterface;
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\DuplicateSettingsFieldException;
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\InvalidSettingsFieldException;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsPage;
 
 /**
  * WooCommerce-backed settings backend for a single page.
diff --git a/packages/woocommerce/src/Backend/index.php b/packages/woocommerce/src/Backend/index.php
new file mode 100644
index 0000000..f767346
--- /dev/null
+++ b/packages/woocommerce/src/Backend/index.php
@@ -0,0 +1 @@
+<?php declare( strict_types=1 ); // Silence is golden.
diff --git a/packages/woocommerce/src/OrderData/OrderFieldStore.php b/packages/woocommerce/src/OrderData/OrderFieldStore.php
index 92f5332..e884ccc 100644
--- a/packages/woocommerce/src/OrderData/OrderFieldStore.php
+++ b/packages/woocommerce/src/OrderData/OrderFieldStore.php
@@ -3,13 +3,13 @@
 namespace DeepWebSolutions\Framework\WooCommerce\OrderData;
 
 use Automattic\WooCommerce\Utilities\OrderUtil;
-use DeepWebSolutions\Framework\Settings\Exceptions\DuplicateSettingsFieldException;
-use DeepWebSolutions\Framework\Settings\FieldProcessor;
-use DeepWebSolutions\Framework\Settings\FieldRenderer;
 use DeepWebSolutions\Framework\Settings\ObjectField\Exceptions\InvalidObjectMetaBoxException;
 use DeepWebSolutions\Framework\Settings\ObjectField\ObjectFieldStoreInterface;
 use DeepWebSolutions\Framework\Settings\ObjectField\ValueObjects\ObjectMetaBox;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\DuplicateSettingsFieldException;
+use DeepWebSolutions\Framework\Settings\Schema\FieldProcessor;
+use DeepWebSolutions\Framework\Settings\Schema\FieldRenderer;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
 
 /**
  * WooCommerce-order object-field store: an order meta box plus per-object meta CRUD.
diff --git a/packages/woocommerce/src/ProductData/ProductDataFieldRenderer.php b/packages/woocommerce/src/ProductData/ProductDataFieldRenderer.php
index 1cd8543..5a3a3b1 100644
--- a/packages/woocommerce/src/ProductData/ProductDataFieldRenderer.php
+++ b/packages/woocommerce/src/ProductData/ProductDataFieldRenderer.php
@@ -2,10 +2,10 @@
 
 namespace DeepWebSolutions\Framework\WooCommerce\ProductData;
 
-use DeepWebSolutions\Framework\Settings\Exceptions\UnknownFieldTypeException;
-use DeepWebSolutions\Framework\Settings\FieldType;
-use DeepWebSolutions\Framework\Settings\OptionsResolver;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\UnknownFieldTypeException;
+use DeepWebSolutions\Framework\Settings\Schema\FieldType;
+use DeepWebSolutions\Framework\Settings\Schema\OptionsResolver;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
 
 /**
  * Renders a product-data field as a native WooCommerce control.
diff --git a/packages/woocommerce/src/ProductData/ProductDataFieldStore.php b/packages/woocommerce/src/ProductData/ProductDataFieldStore.php
index e5f246f..3ec9691 100644
--- a/packages/woocommerce/src/ProductData/ProductDataFieldStore.php
+++ b/packages/woocommerce/src/ProductData/ProductDataFieldStore.php
@@ -2,11 +2,11 @@
 
 namespace DeepWebSolutions\Framework\WooCommerce\ProductData;
 
-use DeepWebSolutions\Framework\Settings\Exceptions\DuplicateSettingsFieldException;
-use DeepWebSolutions\Framework\Settings\Exceptions\InvalidSettingsFieldException;
-use DeepWebSolutions\Framework\Settings\FieldProcessor;
-use DeepWebSolutions\Framework\Settings\FieldType;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\DuplicateSettingsFieldException;
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\InvalidSettingsFieldException;
+use DeepWebSolutions\Framework\Settings\Schema\FieldProcessor;
+use DeepWebSolutions\Framework\Settings\Schema\FieldType;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
 
 /**
  * Registers a WooCommerce product-data settings tab and persists its fields as product meta.
diff --git a/packages/woocommerce/src/ProductData/ProductDataTab.php b/packages/woocommerce/src/ProductData/ProductDataTab.php
index 9803c68..224b759 100644
--- a/packages/woocommerce/src/ProductData/ProductDataTab.php
+++ b/packages/woocommerce/src/ProductData/ProductDataTab.php
@@ -2,7 +2,7 @@
 
 namespace DeepWebSolutions\Framework\WooCommerce\ProductData;
 
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsSection;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsSection;
 use DeepWebSolutions\Framework\WooCommerce\Exceptions\InvalidProductDataTabException;
 
 /**
diff --git a/packages/woocommerce/tests/Integration/DescriptorBackedWCSettingsPageTest.php b/packages/woocommerce/tests/Integration/DescriptorBackedWCSettingsPageTest.php
index b1cd1da..c8d9753 100644
--- a/packages/woocommerce/tests/Integration/DescriptorBackedWCSettingsPageTest.php
+++ b/packages/woocommerce/tests/Integration/DescriptorBackedWCSettingsPageTest.php
@@ -2,10 +2,10 @@
 
 namespace DeepWebSolutions\Framework\WooCommerce\Tests\Integration;
 
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsPage;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsSection;
-use DeepWebSolutions\Framework\WooCommerce\SettingsPage\DescriptorBackedWCSettingsPage;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsPage;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsSection;
+use DeepWebSolutions\Framework\WooCommerce\Backend\DescriptorBackedWCSettingsPage;
 use DeepWebSolutions\Framework\WooCommerce\Exceptions\UnboundSettingsPageException;
 use DeepWebSolutions\Framework\WooCommerce\Tests\Integration\Fixtures\BarWCSettingsPage;
 use DeepWebSolutions\Framework\WooCommerce\Tests\Integration\Fixtures\FooWCSettingsPage;
diff --git a/packages/woocommerce/tests/Integration/Fixtures/BarWCSettingsPage.php b/packages/woocommerce/tests/Integration/Fixtures/BarWCSettingsPage.php
index bb3e2fc..105d8c8 100644
--- a/packages/woocommerce/tests/Integration/Fixtures/BarWCSettingsPage.php
+++ b/packages/woocommerce/tests/Integration/Fixtures/BarWCSettingsPage.php
@@ -2,7 +2,7 @@
 
 namespace DeepWebSolutions\Framework\WooCommerce\Tests\Integration\Fixtures;
 
-use DeepWebSolutions\Framework\WooCommerce\SettingsPage\DescriptorBackedWCSettingsPage;
+use DeepWebSolutions\Framework\WooCommerce\Backend\DescriptorBackedWCSettingsPage;
 
 /**
  * A second distinct settings-page subclass standing in for another plugin's coexisting page.
diff --git a/packages/woocommerce/tests/Integration/Fixtures/FooWCSettingsPage.php b/packages/woocommerce/tests/Integration/Fixtures/FooWCSettingsPage.php
index 5f0ad3e..f827ab2 100644
--- a/packages/woocommerce/tests/Integration/Fixtures/FooWCSettingsPage.php
+++ b/packages/woocommerce/tests/Integration/Fixtures/FooWCSettingsPage.php
@@ -2,7 +2,7 @@
 
 namespace DeepWebSolutions\Framework\WooCommerce\Tests\Integration\Fixtures;
 
-use DeepWebSolutions\Framework\WooCommerce\SettingsPage\DescriptorBackedWCSettingsPage;
+use DeepWebSolutions\Framework\WooCommerce\Backend\DescriptorBackedWCSettingsPage;
 
 /**
  * A distinct, REST-safe settings-page subclass standing in for one consumer plugin's page.
diff --git a/packages/woocommerce/tests/Integration/Fixtures/LazyBindWCSettingsPage.php b/packages/woocommerce/tests/Integration/Fixtures/LazyBindWCSettingsPage.php
index dcbc750..5f322db 100644
--- a/packages/woocommerce/tests/Integration/Fixtures/LazyBindWCSettingsPage.php
+++ b/packages/woocommerce/tests/Integration/Fixtures/LazyBindWCSettingsPage.php
@@ -2,7 +2,7 @@
 
 namespace DeepWebSolutions\Framework\WooCommerce\Tests\Integration\Fixtures;
 
-use DeepWebSolutions\Framework\WooCommerce\SettingsPage\DescriptorBackedWCSettingsPage;
+use DeepWebSolutions\Framework\WooCommerce\Backend\DescriptorBackedWCSettingsPage;
 
 /**
  * A subclass bound by no other test, used to prove register_page() defers binding until the filter fires.
diff --git a/packages/woocommerce/tests/Integration/Fixtures/UnboundWCSettingsPage.php b/packages/woocommerce/tests/Integration/Fixtures/UnboundWCSettingsPage.php
index 83406d9..aa8899d 100644
--- a/packages/woocommerce/tests/Integration/Fixtures/UnboundWCSettingsPage.php
+++ b/packages/woocommerce/tests/Integration/Fixtures/UnboundWCSettingsPage.php
@@ -2,7 +2,7 @@
 
 namespace DeepWebSolutions\Framework\WooCommerce\Tests\Integration\Fixtures;
 
-use DeepWebSolutions\Framework\WooCommerce\SettingsPage\DescriptorBackedWCSettingsPage;
+use DeepWebSolutions\Framework\WooCommerce\Backend\DescriptorBackedWCSettingsPage;
 
 /**
  * A subclass deliberately never bound to a descriptor, to exercise the unbound-instantiation guard.
diff --git a/packages/woocommerce/tests/Integration/OrderData/OrderFieldStoreTest.php b/packages/woocommerce/tests/Integration/OrderData/OrderFieldStoreTest.php
index 5b43349..38cba71 100644
--- a/packages/woocommerce/tests/Integration/OrderData/OrderFieldStoreTest.php
+++ b/packages/woocommerce/tests/Integration/OrderData/OrderFieldStoreTest.php
@@ -3,14 +3,14 @@
 namespace DeepWebSolutions\Framework\WooCommerce\Tests\Integration\OrderData;
 
 use Automattic\WooCommerce\Utilities\OrderUtil;
-use DeepWebSolutions\Framework\Settings\Exceptions\DuplicateSettingsFieldException;
-use DeepWebSolutions\Framework\Settings\FieldProcessor;
-use DeepWebSolutions\Framework\Settings\FieldRenderer;
-use DeepWebSolutions\Framework\Settings\FieldType;
 use DeepWebSolutions\Framework\Settings\ObjectField\Exceptions\InvalidObjectMetaBoxException;
 use DeepWebSolutions\Framework\Settings\ObjectField\ValueObjects\ObjectMetaBox;
-use DeepWebSolutions\Framework\Settings\OptionsResolver;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\DuplicateSettingsFieldException;
+use DeepWebSolutions\Framework\Settings\Schema\FieldProcessor;
+use DeepWebSolutions\Framework\Settings\Schema\FieldRenderer;
+use DeepWebSolutions\Framework\Settings\Schema\FieldType;
+use DeepWebSolutions\Framework\Settings\Schema\OptionsResolver;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
 use DeepWebSolutions\Framework\WooCommerce\OrderData\OrderFieldStore;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\UsesClass;
diff --git a/packages/woocommerce/tests/Integration/ProductDataFieldRendererTest.php b/packages/woocommerce/tests/Integration/ProductDataFieldRendererTest.php
index cfc1728..8e94a86 100644
--- a/packages/woocommerce/tests/Integration/ProductDataFieldRendererTest.php
+++ b/packages/woocommerce/tests/Integration/ProductDataFieldRendererTest.php
@@ -2,9 +2,9 @@
 
 namespace DeepWebSolutions\Framework\WooCommerce\Tests\Integration;
 
-use DeepWebSolutions\Framework\Settings\Exceptions\UnknownFieldTypeException;
-use DeepWebSolutions\Framework\Settings\OptionsResolver;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\UnknownFieldTypeException;
+use DeepWebSolutions\Framework\Settings\Schema\OptionsResolver;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
 use DeepWebSolutions\Framework\WooCommerce\ProductData\ProductDataFieldRenderer;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\UsesClass;
diff --git a/packages/woocommerce/tests/Integration/ProductDataFieldStoreTest.php b/packages/woocommerce/tests/Integration/ProductDataFieldStoreTest.php
index 758e5f2..4429d68 100644
--- a/packages/woocommerce/tests/Integration/ProductDataFieldStoreTest.php
+++ b/packages/woocommerce/tests/Integration/ProductDataFieldStoreTest.php
@@ -2,10 +2,10 @@
 
 namespace DeepWebSolutions\Framework\WooCommerce\Tests\Integration;
 
-use DeepWebSolutions\Framework\Settings\Exceptions\DuplicateSettingsFieldException;
-use DeepWebSolutions\Framework\Settings\Exceptions\InvalidSettingsFieldException;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsSection;
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\DuplicateSettingsFieldException;
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\InvalidSettingsFieldException;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsSection;
 use DeepWebSolutions\Framework\WooCommerce\ProductData\ProductDataFieldStore;
 use DeepWebSolutions\Framework\WooCommerce\ProductData\ProductDataTab;
 use PHPUnit\Framework\TestCase;
diff --git a/packages/woocommerce/tests/Integration/WooCommerceSettingsBackendTest.php b/packages/woocommerce/tests/Integration/WooCommerceSettingsBackendTest.php
index 6799538..51e0c58 100644
--- a/packages/woocommerce/tests/Integration/WooCommerceSettingsBackendTest.php
+++ b/packages/woocommerce/tests/Integration/WooCommerceSettingsBackendTest.php
@@ -2,16 +2,16 @@
 
 namespace DeepWebSolutions\Framework\WooCommerce\Tests\Integration;
 
-use DeepWebSolutions\Framework\Settings\Exceptions\DuplicateSettingsFieldException;
-use DeepWebSolutions\Framework\Settings\Exceptions\InvalidSettingsFieldException;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsPage;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsSection;
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\DuplicateSettingsFieldException;
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\InvalidSettingsFieldException;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsPage;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsSection;
+use DeepWebSolutions\Framework\WooCommerce\Backend\WooCommerceSettingsBackend;
 use DeepWebSolutions\Framework\WooCommerce\Exceptions\UnboundSettingsPageException;
 use DeepWebSolutions\Framework\WooCommerce\Tests\Integration\Fixtures\BarWCSettingsPage;
 use DeepWebSolutions\Framework\WooCommerce\Tests\Integration\Fixtures\FooWCSettingsPage;
 use DeepWebSolutions\Framework\WooCommerce\Tests\Integration\Fixtures\LazyBindWCSettingsPage;
-use DeepWebSolutions\Framework\WooCommerce\SettingsPage\WooCommerceSettingsBackend;
 use PHPUnit\Framework\TestCase;
 
 final class WooCommerceSettingsBackendTest extends TestCase {
diff --git a/packages/woocommerce/tests/Unit/ProductDataFieldRendererTest.php b/packages/woocommerce/tests/Unit/ProductDataFieldRendererTest.php
index 070f3c0..735f7b5 100644
--- a/packages/woocommerce/tests/Unit/ProductDataFieldRendererTest.php
+++ b/packages/woocommerce/tests/Unit/ProductDataFieldRendererTest.php
@@ -2,9 +2,9 @@
 
 namespace DeepWebSolutions\Framework\WooCommerce\Tests\Unit;
 
-use DeepWebSolutions\Framework\Settings\FieldType;
-use DeepWebSolutions\Framework\Settings\OptionsResolver;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
+use DeepWebSolutions\Framework\Settings\Schema\FieldType;
+use DeepWebSolutions\Framework\Settings\Schema\OptionsResolver;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
 use DeepWebSolutions\Framework\WooCommerce\ProductData\ProductDataFieldRenderer;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\UsesClass;
diff --git a/packages/woocommerce/tests/Unit/ProductDataTabTest.php b/packages/woocommerce/tests/Unit/ProductDataTabTest.php
index b36c115..889b171 100644
--- a/packages/woocommerce/tests/Unit/ProductDataTabTest.php
+++ b/packages/woocommerce/tests/Unit/ProductDataTabTest.php
@@ -2,8 +2,8 @@
 
 namespace DeepWebSolutions\Framework\WooCommerce\Tests\Unit;
 
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsSection;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsSection;
 use DeepWebSolutions\Framework\WooCommerce\Exceptions\InvalidProductDataTabException;
 use DeepWebSolutions\Framework\WooCommerce\ProductData\ProductDataTab;
 use PHPUnit\Framework\Attributes\CoversClass;
diff --git a/packages/woocommerce/tests/Unit/WCSettingsBuilderTest.php b/packages/woocommerce/tests/Unit/WCSettingsBuilderTest.php
index d3b4e41..cb1d3c0 100644
--- a/packages/woocommerce/tests/Unit/WCSettingsBuilderTest.php
+++ b/packages/woocommerce/tests/Unit/WCSettingsBuilderTest.php
@@ -2,11 +2,11 @@
 
 namespace DeepWebSolutions\Framework\WooCommerce\Tests\Unit;
 
-use DeepWebSolutions\Framework\Settings\OptionsResolver;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsField;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsPage;
-use DeepWebSolutions\Framework\Settings\ValueObjects\SettingsSection;
-use DeepWebSolutions\Framework\WooCommerce\SettingsPage\WCSettingsBuilder;
+use DeepWebSolutions\Framework\Settings\Schema\OptionsResolver;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsPage;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsSection;
+use DeepWebSolutions\Framework\WooCommerce\Backend\WCSettingsBuilder;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\UsesClass;
 use PHPUnit\Framework\TestCase;
diff --git a/tests/Fixtures/consumer-smoke/smoke.php b/tests/Fixtures/consumer-smoke/smoke.php
index 599d277..f465106 100644
--- a/tests/Fixtures/consumer-smoke/smoke.php
+++ b/tests/Fixtures/consumer-smoke/smoke.php
@@ -47,8 +47,8 @@
 }
 
 // Settings PSR-4: the descriptor value objects resolve under the scoped prefix.
-if ( ! class_exists( 'DWS_CONSUMER_SMOKE_Deps\\DeepWebSolutions\\Framework\\Settings\\ValueObjects\\SettingsField' ) ) {
-	$failures[] = 'missing scoped class: DeepWebSolutions\\Framework\\Settings\\ValueObjects\\SettingsField';
+if ( ! class_exists( 'DWS_CONSUMER_SMOKE_Deps\\DeepWebSolutions\\Framework\\Settings\\Schema\\ValueObjects\\SettingsField' ) ) {
+	$failures[] = 'missing scoped class: DeepWebSolutions\\Framework\\Settings\\Schema\\ValueObjects\\SettingsField';
 }
 
 // WooCommerce order-field store: the class that references WooCommerce symbols resolves under the

From e15840806eda233b49e4ad2bfd43077b141168a1 Mon Sep 17 00:00:00 2001
From: Tony Hegyes <a.hegyes@proton.me>
Date: Sun, 21 Jun 2026 21:13:27 +0200
Subject: [PATCH 06/21] refactor(settings,woocommerce): consolidate duplicated
 field policy into Schema free functions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Pre-Phase-4 hardening — collapse copy-pasted field logic across the
settings/woocommerce tier into namespaced free functions (the framework's
convention, not static utility classes):

  Settings\Schema\filter_field_attributes()                        (#6, #16)
  Settings\Schema\is_valid_identifier()                            (#20)
  Settings\Schema\is_checkbox_checked()                            (#6, canonical)
  Settings\Schema\is_field_editable_by_current_user(SettingsField) (#6)
  WooCommerce\to_yes_no()                                          (#6, Schema wrapper)

#6 — the field-capability gate (copy-pasted across ~6 sites) and the
attribute security filter + checkbox yes/no coercion (copy-pasted 3x with
divergent rules) now have one owner each. The capability gate is a free
function, not a method, to keep current_user_can() off the readonly
SettingsField descriptor.

Fixes a live checkbox bug: WCSettingsBuilder's (bool) cast (and
FieldRenderer's checked state) mapped 'no' and arbitrary non-empty strings
to checked/'yes'; the canonical rule (true/1/'1'/'yes' => checked) maps them
to 'no'. The two ProductData sites already matched the canonical rule.

#20 — id-charset validation now also covers SettingsSection id and
SettingsPage slug (both feed wp_options keys), throwing new typed
InvalidSettingsSectionException / InvalidSettingsPageException.

#16 — the attribute filter keeps its strict on*-prefix block (a security
control; narrowing to a handler denylist would risk under-blocking).

Populating settings + woocommerce functions.php also clears the empty-
aggregator finding (#9) for those two packages. deptrac unchanged.
PHPStan clean, Unit 377, Integration 277.

Assisted-by: Claude Code:claude-opus-4-8
---
 packages/settings/functions.php               |   4 +-
 .../src/Backend/WordPressSettingsBackend.php  |  20 +--
 .../ValueObjects/ObjectMetaBox.php            |  14 +-
 .../InvalidSettingsPageException.php          |  13 ++
 .../InvalidSettingsSectionException.php       |  13 ++
 .../settings/src/Schema/FieldRenderer.php     |  15 +-
 .../src/Schema/ValueObjects/SettingsField.php |  14 +-
 .../src/Schema/ValueObjects/SettingsPage.php  |  15 +-
 .../Schema/ValueObjects/SettingsSection.php   |  15 +-
 packages/settings/src/Schema/functions.php    |  81 +++++++++
 .../tests/Integration/SchemaFunctionsTest.php |  69 ++++++++
 .../tests/Unit/SchemaFunctionsTest.php        | 163 ++++++++++++++++++
 .../settings/tests/Unit/SettingsPageTest.php  |  53 ++++++
 .../tests/Unit/SettingsSectionTest.php        |  43 +++++
 packages/woocommerce/functions.php            |   4 +-
 .../DescriptorBackedWCSettingsPage.php        |   4 +-
 .../src/Backend/WCSettingsBuilder.php         |  53 +-----
 .../Backend/WooCommerceSettingsBackend.php    |  11 +-
 .../src/OrderData/OrderFieldStore.php         |  20 +--
 .../ProductData/ProductDataFieldRenderer.php  |  47 +----
 .../src/ProductData/ProductDataFieldStore.php |  39 +----
 .../src/ProductData/ProductDataTab.php        |  14 +-
 packages/woocommerce/src/functions.php        |  21 +++
 .../woocommerce/tests/Unit/FunctionsTest.php  |  44 +++++
 .../tests/Unit/WCSettingsBuilderTest.php      |  32 ++++
 25 files changed, 608 insertions(+), 213 deletions(-)
 create mode 100644 packages/settings/src/Schema/Exceptions/InvalidSettingsPageException.php
 create mode 100644 packages/settings/src/Schema/Exceptions/InvalidSettingsSectionException.php
 create mode 100644 packages/settings/src/Schema/functions.php
 create mode 100644 packages/settings/tests/Integration/SchemaFunctionsTest.php
 create mode 100644 packages/settings/tests/Unit/SchemaFunctionsTest.php
 create mode 100644 packages/woocommerce/src/functions.php
 create mode 100644 packages/woocommerce/tests/Unit/FunctionsTest.php

diff --git a/packages/settings/functions.php b/packages/settings/functions.php
index c993c4d..8dfe40f 100644
--- a/packages/settings/functions.php
+++ b/packages/settings/functions.php
@@ -1,5 +1,3 @@
 <?php declare( strict_types=1 );
 
-// No namespace functions in settings. This file exists for workspace-wide
-// consistency with the package-root functions.php aggregator pattern; when a
-// <namespace>/functions.php file is added under src/, require_once it here.
+require_once __DIR__ . '/src/Schema/functions.php';
diff --git a/packages/settings/src/Backend/WordPressSettingsBackend.php b/packages/settings/src/Backend/WordPressSettingsBackend.php
index 6fa106f..b23a6b3 100644
--- a/packages/settings/src/Backend/WordPressSettingsBackend.php
+++ b/packages/settings/src/Backend/WordPressSettingsBackend.php
@@ -13,6 +13,8 @@
 use DeepWebSolutions\Framework\Storage\OptionsStore;
 use Psr\Log\LoggerInterface;
 
+use function DeepWebSolutions\Framework\Settings\Schema\is_field_editable_by_current_user;
+
 /**
  * WordPress options-backed settings backend for a single page.
  *
@@ -292,7 +294,7 @@ private function render_page( SettingsPage $page ): void {
 			\settings_fields( $option_name );
 			echo '<table class="form-table" role="presentation"><tbody>';
 			foreach ( $section->fields as $field ) {
-				if ( ! $this->can_edit( $field ) ) {
+				if ( ! is_field_editable_by_current_user( $field ) ) {
 					continue;
 				}
 				echo '<tr><th scope="row">' . \esc_html( $field->label ) . '</th><td>';
@@ -353,7 +355,7 @@ private function sanitize( SettingsSection $section, string $option_name, mixed
 
 		$output = array();
 		foreach ( $section->fields as $field ) {
-			if ( ! $this->can_edit( $field ) ) {
+			if ( ! is_field_editable_by_current_user( $field ) ) {
 				if ( \array_key_exists( $field->id, $existing ) ) {
 					$output[ $field->id ] = $existing[ $field->id ];
 				}
@@ -365,19 +367,5 @@ private function sanitize( SettingsSection $section, string $option_name, mixed
 		return $output;
 	}
 
-	/**
-	 * Whether the current user may edit the given field.
-	 *
-	 * @since   2.0.0
-	 * @version 2.0.0
-	 *
-	 * @param   SettingsField $field Field to check.
-	 *
-	 * @return  bool
-	 */
-	private function can_edit( SettingsField $field ): bool {
-		return null === $field->capability || \current_user_can( $field->capability );
-	}
-
 	// endregion
 }
diff --git a/packages/settings/src/ObjectField/ValueObjects/ObjectMetaBox.php b/packages/settings/src/ObjectField/ValueObjects/ObjectMetaBox.php
index b696c4f..01c2501 100644
--- a/packages/settings/src/ObjectField/ValueObjects/ObjectMetaBox.php
+++ b/packages/settings/src/ObjectField/ValueObjects/ObjectMetaBox.php
@@ -4,6 +4,8 @@
 
 use DeepWebSolutions\Framework\Settings\ObjectField\Exceptions\InvalidObjectMetaBoxException;
 
+use function DeepWebSolutions\Framework\Settings\Schema\is_valid_identifier;
+
 /**
  * Descriptor for a per-entity meta box (object fields).
  *
@@ -18,16 +20,6 @@
 final readonly class ObjectMetaBox {
 	// region FIELDS AND CONSTANTS
 
-	/**
-	 * Meta-box id charset: a lowercase token safe to emit into WordPress meta-box markup unescaped.
-	 *
-	 * @since   2.0.0
-	 * @version 2.0.0
-	 *
-	 * @var     string
-	 */
-	private const ID_PATTERN = '/\A[a-z][a-z0-9_-]*\z/';
-
 	/**
 	 * Builds the fields for a given object id: signature `(int $object_id): list<SettingsField>`.
 	 *
@@ -89,7 +81,7 @@ public function __construct(
 		?callable $render = null,
 		?callable $save = null,
 	) {
-		if ( 1 !== \preg_match( self::ID_PATTERN, $id ) ) {
+		if ( ! is_valid_identifier( $id ) ) {
 			// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- framework-internal exception; never reaches an HTML output context unescaped.
 			throw new InvalidObjectMetaBoxException( "Invalid object meta-box id: '$id'" );
 		}
diff --git a/packages/settings/src/Schema/Exceptions/InvalidSettingsPageException.php b/packages/settings/src/Schema/Exceptions/InvalidSettingsPageException.php
new file mode 100644
index 0000000..b1c8758
--- /dev/null
+++ b/packages/settings/src/Schema/Exceptions/InvalidSettingsPageException.php
@@ -0,0 +1,13 @@
+<?php declare( strict_types=1 );
+
+namespace DeepWebSolutions\Framework\Settings\Schema\Exceptions;
+
+use DeepWebSolutions\Framework\Shared\Exception\AbstractInvalidArgumentException;
+
+/**
+ * Thrown when a settings page slug is malformed against the slug charset at descriptor construction.
+ *
+ * @since   2.0.0
+ * @version 2.0.0
+ */
+final class InvalidSettingsPageException extends AbstractInvalidArgumentException {}
diff --git a/packages/settings/src/Schema/Exceptions/InvalidSettingsSectionException.php b/packages/settings/src/Schema/Exceptions/InvalidSettingsSectionException.php
new file mode 100644
index 0000000..29e194a
--- /dev/null
+++ b/packages/settings/src/Schema/Exceptions/InvalidSettingsSectionException.php
@@ -0,0 +1,13 @@
+<?php declare( strict_types=1 );
+
+namespace DeepWebSolutions\Framework\Settings\Schema\Exceptions;
+
+use DeepWebSolutions\Framework\Shared\Exception\AbstractInvalidArgumentException;
+
+/**
+ * Thrown when a settings section identifier is malformed against the id charset at descriptor construction.
+ *
+ * @since   2.0.0
+ * @version 2.0.0
+ */
+final class InvalidSettingsSectionException extends AbstractInvalidArgumentException {}
diff --git a/packages/settings/src/Schema/FieldRenderer.php b/packages/settings/src/Schema/FieldRenderer.php
index cc53fb7..23fd9f5 100644
--- a/packages/settings/src/Schema/FieldRenderer.php
+++ b/packages/settings/src/Schema/FieldRenderer.php
@@ -5,6 +5,9 @@
 use DeepWebSolutions\Framework\Settings\Schema\Exceptions\UnknownFieldTypeException;
 use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
 
+use function DeepWebSolutions\Framework\Settings\Schema\filter_field_attributes;
+use function DeepWebSolutions\Framework\Settings\Schema\is_checkbox_checked;
+
 /**
  * Renders a field descriptor to an escaped HTML control with its value bound.
  *
@@ -133,7 +136,7 @@ private function render_checkbox( SettingsField $field, mixed $value, string $na
 		return \sprintf(
 			'<input type="checkbox" name="%s" value="1"%s%s />',
 			\esc_attr( $name ),
-			\checked( (bool) $value, true, false ),
+			\checked( is_checkbox_checked( $value ), true, false ),
 			$this->render_attributes( $field->attributes ),
 		);
 	}
@@ -217,15 +220,7 @@ private function render_radio( SettingsField $field, mixed $value, string $name
 	 */
 	private function render_attributes( array $attributes ): string {
 		$rendered = '';
-		foreach ( $attributes as $attribute => $attribute_value ) {
-			$attribute = (string) $attribute;
-
-			// Emit only plain attribute names, never an event handler: a descriptor must not be able to inject
-			// an executable on* attribute, nor a space-separated second attribute through a crafted key.
-			if ( 1 !== \preg_match( '/\A[a-z][a-z0-9-]*\z/i', $attribute ) || 0 === \stripos( $attribute, 'on' ) ) {
-				continue;
-			}
-
+		foreach ( filter_field_attributes( $attributes ) as $attribute => $attribute_value ) {
 			$rendered .= \sprintf( ' %s="%s"', \esc_attr( $attribute ), \esc_attr( (string) $attribute_value ) );
 		}
 
diff --git a/packages/settings/src/Schema/ValueObjects/SettingsField.php b/packages/settings/src/Schema/ValueObjects/SettingsField.php
index 196dfcc..1c2b62e 100644
--- a/packages/settings/src/Schema/ValueObjects/SettingsField.php
+++ b/packages/settings/src/Schema/ValueObjects/SettingsField.php
@@ -5,6 +5,8 @@
 use DeepWebSolutions\Framework\Settings\Schema\Exceptions\InvalidSettingsFieldException;
 use DeepWebSolutions\Framework\Settings\Schema\SettingsOptionsProviderInterface;
 
+use function DeepWebSolutions\Framework\Settings\Schema\is_valid_identifier;
+
 /**
  * Descriptor for a single settings field, storage- and UI-agnostic.
  *
@@ -21,16 +23,6 @@
 final readonly class SettingsField {
 	// region FIELDS AND CONSTANTS
 
-	/**
-	 * Identifier charset: a lowercase letter followed by lowercase letters, digits, underscores, or hyphens.
-	 *
-	 * @since   2.0.0
-	 * @version 2.0.0
-	 *
-	 * @var     string
-	 */
-	private const ID_PATTERN = '/\A[a-z][a-z0-9_-]*\z/';
-
 	/**
 	 * Sanitizer applied to the submitted value before validation; null leaves the value untouched.
 	 *
@@ -92,7 +84,7 @@ public function __construct(
 		public ?string $meta_key = null,
 		public ?string $description = null,
 	) {
-		if ( 1 !== \preg_match( self::ID_PATTERN, $id ) ) {
+		if ( ! is_valid_identifier( $id ) ) {
 			// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- framework-internal exception; never reaches an HTML output context unescaped.
 			throw new InvalidSettingsFieldException( "Invalid settings field id: '$id'" );
 		}
diff --git a/packages/settings/src/Schema/ValueObjects/SettingsPage.php b/packages/settings/src/Schema/ValueObjects/SettingsPage.php
index ba58e4b..c06200c 100644
--- a/packages/settings/src/Schema/ValueObjects/SettingsPage.php
+++ b/packages/settings/src/Schema/ValueObjects/SettingsPage.php
@@ -2,6 +2,10 @@
 
 namespace DeepWebSolutions\Framework\Settings\Schema\ValueObjects;
 
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\InvalidSettingsPageException;
+
+use function DeepWebSolutions\Framework\Settings\Schema\is_valid_identifier;
+
 /**
  * Descriptor for a settings page: a titled, capability-gated screen composed
  * of sections.
@@ -22,12 +26,14 @@
 	 * @since   2.0.0
 	 * @version 2.0.0
 	 *
-	 * @param   string                $slug Menu slug, unique across registered pages.
+	 * @param   string                $slug Menu slug, unique across registered pages; a lowercase token matching the slug charset.
 	 * @param   string                $page_title Title rendered at the top of the page.
 	 * @param   string                $menu_title Label shown in the admin menu.
 	 * @param   string                $capability Capability required to view and save the page.
 	 * @param   ?string               $location Backend-interpreted placement (WordPress parent slug, WooCommerce tab id); null uses the backend default.
 	 * @param   list<SettingsSection> $sections Sections composing the page, in display order.
+	 *
+	 * @throws  InvalidSettingsPageException If $slug does not match the slug charset.
 	 */
 	public function __construct(
 		public string $slug,
@@ -36,7 +42,12 @@ public function __construct(
 		public string $capability,
 		public ?string $location = null,
 		public array $sections = array(),
-	) {}
+	) {
+		if ( ! is_valid_identifier( $slug ) ) {
+			// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- framework-internal exception; never reaches an HTML output context unescaped.
+			throw new InvalidSettingsPageException( "Invalid settings page slug: '$slug'" );
+		}
+	}
 
 	// endregion
 }
diff --git a/packages/settings/src/Schema/ValueObjects/SettingsSection.php b/packages/settings/src/Schema/ValueObjects/SettingsSection.php
index 8c63f7b..91310a4 100644
--- a/packages/settings/src/Schema/ValueObjects/SettingsSection.php
+++ b/packages/settings/src/Schema/ValueObjects/SettingsSection.php
@@ -2,6 +2,10 @@
 
 namespace DeepWebSolutions\Framework\Settings\Schema\ValueObjects;
 
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\InvalidSettingsSectionException;
+
+use function DeepWebSolutions\Framework\Settings\Schema\is_valid_identifier;
+
 /**
  * Descriptor for a settings section: a titled group of fields.
  *
@@ -22,15 +26,22 @@
 	 * @since   2.0.0
 	 * @version 2.0.0
 	 *
-	 * @param   string              $id Section identifier, unique within its page.
+	 * @param   string              $id Section identifier, unique within its page; a lowercase token matching the id charset.
 	 * @param   string              $title Human-readable section heading.
 	 * @param   list<SettingsField> $fields Fields belonging to the section, in display order.
+	 *
+	 * @throws  InvalidSettingsSectionException If $id does not match the id charset.
 	 */
 	public function __construct(
 		public string $id,
 		public string $title,
 		public array $fields,
-	) {}
+	) {
+		if ( ! is_valid_identifier( $id ) ) {
+			// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- framework-internal exception; never reaches an HTML output context unescaped.
+			throw new InvalidSettingsSectionException( "Invalid settings section id: '$id'" );
+		}
+	}
 
 	// endregion
 }
diff --git a/packages/settings/src/Schema/functions.php b/packages/settings/src/Schema/functions.php
new file mode 100644
index 0000000..da0ff72
--- /dev/null
+++ b/packages/settings/src/Schema/functions.php
@@ -0,0 +1,81 @@
+<?php declare( strict_types=1 );
+
+namespace DeepWebSolutions\Framework\Settings\Schema;
+
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
+
+/**
+ * Filters a descriptor's HTML attribute map to the names safe to emit into a control unescaped.
+ *
+ * Keeps an attribute only when its name is a plain attribute token — a letter followed by letters,
+ * digits, or hyphens — and does not begin with `on`. Blocks every `on<event>` handler by prefix
+ * (conservative; no standard control attribute starts with `on`), so a descriptor cannot inject an
+ * executable handler nor smuggle a space-separated second attribute through a crafted key.
+ *
+ * @since   2.0.0
+ * @version 2.0.0
+ *
+ * @param   array<string, scalar> $attributes Attribute map to filter.
+ *
+ * @return  array<string, scalar>
+ */
+function filter_field_attributes( array $attributes ): array {
+	$filtered = array();
+	foreach ( $attributes as $attribute => $value ) {
+		$attribute = (string) $attribute;
+		if ( 1 !== \preg_match( '/\A[a-z][a-z0-9-]*\z/i', $attribute ) || 0 === \stripos( $attribute, 'on' ) ) {
+			continue;
+		}
+
+		$filtered[ $attribute ] = $value;
+	}
+
+	return $filtered;
+}
+
+/**
+ * Whether a string is a valid settings identifier: a lowercase letter followed by lowercase letters,
+ * digits, underscores, or hyphens.
+ *
+ * @since   2.0.0
+ * @version 2.0.0
+ *
+ * @param   string $identifier Identifier to validate.
+ *
+ * @return  bool
+ */
+function is_valid_identifier( string $identifier ): bool {
+	return 1 === \preg_match( '/\A[a-z][a-z0-9_-]*\z/', $identifier );
+}
+
+/**
+ * The canonical checkbox truth rule: a value is checked only when it is boolean true, the integer 1,
+ * the string '1', or the string 'yes'. Everything else — false, 0, '0', 'no', '', null, 'on', any
+ * other string, an array — is unchecked.
+ *
+ * @since   2.0.0
+ * @version 2.0.0
+ *
+ * @param   mixed $value Value to evaluate.
+ *
+ * @return  bool
+ */
+function is_checkbox_checked( mixed $value ): bool {
+	return true === $value || 1 === $value || '1' === $value || 'yes' === $value;
+}
+
+/**
+ * Whether the current user may edit a field: a field with no capability is always editable, otherwise
+ * the current user must hold the field's capability. A free function on purpose, keeping the
+ * current_user_can() runtime check off the readonly SettingsField descriptor.
+ *
+ * @since   2.0.0
+ * @version 2.0.0
+ *
+ * @param   SettingsField $field Field whose capability gate to evaluate.
+ *
+ * @return  bool
+ */
+function is_field_editable_by_current_user( SettingsField $field ): bool {
+	return null === $field->capability || \current_user_can( $field->capability );
+}
diff --git a/packages/settings/tests/Integration/SchemaFunctionsTest.php b/packages/settings/tests/Integration/SchemaFunctionsTest.php
new file mode 100644
index 0000000..9a1d442
--- /dev/null
+++ b/packages/settings/tests/Integration/SchemaFunctionsTest.php
@@ -0,0 +1,69 @@
+<?php declare( strict_types=1 );
+
+namespace DeepWebSolutions\Framework\Settings\Tests\Integration;
+
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
+use PHPUnit\Framework\Attributes\CoversFunction;
+use PHPUnit\Framework\Attributes\UsesClass;
+use PHPUnit\Framework\TestCase;
+
+use function DeepWebSolutions\Framework\Settings\Schema\is_field_editable_by_current_user;
+
+#[CoversFunction( 'DeepWebSolutions\Framework\Settings\Schema\is_field_editable_by_current_user' )]
+#[UsesClass( SettingsField::class )]
+final class SchemaFunctionsTest extends TestCase {
+	private int $original_user;
+	private int $admin;
+	private int $subscriber;
+
+	protected function setUp(): void {
+		parent::setUp();
+		$this->original_user = \get_current_user_id();
+		$this->admin         = $this->make_user( 'dws-field-editable-admin', 'administrator' );
+		$this->subscriber    = $this->make_user( 'dws-field-editable-subscriber', 'subscriber' );
+	}
+
+	protected function tearDown(): void {
+		\wp_set_current_user( $this->original_user );
+		parent::tearDown();
+	}
+
+	public function test_a_field_with_no_capability_is_always_editable(): void {
+		\wp_set_current_user( $this->subscriber );
+		$field = new SettingsField( id: 'open', type: 'text', label: 'Open' );
+
+		self::assertTrue( is_field_editable_by_current_user( $field ) );
+	}
+
+	public function test_a_field_is_editable_when_the_current_user_holds_its_capability(): void {
+		\wp_set_current_user( $this->admin );
+		$field = new SettingsField( id: 'secret', type: 'text', label: 'Secret', capability: 'manage_options' );
+
+		self::assertTrue( is_field_editable_by_current_user( $field ) );
+	}
+
+	public function test_a_field_is_not_editable_when_the_current_user_lacks_its_capability(): void {
+		\wp_set_current_user( $this->subscriber );
+		$field = new SettingsField( id: 'secret', type: 'text', label: 'Secret', capability: 'manage_options' );
+
+		self::assertFalse( is_field_editable_by_current_user( $field ) );
+	}
+
+	private function make_user( string $login, string $role ): int {
+		$existing = \get_user_by( 'login', $login );
+		if ( $existing instanceof \WP_User ) {
+			return $existing->ID;
+		}
+
+		$id = \wp_insert_user(
+			array(
+				'user_login' => $login,
+				'user_pass'  => 'password',
+				'role'       => $role,
+			),
+		);
+		self::assertIsInt( $id );
+
+		return $id;
+	}
+}
diff --git a/packages/settings/tests/Unit/SchemaFunctionsTest.php b/packages/settings/tests/Unit/SchemaFunctionsTest.php
new file mode 100644
index 0000000..d378d58
--- /dev/null
+++ b/packages/settings/tests/Unit/SchemaFunctionsTest.php
@@ -0,0 +1,163 @@
+<?php declare( strict_types=1 );
+
+namespace DeepWebSolutions\Framework\Settings\Tests\Unit;
+
+use PHPUnit\Framework\Attributes\CoversFunction;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+
+use function DeepWebSolutions\Framework\Settings\Schema\filter_field_attributes;
+use function DeepWebSolutions\Framework\Settings\Schema\is_checkbox_checked;
+use function DeepWebSolutions\Framework\Settings\Schema\is_valid_identifier;
+
+#[CoversFunction( 'DeepWebSolutions\Framework\Settings\Schema\filter_field_attributes' )]
+#[CoversFunction( 'DeepWebSolutions\Framework\Settings\Schema\is_valid_identifier' )]
+#[CoversFunction( 'DeepWebSolutions\Framework\Settings\Schema\is_checkbox_checked' )]
+final class SchemaFunctionsTest extends TestCase {
+	public function test_keeps_well_formed_non_event_attribute_names(): void {
+		$kept = filter_field_attributes(
+			array( 'class' => 'widefat', 'data-foo' => 'bar', 'min' => '0', 'step' => '1' ),
+		);
+
+		self::assertSame(
+			array( 'class' => 'widefat', 'data-foo' => 'bar', 'min' => '0', 'step' => '1' ),
+			$kept,
+		);
+	}
+
+	public function test_keeps_a_mixed_case_attribute_name(): void {
+		self::assertSame(
+			array( 'data-Foo' => 'bar' ),
+			filter_field_attributes( array( 'data-Foo' => 'bar' ) ),
+		);
+	}
+
+	#[DataProvider( 'event_handler_names' )]
+	public function test_drops_every_on_prefixed_name( string $name ): void {
+		self::assertSame(
+			array(),
+			filter_field_attributes( array( $name => 'evil()' ) ),
+		);
+	}
+
+	/**
+	 * Every name beginning with "on" is dropped by prefix, including ones that are not real handlers
+	 * (once, on-call) — the strict prefix block is conservative on purpose.
+	 *
+	 * @return array<string, array{string}>
+	 */
+	public static function event_handler_names(): array {
+		return array(
+			'onclick'      => array( 'onclick' ),
+			'onmouseover'  => array( 'onmouseover' ),
+			'onfocus'      => array( 'onfocus' ),
+			'once'         => array( 'once' ),
+			'on-call'      => array( 'on-call' ),
+			'mixed-case ON' => array( 'ONload' ),
+		);
+	}
+
+	#[DataProvider( 'malformed_attribute_names' )]
+	public function test_drops_malformed_attribute_names( string $name ): void {
+		self::assertSame(
+			array(),
+			filter_field_attributes( array( $name => 'x' ) ),
+		);
+	}
+
+	/**
+	 * @return array<string, array{string}>
+	 */
+	public static function malformed_attribute_names(): array {
+		return array(
+			'empty'            => array( '' ),
+			'leading digit'    => array( '1bad' ),
+			'leading hyphen'   => array( '-bad' ),
+			'underscore'       => array( 'data_foo' ),
+			'space-separated'  => array( 'autofocus onfocus' ),
+			'dot'              => array( 'data.foo' ),
+		);
+	}
+
+	public function test_keeps_valid_drops_invalid_in_one_pass(): void {
+		// The dropped names precede the kept one so a skip that fell through to break would drop it too.
+		$kept = filter_field_attributes(
+			array( 'onclick' => 'evil()', '1bad' => 'x', 'min' => '0' ),
+		);
+
+		self::assertSame( array( 'min' => '0' ), $kept );
+	}
+
+	#[DataProvider( 'valid_identifiers' )]
+	public function test_accepts_valid_identifiers( string $identifier ): void {
+		self::assertTrue( is_valid_identifier( $identifier ) );
+	}
+
+	/**
+	 * @return array<string, array{string}>
+	 */
+	public static function valid_identifiers(): array {
+		return array(
+			'single letter'   => array( 'a' ),
+			'word'            => array( 'field' ),
+			'with digit'      => array( 'field2' ),
+			'with underscore' => array( 'my_field' ),
+			'with hyphen'     => array( 'my-field' ),
+			'mixed'           => array( 'a1_b-2' ),
+		);
+	}
+
+	#[DataProvider( 'invalid_identifiers' )]
+	public function test_rejects_invalid_identifiers( string $identifier ): void {
+		self::assertFalse( is_valid_identifier( $identifier ) );
+	}
+
+	/**
+	 * @return array<string, array{string}>
+	 */
+	public static function invalid_identifiers(): array {
+		return array(
+			'empty'              => array( '' ),
+			'leading digit'      => array( '1field' ),
+			'leading hyphen'     => array( '-field' ),
+			'leading underscore' => array( '_field' ),
+			'uppercase'          => array( 'Field' ),
+			'space'              => array( 'my field' ),
+			'dot'                => array( 'my.field' ),
+			'slash'              => array( 'my/field' ),
+			'trailing newline'   => array( "field\n" ),
+		);
+	}
+
+	#[DataProvider( 'checkbox_truth_matrix' )]
+	public function test_checkbox_truth_rule( mixed $value, bool $expected ): void {
+		self::assertSame( $expected, is_checkbox_checked( $value ) );
+	}
+
+	/**
+	 * The canonical checkbox truth rule: only true, 1, '1', and 'yes' are checked. Everything else,
+	 * including the previously-truthy 'no'/'off'/'false'/arbitrary strings, is unchecked.
+	 *
+	 * @return array<string, array{mixed, bool}>
+	 */
+	public static function checkbox_truth_matrix(): array {
+		return array(
+			'bool true'          => array( true, true ),
+			'int 1'              => array( 1, true ),
+			'string 1'          => array( '1', true ),
+			'string yes'        => array( 'yes', true ),
+			'bool false'         => array( false, false ),
+			'int 0'              => array( 0, false ),
+			'string 0'          => array( '0', false ),
+			'string no'         => array( 'no', false ),
+			'string off'        => array( 'off', false ),
+			'string false'      => array( 'false', false ),
+			'string on'         => array( 'on', false ),
+			'arbitrary string'   => array( 'anything', false ),
+			'empty string'       => array( '', false ),
+			'null'               => array( null, false ),
+			'array'              => array( array( 'yes' ), false ),
+			'int 2'              => array( 2, false ),
+		);
+	}
+}
diff --git a/packages/settings/tests/Unit/SettingsPageTest.php b/packages/settings/tests/Unit/SettingsPageTest.php
index 0d32afb..25bffd1 100644
--- a/packages/settings/tests/Unit/SettingsPageTest.php
+++ b/packages/settings/tests/Unit/SettingsPageTest.php
@@ -2,9 +2,11 @@
 
 namespace DeepWebSolutions\Framework\Settings\Tests\Unit;
 
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\InvalidSettingsPageException;
 use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsPage;
 use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsSection;
 use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\Attributes\UsesClass;
 use PHPUnit\Framework\TestCase;
 
@@ -41,4 +43,55 @@ public function test_location_defaults_to_null(): void {
 
 		self::assertNull( $page->location );
 	}
+
+	#[DataProvider( 'valid_slugs' )]
+	public function test_accepts_valid_slugs( string $valid_slug ): void {
+		$page = new SettingsPage(
+			slug: $valid_slug,
+			page_title: 'T',
+			menu_title: 'T',
+			capability: 'manage_options',
+		);
+
+		self::assertSame( $valid_slug, $page->slug );
+	}
+
+	/**
+	 * @return array<string, array{string}>
+	 */
+	public static function valid_slugs(): array {
+		return array(
+			'single letter'   => array( 'a' ),
+			'with digit'      => array( 'page2' ),
+			'with underscore' => array( 'my_page' ),
+			'with hyphen'     => array( 'my-plugin' ),
+		);
+	}
+
+	#[DataProvider( 'invalid_slugs' )]
+	public function test_rejects_invalid_slugs( string $invalid_slug ): void {
+		$this->expectException( InvalidSettingsPageException::class );
+
+		new SettingsPage(
+			slug: $invalid_slug,
+			page_title: 'T',
+			menu_title: 'T',
+			capability: 'manage_options',
+		);
+	}
+
+	/**
+	 * @return array<string, array{string}>
+	 */
+	public static function invalid_slugs(): array {
+		return array(
+			'empty'              => array( '' ),
+			'leading digit'      => array( '1page' ),
+			'leading hyphen'     => array( '-page' ),
+			'leading underscore' => array( '_page' ),
+			'uppercase'          => array( 'Page' ),
+			'space'              => array( 'my page' ),
+			'slash'              => array( 'my/page' ),
+		);
+	}
 }
diff --git a/packages/settings/tests/Unit/SettingsSectionTest.php b/packages/settings/tests/Unit/SettingsSectionTest.php
index 0d2000f..9f1e4d8 100644
--- a/packages/settings/tests/Unit/SettingsSectionTest.php
+++ b/packages/settings/tests/Unit/SettingsSectionTest.php
@@ -2,9 +2,11 @@
 
 namespace DeepWebSolutions\Framework\Settings\Tests\Unit;
 
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\InvalidSettingsSectionException;
 use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
 use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsSection;
 use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\Attributes\UsesClass;
 use PHPUnit\Framework\TestCase;
 
@@ -28,4 +30,45 @@ public function test_accepts_an_empty_field_list(): void {
 
 		self::assertSame( array(), $section->fields );
 	}
+
+	#[DataProvider( 'valid_ids' )]
+	public function test_accepts_valid_ids( string $valid_id ): void {
+		$section = new SettingsSection( id: $valid_id, title: 'T', fields: array() );
+
+		self::assertSame( $valid_id, $section->id );
+	}
+
+	/**
+	 * @return array<string, array{string}>
+	 */
+	public static function valid_ids(): array {
+		return array(
+			'single letter'   => array( 'a' ),
+			'with digit'      => array( 'section2' ),
+			'with underscore' => array( 'my_section' ),
+			'with hyphen'     => array( 'my-section' ),
+		);
+	}
+
+	#[DataProvider( 'invalid_ids' )]
+	public function test_rejects_invalid_ids( string $invalid_id ): void {
+		$this->expectException( InvalidSettingsSectionException::class );
+
+		new SettingsSection( id: $invalid_id, title: 'T', fields: array() );
+	}
+
+	/**
+	 * @return array<string, array{string}>
+	 */
+	public static function invalid_ids(): array {
+		return array(
+			'empty'              => array( '' ),
+			'leading digit'      => array( '1section' ),
+			'leading hyphen'     => array( '-section' ),
+			'leading underscore' => array( '_section' ),
+			'uppercase'          => array( 'Section' ),
+			'space'              => array( 'my section' ),
+			'dot'                => array( 'my.section' ),
+		);
+	}
 }
diff --git a/packages/woocommerce/functions.php b/packages/woocommerce/functions.php
index 8a0e776..aa8912f 100644
--- a/packages/woocommerce/functions.php
+++ b/packages/woocommerce/functions.php
@@ -1,5 +1,3 @@
 <?php declare( strict_types=1 );
 
-// No namespace functions in woocommerce yet. This file exists for workspace-wide
-// consistency with the package-root functions.php aggregator pattern; when a
-// <namespace>/functions.php file is added under src/, require_once it here.
+require_once __DIR__ . '/src/functions.php';
diff --git a/packages/woocommerce/src/Backend/DescriptorBackedWCSettingsPage.php b/packages/woocommerce/src/Backend/DescriptorBackedWCSettingsPage.php
index 0404a05..4625be2 100644
--- a/packages/woocommerce/src/Backend/DescriptorBackedWCSettingsPage.php
+++ b/packages/woocommerce/src/Backend/DescriptorBackedWCSettingsPage.php
@@ -6,6 +6,8 @@
 use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsSection;
 use DeepWebSolutions\Framework\WooCommerce\Exceptions\UnboundSettingsPageException;
 
+use function DeepWebSolutions\Framework\Settings\Schema\is_field_editable_by_current_user;
+
 /**
  * Base for a per-page WooCommerce settings tab backed by a framework settings descriptor.
  *
@@ -133,7 +135,7 @@ private function editable_page(): SettingsPage {
 		foreach ( $descriptor->sections as $section ) {
 			$fields = array();
 			foreach ( $section->fields as $field ) {
-				if ( null === $field->capability || \current_user_can( $field->capability ) ) {
+				if ( is_field_editable_by_current_user( $field ) ) {
 					$fields[] = $field;
 				}
 			}
diff --git a/packages/woocommerce/src/Backend/WCSettingsBuilder.php b/packages/woocommerce/src/Backend/WCSettingsBuilder.php
index 75e6c39..cbadf7e 100644
--- a/packages/woocommerce/src/Backend/WCSettingsBuilder.php
+++ b/packages/woocommerce/src/Backend/WCSettingsBuilder.php
@@ -7,6 +7,9 @@
 use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
 use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsPage;
 
+use function DeepWebSolutions\Framework\Settings\Schema\filter_field_attributes;
+use function DeepWebSolutions\Framework\WooCommerce\to_yes_no;
+
 /**
  * Translates a settings page descriptor into WooCommerce's settings-array format.
  *
@@ -106,7 +109,7 @@ private function build_field( string $slug, SettingsField $field ): array {
 			$entry['options'] = $this->stringify_labels( $this->options_resolver->resolve( $field->options ) );
 		}
 
-		$attributes = $this->filter_attributes( $field->attributes );
+		$attributes = filter_field_attributes( $field->attributes );
 		if ( array() !== $attributes ) {
 			$entry['custom_attributes'] = $attributes;
 		}
@@ -126,33 +129,13 @@ private function build_field( string $slug, SettingsField $field ): array {
 	 */
 	private function map_default( SettingsField $field ): mixed {
 		return match ( $field->type ) {
-			FieldType::Checkbox->value    => $this->checkbox_default( $field->default ),
+			FieldType::Checkbox->value    => to_yes_no( $field->default ),
 			// WooCommerce matches multiselect selections with a strict (string) in_array, so the set must be strings.
 			FieldType::Multiselect->value => $this->stringify_selected( $field->default ),
 			default                       => $field->default,
 		};
 	}
 
-	/**
-	 * Maps a checkbox default to WooCommerce's yes/no string.
-	 *
-	 * WooCommerce compares a checkbox against the literal 'yes'; the framework's checkbox value is
-	 * boolean, so any truthy default becomes 'yes'.
-	 *
-	 * @since   2.0.0
-	 * @version 2.0.0
-	 *
-	 * @param   mixed $default Field default to coerce.
-	 *
-	 * @return  string
-	 */
-	private function checkbox_default( mixed $default ): string {
-		return match ( (bool) $default ) {
-			true  => 'yes',
-			false => 'no',
-		};
-	}
-
 	/**
 	 * Whether a field type renders a WooCommerce options list.
 	 *
@@ -214,31 +197,5 @@ private function stringify_selected( mixed $default ): array {
 		);
 	}
 
-	/**
-	 * Keeps only safe HTML attributes, dropping malformed names and executable on* event handlers.
-	 *
-	 * WooCommerce escapes attribute names and values but does not reject event handlers, so a descriptor
-	 * is filtered here to the same allow-list the WordPress field renderer enforces.
-	 *
-	 * @since   2.0.0
-	 * @version 2.0.0
-	 *
-	 * @param   array<string, scalar> $attributes Descriptor attribute map.
-	 *
-	 * @return  array<string, scalar>
-	 */
-	private function filter_attributes( array $attributes ): array {
-		$filtered = array();
-		foreach ( $attributes as $attribute => $value ) {
-			if ( 1 !== \preg_match( '/\A[a-z][a-z0-9-]*\z/i', $attribute ) || 0 === \stripos( $attribute, 'on' ) ) {
-				continue;
-			}
-
-			$filtered[ $attribute ] = $value;
-		}
-
-		return $filtered;
-	}
-
 	// endregion
 }
diff --git a/packages/woocommerce/src/Backend/WooCommerceSettingsBackend.php b/packages/woocommerce/src/Backend/WooCommerceSettingsBackend.php
index 0067f18..3490944 100644
--- a/packages/woocommerce/src/Backend/WooCommerceSettingsBackend.php
+++ b/packages/woocommerce/src/Backend/WooCommerceSettingsBackend.php
@@ -8,6 +8,8 @@
 use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
 use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsPage;
 
+use function DeepWebSolutions\Framework\Settings\Schema\is_field_editable_by_current_user;
+
 /**
  * WooCommerce-backed settings backend for a single page.
  *
@@ -181,16 +183,15 @@ private function register_field_filters( SettingsPage $page ): void {
 				continue;
 			}
 
-			$key        = $page->slug . '_' . $field_id;
-			$sanitize   = $field->sanitize;
-			$capability = $field->capability;
+			$key      = $page->slug . '_' . $field_id;
+			$sanitize = $field->sanitize;
 			\add_filter(
 				'woocommerce_admin_settings_sanitize_option_' . $key,
-				static function ( mixed $value ) use ( $key, $sanitize, $capability ): mixed {
+				static function ( mixed $value ) use ( $key, $sanitize, $field ): mixed {
 					// A user without the field's capability cannot change it: keep the stored value, or skip
 					// the write (null, which WooCommerce honors) when none is stored, so a protected field
 					// the user cannot edit is never created.
-					if ( null !== $capability && ! \current_user_can( $capability ) ) {
+					if ( ! is_field_editable_by_current_user( $field ) ) {
 						$sentinel = new \stdClass();
 						$stored   = \get_option( $key, $sentinel );
 
diff --git a/packages/woocommerce/src/OrderData/OrderFieldStore.php b/packages/woocommerce/src/OrderData/OrderFieldStore.php
index e884ccc..05fc977 100644
--- a/packages/woocommerce/src/OrderData/OrderFieldStore.php
+++ b/packages/woocommerce/src/OrderData/OrderFieldStore.php
@@ -11,6 +11,8 @@
 use DeepWebSolutions\Framework\Settings\Schema\FieldRenderer;
 use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
 
+use function DeepWebSolutions\Framework\Settings\Schema\is_field_editable_by_current_user;
+
 /**
  * WooCommerce-order object-field store: an order meta box plus per-object meta CRUD.
  *
@@ -249,7 +251,7 @@ private function render_box( ObjectMetaBox $box, mixed $object ): void {
 		}
 
 		foreach ( $this->fields_of( $box, $object_id ) as $field ) {
-			if ( ! $this->can_edit( $field ) ) {
+			if ( ! is_field_editable_by_current_user( $field ) ) {
 				continue;
 			}
 			// Object fields are revoke-based: an absent meta renders as unset, NOT the field default, so a
@@ -305,7 +307,7 @@ private function save_box( ObjectMetaBox $box, int $object_id ): void {
 		// queued a write — so a K-field box is one order write (or none for a no-op submit) rather than K.
 		$changed = false;
 		foreach ( $this->fields_of( $box, $object_id ) as $field ) {
-			if ( ! $this->can_edit( $field ) ) {
+			if ( ! is_field_editable_by_current_user( $field ) ) {
 				continue;
 			}
 
@@ -381,20 +383,6 @@ private function object_id_of( mixed $object ): int {
 		return 0;
 	}
 
-	/**
-	 * Whether the current user may edit the given field.
-	 *
-	 * @since   2.0.0
-	 * @version 2.0.0
-	 *
-	 * @param   SettingsField $field Field to check.
-	 *
-	 * @return  bool
-	 */
-	private function can_edit( SettingsField $field ): bool {
-		return null === $field->capability || \current_user_can( $field->capability );
-	}
-
 	/**
 	 * Whether a processed value should be stored. An empty value — an unchecked control (false), a
 	 * cleared field ('') or an empty multi-select (array()) — is not stored; its meta key is deleted
diff --git a/packages/woocommerce/src/ProductData/ProductDataFieldRenderer.php b/packages/woocommerce/src/ProductData/ProductDataFieldRenderer.php
index 5a3a3b1..4d686f8 100644
--- a/packages/woocommerce/src/ProductData/ProductDataFieldRenderer.php
+++ b/packages/woocommerce/src/ProductData/ProductDataFieldRenderer.php
@@ -7,6 +7,9 @@
 use DeepWebSolutions\Framework\Settings\Schema\OptionsResolver;
 use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
 
+use function DeepWebSolutions\Framework\Settings\Schema\filter_field_attributes;
+use function DeepWebSolutions\Framework\WooCommerce\to_yes_no;
+
 /**
  * Renders a product-data field as a native WooCommerce control.
  *
@@ -62,11 +65,11 @@ public function args( SettingsField $field, FieldType $type, mixed $value, strin
 			$args['desc_tip']    = true;
 		}
 
-		$custom_attributes = $this->filter_attributes( $field->attributes );
+		$custom_attributes = filter_field_attributes( $field->attributes );
 
 		switch ( $type ) {
 			case FieldType::Checkbox:
-				$args['value'] = $this->checkbox_value( $value );
+				$args['value'] = to_yes_no( $value );
 				break;
 			case FieldType::Multiselect:
 				$args['name'] = $meta_key . '[]';
@@ -141,46 +144,6 @@ public function render( SettingsField $field, mixed $value, string $meta_key ):
 
 	// region HELPERS
 
-	/**
-	 * Normalizes a value to WooCommerce's yes/no checkbox string; a checkbox control's checked state turns on it.
-	 *
-	 * @since   2.0.0
-	 * @version 2.0.0
-	 *
-	 * @param   mixed $value Current value, a boolean default or a stored yes/no string.
-	 *
-	 * @return  string
-	 */
-	private function checkbox_value( mixed $value ): string {
-		return ( true === $value || 'yes' === $value || 1 === $value || '1' === $value ) ? 'yes' : 'no';
-	}
-
-	/**
-	 * Keeps only safe HTML attributes, dropping malformed names and executable on* event handlers.
-	 *
-	 * WooCommerce escapes attribute names and values but does not reject event handlers, so a descriptor is
-	 * filtered here to the same allow-list the field renderer and WC settings builder enforce.
-	 *
-	 * @since   2.0.0
-	 * @version 2.0.0
-	 *
-	 * @param   array<string, scalar> $attributes Descriptor attribute map.
-	 *
-	 * @return  array<string, scalar>
-	 */
-	private function filter_attributes( array $attributes ): array {
-		$filtered = array();
-		foreach ( $attributes as $attribute => $value ) {
-			if ( 1 !== \preg_match( '/\A[a-z][a-z0-9-]*\z/i', $attribute ) || 0 === \stripos( $attribute, 'on' ) ) {
-				continue;
-			}
-
-			$filtered[ $attribute ] = $value;
-		}
-
-		return $filtered;
-	}
-
 	/**
 	 * Stringifies a resolved options map's labels; a non-scalar label becomes an empty string, as WooCommerce
 	 * passes each label through esc_html().
diff --git a/packages/woocommerce/src/ProductData/ProductDataFieldStore.php b/packages/woocommerce/src/ProductData/ProductDataFieldStore.php
index 3ec9691..f7a4d58 100644
--- a/packages/woocommerce/src/ProductData/ProductDataFieldStore.php
+++ b/packages/woocommerce/src/ProductData/ProductDataFieldStore.php
@@ -8,6 +8,9 @@
 use DeepWebSolutions\Framework\Settings\Schema\FieldType;
 use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
 
+use function DeepWebSolutions\Framework\Settings\Schema\is_field_editable_by_current_user;
+use function DeepWebSolutions\Framework\WooCommerce\to_yes_no;
+
 /**
  * Registers a WooCommerce product-data settings tab and persists its fields as product meta.
  *
@@ -149,7 +152,7 @@ public function set( int $product_id, string $section_id, string $field_id, mixe
 
 		// A checkbox persists as WooCommerce's yes/no string on every write path, so its render and reads agree.
 		if ( FieldType::Checkbox === FieldType::tryFrom( $this->by_meta_key[ $meta_key ]->type ) ) {
-			$value = $this->checkbox_value( $value );
+			$value = to_yes_no( $value );
 		}
 
 		$product->update_meta_data( $meta_key, $value );
@@ -283,7 +286,7 @@ private function render_panel(): void {
 		echo '<div id="' . \esc_attr( $tab->slug . '_product_data' ) . '" class="panel woocommerce_options_panel">';
 
 		foreach ( $tab->sections as $section ) {
-			$fields = \array_values( \array_filter( $section->fields, fn ( SettingsField $field ): bool => $this->can_edit( $field ) ) );
+			$fields = \array_values( \array_filter( $section->fields, static fn ( SettingsField $field ): bool => is_field_editable_by_current_user( $field ) ) );
 			if ( array() === $fields ) {
 				continue;
 			}
@@ -328,7 +331,7 @@ private function save( int $product_id ): void {
 
 		foreach ( $this->tab()->sections as $section ) {
 			foreach ( $section->fields as $field ) {
-				if ( ! $this->can_edit( $field ) ) {
+				if ( ! is_field_editable_by_current_user( $field ) ) {
 					continue;
 				}
 				$meta_key = $this->meta_key_for( $section->id, $field );
@@ -545,24 +548,10 @@ private function sanitize_and_validate( SettingsField $field, mixed $value, mixe
 	 */
 	private function default_value( SettingsField $field ): mixed {
 		return FieldType::Checkbox === FieldType::tryFrom( $field->type )
-			? $this->checkbox_value( $field->default )
+			? to_yes_no( $field->default )
 			: $field->default;
 	}
 
-	/**
-	 * Normalizes a value to WooCommerce's yes/no checkbox string, on which a checkbox's checked state turns.
-	 *
-	 * @since   2.0.0
-	 * @version 2.0.0
-	 *
-	 * @param   mixed $value Value to normalize.
-	 *
-	 * @return  string
-	 */
-	private function checkbox_value( mixed $value ): string {
-		return ( true === $value || 'yes' === $value || 1 === $value || '1' === $value ) ? 'yes' : 'no';
-	}
-
 	/**
 	 * Whether the tab applies to a product: a product WooCommerce recognizes, narrowed by the tab's gate when set.
 	 *
@@ -601,20 +590,6 @@ private function tab_classes( int $product_id ): array {
 		return \is_array( $classes ) ? \array_values( $classes ) : \array_values( (array) $classes( $product_id ) );
 	}
 
-	/**
-	 * Whether the current user may edit a field.
-	 *
-	 * @since   2.0.0
-	 * @version 2.0.0
-	 *
-	 * @param   SettingsField $field Field to check.
-	 *
-	 * @return  bool
-	 */
-	private function can_edit( SettingsField $field ): bool {
-		return null === $field->capability || \current_user_can( $field->capability );
-	}
-
 	/**
 	 * The registered tab, asserted present — every caller runs after register_tab().
 	 *
diff --git a/packages/woocommerce/src/ProductData/ProductDataTab.php b/packages/woocommerce/src/ProductData/ProductDataTab.php
index 224b759..dd35868 100644
--- a/packages/woocommerce/src/ProductData/ProductDataTab.php
+++ b/packages/woocommerce/src/ProductData/ProductDataTab.php
@@ -5,6 +5,8 @@
 use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsSection;
 use DeepWebSolutions\Framework\WooCommerce\Exceptions\InvalidProductDataTabException;
 
+use function DeepWebSolutions\Framework\Settings\Schema\is_valid_identifier;
+
 /**
  * Declarative description of a WooCommerce product-data settings tab — a custom panel in the product
  * editor's Product data meta box.
@@ -19,16 +21,6 @@
 final readonly class ProductDataTab {
 	// region FIELDS AND CONSTANTS
 
-	/**
-	 * Slug charset: a lowercase letter then lowercase letters, digits, underscores, or hyphens.
-	 *
-	 * @since   2.0.0
-	 * @version 2.0.0
-	 *
-	 * @var     string
-	 */
-	private const SLUG_PATTERN = '/\A[a-z][a-z0-9_-]*\z/';
-
 	/**
 	 * Product-type gate deciding whether the tab applies to a product; null applies it to every product
 	 * WooCommerce recognizes. Signature `(int $product_id): bool`.
@@ -82,7 +74,7 @@ public function __construct(
 		?callable $supports_product = null,
 		array $custom_renderers = array(),
 	) {
-		if ( 1 !== \preg_match( self::SLUG_PATTERN, $slug ) ) {
+		if ( ! is_valid_identifier( $slug ) ) {
 			// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- framework-internal exception; never reaches an HTML output context unescaped.
 			throw new InvalidProductDataTabException( "Invalid product-data tab slug: '$slug'" );
 		}
diff --git a/packages/woocommerce/src/functions.php b/packages/woocommerce/src/functions.php
new file mode 100644
index 0000000..23c4218
--- /dev/null
+++ b/packages/woocommerce/src/functions.php
@@ -0,0 +1,21 @@
+<?php declare( strict_types=1 );
+
+namespace DeepWebSolutions\Framework\WooCommerce;
+
+use function DeepWebSolutions\Framework\Settings\Schema\is_checkbox_checked;
+
+/**
+ * Maps a value to WooCommerce's yes/no checkbox string via the canonical checkbox truth rule: a checked
+ * value becomes 'yes', everything else 'no'. WooCommerce string-compares a checkbox against the literal
+ * 'yes', so its render and save round-trip through this representation.
+ *
+ * @since   2.0.0
+ * @version 2.0.0
+ *
+ * @param   mixed $value Value to coerce.
+ *
+ * @return  string
+ */
+function to_yes_no( mixed $value ): string {
+	return is_checkbox_checked( $value ) ? 'yes' : 'no';
+}
diff --git a/packages/woocommerce/tests/Unit/FunctionsTest.php b/packages/woocommerce/tests/Unit/FunctionsTest.php
new file mode 100644
index 0000000..c378414
--- /dev/null
+++ b/packages/woocommerce/tests/Unit/FunctionsTest.php
@@ -0,0 +1,44 @@
+<?php declare( strict_types=1 );
+
+namespace DeepWebSolutions\Framework\WooCommerce\Tests\Unit;
+
+use PHPUnit\Framework\Attributes\CoversFunction;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+
+use function DeepWebSolutions\Framework\WooCommerce\to_yes_no;
+
+#[CoversFunction( 'DeepWebSolutions\Framework\WooCommerce\to_yes_no' )]
+final class FunctionsTest extends TestCase {
+	#[DataProvider( 'yes_no_matrix' )]
+	public function test_maps_a_value_to_the_wc_yes_no_string( mixed $value, string $expected ): void {
+		self::assertSame( $expected, to_yes_no( $value ) );
+	}
+
+	/**
+	 * Mirrors the canonical checkbox truth rule: only true, 1, '1', and 'yes' map to 'yes'; the
+	 * previously-truthy 'no'/'off'/'false'/arbitrary strings now map to 'no'.
+	 *
+	 * @return array<string, array{mixed, string}>
+	 */
+	public static function yes_no_matrix(): array {
+		return array(
+			'bool true'        => array( true, 'yes' ),
+			'int 1'            => array( 1, 'yes' ),
+			'string 1'        => array( '1', 'yes' ),
+			'string yes'      => array( 'yes', 'yes' ),
+			'bool false'       => array( false, 'no' ),
+			'int 0'            => array( 0, 'no' ),
+			'string 0'        => array( '0', 'no' ),
+			'string no'       => array( 'no', 'no' ),
+			'string off'      => array( 'off', 'no' ),
+			'string false'    => array( 'false', 'no' ),
+			'string on'       => array( 'on', 'no' ),
+			'arbitrary string' => array( 'anything', 'no' ),
+			'empty string'     => array( '', 'no' ),
+			'null'             => array( null, 'no' ),
+			'array'            => array( array( 'yes' ), 'no' ),
+			'int 2'            => array( 2, 'no' ),
+		);
+	}
+}
diff --git a/packages/woocommerce/tests/Unit/WCSettingsBuilderTest.php b/packages/woocommerce/tests/Unit/WCSettingsBuilderTest.php
index cb1d3c0..713ea3e 100644
--- a/packages/woocommerce/tests/Unit/WCSettingsBuilderTest.php
+++ b/packages/woocommerce/tests/Unit/WCSettingsBuilderTest.php
@@ -138,6 +138,38 @@ public function test_a_truthy_non_boolean_checkbox_default_maps_to_the_wc_yes_st
 		self::assertSame( 'yes', $row['default'] );
 	}
 
+	public function test_a_string_yes_checkbox_default_maps_to_the_wc_yes_string(): void {
+		$page = $this->page_with_field(
+			new SettingsField( id: 'flag', type: 'checkbox', label: 'Flag', default: 'yes' ),
+		);
+
+		$row = $this->row_by_id( ( new WCSettingsBuilder() )->build( $page ), 'dws-shop_flag' );
+
+		self::assertSame( 'yes', $row['default'] );
+	}
+
+	public function test_a_string_no_checkbox_default_maps_to_the_wc_no_string(): void {
+		// Canonical rule: 'no' is unchecked. The superseded (bool) cast mapped the truthy 'no' to 'yes'.
+		$page = $this->page_with_field(
+			new SettingsField( id: 'flag', type: 'checkbox', label: 'Flag', default: 'no' ),
+		);
+
+		$row = $this->row_by_id( ( new WCSettingsBuilder() )->build( $page ), 'dws-shop_flag' );
+
+		self::assertSame( 'no', $row['default'] );
+	}
+
+	public function test_an_arbitrary_string_checkbox_default_maps_to_the_wc_no_string(): void {
+		// Canonical rule: any non-canonical string is unchecked. The superseded (bool) cast mapped it to 'yes'.
+		$page = $this->page_with_field(
+			new SettingsField( id: 'flag', type: 'checkbox', label: 'Flag', default: 'anything' ),
+		);
+
+		$row = $this->row_by_id( ( new WCSettingsBuilder() )->build( $page ), 'dws-shop_flag' );
+
+		self::assertSame( 'no', $row['default'] );
+	}
+
 	public function test_non_string_option_labels_are_stringified(): void {
 		$page = $this->page_with_field(
 			new SettingsField( id: 'amount', type: 'select', label: 'Amount', options: array( 1 => 100, 2 => 'Two' ) ),

From 445b33eff75cb984ad665b84e8651201e813d9bf Mon Sep 17 00:00:00 2001
From: Tony Hegyes <a.hegyes@proton.me>
Date: Mon, 22 Jun 2026 11:10:08 +0200
Subject: [PATCH 07/21] feat(settings,woocommerce): add custom field-type seam
 to the Schema render/process layer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Finding #14. The descriptor model was extensible on the WC product-data tab (a
type-to-closure render registry) but the core Schema layer threw
UnknownFieldTypeException on any type outside the closed FieldType enum — so a
wave-2 consumer needing a bespoke control (QR's single_select_page) on a
WordPress settings page would have to fork FieldRenderer/FieldProcessor.

Inject a CustomFieldType registry — a final readonly descriptor carrying a type
token and a string-returning render closure — into FieldRenderer and
FieldProcessor, parallel to the existing OptionsResolver injection. Dispatch is
enum-first -> registry-second -> throw-third: the enum stays the canonical
taxonomy, the registry is the documented extension point, and the processor
treats it as an allowlist so an unregistered type still throws (a typo stays
loud). The seam is render-only; a custom type saves through the field's own
sanitize/validate, matching the ProductData prior art (which has no sanitizer
registry), falling back to the field default on absent or rejected input. Both
WordPressSettingsBackend and OrderFieldStore already accept injected primitives,
so the seam reaches every settings surface — options pages and order/object meta
boxes — with no per-surface change.

Drops the audit's custom_sanitizers half: both independent proposers verified
the prior art saves through the field's own closures, so a parallel sanitizer
registry would be a redundant second channel.

Gates: PHPStan clean, deptrac 0, Unit 397, Integration 284.

Assisted-by: Claude Code:claude-opus-4-8
---
 .../InvalidCustomFieldTypeException.php       |  13 +++
 .../settings/src/Schema/FieldProcessor.php    |  58 +++++++++-
 .../settings/src/Schema/FieldRenderer.php     |  13 ++-
 .../Schema/ValueObjects/CustomFieldType.php   |  62 +++++++++++
 .../tests/Integration/FieldRendererTest.php   |  58 ++++++++++
 .../WordPressSettingsBackendTest.php          | 103 ++++++++++++++++++
 .../tests/Unit/CustomFieldTypeTest.php        |  91 ++++++++++++++++
 .../tests/Unit/FieldProcessorTest.php         |  72 ++++++++++++
 .../OrderData/OrderFieldStoreTest.php         |  50 +++++++++
 9 files changed, 514 insertions(+), 6 deletions(-)
 create mode 100644 packages/settings/src/Schema/Exceptions/InvalidCustomFieldTypeException.php
 create mode 100644 packages/settings/src/Schema/ValueObjects/CustomFieldType.php
 create mode 100644 packages/settings/tests/Unit/CustomFieldTypeTest.php

diff --git a/packages/settings/src/Schema/Exceptions/InvalidCustomFieldTypeException.php b/packages/settings/src/Schema/Exceptions/InvalidCustomFieldTypeException.php
new file mode 100644
index 0000000..e87b1bc
--- /dev/null
+++ b/packages/settings/src/Schema/Exceptions/InvalidCustomFieldTypeException.php
@@ -0,0 +1,13 @@
+<?php declare( strict_types=1 );
+
+namespace DeepWebSolutions\Framework\Settings\Schema\Exceptions;
+
+use DeepWebSolutions\Framework\Shared\Exception\AbstractInvalidArgumentException;
+
+/**
+ * Thrown when a custom field type declares a type token outside the identifier charset.
+ *
+ * @since   2.0.0
+ * @version 2.0.0
+ */
+final class InvalidCustomFieldTypeException extends AbstractInvalidArgumentException {}
diff --git a/packages/settings/src/Schema/FieldProcessor.php b/packages/settings/src/Schema/FieldProcessor.php
index cf9f301..fec4b30 100644
--- a/packages/settings/src/Schema/FieldProcessor.php
+++ b/packages/settings/src/Schema/FieldProcessor.php
@@ -3,6 +3,7 @@
 namespace DeepWebSolutions\Framework\Settings\Schema;
 
 use DeepWebSolutions\Framework\Settings\Schema\Exceptions\UnknownFieldTypeException;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\CustomFieldType;
 use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
 
 /**
@@ -13,7 +14,10 @@
  * value (an empty array for a multi-value field, otherwise false — never null),
  * and for a present value applies the field's sanitizer, gates a choice value
  * against its resolved option set, then applies the field's own validator; a
- * value any step rejects falls back to the empty value.
+ * value any step rejects falls back to the empty value. A type outside the
+ * taxonomy but present in the injected custom-type registry is processed as a
+ * plain scalar through the field's own sanitize/validate, falling back to the
+ * field's default; a type in neither still throws.
  *
  * @since   2.0.0
  * @version 2.0.0
@@ -27,10 +31,12 @@ final class FieldProcessor {
 	 * @since   2.0.0
 	 * @version 2.0.0
 	 *
-	 * @param   OptionsResolver $resolver Resolver for choice fields' option sets.
+	 * @param   OptionsResolver                $resolver     Resolver for choice fields' option sets.
+	 * @param   array<string, CustomFieldType> $custom_types Registry of types outside the taxonomy whose submissions are accepted, keyed by type token.
 	 */
 	public function __construct(
 		private OptionsResolver $resolver = new OptionsResolver(),
+		private array $custom_types = array(),
 	) {}
 
 	// endregion
@@ -46,13 +52,16 @@ public function __construct(
 	 * @param   SettingsField        $field Field whose value is processed.
 	 * @param   array<string, mixed> $input Raw submitted values keyed by field id; a missing key means the field was not submitted.
 	 *
-	 * @throws  UnknownFieldTypeException If the field declares a type outside the taxonomy.
+	 * @throws  UnknownFieldTypeException If the field declares a type outside both the taxonomy and the custom-type registry.
 	 *
 	 * @return  mixed
 	 */
 	public function process( SettingsField $field, array $input ): mixed {
 		$type = FieldType::tryFrom( $field->type );
 		if ( null === $type ) {
+			if ( isset( $this->custom_types[ $field->type ] ) ) {
+				return $this->process_custom( $field, $input );
+			}
 			// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- framework-internal exception; never reaches an HTML output context unescaped.
 			throw new UnknownFieldTypeException( "Unknown settings field type: '$field->type'" );
 		}
@@ -94,6 +103,49 @@ public function process( SettingsField $field, array $input ): mixed {
 
 	// region HELPERS
 
+	/**
+	 * Processes a custom-typed field as a plain scalar: an absent submission yields the field's default, a
+	 * present one runs the field's own sanitize then validate, falling back to the default when validation rejects.
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 *
+	 * @param   SettingsField        $field Field whose value is processed.
+	 * @param   array<string, mixed> $input Raw submitted values keyed by field id.
+	 *
+	 * @return  mixed
+	 */
+	private function process_custom( SettingsField $field, array $input ): mixed {
+		if ( ! \array_key_exists( $field->id, $input ) ) {
+			return $field->default;
+		}
+
+		return $this->sanitize_and_validate( $field, $input[ $field->id ], $field->default );
+	}
+
+	/**
+	 * Runs a field's sanitize then validate, returning the fallback when validation rejects the value.
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 *
+	 * @param   SettingsField $field    Field whose closures to apply.
+	 * @param   mixed         $value    Value to sanitize and validate.
+	 * @param   mixed         $rejected Value returned when validation rejects.
+	 *
+	 * @return  mixed
+	 */
+	private function sanitize_and_validate( SettingsField $field, mixed $value, mixed $rejected ): mixed {
+		if ( null !== $field->sanitize ) {
+			$value = ( $field->sanitize )( $value );
+		}
+		if ( null !== $field->validate && ! ( $field->validate )( $value ) ) {
+			return $rejected;
+		}
+
+		return $value;
+	}
+
 	/**
 	 * Whether a single submitted value is a key in the field's resolved options.
 	 *
diff --git a/packages/settings/src/Schema/FieldRenderer.php b/packages/settings/src/Schema/FieldRenderer.php
index 23fd9f5..86abbaf 100644
--- a/packages/settings/src/Schema/FieldRenderer.php
+++ b/packages/settings/src/Schema/FieldRenderer.php
@@ -3,6 +3,7 @@
 namespace DeepWebSolutions\Framework\Settings\Schema;
 
 use DeepWebSolutions\Framework\Settings\Schema\Exceptions\UnknownFieldTypeException;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\CustomFieldType;
 use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
 
 use function DeepWebSolutions\Framework\Settings\Schema\filter_field_attributes;
@@ -15,7 +16,8 @@
  * backends (WooCommerce renders its own). Resolves a field's options through the
  * same {@see OptionsResolver} the processor validates against, so the rendered
  * choices and the accepted values always agree. The caller supplies the control's
- * HTML name; an unknown field type throws.
+ * HTML name; a field type outside the taxonomy and the injected custom-type
+ * registry throws.
  *
  * @since   2.0.0
  * @version 2.0.0
@@ -29,10 +31,12 @@ final class FieldRenderer {
 	 * @since   2.0.0
 	 * @version 2.0.0
 	 *
-	 * @param   OptionsResolver $resolver Resolver for choice fields' option sets.
+	 * @param   OptionsResolver                $resolver     Resolver for choice fields' option sets.
+	 * @param   array<string, CustomFieldType> $custom_types Registry of render seams for types outside the taxonomy, keyed by type token.
 	 */
 	public function __construct(
 		private OptionsResolver $resolver = new OptionsResolver(),
+		private array $custom_types = array(),
 	) {}
 
 	// endregion
@@ -49,13 +53,16 @@ public function __construct(
 	 * @param   mixed         $value Current value to bind into the control.
 	 * @param   string        $name  HTML name attribute for the control.
 	 *
-	 * @throws  UnknownFieldTypeException If the field declares a type outside the taxonomy.
+	 * @throws  UnknownFieldTypeException If the field declares a type outside both the taxonomy and the custom-type registry.
 	 *
 	 * @return  string
 	 */
 	public function render( SettingsField $field, mixed $value, string $name ): string {
 		$type = FieldType::tryFrom( $field->type );
 		if ( null === $type ) {
+			if ( isset( $this->custom_types[ $field->type ] ) ) {
+				return ( $this->custom_types[ $field->type ]->render )( $field, $value, $name ) . $this->render_description( $field );
+			}
 			// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- framework-internal exception; never reaches an HTML output context unescaped.
 			throw new UnknownFieldTypeException( "Unknown settings field type: '$field->type'" );
 		}
diff --git a/packages/settings/src/Schema/ValueObjects/CustomFieldType.php b/packages/settings/src/Schema/ValueObjects/CustomFieldType.php
new file mode 100644
index 0000000..ffd8834
--- /dev/null
+++ b/packages/settings/src/Schema/ValueObjects/CustomFieldType.php
@@ -0,0 +1,62 @@
+<?php declare( strict_types=1 );
+
+namespace DeepWebSolutions\Framework\Settings\Schema\ValueObjects;
+
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\InvalidCustomFieldTypeException;
+
+use function DeepWebSolutions\Framework\Settings\Schema\is_valid_identifier;
+
+/**
+ * Descriptor for a settings field type outside the framework taxonomy.
+ *
+ * Immutable carrier registering a render seam for a type token the closed FieldType enum does not
+ * define. A consumer hands a map of these to the FieldRenderer and FieldProcessor primitives, which
+ * consult the registry after the enum and before rejecting an unknown type. The registry is
+ * render-only: saving reuses the field's own sanitize/validate seam, so this descriptor carries no
+ * processing logic. The type token is validated against the identifier charset at construction.
+ *
+ * @since   2.0.0
+ * @version 2.0.0
+ */
+final readonly class CustomFieldType {
+	// region FIELDS AND CONSTANTS
+
+	/**
+	 * Renderer producing the type's escaped HTML control. Signature `(SettingsField $field, mixed $value, string $name): string`.
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 *
+	 * @var     \Closure
+	 */
+	public \Closure $render;
+
+	// endregion
+
+	// region MAGIC METHODS
+
+	/**
+	 * Constructor.
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 *
+	 * @param   string   $type Type token the field declares; a lowercase identifier outside the FieldType enum.
+	 * @param   callable $render Renderer for the type's control; stored as a Closure.
+	 *
+	 * @throws  InvalidCustomFieldTypeException If $type does not match the identifier charset.
+	 */
+	public function __construct(
+		public string $type,
+		callable $render,
+	) {
+		if ( ! is_valid_identifier( $type ) ) {
+			// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- framework-internal exception; never reaches an HTML output context unescaped.
+			throw new InvalidCustomFieldTypeException( "Invalid custom field type: '$type'" );
+		}
+
+		$this->render = \Closure::fromCallable( $render );
+	}
+
+	// endregion
+}
diff --git a/packages/settings/tests/Integration/FieldRendererTest.php b/packages/settings/tests/Integration/FieldRendererTest.php
index 0fc12a8..e996345 100644
--- a/packages/settings/tests/Integration/FieldRendererTest.php
+++ b/packages/settings/tests/Integration/FieldRendererTest.php
@@ -4,6 +4,7 @@
 
 use DeepWebSolutions\Framework\Settings\Schema\Exceptions\UnknownFieldTypeException;
 use DeepWebSolutions\Framework\Settings\Schema\FieldRenderer;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\CustomFieldType;
 use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\UsesClass;
@@ -11,6 +12,7 @@
 
 #[CoversClass( FieldRenderer::class )]
 #[UsesClass( SettingsField::class )]
+#[UsesClass( CustomFieldType::class )]
 final class FieldRendererTest extends TestCase {
 	public function test_renders_a_text_input_with_the_value_bound(): void {
 		$html = ( new FieldRenderer() )->render( $this->field( 'name', 'text' ), 'Ada', 'opt[name]' );
@@ -223,6 +225,62 @@ public function test_an_unknown_type_throws(): void {
 		( new FieldRenderer() )->render( $this->field( 'x', 'bogus' ), '', 'x' );
 	}
 
+	public function test_an_unregistered_custom_type_still_throws(): void {
+		// A registry registered for a different type does not make every unknown token valid.
+		$renderer = new FieldRenderer(
+			custom_types: array(
+				'color_picker' => new CustomFieldType(
+					type: 'color_picker',
+					render: static fn ( SettingsField $field, mixed $value, string $name ): string => '',
+				),
+			),
+		);
+
+		$this->expectException( UnknownFieldTypeException::class );
+
+		$renderer->render( $this->field( 'x', 'bogus' ), '', 'x' );
+	}
+
+	public function test_a_registered_custom_renderer_is_invoked_with_the_field_value_and_name(): void {
+		$renderer = new FieldRenderer(
+			custom_types: array(
+				'color_picker' => new CustomFieldType(
+					type: 'color_picker',
+					render: static fn ( SettingsField $field, mixed $value, string $name ): string => \sprintf(
+						'<input class="dws-color" name="%s" value="%s" />',
+						\esc_attr( $name ),
+						\esc_attr( (string) $value ),
+					),
+				),
+			),
+		);
+
+		$html = $renderer->render( $this->field( 'shade', 'color_picker' ), '#abc', 'opt[shade]' );
+
+		self::assertStringContainsString( 'class="dws-color"', $html );
+		self::assertStringContainsString( 'name="opt[shade]"', $html );
+		self::assertStringContainsString( 'value="#abc"', $html );
+	}
+
+	public function test_a_custom_renderer_gets_the_field_description_appended(): void {
+		$field    = new SettingsField( id: 'shade', type: 'color_picker', label: 'Shade', description: 'Pick a shade.' );
+		$renderer = new FieldRenderer(
+			custom_types: array(
+				'color_picker' => new CustomFieldType(
+					type: 'color_picker',
+					render: static fn ( SettingsField $f, mixed $value, string $name ): string => '<input id="control" />',
+				),
+			),
+		);
+
+		$html = $renderer->render( $field, '', 'shade' );
+
+		self::assertStringContainsString( 'Pick a shade.', $html );
+		self::assertStringContainsString( 'class="description"', $html );
+		// The description follows the custom control, parity with the built-in types.
+		self::assertGreaterThan( \strpos( $html, '<input' ), \strpos( $html, 'Pick a shade.' ) );
+	}
+
 	public function test_renders_the_field_description_after_the_control(): void {
 		$field = new SettingsField( id: 'x', type: 'text', label: 'X', description: 'Helpful hint.' );
 
diff --git a/packages/settings/tests/Integration/WordPressSettingsBackendTest.php b/packages/settings/tests/Integration/WordPressSettingsBackendTest.php
index 0bd8c64..2afb79a 100644
--- a/packages/settings/tests/Integration/WordPressSettingsBackendTest.php
+++ b/packages/settings/tests/Integration/WordPressSettingsBackendTest.php
@@ -5,6 +5,9 @@
 use DeepWebSolutions\Framework\Settings\Backend\WordPressSettingsBackend;
 use DeepWebSolutions\Framework\Settings\Schema\Exceptions\DuplicateSettingsFieldException;
 use DeepWebSolutions\Framework\Settings\Schema\Exceptions\DuplicateSettingsSectionException;
+use DeepWebSolutions\Framework\Settings\Schema\FieldProcessor;
+use DeepWebSolutions\Framework\Settings\Schema\FieldRenderer;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\CustomFieldType;
 use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
 use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsPage;
 use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsSection;
@@ -16,6 +19,9 @@
 #[UsesClass( SettingsField::class )]
 #[UsesClass( SettingsSection::class )]
 #[UsesClass( SettingsPage::class )]
+#[UsesClass( CustomFieldType::class )]
+#[UsesClass( FieldRenderer::class )]
+#[UsesClass( FieldProcessor::class )]
 final class WordPressSettingsBackendTest extends TestCase {
 	private const SLUG            = 'dws-test-settings';
 	private const GENERAL_OPTION  = 'dws-test-settings-general';
@@ -313,6 +319,66 @@ static function ( mixed $value ) use ( $backend, &$nested_done ): mixed {
 		self::assertNull( $backend->get( 'site_name', 'sentinel' ) );
 	}
 
+	public function test_a_custom_field_type_renders_through_an_injected_renderer(): void {
+		// The page render emits a full admin form; its helpers (submit_button, settings_fields) live in the
+		// admin includes loaded on real admin requests, so the CLI context must require them.
+		require_once ABSPATH . 'wp-admin/includes/plugin.php';
+		require_once ABSPATH . 'wp-admin/includes/template.php';
+		$this->register_with_custom( $this->custom_page() );
+		\do_action( 'admin_menu' );
+
+		// The page render callback is registered on the page's resolved menu hook; invoke that hook to render
+		// the whole page, proving the injected renderer's custom-type control reaches the page markup.
+		\ob_start();
+		\do_action( \get_plugin_page_hookname( self::SLUG, 'options-general.php' ) );
+		$html = (string) \ob_get_clean();
+
+		self::assertStringContainsString( 'class="dws-page-select"', $html );
+		self::assertStringContainsString( 'name="' . self::GENERAL_OPTION . '[home_page]"', $html );
+	}
+
+	public function test_a_custom_field_type_value_round_trips_through_sanitize_option_and_get(): void {
+		$backend = $this->register_with_custom( $this->custom_page() );
+		\do_action( 'admin_init' );
+
+		// A form save routes through register_setting's sanitize_callback (sanitize_option), where the injected
+		// processor accepts the custom type's submission; the stored value reads back through get().
+		$this->form_save( self::GENERAL_OPTION, array( 'home_page' => '42' ) );
+
+		self::assertSame( '42', $backend->get( 'home_page' ) );
+		self::assertSame( '42', \get_option( self::GENERAL_OPTION )['home_page'] ?? null );
+	}
+
+	public function test_a_custom_field_type_falls_back_to_its_default_when_validation_rejects(): void {
+		$page = new SettingsPage(
+			slug: self::SLUG,
+			page_title: 'DWS Test',
+			menu_title: 'DWS Test',
+			capability: 'edit_pages',
+			sections: array(
+				new SettingsSection(
+					'general',
+					'General',
+					array(
+						new SettingsField(
+							id: 'home_page',
+							type: 'single_select_page',
+							label: 'Home Page',
+							default: '7',
+							validate: static fn ( mixed $value ): bool => false,
+						),
+					),
+				),
+			),
+		);
+		$backend = $this->register_with_custom( $page );
+		\do_action( 'admin_init' );
+
+		$this->form_save( self::GENERAL_OPTION, array( 'home_page' => '999' ) );
+
+		self::assertSame( '7', $backend->get( 'home_page' ) );
+	}
+
 	private function register( SettingsPage $page ): WordPressSettingsBackend {
 		$backend = new WordPressSettingsBackend();
 		$backend->register_page( $page );
@@ -320,6 +386,43 @@ private function register( SettingsPage $page ): WordPressSettingsBackend {
 		return $backend;
 	}
 
+	private function register_with_custom( SettingsPage $page ): WordPressSettingsBackend {
+		$custom_types = array(
+			'single_select_page' => new CustomFieldType(
+				type: 'single_select_page',
+				render: static fn ( SettingsField $field, mixed $value, string $name ): string => \sprintf(
+					'<select class="dws-page-select" name="%s"><option value="42"%s>Sample Page</option></select>',
+					\esc_attr( $name ),
+					\selected( '42', (string) $value, false ),
+				),
+			),
+		);
+
+		$backend = new WordPressSettingsBackend(
+			renderer: new FieldRenderer( custom_types: $custom_types ),
+			processor: new FieldProcessor( custom_types: $custom_types ),
+		);
+		$backend->register_page( $page );
+
+		return $backend;
+	}
+
+	private function custom_page(): SettingsPage {
+		return new SettingsPage(
+			slug: self::SLUG,
+			page_title: 'DWS Test',
+			menu_title: 'DWS Test',
+			capability: 'edit_pages',
+			sections: array(
+				new SettingsSection(
+					'general',
+					'General',
+					array( new SettingsField( id: 'home_page', type: 'single_select_page', label: 'Home Page' ) ),
+				),
+			),
+		);
+	}
+
 	/**
 	 * Simulates the options.php save of $data for the given option group.
 	 *
diff --git a/packages/settings/tests/Unit/CustomFieldTypeTest.php b/packages/settings/tests/Unit/CustomFieldTypeTest.php
new file mode 100644
index 0000000..b6fc4a5
--- /dev/null
+++ b/packages/settings/tests/Unit/CustomFieldTypeTest.php
@@ -0,0 +1,91 @@
+<?php declare( strict_types=1 );
+
+namespace DeepWebSolutions\Framework\Settings\Tests\Unit;
+
+use DeepWebSolutions\Framework\Settings\Schema\Exceptions\InvalidCustomFieldTypeException;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\CustomFieldType;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\UsesClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass( CustomFieldType::class )]
+#[UsesClass( SettingsField::class )]
+final class CustomFieldTypeTest extends TestCase {
+	public function test_a_valid_token_round_trips(): void {
+		$render = static fn ( SettingsField $field, mixed $value, string $name ): string => '<custom />';
+		$type   = new CustomFieldType( type: 'color_picker', render: $render );
+
+		self::assertSame( 'color_picker', $type->type );
+	}
+
+	public function test_the_callable_is_normalized_to_a_closure(): void {
+		$type = new CustomFieldType( type: 'my_type', render: array( $this, 'render_stub' ) );
+
+		self::assertInstanceOf( \Closure::class, $type->render );
+		self::assertSame(
+			'stub',
+			( $type->render )( new SettingsField( id: 'f', type: 'my_type', label: 'F' ), null, 'f' ),
+		);
+	}
+
+	public function test_a_closure_render_is_preserved(): void {
+		$closure = static fn ( SettingsField $field, mixed $value, string $name ): string => '<x />';
+		$type    = new CustomFieldType( type: 'my_type', render: $closure );
+
+		self::assertInstanceOf( \Closure::class, $type->render );
+	}
+
+	#[DataProvider( 'valid_types' )]
+	public function test_accepts_valid_type_tokens( string $valid_type ): void {
+		$type = new CustomFieldType(
+			type: $valid_type,
+			render: static fn ( SettingsField $field, mixed $value, string $name ): string => '',
+		);
+
+		self::assertSame( $valid_type, $type->type );
+	}
+
+	/**
+	 * @return array<string, array{string}>
+	 */
+	public static function valid_types(): array {
+		return array(
+			'single letter'   => array( 'a' ),
+			'word'            => array( 'colorpicker' ),
+			'with digit'      => array( 'type2' ),
+			'with underscore' => array( 'color_picker' ),
+			'with hyphen'     => array( 'color-picker' ),
+		);
+	}
+
+	#[DataProvider( 'invalid_types' )]
+	public function test_rejects_an_invalid_type_token( string $invalid_type ): void {
+		$this->expectException( InvalidCustomFieldTypeException::class );
+
+		new CustomFieldType(
+			type: $invalid_type,
+			render: static fn ( SettingsField $field, mixed $value, string $name ): string => '',
+		);
+	}
+
+	/**
+	 * @return array<string, array{string}>
+	 */
+	public static function invalid_types(): array {
+		return array(
+			'empty'              => array( '' ),
+			'leading digit'      => array( '1type' ),
+			'leading hyphen'     => array( '-type' ),
+			'leading underscore' => array( '_type' ),
+			'uppercase'          => array( 'Type' ),
+			'space'              => array( 'my type' ),
+			'dot'                => array( 'my.type' ),
+		);
+	}
+
+	public function render_stub( SettingsField $field, mixed $value, string $name ): string {
+		return 'stub';
+	}
+}
diff --git a/packages/settings/tests/Unit/FieldProcessorTest.php b/packages/settings/tests/Unit/FieldProcessorTest.php
index dc95ef7..60eb165 100644
--- a/packages/settings/tests/Unit/FieldProcessorTest.php
+++ b/packages/settings/tests/Unit/FieldProcessorTest.php
@@ -5,6 +5,7 @@
 use DeepWebSolutions\Framework\Settings\Schema\Exceptions\UnknownFieldTypeException;
 use DeepWebSolutions\Framework\Settings\Schema\FieldProcessor;
 use DeepWebSolutions\Framework\Settings\Schema\OptionsResolver;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\CustomFieldType;
 use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\UsesClass;
@@ -13,6 +14,7 @@
 #[CoversClass( FieldProcessor::class )]
 #[UsesClass( SettingsField::class )]
 #[UsesClass( OptionsResolver::class )]
+#[UsesClass( CustomFieldType::class )]
 final class FieldProcessorTest extends TestCase {
 	public function test_an_unknown_field_type_throws(): void {
 		$this->expectException( UnknownFieldTypeException::class );
@@ -20,6 +22,76 @@ public function test_an_unknown_field_type_throws(): void {
 		( new FieldProcessor() )->process( $this->field( 'f', 'bogus' ), array( 'f' => 'x' ) );
 	}
 
+	public function test_an_unregistered_custom_type_still_throws(): void {
+		// The registry is an allowlist: a type absent from it stays loud, so a typo is caught, not silently persisted.
+		$processor = new FieldProcessor(
+			custom_types: array( 'color_picker' => $this->custom_type( 'color_picker' ) ),
+		);
+
+		$this->expectException( UnknownFieldTypeException::class );
+
+		$processor->process( $this->field( 'f', 'bogus' ), array( 'f' => 'x' ) );
+	}
+
+	public function test_a_registered_custom_type_applies_the_fields_sanitize(): void {
+		$processor = new FieldProcessor(
+			custom_types: array( 'color_picker' => $this->custom_type( 'color_picker' ) ),
+		);
+		$field     = new SettingsField( id: 'shade', type: 'color_picker', label: 'Shade', sanitize: 'trim' );
+
+		self::assertSame( '#abc', $processor->process( $field, array( 'shade' => '  #abc  ' ) ) );
+	}
+
+	public function test_a_registered_custom_type_with_no_submission_returns_the_default(): void {
+		// A custom type follows the established custom-save shape (ProductData): an absent submission falls
+		// back to the field's default, not the scalar-empty false the taxonomy branch coerces to.
+		$processor = new FieldProcessor(
+			custom_types: array( 'color_picker' => $this->custom_type( 'color_picker' ) ),
+		);
+		$field     = new SettingsField( id: 'shade', type: 'color_picker', label: 'Shade', default: '#000' );
+
+		self::assertSame( '#000', $processor->process( $field, array() ) );
+	}
+
+	public function test_a_registered_custom_type_failing_validation_returns_the_default(): void {
+		$processor = new FieldProcessor(
+			custom_types: array( 'color_picker' => $this->custom_type( 'color_picker' ) ),
+		);
+		$field     = new SettingsField(
+			id: 'shade',
+			type: 'color_picker',
+			label: 'Shade',
+			default: '#fallback',
+			validate: static fn ( mixed $value ): bool => false,
+		);
+
+		self::assertSame( '#fallback', $processor->process( $field, array( 'shade' => '#abc' ) ) );
+	}
+
+	public function test_a_registered_custom_type_applies_sanitize_before_validate(): void {
+		$processor = new FieldProcessor(
+			custom_types: array( 'color_picker' => $this->custom_type( 'color_picker' ) ),
+		);
+		// The validator accepts only the trimmed value; were it run before sanitize, it would reject to the default.
+		$field = new SettingsField(
+			id: 'shade',
+			type: 'color_picker',
+			label: 'Shade',
+			default: '#fallback',
+			sanitize: 'trim',
+			validate: static fn ( mixed $value ): bool => '#abc' === $value,
+		);
+
+		self::assertSame( '#abc', $processor->process( $field, array( 'shade' => '  #abc  ' ) ) );
+	}
+
+	private function custom_type( string $type ): CustomFieldType {
+		return new CustomFieldType(
+			type: $type,
+			render: static fn ( SettingsField $field, mixed $value, string $name ): string => '',
+		);
+	}
+
 	public function test_an_absent_checkbox_coerces_to_false(): void {
 		$result = ( new FieldProcessor() )->process( $this->field( 'agree', 'checkbox' ), array() );
 
diff --git a/packages/woocommerce/tests/Integration/OrderData/OrderFieldStoreTest.php b/packages/woocommerce/tests/Integration/OrderData/OrderFieldStoreTest.php
index 38cba71..6e10a57 100644
--- a/packages/woocommerce/tests/Integration/OrderData/OrderFieldStoreTest.php
+++ b/packages/woocommerce/tests/Integration/OrderData/OrderFieldStoreTest.php
@@ -10,6 +10,7 @@
 use DeepWebSolutions\Framework\Settings\Schema\FieldRenderer;
 use DeepWebSolutions\Framework\Settings\Schema\FieldType;
 use DeepWebSolutions\Framework\Settings\Schema\OptionsResolver;
+use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\CustomFieldType;
 use DeepWebSolutions\Framework\Settings\Schema\ValueObjects\SettingsField;
 use DeepWebSolutions\Framework\WooCommerce\OrderData\OrderFieldStore;
 use PHPUnit\Framework\Attributes\CoversClass;
@@ -23,6 +24,7 @@
 #[UsesClass( FieldProcessor::class )]
 #[UsesClass( OptionsResolver::class )]
 #[UsesClass( FieldType::class )]
+#[UsesClass( CustomFieldType::class )]
 final class OrderFieldStoreTest extends TestCase {
 	private const BOX_ID       = 'dws_unlock';
 	private const NONCE_NAME   = 'dws_object_field_dws_unlock_nonce';
@@ -491,6 +493,54 @@ public function test_a_meta_box_title_is_escaped_before_registration(): void {
 		self::assertStringContainsString( '&lt;script&gt;', $title );
 	}
 
+	public function test_a_custom_field_type_renders_and_saves_through_the_order_surface(): void {
+		$screen = OrderUtil::custom_orders_table_usage_is_enabled() ? 'woocommerce_page_wc-orders' : 'shop_order';
+		\set_current_screen( $screen );
+
+		$custom_types = array(
+			'single_select_page' => new CustomFieldType(
+				type: 'single_select_page',
+				render: static fn ( SettingsField $field, mixed $value, string $name ): string => \sprintf(
+					'<select class="dws-page-select" name="%s"><option value="42"%s>Sample</option></select>',
+					\esc_attr( $name ),
+					\selected( '42', (string) $value, false ),
+				),
+			),
+		);
+		$box   = new ObjectMetaBox(
+			id: self::BOX_ID,
+			title: 'Home',
+			screen: 'shop_order',
+			context: 'side',
+			priority: 'default',
+			fields_provider: static fn ( int $object_id ): array => array(
+				new SettingsField( id: 'home_page', type: 'single_select_page', label: 'Home Page' ),
+			),
+		);
+		$store = new OrderFieldStore(
+			renderer: new FieldRenderer( custom_types: $custom_types ),
+			processor: new FieldProcessor( custom_types: $custom_types ),
+		);
+		$store->register_meta_box( $box );
+
+		// The injected renderer's custom control reaches the rendered box.
+		\do_action( "add_meta_boxes_$screen" );
+		$definition = (array) ( $this->boxes_on( $screen )[ self::BOX_ID ] ?? array() );
+		$callback   = $definition['callback'] ?? null;
+		\assert( \is_callable( $callback ) );
+		\ob_start();
+		$callback( \wc_get_order( $this->order_id ) );
+		$html = (string) \ob_get_clean();
+		self::assertStringContainsString( 'class="dws-page-select"', $html );
+		self::assertStringContainsString( 'name="dws_unlock[home_page]"', $html );
+
+		// The injected processor accepts the custom type's submission, which the store persists as order meta.
+		$_POST = array( self::NONCE_NAME => $this->nonce(), self::BOX_ID => array( 'home_page' => '42' ) );
+		\do_action( 'woocommerce_process_shop_order_meta', $this->order_id );
+
+		self::assertSame( '42', $store->get( $this->order_id, 'home_page' ) );
+	}
+
 	private function nonce(): string {
 		return \wp_create_nonce( self::NONCE_ACTION . '_' . $this->order_id );
 	}

From b2d6a80c377acffafa6e89c5f125d12d0987198e Mon Sep 17 00:00:00 2001
From: Tony Hegyes <a.hegyes@proton.me>
Date: Mon, 22 Jun 2026 12:09:25 +0200
Subject: [PATCH 08/21] feat(utilities): add backend-abstracted action
 scheduler
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Finding #13. Two demand-certain wave-2 consumers (QR, PPW) duplicate the same
Action Scheduler idiom — schedule a recurring action only if not already
scheduled. Rather than a thin AS wrapper bundled in the woocommerce package
(Action Scheduler is not WooCommerce-specific, only bundled with it), add a
backend-abstracted scheduler to utilities, shaped like the settings backend
pattern.

Scheduling/SchedulerBackendInterface is a generic hook+args contract with a
hybrid return surface: mutations (schedule_recurring/schedule_single/unschedule)
return a Result carrying a SchedulingError on failure; queries (is_scheduled,
get_next_scheduled) return plain scalars. Two final backends implement it —
ActionSchedulerBackend (as_* functions, function_exists-gated) and WPCronBackend
(the always-available fallback) — and select_scheduler_backend() picks Action
Scheduler when loaded, else WP-Cron. The Scheduler facade delegates to the
selected backend.

Backend specifics: AS idempotency uses the args-aware as_has_scheduled_action()
guard with unique=false, because AS's native unique flag keys on hook+group only
and ignores args. WP-Cron addresses a recurring event by a named schedule, not a
raw interval, so each interval N gets a synthetic dws_every_{N}s schedule
injected once through a stable cron_schedules filter callback; WP-Cron has no
grouping, so a non-empty group is rejected on every mutation. SchedulingError is
the framework's first concrete Shared\Error\ErrorInterface, pairing a
SchedulingErrorReason enum with a message and context.

Stub wiring: phpstan.dist.neon bootstraps woocommerce-packages-stubs.php (it
defines the as_* functions; woocommerce-stubs.php does not). utilities'
scoping-stubs declares the explicit-file form
"php-stubs/woocommerce-stubs:woocommerce-packages-stubs.php" so a consumer's
php-scoper leaves the as_* symbols external. That form depends on the
wordpress-configs CollectScopingStubs explicit-file support (separate repo); the
current collector silently skips the entry until then, harmless pre-Phase-4 as
no consumer scopes utilities yet. No deptrac change — as_*/wp_* are external
globals and the Utilities to Shared edge already exists.

Gates: PHPStan clean, deptrac 0, Unit 416, Integration 300.

Assisted-by: Claude Code:claude-opus-4-8
---
 packages/utilities/composer.json              |   3 +-
 packages/utilities/functions.php              |   4 +-
 .../Backends/ActionSchedulerBackend.php       | 192 ++++++++++++
 .../src/Scheduling/Backends/WPCronBackend.php | 290 ++++++++++++++++++
 .../src/Scheduling/Backends/index.php         |   1 +
 .../src/Scheduling/Errors/SchedulingError.php |  38 +++
 .../utilities/src/Scheduling/Errors/index.php |   1 +
 .../utilities/src/Scheduling/Scheduler.php    | 104 +++++++
 .../Scheduling/SchedulerBackendInterface.php  |  95 ++++++
 .../src/Scheduling/SchedulingErrorReason.php  |  21 ++
 .../utilities/src/Scheduling/functions.php    |  30 ++
 packages/utilities/src/Scheduling/index.php   |   1 +
 .../Backends/ActionSchedulerBackendTest.php   | 131 ++++++++
 .../Scheduling/Backends/WPCronBackendTest.php | 167 ++++++++++
 .../Integration/Scheduling/Backends/index.php |   1 +
 .../tests/Integration/Scheduling/index.php    |   1 +
 .../Backends/ActionSchedulerBackendTest.php   |  68 ++++
 .../tests/Unit/Scheduling/Backends/index.php  |   1 +
 .../Scheduling/Errors/SchedulingErrorTest.php |  38 +++
 .../tests/Unit/Scheduling/Errors/index.php    |   1 +
 .../tests/Unit/Scheduling/SchedulerTest.php   | 143 +++++++++
 .../Scheduling/SchedulingErrorReasonTest.php  |  24 ++
 .../Scheduling/SelectSchedulerBackendTest.php |  25 ++
 .../utilities/tests/Unit/Scheduling/index.php |   1 +
 phpstan.dist.neon                             |   3 +
 25 files changed, 1380 insertions(+), 4 deletions(-)
 create mode 100644 packages/utilities/src/Scheduling/Backends/ActionSchedulerBackend.php
 create mode 100644 packages/utilities/src/Scheduling/Backends/WPCronBackend.php
 create mode 100644 packages/utilities/src/Scheduling/Backends/index.php
 create mode 100644 packages/utilities/src/Scheduling/Errors/SchedulingError.php
 create mode 100644 packages/utilities/src/Scheduling/Errors/index.php
 create mode 100644 packages/utilities/src/Scheduling/Scheduler.php
 create mode 100644 packages/utilities/src/Scheduling/SchedulerBackendInterface.php
 create mode 100644 packages/utilities/src/Scheduling/SchedulingErrorReason.php
 create mode 100644 packages/utilities/src/Scheduling/functions.php
 create mode 100644 packages/utilities/src/Scheduling/index.php
 create mode 100644 packages/utilities/tests/Integration/Scheduling/Backends/ActionSchedulerBackendTest.php
 create mode 100644 packages/utilities/tests/Integration/Scheduling/Backends/WPCronBackendTest.php
 create mode 100644 packages/utilities/tests/Integration/Scheduling/Backends/index.php
 create mode 100644 packages/utilities/tests/Integration/Scheduling/index.php
 create mode 100644 packages/utilities/tests/Unit/Scheduling/Backends/ActionSchedulerBackendTest.php
 create mode 100644 packages/utilities/tests/Unit/Scheduling/Backends/index.php
 create mode 100644 packages/utilities/tests/Unit/Scheduling/Errors/SchedulingErrorTest.php
 create mode 100644 packages/utilities/tests/Unit/Scheduling/Errors/index.php
 create mode 100644 packages/utilities/tests/Unit/Scheduling/SchedulerTest.php
 create mode 100644 packages/utilities/tests/Unit/Scheduling/SchedulingErrorReasonTest.php
 create mode 100644 packages/utilities/tests/Unit/Scheduling/SelectSchedulerBackendTest.php
 create mode 100644 packages/utilities/tests/Unit/Scheduling/index.php

diff --git a/packages/utilities/composer.json b/packages/utilities/composer.json
index 7687398..337b8b8 100644
--- a/packages/utilities/composer.json
+++ b/packages/utilities/composer.json
@@ -45,7 +45,8 @@
       "dev-trunk": "2.0.x-dev"
     },
     "scoping-stubs": [
-      "php-stubs/wordpress-stubs"
+      "php-stubs/wordpress-stubs",
+      "php-stubs/woocommerce-stubs:woocommerce-packages-stubs.php"
     ],
     "changelogger": {
       "versioning": "semver",
diff --git a/packages/utilities/functions.php b/packages/utilities/functions.php
index 80d592a..2b7ff1a 100644
--- a/packages/utilities/functions.php
+++ b/packages/utilities/functions.php
@@ -1,5 +1,3 @@
 <?php declare( strict_types=1 );
 
-// No namespace functions in utilities yet. This file exists for workspace-wide
-// consistency with the package-root functions.php aggregator pattern; when a
-// <namespace>/functions.php file is added under src/, require_once it here.
+require_once __DIR__ . '/src/Scheduling/functions.php';
diff --git a/packages/utilities/src/Scheduling/Backends/ActionSchedulerBackend.php b/packages/utilities/src/Scheduling/Backends/ActionSchedulerBackend.php
new file mode 100644
index 0000000..2dc58fb
--- /dev/null
+++ b/packages/utilities/src/Scheduling/Backends/ActionSchedulerBackend.php
@@ -0,0 +1,192 @@
+<?php declare( strict_types=1 );
+
+namespace DeepWebSolutions\Framework\Utilities\Scheduling\Backends;
+
+use DeepWebSolutions\Framework\Shared\Result\AbstractResult;
+use DeepWebSolutions\Framework\Shared\Result\Failure;
+use DeepWebSolutions\Framework\Shared\Result\Success;
+use DeepWebSolutions\Framework\Utilities\Scheduling\Errors\SchedulingError;
+use DeepWebSolutions\Framework\Utilities\Scheduling\SchedulerBackendInterface;
+use DeepWebSolutions\Framework\Utilities\Scheduling\SchedulingErrorReason;
+use Psr\Log\LoggerInterface;
+
+/**
+ * Scheduler backend over Action Scheduler.
+ *
+ * Every as_* call is guarded by function_exists so a missing Action Scheduler fails
+ * cleanly rather than fataling. Idempotency is enforced by the args-aware
+ * as_has_scheduled_action() guard rather than Action Scheduler's $unique flag, which
+ * keys on hook plus group only and ignores args — two schedules differing only in args
+ * must both be allowed. The optional logger records the absent-scheduler condition.
+ *
+ * @since   2.0.0
+ * @version 2.0.0
+ */
+final class ActionSchedulerBackend implements SchedulerBackendInterface {
+	// region MAGIC METHODS
+
+	/**
+	 * Constructor.
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 *
+	 * @param   LoggerInterface|null $logger Optional PSR-3 logger for the absent-scheduler condition.
+	 */
+	public function __construct(
+		private ?LoggerInterface $logger = null,
+	) {}
+
+	// endregion
+
+	// region INHERITED METHODS
+
+	/**
+	 * {@inheritDoc}
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 */
+	public function schedule_recurring( string $hook, int $interval, array $args = array(), ?int $first_run_timestamp = null, string $group = '' ): AbstractResult {
+		if ( ! $this->is_available() ) {
+			return $this->unavailable();
+		}
+		if ( $interval <= 0 ) {
+			return Failure::from(
+				new SchedulingError(
+					SchedulingErrorReason::InvalidInterval,
+					'A recurring schedule requires a positive interval.',
+					array( 'interval' => $interval ),
+				),
+			);
+		}
+		if ( \as_has_scheduled_action( $hook, $args, $group ) ) {
+			return Success::from( true );
+		}
+
+		$action_id = \as_schedule_recurring_action( $first_run_timestamp ?? \time(), $interval, $hook, $args, $group, false );
+		return $this->result_for_action_id( $action_id, $hook );
+	}
+
+	/**
+	 * {@inheritDoc}
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 */
+	public function schedule_single( string $hook, int $timestamp, array $args = array(), string $group = '' ): AbstractResult {
+		if ( ! $this->is_available() ) {
+			return $this->unavailable();
+		}
+		if ( \as_has_scheduled_action( $hook, $args, $group ) ) {
+			return Success::from( true );
+		}
+
+		$action_id = \as_schedule_single_action( $timestamp, $hook, $args, $group, false );
+		return $this->result_for_action_id( $action_id, $hook );
+	}
+
+	/**
+	 * {@inheritDoc}
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 */
+	public function unschedule( string $hook, array $args = array(), string $group = '' ): AbstractResult {
+		if ( ! $this->is_available() ) {
+			return $this->unavailable();
+		}
+
+		\as_unschedule_action( $hook, $args, $group );
+		return Success::from( true );
+	}
+
+	/**
+	 * {@inheritDoc}
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 */
+	public function is_scheduled( string $hook, array $args = array(), string $group = '' ): bool {
+		if ( ! $this->is_available() ) {
+			return false;
+		}
+
+		return \as_has_scheduled_action( $hook, $args, $group );
+	}
+
+	/**
+	 * {@inheritDoc}
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 */
+	public function get_next_scheduled( string $hook, array $args = array(), string $group = '' ): ?int {
+		if ( ! $this->is_available() ) {
+			return null;
+		}
+
+		$next = \as_next_scheduled_action( $hook, $args, $group );
+		return \is_int( $next ) ? $next : null;
+	}
+
+	// endregion
+
+	// region HELPERS
+
+	/**
+	 * Whether Action Scheduler's scheduling API is loaded.
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 *
+	 * @return  bool
+	 */
+	private function is_available(): bool {
+		return \function_exists( 'as_schedule_recurring_action' );
+	}
+
+	/**
+	 * Builds the failure returned when Action Scheduler is not loaded, logging the condition.
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 *
+	 * @return  Failure<SchedulingError>
+	 */
+	private function unavailable(): Failure {
+		$message = 'Action Scheduler is not loaded; cannot schedule the action.';
+		$this->logger?->error( $message );
+
+		return Failure::from(
+			new SchedulingError( SchedulingErrorReason::ActionSchedulerNotLoaded, $message ),
+		);
+	}
+
+	/**
+	 * Maps an Action Scheduler action id to a result — zero is a scheduling failure.
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 *
+	 * @param   int    $action_id Action id returned by Action Scheduler; zero on error.
+	 * @param   string $hook      Hook that was being scheduled, for the error context.
+	 *
+	 * @return  Success<true>|Failure<SchedulingError> Success, or a failure when the id is zero.
+	 */
+	private function result_for_action_id( int $action_id, string $hook ): AbstractResult {
+		if ( 0 === $action_id ) {
+			return Failure::from(
+				new SchedulingError(
+					SchedulingErrorReason::ScheduleFailed,
+					'Action Scheduler returned a zero action id when scheduling the action.',
+					array( 'hook' => $hook ),
+				),
+			);
+		}
+
+		return Success::from( true );
+	}
+
+	// endregion
+}
diff --git a/packages/utilities/src/Scheduling/Backends/WPCronBackend.php b/packages/utilities/src/Scheduling/Backends/WPCronBackend.php
new file mode 100644
index 0000000..d832642
--- /dev/null
+++ b/packages/utilities/src/Scheduling/Backends/WPCronBackend.php
@@ -0,0 +1,290 @@
+<?php declare( strict_types=1 );
+
+namespace DeepWebSolutions\Framework\Utilities\Scheduling\Backends;
+
+use DeepWebSolutions\Framework\Shared\Result\AbstractResult;
+use DeepWebSolutions\Framework\Shared\Result\Failure;
+use DeepWebSolutions\Framework\Shared\Result\Success;
+use DeepWebSolutions\Framework\Utilities\Scheduling\Errors\SchedulingError;
+use DeepWebSolutions\Framework\Utilities\Scheduling\SchedulerBackendInterface;
+use DeepWebSolutions\Framework\Utilities\Scheduling\SchedulingErrorReason;
+use Psr\Log\LoggerInterface;
+use WP_Error;
+
+/**
+ * Scheduler backend over WordPress cron — the fallback when Action Scheduler is absent.
+ *
+ * WordPress cron addresses a recurring event by a named schedule, not a raw interval, so
+ * each distinct interval gets a synthetic schedule 'dws_every_{N}s' injected through the
+ * 'cron_schedules' filter. The filter callback is a stable [object, method] pair wired
+ * exactly once (WordPress cannot de-duplicate fresh closures, so a stable reference and a
+ * one-time guard are both required); it reads an internal interval registry, so later
+ * intervals are covered without re-adding the filter. WordPress cron has no grouping, so a
+ * non-empty group is rejected on every mutation.
+ *
+ * @since   2.0.0
+ * @version 2.0.0
+ */
+final class WPCronBackend implements SchedulerBackendInterface {
+	// region FIELDS AND CONSTANTS
+
+	/**
+	 * Optional PSR-3 logger for failure conditions.
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 *
+	 * @var     LoggerInterface|null
+	 */
+	private ?LoggerInterface $logger;
+
+	/**
+	 * Intervals (in seconds) for which a synthetic schedule has been registered, used as a set.
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 *
+	 * @var     array<int, bool>
+	 */
+	private array $registered_intervals = array();
+
+	/**
+	 * Whether the 'cron_schedules' filter callback has been wired this request.
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 *
+	 * @var     bool
+	 */
+	private bool $schedules_filter_registered = false;
+
+	// endregion
+
+	// region MAGIC METHODS
+
+	/**
+	 * Constructor.
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 *
+	 * @param   LoggerInterface|null $logger Optional PSR-3 logger for failure conditions.
+	 */
+	public function __construct( ?LoggerInterface $logger = null ) {
+		$this->logger = $logger;
+	}
+
+	// endregion
+
+	// region INHERITED METHODS
+
+	/**
+	 * {@inheritDoc}
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 */
+	public function schedule_recurring( string $hook, int $interval, array $args = array(), ?int $first_run_timestamp = null, string $group = '' ): AbstractResult {
+		$rejection = $this->reject_group( $group );
+		if ( null !== $rejection ) {
+			return $rejection;
+		}
+		if ( $interval <= 0 ) {
+			return Failure::from(
+				new SchedulingError(
+					SchedulingErrorReason::InvalidInterval,
+					'A recurring schedule requires a positive interval.',
+					array( 'interval' => $interval ),
+				),
+			);
+		}
+		if ( false !== \wp_next_scheduled( $hook, $args ) ) {
+			return Success::from( true );
+		}
+
+		$schedule_name = $this->ensure_schedule( $interval );
+		$scheduled     = \wp_schedule_event( $first_run_timestamp ?? \time(), $schedule_name, $hook, $args, true );
+		return $this->result_for_schedule( $scheduled, $hook );
+	}
+
+	/**
+	 * {@inheritDoc}
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 */
+	public function schedule_single( string $hook, int $timestamp, array $args = array(), string $group = '' ): AbstractResult {
+		$rejection = $this->reject_group( $group );
+		if ( null !== $rejection ) {
+			return $rejection;
+		}
+		if ( false !== \wp_next_scheduled( $hook, $args ) ) {
+			return Success::from( true );
+		}
+
+		$scheduled = \wp_schedule_single_event( $timestamp, $hook, $args, true );
+		return $this->result_for_schedule( $scheduled, $hook );
+	}
+
+	/**
+	 * {@inheritDoc}
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 */
+	public function unschedule( string $hook, array $args = array(), string $group = '' ): AbstractResult {
+		$rejection = $this->reject_group( $group );
+		if ( null !== $rejection ) {
+			return $rejection;
+		}
+
+		\wp_clear_scheduled_hook( $hook, $args, true );
+		return Success::from( true );
+	}
+
+	/**
+	 * {@inheritDoc}
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 */
+	public function is_scheduled( string $hook, array $args = array(), string $group = '' ): bool {
+		return false !== \wp_next_scheduled( $hook, $args );
+	}
+
+	/**
+	 * {@inheritDoc}
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 */
+	public function get_next_scheduled( string $hook, array $args = array(), string $group = '' ): ?int {
+		$next = \wp_next_scheduled( $hook, $args );
+		return \is_int( $next ) ? $next : null;
+	}
+
+	// endregion
+
+	// region HOOKS
+
+	/**
+	 * Injects a synthetic 'dws_every_{N}s' schedule for every registered interval.
+	 *
+	 * Filter callback for 'cron_schedules'. A stable [object, method] reference so WordPress
+	 * de-duplicates it and the one-time wiring holds; it reads the interval registry, so a
+	 * single registration covers every interval scheduled this request.
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 *
+	 * @param   array<string, array{interval: int, display: string}> $schedules Existing schedules from WordPress.
+	 *
+	 * @return  array<string, array{interval: int, display: string}>
+	 */
+	public function register_synthetic_schedules( array $schedules ): array {
+		foreach ( \array_keys( $this->registered_intervals ) as $interval ) {
+			$schedules[ $this->schedule_name( $interval ) ] = array(
+				'interval' => $interval,
+				'display'  => \sprintf( 'Every %d seconds (DWS)', $interval ),
+			);
+		}
+
+		return $schedules;
+	}
+
+	// endregion
+
+	// region HELPERS
+
+	/**
+	 * Rejects a non-empty group, which WordPress cron cannot honor.
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 *
+	 * @param   string $group Requested grouping label.
+	 *
+	 * @return  Failure<SchedulingError>|null A failure when the group is non-empty, null when it is empty.
+	 */
+	private function reject_group( string $group ): ?Failure {
+		if ( '' === $group ) {
+			return null;
+		}
+
+		$message = 'WordPress cron does not support action groups.';
+		$this->logger?->error( $message, array( 'group' => $group ) );
+
+		return Failure::from(
+			new SchedulingError(
+				SchedulingErrorReason::UnsupportedGroup,
+				$message,
+				array( 'group' => $group ),
+			),
+		);
+	}
+
+	/**
+	 * Registers a synthetic schedule for an interval and returns its name.
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 *
+	 * @param   int $interval Interval in seconds.
+	 *
+	 * @return  string
+	 */
+	private function ensure_schedule( int $interval ): string {
+		$this->registered_intervals[ $interval ] = true;
+		if ( ! $this->schedules_filter_registered ) {
+			\add_filter( 'cron_schedules', array( $this, 'register_synthetic_schedules' ) );
+			$this->schedules_filter_registered = true;
+		}
+
+		return $this->schedule_name( $interval );
+	}
+
+	/**
+	 * Builds the synthetic schedule name for an interval.
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 *
+	 * @param   int $interval Interval in seconds.
+	 *
+	 * @return  string
+	 */
+	private function schedule_name( int $interval ): string {
+		return 'dws_every_' . $interval . 's';
+	}
+
+	/**
+	 * Maps a WordPress cron scheduling return to a result — false or a WP_Error is a failure.
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 *
+	 * @param   bool|WP_Error $scheduled Return of wp_schedule_event / wp_schedule_single_event.
+	 * @param   string        $hook      Hook that was being scheduled, for the error context.
+	 *
+	 * @return  Success<true>|Failure<SchedulingError> Success, or a failure on a false / WP_Error return.
+	 */
+	private function result_for_schedule( bool|WP_Error $scheduled, string $hook ): AbstractResult {
+		if ( true === $scheduled ) {
+			return Success::from( true );
+		}
+
+		$context = array( 'hook' => $hook );
+		if ( $scheduled instanceof WP_Error ) {
+			$context['wp_error'] = $scheduled->get_error_message();
+		}
+
+		$message = 'WordPress cron rejected the scheduling request.';
+		$this->logger?->error( $message, $context );
+
+		return Failure::from(
+			new SchedulingError( SchedulingErrorReason::ScheduleFailed, $message, $context ),
+		);
+	}
+
+	// endregion
+}
diff --git a/packages/utilities/src/Scheduling/Backends/index.php b/packages/utilities/src/Scheduling/Backends/index.php
new file mode 100644
index 0000000..f767346
--- /dev/null
+++ b/packages/utilities/src/Scheduling/Backends/index.php
@@ -0,0 +1 @@
+<?php declare( strict_types=1 ); // Silence is golden.
diff --git a/packages/utilities/src/Scheduling/Errors/SchedulingError.php b/packages/utilities/src/Scheduling/Errors/SchedulingError.php
new file mode 100644
index 0000000..3330685
--- /dev/null
+++ b/packages/utilities/src/Scheduling/Errors/SchedulingError.php
@@ -0,0 +1,38 @@
+<?php declare( strict_types=1 );
+
+namespace DeepWebSolutions\Framework\Utilities\Scheduling\Errors;
+
+use DeepWebSolutions\Framework\Shared\Error\ErrorInterface;
+use DeepWebSolutions\Framework\Utilities\Scheduling\SchedulingErrorReason;
+
+/**
+ * Failure payload for a scheduling mutation, carried by a {@see \DeepWebSolutions\Framework\Shared\Result\Failure}.
+ *
+ * Pairs a machine-readable {@see SchedulingErrorReason} with a human-readable message
+ * and optional context (e.g. the offending interval, or a backend's own error text).
+ * The reason is the branch key; the message and context are for logging and display.
+ *
+ * @since   2.0.0
+ * @version 2.0.0
+ */
+final readonly class SchedulingError implements ErrorInterface {
+	// region MAGIC METHODS
+
+	/**
+	 * Constructor.
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 *
+	 * @param   SchedulingErrorReason $reason  Machine-readable cause of the failure.
+	 * @param   string                $message Human-readable description of the failure.
+	 * @param   array<string, mixed>  $context Optional structured detail about the failure.
+	 */
+	public function __construct(
+		public SchedulingErrorReason $reason,
+		public string $message,
+		public array $context = array(),
+	) {}
+
+	// endregion
+}
diff --git a/packages/utilities/src/Scheduling/Errors/index.php b/packages/utilities/src/Scheduling/Errors/index.php
new file mode 100644
index 0000000..f767346
--- /dev/null
+++ b/packages/utilities/src/Scheduling/Errors/index.php
@@ -0,0 +1 @@
+<?php declare( strict_types=1 ); // Silence is golden.
diff --git a/packages/utilities/src/Scheduling/Scheduler.php b/packages/utilities/src/Scheduling/Scheduler.php
new file mode 100644
index 0000000..2f4b3a9
--- /dev/null
+++ b/packages/utilities/src/Scheduling/Scheduler.php
@@ -0,0 +1,104 @@
+<?php declare( strict_types=1 );
+
+namespace DeepWebSolutions\Framework\Utilities\Scheduling;
+
+use DeepWebSolutions\Framework\Shared\Result\AbstractResult;
+
+/**
+ * Backend-agnostic scheduling facade.
+ *
+ * Delegates every call to the injected {@see SchedulerBackendInterface}, which targets
+ * either Action Scheduler or WordPress cron. Construct via {@see select_scheduler_backend()}
+ * to auto-select the backend, or inject a specific backend (or a test fake) directly.
+ * Components typehint this class — or the interface — and schedule through it.
+ *
+ * @since   2.0.0
+ * @version 2.0.0
+ */
+final class Scheduler implements SchedulerBackendInterface {
+	// region MAGIC METHODS
+
+	/**
+	 * Constructor.
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 *
+	 * @param   SchedulerBackendInterface $backend Backend that performs the scheduling.
+	 */
+	public function __construct(
+		private SchedulerBackendInterface $backend,
+	) {}
+
+	// endregion
+
+	// region INHERITED METHODS
+
+	/**
+	 * {@inheritDoc}
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 */
+	public function schedule_recurring( string $hook, int $interval, array $args = array(), ?int $first_run_timestamp = null, string $group = '' ): AbstractResult {
+		return $this->backend->schedule_recurring( $hook, $interval, $args, $first_run_timestamp, $group );
+	}
+
+	/**
+	 * {@inheritDoc}
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 */
+	public function schedule_single( string $hook, int $timestamp, array $args = array(), string $group = '' ): AbstractResult {
+		return $this->backend->schedule_single( $hook, $timestamp, $args, $group );
+	}
+
+	/**
+	 * {@inheritDoc}
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 */
+	public function unschedule( string $hook, array $args = array(), string $group = '' ): AbstractResult {
+		return $this->backend->unschedule( $hook, $args, $group );
+	}
+
+	/**
+	 * {@inheritDoc}
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 */
+	public function is_scheduled( string $hook, array $args = array(), string $group = '' ): bool {
+		return $this->backend->is_scheduled( $hook, $args, $group );
+	}
+
+	/**
+	 * {@inheritDoc}
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 */
+	public function get_next_scheduled( string $hook, array $args = array(), string $group = '' ): ?int {
+		return $this->backend->get_next_scheduled( $hook, $args, $group );
+	}
+
+	// endregion
+
+	// region GETTERS
+
+	/**
+	 * Returns the backend this facade delegates to.
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 *
+	 * @return  SchedulerBackendInterface
+	 */
+	public function get_backend(): SchedulerBackendInterface {
+		return $this->backend;
+	}
+
+	// endregion
+}
diff --git a/packages/utilities/src/Scheduling/SchedulerBackendInterface.php b/packages/utilities/src/Scheduling/SchedulerBackendInterface.php
new file mode 100644
index 0000000..11ba3db
--- /dev/null
+++ b/packages/utilities/src/Scheduling/SchedulerBackendInterface.php
@@ -0,0 +1,95 @@
+<?php declare( strict_types=1 );
+
+namespace DeepWebSolutions\Framework\Utilities\Scheduling;
+
+use DeepWebSolutions\Framework\Shared\Result\AbstractResult;
+use DeepWebSolutions\Framework\Shared\Result\Failure;
+use DeepWebSolutions\Framework\Shared\Result\Success;
+use DeepWebSolutions\Framework\Utilities\Scheduling\Errors\SchedulingError;
+
+/**
+ * Strategy for scheduling recurring and one-off actions.
+ *
+ * Implementations target a concrete scheduler — Action Scheduler when the plugin is
+ * active, WordPress cron otherwise. Mutations return a {@see AbstractResult} carrying a
+ * {@see SchedulingError} on failure; queries return plain scalars. Scheduling is
+ * idempotent: re-scheduling a hook that is already queued with the same args (and group)
+ * is a success no-op.
+ *
+ * @since   2.0.0
+ * @version 2.0.0
+ */
+interface SchedulerBackendInterface {
+	/**
+	 * Schedules a recurring action firing every $interval seconds.
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 *
+	 * @param   string      $hook                Hook to fire on each run.
+	 * @param   int         $interval            Seconds between runs; must be positive.
+	 * @param   list<mixed> $args                Arguments passed to the hook and used to identify the action.
+	 * @param   int|null    $first_run_timestamp Unix timestamp of the first run; null schedules from now.
+	 * @param   string      $group               Backend grouping label; not all backends support grouping.
+	 *
+	 * @return  Success<true>|Failure<SchedulingError> Success, or a failure carrying the cause.
+	 */
+	public function schedule_recurring( string $hook, int $interval, array $args = array(), ?int $first_run_timestamp = null, string $group = '' ): AbstractResult;
+
+	/**
+	 * Schedules a one-off action firing once at $timestamp.
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 *
+	 * @param   string      $hook      Hook to fire.
+	 * @param   int         $timestamp Unix timestamp at which to fire.
+	 * @param   list<mixed> $args      Arguments passed to the hook and used to identify the action.
+	 * @param   string      $group     Backend grouping label; not all backends support grouping.
+	 *
+	 * @return  Success<true>|Failure<SchedulingError> Success, or a failure carrying the cause.
+	 */
+	public function schedule_single( string $hook, int $timestamp, array $args = array(), string $group = '' ): AbstractResult;
+
+	/**
+	 * Cancels a scheduled action matching the hook, args, and group.
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 *
+	 * @param   string      $hook  Hook whose scheduled action to cancel.
+	 * @param   list<mixed> $args  Arguments the action was scheduled with.
+	 * @param   string      $group Backend grouping label the action was scheduled under.
+	 *
+	 * @return  Success<true>|Failure<SchedulingError> Success, or a failure carrying the cause.
+	 */
+	public function unschedule( string $hook, array $args = array(), string $group = '' ): AbstractResult;
+
+	/**
+	 * Whether an action is currently scheduled for the hook, args, and group.
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 *
+	 * @param   string      $hook  Hook to check.
+	 * @param   list<mixed> $args  Arguments the action was scheduled with.
+	 * @param   string      $group Backend grouping label the action was scheduled under.
+	 *
+	 * @return  bool
+	 */
+	public function is_scheduled( string $hook, array $args = array(), string $group = '' ): bool;
+
+	/**
+	 * Returns the Unix timestamp of the next scheduled run, or null when none is scheduled.
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 *
+	 * @param   string      $hook  Hook to check.
+	 * @param   list<mixed> $args  Arguments the action was scheduled with.
+	 * @param   string      $group Backend grouping label the action was scheduled under.
+	 *
+	 * @return  int|null
+	 */
+	public function get_next_scheduled( string $hook, array $args = array(), string $group = '' ): ?int;
+}
diff --git a/packages/utilities/src/Scheduling/SchedulingErrorReason.php b/packages/utilities/src/Scheduling/SchedulingErrorReason.php
new file mode 100644
index 0000000..5bd3834
--- /dev/null
+++ b/packages/utilities/src/Scheduling/SchedulingErrorReason.php
@@ -0,0 +1,21 @@
+<?php declare( strict_types=1 );
+
+namespace DeepWebSolutions\Framework\Utilities\Scheduling;
+
+/**
+ * Machine-readable reason a scheduling mutation failed.
+ *
+ * Carried by {@see SchedulingError} so a caller can branch on the cause without
+ * parsing the human message. The closed set covers every failure a backend can
+ * report: Action Scheduler absent, a grouping request a backend cannot honor,
+ * a non-positive interval, and a backend rejecting the schedule outright.
+ *
+ * @since   2.0.0
+ * @version 2.0.0
+ */
+enum SchedulingErrorReason: string {
+	case ActionSchedulerNotLoaded = 'action_scheduler_not_loaded';
+	case UnsupportedGroup         = 'unsupported_group';
+	case InvalidInterval          = 'invalid_interval';
+	case ScheduleFailed           = 'schedule_failed';
+}
diff --git a/packages/utilities/src/Scheduling/functions.php b/packages/utilities/src/Scheduling/functions.php
new file mode 100644
index 0000000..327555d
--- /dev/null
+++ b/packages/utilities/src/Scheduling/functions.php
@@ -0,0 +1,30 @@
+<?php declare( strict_types=1 );
+
+namespace DeepWebSolutions\Framework\Utilities\Scheduling;
+
+use DeepWebSolutions\Framework\Utilities\Scheduling\Backends\ActionSchedulerBackend;
+use DeepWebSolutions\Framework\Utilities\Scheduling\Backends\WPCronBackend;
+use Psr\Log\LoggerInterface;
+
+/**
+ * Selects the scheduler backend, preferring Action Scheduler when it is loaded.
+ *
+ * Returns an {@see ActionSchedulerBackend} when Action Scheduler's scheduling API is
+ * available, otherwise a {@see WPCronBackend}. The availability probe is injectable so
+ * both branches are testable without manipulating the global function table.
+ *
+ * @since   2.0.0
+ * @version 2.0.0
+ *
+ * @param   LoggerInterface|null $logger                  Optional PSR-3 logger passed to the chosen backend.
+ * @param   callable|null        $action_scheduler_probe  Predicate reporting whether Action Scheduler is available; defaults to a function_exists check.
+ *
+ * @return  SchedulerBackendInterface
+ */
+function select_scheduler_backend( ?LoggerInterface $logger = null, ?callable $action_scheduler_probe = null ): SchedulerBackendInterface {
+	$probe = $action_scheduler_probe ?? static fn (): bool => \function_exists( 'as_schedule_recurring_action' );
+
+	return $probe()
+		? new ActionSchedulerBackend( $logger )
+		: new WPCronBackend( $logger );
+}
diff --git a/packages/utilities/src/Scheduling/index.php b/packages/utilities/src/Scheduling/index.php
new file mode 100644
index 0000000..f767346
--- /dev/null
+++ b/packages/utilities/src/Scheduling/index.php
@@ -0,0 +1 @@
+<?php declare( strict_types=1 ); // Silence is golden.
diff --git a/packages/utilities/tests/Integration/Scheduling/Backends/ActionSchedulerBackendTest.php b/packages/utilities/tests/Integration/Scheduling/Backends/ActionSchedulerBackendTest.php
new file mode 100644
index 0000000..b88385f
--- /dev/null
+++ b/packages/utilities/tests/Integration/Scheduling/Backends/ActionSchedulerBackendTest.php
@@ -0,0 +1,131 @@
+<?php declare( strict_types=1 );
+
+namespace DeepWebSolutions\Framework\Utilities\Tests\Integration\Scheduling\Backends;
+
+use DeepWebSolutions\Framework\Shared\Result\Failure;
+use DeepWebSolutions\Framework\Shared\Result\Success;
+use DeepWebSolutions\Framework\Utilities\Scheduling\Backends\ActionSchedulerBackend;
+use DeepWebSolutions\Framework\Utilities\Scheduling\Errors\SchedulingError;
+use DeepWebSolutions\Framework\Utilities\Scheduling\SchedulingErrorReason;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\UsesClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass( ActionSchedulerBackend::class )]
+#[UsesClass( SchedulingError::class )]
+#[UsesClass( SchedulingErrorReason::class )]
+#[UsesClass( Success::class )]
+#[UsesClass( Failure::class )]
+final class ActionSchedulerBackendTest extends TestCase {
+	private const HOOK  = 'dws_test_as_hook';
+	private const GROUP = 'dws_test_as_group';
+
+	protected function setUp(): void {
+		parent::setUp();
+		if ( ! \function_exists( 'as_schedule_recurring_action' ) ) {
+			self::markTestSkipped( 'Action Scheduler is not loaded in this environment.' );
+		}
+		$this->clear_hook();
+	}
+
+	protected function tearDown(): void {
+		$this->clear_hook();
+		parent::tearDown();
+	}
+
+	public function test_schedule_recurring_is_idempotent_across_repeat_calls(): void {
+		$backend = new ActionSchedulerBackend();
+
+		$first  = $backend->schedule_recurring( self::HOOK, 300, array(), null, self::GROUP );
+		$second = $backend->schedule_recurring( self::HOOK, 300, array(), null, self::GROUP );
+
+		self::assertInstanceOf( Success::class, $first );
+		self::assertInstanceOf( Success::class, $second );
+		self::assertSame( 1, $this->count_pending( self::HOOK, self::GROUP ) );
+	}
+
+	public function test_schedule_single_is_idempotent_across_repeat_calls(): void {
+		$backend = new ActionSchedulerBackend();
+
+		$first  = $backend->schedule_single( self::HOOK, \time() + 3600, array(), self::GROUP );
+		$second = $backend->schedule_single( self::HOOK, \time() + 3600, array(), self::GROUP );
+
+		self::assertInstanceOf( Success::class, $first );
+		self::assertInstanceOf( Success::class, $second );
+		self::assertSame( 1, $this->count_pending( self::HOOK, self::GROUP ) );
+	}
+
+	public function test_is_scheduled_reflects_a_scheduled_action(): void {
+		$backend = new ActionSchedulerBackend();
+
+		self::assertFalse( $backend->is_scheduled( self::HOOK, array(), self::GROUP ) );
+
+		$backend->schedule_single( self::HOOK, \time() + 3600, array(), self::GROUP );
+
+		self::assertTrue( $backend->is_scheduled( self::HOOK, array(), self::GROUP ) );
+	}
+
+	public function test_get_next_scheduled_returns_the_pending_timestamp(): void {
+		$backend   = new ActionSchedulerBackend();
+		$timestamp = \time() + 3600;
+
+		self::assertNull( $backend->get_next_scheduled( self::HOOK, array(), self::GROUP ) );
+
+		$backend->schedule_single( self::HOOK, $timestamp, array(), self::GROUP );
+
+		self::assertSame( $timestamp, $backend->get_next_scheduled( self::HOOK, array(), self::GROUP ) );
+	}
+
+	public function test_unschedule_cancels_a_scheduled_action(): void {
+		$backend = new ActionSchedulerBackend();
+		$backend->schedule_single( self::HOOK, \time() + 3600, array(), self::GROUP );
+
+		$result = $backend->unschedule( self::HOOK, array(), self::GROUP );
+
+		self::assertInstanceOf( Success::class, $result );
+		self::assertFalse( $backend->is_scheduled( self::HOOK, array(), self::GROUP ) );
+	}
+
+	public function test_args_distinguish_two_concurrent_actions(): void {
+		$backend = new ActionSchedulerBackend();
+
+		$backend->schedule_single( self::HOOK, \time() + 3600, array( 'a' ), self::GROUP );
+		$backend->schedule_single( self::HOOK, \time() + 3600, array( 'b' ), self::GROUP );
+
+		self::assertSame( 2, $this->count_pending( self::HOOK, self::GROUP ) );
+	}
+
+	/**
+	 * Cancels every action for the test hook, regardless of args or group.
+	 *
+	 * Passing an empty group takes Action Scheduler's cancel_actions_by_hook() fast path,
+	 * which clears all args — unlike the hook+group form, which only matches empty args.
+	 *
+	 * @return  void
+	 */
+	private function clear_hook(): void {
+		\as_unschedule_all_actions( self::HOOK );
+	}
+
+	/**
+	 * Counts pending Action Scheduler actions for a hook and group.
+	 *
+	 * @param   string $hook  Hook to count.
+	 * @param   string $group Group to count within.
+	 *
+	 * @return  int
+	 */
+	private function count_pending( string $hook, string $group ): int {
+		return \count(
+			\as_get_scheduled_actions(
+				array(
+					'hook'     => $hook,
+					'group'    => $group,
+					'status'   => \ActionScheduler_Store::STATUS_PENDING,
+					'per_page' => -1,
+				),
+				'ids',
+			),
+		);
+	}
+}
diff --git a/packages/utilities/tests/Integration/Scheduling/Backends/WPCronBackendTest.php b/packages/utilities/tests/Integration/Scheduling/Backends/WPCronBackendTest.php
new file mode 100644
index 0000000..03c1c76
--- /dev/null
+++ b/packages/utilities/tests/Integration/Scheduling/Backends/WPCronBackendTest.php
@@ -0,0 +1,167 @@
+<?php declare( strict_types=1 );
+
+namespace DeepWebSolutions\Framework\Utilities\Tests\Integration\Scheduling\Backends;
+
+use DeepWebSolutions\Framework\Shared\Result\Failure;
+use DeepWebSolutions\Framework\Shared\Result\Success;
+use DeepWebSolutions\Framework\Utilities\Scheduling\Backends\WPCronBackend;
+use DeepWebSolutions\Framework\Utilities\Scheduling\Errors\SchedulingError;
+use DeepWebSolutions\Framework\Utilities\Scheduling\SchedulingErrorReason;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\UsesClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass( WPCronBackend::class )]
+#[UsesClass( SchedulingError::class )]
+#[UsesClass( SchedulingErrorReason::class )]
+#[UsesClass( Success::class )]
+#[UsesClass( Failure::class )]
+final class WPCronBackendTest extends TestCase {
+	private const HOOK = 'dws_test_wpcron_hook';
+
+	/**
+	 * @var list<WPCronBackend>
+	 */
+	private array $backends = array();
+
+	protected function setUp(): void {
+		parent::setUp();
+		// wp_unschedule_hook clears every event for the hook regardless of args; wp_clear_scheduled_hook
+		// only matches the exact args passed, so arg'd events from other tests would leak.
+		\wp_unschedule_hook( self::HOOK );
+	}
+
+	protected function tearDown(): void {
+		\wp_unschedule_hook( self::HOOK );
+		// Each backend wired its own stable filter callback; drop them so schedules do not leak between tests.
+		foreach ( $this->backends as $backend ) {
+			\remove_filter( 'cron_schedules', array( $backend, 'register_synthetic_schedules' ) );
+		}
+		$this->backends = array();
+		parent::tearDown();
+	}
+
+	public function test_schedule_recurring_is_idempotent_across_repeat_calls(): void {
+		$backend = $this->backend();
+
+		$first  = $backend->schedule_recurring( self::HOOK, 900 );
+		$second = $backend->schedule_recurring( self::HOOK, 900 );
+
+		self::assertInstanceOf( Success::class, $first );
+		self::assertInstanceOf( Success::class, $second );
+		self::assertSame( 1, $this->count_events( self::HOOK ) );
+	}
+
+	public function test_schedule_single_is_idempotent_across_repeat_calls(): void {
+		$backend   = $this->backend();
+		$timestamp = \time() + 3600;
+
+		$first  = $backend->schedule_single( self::HOOK, $timestamp );
+		$second = $backend->schedule_single( self::HOOK, $timestamp );
+
+		self::assertInstanceOf( Success::class, $first );
+		self::assertInstanceOf( Success::class, $second );
+		self::assertSame( 1, $this->count_events( self::HOOK ) );
+	}
+
+	public function test_is_scheduled_and_get_next_scheduled_reflect_a_single_event(): void {
+		$backend   = $this->backend();
+		$timestamp = \time() + 3600;
+
+		self::assertFalse( $backend->is_scheduled( self::HOOK ) );
+		self::assertNull( $backend->get_next_scheduled( self::HOOK ) );
+
+		$backend->schedule_single( self::HOOK, $timestamp );
+
+		self::assertTrue( $backend->is_scheduled( self::HOOK ) );
+		self::assertSame( $timestamp, $backend->get_next_scheduled( self::HOOK ) );
+	}
+
+	public function test_unschedule_clears_a_scheduled_event(): void {
+		$backend = $this->backend();
+		$backend->schedule_single( self::HOOK, \time() + 3600 );
+
+		$result = $backend->unschedule( self::HOOK );
+
+		self::assertInstanceOf( Success::class, $result );
+		self::assertFalse( $backend->is_scheduled( self::HOOK ) );
+	}
+
+	public function test_recurring_registers_a_synthetic_named_schedule(): void {
+		$backend = $this->backend();
+
+		$backend->schedule_recurring( self::HOOK, 900 );
+
+		$schedules = \wp_get_schedules();
+		self::assertArrayHasKey( 'dws_every_900s', $schedules );
+		self::assertSame( 900, $schedules['dws_every_900s']['interval'] );
+	}
+
+	public function test_args_distinguish_two_concurrent_recurring_events(): void {
+		$backend = $this->backend();
+
+		$backend->schedule_recurring( self::HOOK, 900, array( 'a' ) );
+		$backend->schedule_recurring( self::HOOK, 900, array( 'b' ) );
+
+		self::assertTrue( $backend->is_scheduled( self::HOOK, array( 'a' ) ) );
+		self::assertTrue( $backend->is_scheduled( self::HOOK, array( 'b' ) ) );
+		self::assertSame( 2, $this->count_events( self::HOOK ) );
+	}
+
+	public function test_schedule_recurring_rejects_a_non_empty_group(): void {
+		$result = $this->backend()->schedule_recurring( self::HOOK, 900, array(), null, 'reports' );
+
+		self::assertInstanceOf( Failure::class, $result );
+		self::assertInstanceOf( SchedulingError::class, $result->error );
+		self::assertSame( SchedulingErrorReason::UnsupportedGroup, $result->error->reason );
+		self::assertFalse( $this->backend()->is_scheduled( self::HOOK ) );
+	}
+
+	public function test_schedule_single_rejects_a_non_empty_group(): void {
+		$result = $this->backend()->schedule_single( self::HOOK, \time() + 3600, array(), 'reports' );
+
+		self::assertInstanceOf( Failure::class, $result );
+		self::assertInstanceOf( SchedulingError::class, $result->error );
+		self::assertSame( SchedulingErrorReason::UnsupportedGroup, $result->error->reason );
+	}
+
+	public function test_unschedule_rejects_a_non_empty_group(): void {
+		$result = $this->backend()->unschedule( self::HOOK, array(), 'reports' );
+
+		self::assertInstanceOf( Failure::class, $result );
+		self::assertInstanceOf( SchedulingError::class, $result->error );
+		self::assertSame( SchedulingErrorReason::UnsupportedGroup, $result->error->reason );
+	}
+
+	public function test_schedule_recurring_rejects_a_non_positive_interval(): void {
+		$result = $this->backend()->schedule_recurring( self::HOOK, 0 );
+
+		self::assertInstanceOf( Failure::class, $result );
+		self::assertInstanceOf( SchedulingError::class, $result->error );
+		self::assertSame( SchedulingErrorReason::InvalidInterval, $result->error->reason );
+	}
+
+	private function backend(): WPCronBackend {
+		$backend          = new WPCronBackend();
+		$this->backends[] = $backend;
+		return $backend;
+	}
+
+	/**
+	 * Counts how many distinct scheduled events exist for a hook across the cron option.
+	 *
+	 * @param   string $hook Hook to count events for.
+	 *
+	 * @return  int
+	 */
+	private function count_events( string $hook ): int {
+		$count = 0;
+		foreach ( \_get_cron_array() as $events ) {
+			if ( isset( $events[ $hook ] ) ) {
+				$count += \count( $events[ $hook ] );
+			}
+		}
+
+		return $count;
+	}
+}
diff --git a/packages/utilities/tests/Integration/Scheduling/Backends/index.php b/packages/utilities/tests/Integration/Scheduling/Backends/index.php
new file mode 100644
index 0000000..f767346
--- /dev/null
+++ b/packages/utilities/tests/Integration/Scheduling/Backends/index.php
@@ -0,0 +1 @@
+<?php declare( strict_types=1 ); // Silence is golden.
diff --git a/packages/utilities/tests/Integration/Scheduling/index.php b/packages/utilities/tests/Integration/Scheduling/index.php
new file mode 100644
index 0000000..f767346
--- /dev/null
+++ b/packages/utilities/tests/Integration/Scheduling/index.php
@@ -0,0 +1 @@
+<?php declare( strict_types=1 ); // Silence is golden.
diff --git a/packages/utilities/tests/Unit/Scheduling/Backends/ActionSchedulerBackendTest.php b/packages/utilities/tests/Unit/Scheduling/Backends/ActionSchedulerBackendTest.php
new file mode 100644
index 0000000..cd8b5ea
--- /dev/null
+++ b/packages/utilities/tests/Unit/Scheduling/Backends/ActionSchedulerBackendTest.php
@@ -0,0 +1,68 @@
+<?php declare( strict_types=1 );
+
+namespace DeepWebSolutions\Framework\Utilities\Tests\Unit\Scheduling\Backends;
+
+use DeepWebSolutions\Framework\Shared\Result\Failure;
+use DeepWebSolutions\Framework\Utilities\Scheduling\Backends\ActionSchedulerBackend;
+use DeepWebSolutions\Framework\Utilities\Scheduling\Errors\SchedulingError;
+use DeepWebSolutions\Framework\Utilities\Scheduling\SchedulingErrorReason;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\UsesClass;
+use PHPUnit\Framework\TestCase;
+use Psr\Log\LoggerInterface;
+
+/**
+ * Action Scheduler is absent in the unit context, so every mutation reports the
+ * not-loaded failure and every query degrades safely. The live as_* behaviour is
+ * exercised in the integration suite.
+ */
+#[CoversClass( ActionSchedulerBackend::class )]
+#[UsesClass( SchedulingError::class )]
+#[UsesClass( SchedulingErrorReason::class )]
+#[UsesClass( Failure::class )]
+final class ActionSchedulerBackendTest extends TestCase {
+	protected function setUp(): void {
+		parent::setUp();
+		if ( \function_exists( 'as_schedule_recurring_action' ) ) {
+			self::markTestSkipped( 'Action Scheduler is loaded; the not-loaded path is unobservable.' );
+		}
+	}
+
+	public function test_schedule_recurring_fails_when_action_scheduler_absent(): void {
+		$result = ( new ActionSchedulerBackend() )->schedule_recurring( 'dws_hook', 300 );
+
+		self::assertInstanceOf( Failure::class, $result );
+		self::assertInstanceOf( SchedulingError::class, $result->error );
+		self::assertSame( SchedulingErrorReason::ActionSchedulerNotLoaded, $result->error->reason );
+	}
+
+	public function test_schedule_single_fails_when_action_scheduler_absent(): void {
+		$result = ( new ActionSchedulerBackend() )->schedule_single( 'dws_hook', 1700000000 );
+
+		self::assertInstanceOf( Failure::class, $result );
+		self::assertInstanceOf( SchedulingError::class, $result->error );
+		self::assertSame( SchedulingErrorReason::ActionSchedulerNotLoaded, $result->error->reason );
+	}
+
+	public function test_unschedule_fails_when_action_scheduler_absent(): void {
+		$result = ( new ActionSchedulerBackend() )->unschedule( 'dws_hook' );
+
+		self::assertInstanceOf( Failure::class, $result );
+		self::assertInstanceOf( SchedulingError::class, $result->error );
+		self::assertSame( SchedulingErrorReason::ActionSchedulerNotLoaded, $result->error->reason );
+	}
+
+	public function test_queries_degrade_safely_when_action_scheduler_absent(): void {
+		$backend = new ActionSchedulerBackend();
+
+		self::assertFalse( $backend->is_scheduled( 'dws_hook' ) );
+		self::assertNull( $backend->get_next_scheduled( 'dws_hook' ) );
+	}
+
+	public function test_logs_the_not_loaded_condition_when_a_logger_is_given(): void {
+		$logger = $this->createMock( LoggerInterface::class );
+		$logger->expects( self::once() )->method( 'error' );
+
+		( new ActionSchedulerBackend( $logger ) )->schedule_recurring( 'dws_hook', 300 );
+	}
+}
diff --git a/packages/utilities/tests/Unit/Scheduling/Backends/index.php b/packages/utilities/tests/Unit/Scheduling/Backends/index.php
new file mode 100644
index 0000000..f767346
--- /dev/null
+++ b/packages/utilities/tests/Unit/Scheduling/Backends/index.php
@@ -0,0 +1 @@
+<?php declare( strict_types=1 ); // Silence is golden.
diff --git a/packages/utilities/tests/Unit/Scheduling/Errors/SchedulingErrorTest.php b/packages/utilities/tests/Unit/Scheduling/Errors/SchedulingErrorTest.php
new file mode 100644
index 0000000..caedc89
--- /dev/null
+++ b/packages/utilities/tests/Unit/Scheduling/Errors/SchedulingErrorTest.php
@@ -0,0 +1,38 @@
+<?php declare( strict_types=1 );
+
+namespace DeepWebSolutions\Framework\Utilities\Tests\Unit\Scheduling\Errors;
+
+use DeepWebSolutions\Framework\Shared\Error\ErrorInterface;
+use DeepWebSolutions\Framework\Utilities\Scheduling\Errors\SchedulingError;
+use DeepWebSolutions\Framework\Utilities\Scheduling\SchedulingErrorReason;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\UsesClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass( SchedulingError::class )]
+#[UsesClass( SchedulingErrorReason::class )]
+final class SchedulingErrorTest extends TestCase {
+	public function test_is_an_error_interface(): void {
+		$error = new SchedulingError( SchedulingErrorReason::ScheduleFailed, 'boom' );
+
+		self::assertInstanceOf( ErrorInterface::class, $error );
+	}
+
+	public function test_exposes_reason_message_and_default_empty_context(): void {
+		$error = new SchedulingError( SchedulingErrorReason::InvalidInterval, 'Interval must be positive.' );
+
+		self::assertSame( SchedulingErrorReason::InvalidInterval, $error->reason );
+		self::assertSame( 'Interval must be positive.', $error->message );
+		self::assertSame( array(), $error->context );
+	}
+
+	public function test_carries_supplied_context(): void {
+		$error = new SchedulingError(
+			SchedulingErrorReason::UnsupportedGroup,
+			'No groups.',
+			array( 'group' => 'reports' ),
+		);
+
+		self::assertSame( array( 'group' => 'reports' ), $error->context );
+	}
+}
diff --git a/packages/utilities/tests/Unit/Scheduling/Errors/index.php b/packages/utilities/tests/Unit/Scheduling/Errors/index.php
new file mode 100644
index 0000000..f767346
--- /dev/null
+++ b/packages/utilities/tests/Unit/Scheduling/Errors/index.php
@@ -0,0 +1 @@
+<?php declare( strict_types=1 ); // Silence is golden.
diff --git a/packages/utilities/tests/Unit/Scheduling/SchedulerTest.php b/packages/utilities/tests/Unit/Scheduling/SchedulerTest.php
new file mode 100644
index 0000000..0700acb
--- /dev/null
+++ b/packages/utilities/tests/Unit/Scheduling/SchedulerTest.php
@@ -0,0 +1,143 @@
+<?php declare( strict_types=1 );
+
+namespace DeepWebSolutions\Framework\Utilities\Tests\Unit\Scheduling;
+
+use DeepWebSolutions\Framework\Shared\Result\AbstractResult;
+use DeepWebSolutions\Framework\Shared\Result\Success;
+use DeepWebSolutions\Framework\Utilities\Scheduling\Scheduler;
+use DeepWebSolutions\Framework\Utilities\Scheduling\SchedulerBackendInterface;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass( Scheduler::class )]
+final class SchedulerTest extends TestCase {
+	public function test_get_backend_returns_the_injected_backend(): void {
+		$backend = $this->recording_backend();
+
+		self::assertSame( $backend, ( new Scheduler( $backend ) )->get_backend() );
+	}
+
+	public function test_schedule_recurring_delegates_with_all_arguments(): void {
+		$backend   = $this->recording_backend();
+		$scheduler = new Scheduler( $backend );
+
+		$result = $scheduler->schedule_recurring( 'dws_hook', 300, array( 1, 'a' ), 1700000000, 'grp' );
+
+		self::assertSame(
+			array( array( 'schedule_recurring', 'dws_hook', 300, array( 1, 'a' ), 1700000000, 'grp' ) ),
+			$backend->calls,
+		);
+		self::assertSame( $backend->next_result, $result );
+	}
+
+	public function test_schedule_recurring_delegates_with_defaults(): void {
+		$backend   = $this->recording_backend();
+		$scheduler = new Scheduler( $backend );
+
+		$scheduler->schedule_recurring( 'dws_hook', 300 );
+
+		self::assertSame(
+			array( array( 'schedule_recurring', 'dws_hook', 300, array(), null, '' ) ),
+			$backend->calls,
+		);
+	}
+
+	public function test_schedule_single_delegates_with_all_arguments(): void {
+		$backend   = $this->recording_backend();
+		$scheduler = new Scheduler( $backend );
+
+		$result = $scheduler->schedule_single( 'dws_hook', 1700000000, array( 'x' ), 'grp' );
+
+		self::assertSame(
+			array( array( 'schedule_single', 'dws_hook', 1700000000, array( 'x' ), 'grp' ) ),
+			$backend->calls,
+		);
+		self::assertSame( $backend->next_result, $result );
+	}
+
+	public function test_unschedule_delegates_with_all_arguments(): void {
+		$backend   = $this->recording_backend();
+		$scheduler = new Scheduler( $backend );
+
+		$result = $scheduler->unschedule( 'dws_hook', array( 'x' ), 'grp' );
+
+		self::assertSame(
+			array( array( 'unschedule', 'dws_hook', array( 'x' ), 'grp' ) ),
+			$backend->calls,
+		);
+		self::assertSame( $backend->next_result, $result );
+	}
+
+	public function test_is_scheduled_delegates_and_returns_the_backend_value(): void {
+		$backend   = $this->recording_backend( true );
+		$scheduler = new Scheduler( $backend );
+
+		self::assertTrue( $scheduler->is_scheduled( 'dws_hook', array( 'x' ), 'grp' ) );
+		self::assertSame(
+			array( array( 'is_scheduled', 'dws_hook', array( 'x' ), 'grp' ) ),
+			$backend->calls,
+		);
+	}
+
+	public function test_get_next_scheduled_delegates_and_returns_the_backend_value(): void {
+		$backend   = $this->recording_backend( false, 1700000000 );
+		$scheduler = new Scheduler( $backend );
+
+		self::assertSame( 1700000000, $scheduler->get_next_scheduled( 'dws_hook', array( 'x' ), 'grp' ) );
+		self::assertSame(
+			array( array( 'get_next_scheduled', 'dws_hook', array( 'x' ), 'grp' ) ),
+			$backend->calls,
+		);
+	}
+
+	/**
+	 * @param   bool     $next_bool Value the fake returns from is_scheduled().
+	 * @param   int|null $next_int  Value the fake returns from get_next_scheduled().
+	 *
+	 * @return SchedulerBackendInterface&object{calls: list<array<int, mixed>>, next_result: Success<true>}
+	 */
+	private function recording_backend( bool $next_bool = false, ?int $next_int = null ): SchedulerBackendInterface {
+		return new class( $next_bool, $next_int ) implements SchedulerBackendInterface {
+			/** @var list<array<int, mixed>> */
+			public array $calls = array();
+
+			/** @var Success<true> */
+			public readonly Success $next_result;
+
+			public function __construct(
+				private readonly bool $next_bool,
+				private readonly ?int $next_int,
+			) {
+				$this->next_result = Success::from( true );
+			}
+
+			/** @return Success<true> */
+			public function schedule_recurring( string $hook, int $interval, array $args = array(), ?int $first_run_timestamp = null, string $group = '' ): AbstractResult {
+				$this->calls[] = array( 'schedule_recurring', $hook, $interval, $args, $first_run_timestamp, $group );
+				return $this->next_result;
+			}
+
+			/** @return Success<true> */
+			public function schedule_single( string $hook, int $timestamp, array $args = array(), string $group = '' ): AbstractResult {
+				$this->calls[] = array( 'schedule_single', $hook, $timestamp, $args, $group );
+				return $this->next_result;
+			}
+
+			/** @return Success<true> */
+			public function unschedule( string $hook, array $args = array(), string $group = '' ): AbstractResult {
+				$this->calls[] = array( 'unschedule', $hook, $args, $group );
+				return $this->next_result;
+			}
+
+			public function is_scheduled( string $hook, array $args = array(), string $group = '' ): bool {
+				$this->calls[] = array( 'is_scheduled', $hook, $args, $group );
+				return $this->next_bool;
+			}
+
+			public function get_next_scheduled( string $hook, array $args = array(), string $group = '' ): ?int {
+				$this->calls[] = array( 'get_next_scheduled', $hook, $args, $group );
+				return $this->next_int;
+			}
+		};
+	}
+}
diff --git a/packages/utilities/tests/Unit/Scheduling/SchedulingErrorReasonTest.php b/packages/utilities/tests/Unit/Scheduling/SchedulingErrorReasonTest.php
new file mode 100644
index 0000000..a0ec689
--- /dev/null
+++ b/packages/utilities/tests/Unit/Scheduling/SchedulingErrorReasonTest.php
@@ -0,0 +1,24 @@
+<?php declare( strict_types=1 );
+
+namespace DeepWebSolutions\Framework\Utilities\Tests\Unit\Scheduling;
+
+use DeepWebSolutions\Framework\Utilities\Scheduling\SchedulingErrorReason;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass( SchedulingErrorReason::class )]
+final class SchedulingErrorReasonTest extends TestCase {
+	public function test_backing_values_are_stable(): void {
+		self::assertSame( 'action_scheduler_not_loaded', SchedulingErrorReason::ActionSchedulerNotLoaded->value );
+		self::assertSame( 'unsupported_group', SchedulingErrorReason::UnsupportedGroup->value );
+		self::assertSame( 'invalid_interval', SchedulingErrorReason::InvalidInterval->value );
+		self::assertSame( 'schedule_failed', SchedulingErrorReason::ScheduleFailed->value );
+	}
+
+	public function test_holds_exactly_the_expected_cases(): void {
+		self::assertSame(
+			array( 'ActionSchedulerNotLoaded', 'UnsupportedGroup', 'InvalidInterval', 'ScheduleFailed' ),
+			\array_map( static fn ( SchedulingErrorReason $case ): string => $case->name, SchedulingErrorReason::cases() ),
+		);
+	}
+}
diff --git a/packages/utilities/tests/Unit/Scheduling/SelectSchedulerBackendTest.php b/packages/utilities/tests/Unit/Scheduling/SelectSchedulerBackendTest.php
new file mode 100644
index 0000000..1d7cd06
--- /dev/null
+++ b/packages/utilities/tests/Unit/Scheduling/SelectSchedulerBackendTest.php
@@ -0,0 +1,25 @@
+<?php declare( strict_types=1 );
+
+namespace DeepWebSolutions\Framework\Utilities\Tests\Unit\Scheduling;
+
+use DeepWebSolutions\Framework\Utilities\Scheduling\Backends\ActionSchedulerBackend;
+use DeepWebSolutions\Framework\Utilities\Scheduling\Backends\WPCronBackend;
+use PHPUnit\Framework\Attributes\CoversFunction;
+use PHPUnit\Framework\TestCase;
+
+use function DeepWebSolutions\Framework\Utilities\Scheduling\select_scheduler_backend;
+
+#[CoversFunction( 'DeepWebSolutions\Framework\Utilities\Scheduling\select_scheduler_backend' )]
+final class SelectSchedulerBackendTest extends TestCase {
+	public function test_selects_action_scheduler_when_probe_reports_available(): void {
+		$backend = select_scheduler_backend( null, static fn (): bool => true );
+
+		self::assertInstanceOf( ActionSchedulerBackend::class, $backend );
+	}
+
+	public function test_selects_wp_cron_when_probe_reports_unavailable(): void {
+		$backend = select_scheduler_backend( null, static fn (): bool => false );
+
+		self::assertInstanceOf( WPCronBackend::class, $backend );
+	}
+}
diff --git a/packages/utilities/tests/Unit/Scheduling/index.php b/packages/utilities/tests/Unit/Scheduling/index.php
new file mode 100644
index 0000000..f767346
--- /dev/null
+++ b/packages/utilities/tests/Unit/Scheduling/index.php
@@ -0,0 +1 @@
+<?php declare( strict_types=1 ); // Silence is golden.
diff --git a/phpstan.dist.neon b/phpstan.dist.neon
index d964cf8..117d2b9 100644
--- a/phpstan.dist.neon
+++ b/phpstan.dist.neon
@@ -4,8 +4,11 @@ includes:
 parameters:
     # WooCommerce symbols (OrderUtil, WC_Order, wc_get_order) used by the woocommerce
     # package's order-field store and settings page; the shared config only wires the WordPress stubs.
+    # The packages-stubs file additionally defines the Action Scheduler as_* functions the
+    # utilities scheduling backend calls (woocommerce-stubs.php does not).
     bootstrapFiles:
         - vendor/php-stubs/woocommerce-stubs/woocommerce-stubs.php
+        - vendor/php-stubs/woocommerce-stubs/woocommerce-packages-stubs.php
     # PHPStan does not expand globs in `paths`; each package is enumerated literally.
     paths:
         - packages/bootstrap/functions.php

From cdef4cea8338532b0fdf7cad3bd54b51ab5a429d Mon Sep 17 00:00:00 2001
From: Tony Hegyes <a.hegyes@proton.me>
Date: Mon, 22 Jun 2026 12:59:08 +0200
Subject: [PATCH 09/21] fix(utilities,settings): address Codex validation
 findings on the seam + scheduler
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A cold Codex review of this session's #14 (custom field-type seam) and #13
(scheduler) surfaced three real issues. (Two louder findings were verified
non-issues: WP-Cron does NOT lose its synthetic schedule — wp_reschedule_event
falls back to the interval stored in the event — and the scoping-stubs colon
form is the already-flagged cross-repo dependency.)

- FieldProcessor::process_custom coerces a non-scalar custom submission to the
  field default before the sanitizer runs, mirroring the built-in scalar guard.
  A tampered field[]=x to a scalar custom field with e.g. trim no longer fatals
  with a TypeError on save.
- WPCronBackend::unschedule maps wp_clear_scheduled_hook's return instead of
  always returning Success: a WP_Error becomes Failure(ScheduleFailed) with the
  message preserved in context; an int count (including zero) stays Success —
  parity with the Action Scheduler backend's fail-loud mapping.
- WPCronBackend::is_scheduled / get_next_scheduled return false / null for a
  non-empty group. A grouped schedule can never exist on WP-Cron (mutations
  already reject one), so the queries are consistent rather than group-blind.

Gates: PHPStan clean, deptrac 0, Unit 417, Integration 303.

Assisted-by: Claude Code:claude-opus-4-8
---
 .../settings/src/Schema/FieldProcessor.php    | 17 +++++--
 .../tests/Unit/FieldProcessorTest.php         | 11 +++++
 .../src/Scheduling/Backends/WPCronBackend.php | 49 +++++++++++++++++--
 .../Scheduling/Backends/WPCronBackendTest.php | 38 ++++++++++++++
 4 files changed, 108 insertions(+), 7 deletions(-)

diff --git a/packages/settings/src/Schema/FieldProcessor.php b/packages/settings/src/Schema/FieldProcessor.php
index fec4b30..6648044 100644
--- a/packages/settings/src/Schema/FieldProcessor.php
+++ b/packages/settings/src/Schema/FieldProcessor.php
@@ -17,7 +17,8 @@
  * value any step rejects falls back to the empty value. A type outside the
  * taxonomy but present in the injected custom-type registry is processed as a
  * plain scalar through the field's own sanitize/validate, falling back to the
- * field's default; a type in neither still throws.
+ * field's default (a non-scalar submission is coerced to the default before the
+ * sanitizer runs, mirroring the built-in scalar guard); a type in neither still throws.
  *
  * @since   2.0.0
  * @version 2.0.0
@@ -104,8 +105,8 @@ public function process( SettingsField $field, array $input ): mixed {
 	// region HELPERS
 
 	/**
-	 * Processes a custom-typed field as a plain scalar: an absent submission yields the field's default, a
-	 * present one runs the field's own sanitize then validate, falling back to the default when validation rejects.
+	 * Processes a custom-typed field as a plain scalar: an absent or non-scalar submission yields the field's
+	 * default, a present scalar runs the field's own sanitize then validate, falling back to the default when validation rejects.
 	 *
 	 * @since   2.0.0
 	 * @version 2.0.0
@@ -120,7 +121,15 @@ private function process_custom( SettingsField $field, array $input ): mixed {
 			return $field->default;
 		}
 
-		return $this->sanitize_and_validate( $field, $input[ $field->id ], $field->default );
+		$value = $input[ $field->id ];
+
+		// A custom type is treated as scalar: a tampered array submission would fatal a scalar sanitizer
+		// (e.g. trim), so coerce a non-scalar to the field's default — mirroring the built-in scalar guard.
+		if ( ! \is_scalar( $value ) ) {
+			return $field->default;
+		}
+
+		return $this->sanitize_and_validate( $field, $value, $field->default );
 	}
 
 	/**
diff --git a/packages/settings/tests/Unit/FieldProcessorTest.php b/packages/settings/tests/Unit/FieldProcessorTest.php
index 60eb165..f1dfabb 100644
--- a/packages/settings/tests/Unit/FieldProcessorTest.php
+++ b/packages/settings/tests/Unit/FieldProcessorTest.php
@@ -85,6 +85,17 @@ public function test_a_registered_custom_type_applies_sanitize_before_validate()
 		self::assertSame( '#abc', $processor->process( $field, array( 'shade' => '  #abc  ' ) ) );
 	}
 
+	public function test_a_registered_custom_type_with_a_non_scalar_submission_returns_the_default(): void {
+		// A tampered array submission (shade[]=x) to a scalar custom field whose sanitize is a scalar callable
+		// (trim) must coerce to the default, not fatal the sanitizer with a TypeError.
+		$processor = new FieldProcessor(
+			custom_types: array( 'color_picker' => $this->custom_type( 'color_picker' ) ),
+		);
+		$field     = new SettingsField( id: 'shade', type: 'color_picker', label: 'Shade', default: '#000', sanitize: 'trim' );
+
+		self::assertSame( '#000', $processor->process( $field, array( 'shade' => array( 'x' ) ) ) );
+	}
+
 	private function custom_type( string $type ): CustomFieldType {
 		return new CustomFieldType(
 			type: $type,
diff --git a/packages/utilities/src/Scheduling/Backends/WPCronBackend.php b/packages/utilities/src/Scheduling/Backends/WPCronBackend.php
index d832642..4d1511f 100644
--- a/packages/utilities/src/Scheduling/Backends/WPCronBackend.php
+++ b/packages/utilities/src/Scheduling/Backends/WPCronBackend.php
@@ -20,7 +20,7 @@
  * exactly once (WordPress cannot de-duplicate fresh closures, so a stable reference and a
  * one-time guard are both required); it reads an internal interval registry, so later
  * intervals are covered without re-adding the filter. WordPress cron has no grouping, so a
- * non-empty group is rejected on every mutation.
+ * non-empty group is rejected on every mutation and treated as never-scheduled by every query.
  *
  * @since   2.0.0
  * @version 2.0.0
@@ -138,8 +138,8 @@ public function unschedule( string $hook, array $args = array(), string $group =
 			return $rejection;
 		}
 
-		\wp_clear_scheduled_hook( $hook, $args, true );
-		return Success::from( true );
+		$cleared = \wp_clear_scheduled_hook( $hook, $args, true );
+		return $this->result_for_unschedule( $cleared, $hook );
 	}
 
 	/**
@@ -149,6 +149,11 @@ public function unschedule( string $hook, array $args = array(), string $group =
 	 * @version 2.0.0
 	 */
 	public function is_scheduled( string $hook, array $args = array(), string $group = '' ): bool {
+		// A grouped schedule can never exist on WP-Cron, so a query naming a group is consistently false.
+		if ( '' !== $group ) {
+			return false;
+		}
+
 		return false !== \wp_next_scheduled( $hook, $args );
 	}
 
@@ -159,6 +164,11 @@ public function is_scheduled( string $hook, array $args = array(), string $group
 	 * @version 2.0.0
 	 */
 	public function get_next_scheduled( string $hook, array $args = array(), string $group = '' ): ?int {
+		// A grouped schedule can never exist on WP-Cron, so a query naming a group has no next run.
+		if ( '' !== $group ) {
+			return null;
+		}
+
 		$next = \wp_next_scheduled( $hook, $args );
 		return \is_int( $next ) ? $next : null;
 	}
@@ -286,5 +296,38 @@ private function result_for_schedule( bool|WP_Error $scheduled, string $hook ):
 		);
 	}
 
+	/**
+	 * Maps a WordPress cron clear return to a result — an int count is a success, a WP_Error (or any non-int) a failure.
+	 *
+	 * With $wp_error = true, wp_clear_scheduled_hook returns the count of unscheduled events (zero when none
+	 * matched) on success, or a WP_Error when one or more events failed to unschedule; a count of zero is not a
+	 * failure, so only a non-int return surfaces as one.
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 *
+	 * @param   int|WP_Error $cleared Return of wp_clear_scheduled_hook with $wp_error = true.
+	 * @param   string       $hook    Hook that was being unscheduled, for the error context.
+	 *
+	 * @return  Success<true>|Failure<SchedulingError> Success on an int count, a failure on a WP_Error / non-int return.
+	 */
+	private function result_for_unschedule( int|WP_Error $cleared, string $hook ): AbstractResult {
+		if ( \is_int( $cleared ) ) {
+			return Success::from( true );
+		}
+
+		$context = array(
+			'hook'     => $hook,
+			'wp_error' => $cleared->get_error_message(),
+		);
+
+		$message = 'WordPress cron failed to clear the scheduled hook.';
+		$this->logger?->error( $message, $context );
+
+		return Failure::from(
+			new SchedulingError( SchedulingErrorReason::ScheduleFailed, $message, $context ),
+		);
+	}
+
 	// endregion
 }
diff --git a/packages/utilities/tests/Integration/Scheduling/Backends/WPCronBackendTest.php b/packages/utilities/tests/Integration/Scheduling/Backends/WPCronBackendTest.php
index 03c1c76..b33cce8 100644
--- a/packages/utilities/tests/Integration/Scheduling/Backends/WPCronBackendTest.php
+++ b/packages/utilities/tests/Integration/Scheduling/Backends/WPCronBackendTest.php
@@ -87,6 +87,44 @@ public function test_unschedule_clears_a_scheduled_event(): void {
 		self::assertFalse( $backend->is_scheduled( self::HOOK ) );
 	}
 
+	public function test_unschedule_returns_a_failure_when_the_clear_fails(): void {
+		$backend = $this->backend();
+		$backend->schedule_single( self::HOOK, \time() + 3600 );
+
+		// pre_clear_scheduled_hook short-circuits wp_clear_scheduled_hook; a WP_Error return models a backend
+		// (e.g. a wp-cron replacement) failing to unschedule, the exact failure case unschedule must surface.
+		$wp_error = new \WP_Error( 'clear_failed', 'Could not clear the hook.' );
+		$filter   = static fn (): \WP_Error => $wp_error;
+		\add_filter( 'pre_clear_scheduled_hook', $filter );
+
+		try {
+			$result = $backend->unschedule( self::HOOK );
+		} finally {
+			\remove_filter( 'pre_clear_scheduled_hook', $filter );
+		}
+
+		self::assertInstanceOf( Failure::class, $result );
+		self::assertInstanceOf( SchedulingError::class, $result->error );
+		self::assertSame( SchedulingErrorReason::ScheduleFailed, $result->error->reason );
+		self::assertSame( 'Could not clear the hook.', $result->error->context['wp_error'] );
+	}
+
+	public function test_is_scheduled_rejects_a_non_empty_group(): void {
+		$backend = $this->backend();
+		$backend->schedule_single( self::HOOK, \time() + 3600 );
+
+		// A grouped schedule can never exist on WP-Cron, so a query naming a group is consistently false.
+		self::assertFalse( $backend->is_scheduled( self::HOOK, array(), 'reports' ) );
+	}
+
+	public function test_get_next_scheduled_rejects_a_non_empty_group(): void {
+		$backend   = $this->backend();
+		$timestamp = \time() + 3600;
+		$backend->schedule_single( self::HOOK, $timestamp );
+
+		self::assertNull( $backend->get_next_scheduled( self::HOOK, array(), 'reports' ) );
+	}
+
 	public function test_recurring_registers_a_synthetic_named_schedule(): void {
 		$backend = $this->backend();
 

From d0d04d5e74033437a7556945681029704379d92f Mon Sep 17 00:00:00 2001
From: Tony Hegyes <a.hegyes@proton.me>
Date: Mon, 22 Jun 2026 13:32:39 +0200
Subject: [PATCH 10/21] chore(framework): resolve the audit trivial cluster
 (doc-rot, nicks, #9/#10/#15)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A batch of low-risk audit findings, each verified against current source.

Doc-rot (#22): strike the phantom settings "dispatcher" (the component is the
SettingsFieldAggregator; no dispatcher exists); reconcile core's boot to
"two-pass" in composer.json (README/CHANGELOG already said two-pass — boot()
makes two component passes, initialize then register_hooks); trim
SettingsBackendInterface::get()'s docblock (the field default is render-time,
not a read-time fallback) and KeyValueStoreInterface's "compose stores by ID"
over-promise.

Consistency nicks (#23): Version constructor protected to private (final,
factory-only, matching Success/Failure); AdminNotice::$dismissible to
$is_dismissible (aligns with is_persistent; the WP wp_admin_notice() 'dismissible'
arg key and the is-dismissible class are preserved); move NoticeType to the
AdminNotices concept root (matching FieldType at Schema/ root); standardize the
per-package functions.php aggregator header; add is_wp_compatible()'s trailing
.0-strip from a 3-part minimum so it agrees with WPVersionConditional (with a
unit test).

Empty aggregators (#9): drop the placeholder functions.php (and its composer
files autoload entry + phpstan path) for core and storage; re-add when a
namespace function lands.

Contract clarifications: document get_plugin_header() as a consumer-facing
accessor the kernel does not consult (#10, kept by decision); document that
KeyValueStore callers supply valid keys and stores pass them through unsanitized
(#15).

Excluded by standing decisions: deptrac.yaml untouched (#25 — the unused
WooCommerce-to-Core allow is harmless); the FieldRenderer on*-attribute filter
stays strict (#16); OptionsStore memoization skipped (#11 — final readonly, and
WordPress already caches options in-request).

Gates: PHPStan clean, deptrac 0, Unit 418, Integration 303.

Assisted-by: Claude Code:claude-opus-4-8
---
 AGENTS.md                                     |  4 +-
 composer.lock                                 | 34 +++++-------
 packages/bootstrap/functions.php              |  8 +--
 .../bootstrap/src/Environment/functions.php   | 15 ++++--
 .../bootstrap/tests/Unit/IsCompatibleTest.php | 13 +++++
 packages/core/composer.json                   |  7 +--
 packages/core/functions.php                   |  5 --
 packages/core/src/PluginInterface.php         |  5 +-
 packages/settings/functions.php               |  2 +
 .../src/Backend/SettingsBackendInterface.php  |  3 +-
 packages/shared/functions.php                 |  2 +
 packages/shared/src/Version/Version.php       |  2 +-
 packages/storage/composer.json                |  5 +-
 packages/storage/functions.php                |  5 --
 .../storage/src/KeyValueStoreInterface.php    |  5 +-
 packages/utilities/functions.php              |  2 +
 .../src/AdminNotices/AdminNoticesService.php  |  8 +--
 .../DependencyAdminNoticeRenderer.php         |  2 +-
 .../{ValueObjects => }/NoticeType.php         |  2 +-
 .../AdminNotices/ValueObjects/AdminNotice.php | 30 ++++++-----
 .../ValueObjects/DependencyRequirement.php    |  1 +
 .../AdminNotices/AdminNoticesServiceTest.php  |  6 +--
 .../DependencyAdminNoticeRendererTest.php     |  6 +--
 .../AdminNotices/AdminNoticesServiceTest.php  |  2 +-
 .../Unit/AdminNotices/NoticeStoreTest.php     |  2 +-
 .../ValueObjects/AdminNoticeTest.php          | 52 +++++++++----------
 .../DependencyRequirementTest.php             |  2 +-
 packages/woocommerce/functions.php            |  2 +
 phpstan.dist.neon                             |  2 -
 29 files changed, 117 insertions(+), 117 deletions(-)
 delete mode 100644 packages/core/functions.php
 delete mode 100644 packages/storage/functions.php
 rename packages/utilities/src/AdminNotices/{ValueObjects => }/NoticeType.php (81%)

diff --git a/AGENTS.md b/AGENTS.md
index 516d950..70cf1b0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,7 +4,7 @@ DWS v2 WordPress framework — monorepo for 7 packages (bootstrap, shared, stora
 
 ## Status
 
-`bootstrap`, `shared` (Error / Exception / Result / ValueObject scaffolding + Reflection helpers), `storage` (KeyValueStore + Memory / Options / UserMeta backends), `core`, `utilities` (Hooks + AdminNotices + Conditionals + Caching), and `settings` (descriptors + aggregator / dispatcher + WordPress options & object-field backends) have implementations. `woocommerce` has a settings-backend implementation (`WooCommerceSettingsBackend` + `DescriptorBackedWCSettingsPage` + `WCSettingsBuilder`, Spec C Task 3.2) and a **product-data settings tab** primitive (`ProductData/` — `ProductDataTab` + `ProductDataFieldRenderer` + `ProductDataFieldStore`, 2026-06-15); its remaining WC helpers (version conditionals, `WC_Logger` PSR-3 bridge) await plugin-migration demand.
+`bootstrap`, `shared` (Error / Exception / Result / ValueObject scaffolding + Reflection helpers), `storage` (KeyValueStore + Memory / Options / UserMeta backends), `core`, `utilities` (Hooks + AdminNotices + Conditionals + Caching), and `settings` (descriptors + aggregator + WordPress options & object-field backends) have implementations. `woocommerce` has a settings-backend implementation (`WooCommerceSettingsBackend` + `DescriptorBackedWCSettingsPage` + `WCSettingsBuilder`, Spec C Task 3.2) and a **product-data settings tab** primitive (`ProductData/` — `ProductDataTab` + `ProductDataFieldRenderer` + `ProductDataFieldStore`, 2026-06-15); its remaining WC helpers (version conditionals, `WC_Logger` PSR-3 bridge) await plugin-migration demand.
 
 ## Monorepo structure
 
@@ -46,7 +46,7 @@ wordpress-framework/
 │   │       ├── Lifecycle/                   # per-action markers: Hookable/, Initializable/, Renderable/, Outputtable/
 │   │       └── Installer/                   # install/update/activate/deactivate/uninstall + version I/O (get/set stored, get current)
 │   ├── utilities/          # ahegyes/wp-framework-utilities (Hooks + AdminNotices + Conditionals + Caching)
-│   ├── settings/           # ahegyes/wp-framework-settings (declarative settings: descriptors + aggregator/dispatcher + WP options & object-field backends; depends on storage + shared)
+│   ├── settings/           # ahegyes/wp-framework-settings (declarative settings: descriptors + aggregator + WP options & object-field backends; depends on storage + shared)
 │   └── woocommerce/        # ahegyes/wp-framework-woocommerce (WooCommerceSettingsBackend + page base + WCSettingsBuilder; ProductData/ tab primitive)
 ├── tests/Fixtures/consumer-smoke/  # plugin-template-shaped scoping smoke fixture
 ├── composer.json                   # path repos for all 7 packages + VCS for wordpress-configs + WP Packages registry for wp-plugin/woocommerce
diff --git a/composer.lock b/composer.lock
index bfce1cc..4ed18c7 100644
--- a/composer.lock
+++ b/composer.lock
@@ -4,7 +4,7 @@
         "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
         "This file is @generated automatically"
     ],
-    "content-hash": "45c9da7415957a2cafc149881a7eb147",
+    "content-hash": "9ebeab9b8d0cd3c3e827a8374a1932c4",
     "packages": [
         {
             "name": "ahegyes/wp-framework-bootstrap",
@@ -83,7 +83,7 @@
             "dist": {
                 "type": "path",
                 "url": "packages/core",
-                "reference": "8d1b39d07cd26bbccbf3ef38f4d0c61791576318"
+                "reference": "85894d9c704a66a1b2b6f0464eb7bd91512d1224"
             },
             "require": {
                 "ahegyes/wp-framework-bootstrap": "^2.0@dev",
@@ -118,10 +118,7 @@
             "autoload": {
                 "psr-4": {
                     "DeepWebSolutions\\Framework\\Core\\": "src/"
-                },
-                "files": [
-                    "functions.php"
-                ]
+                }
             },
             "autoload-dev": {
                 "psr-4": {
@@ -137,7 +134,7 @@
                     "homepage": "https://github.com/ahegyes/wordpress-framework/graphs/contributors"
                 }
             ],
-            "description": "PSR-11-based plugin kernel and lifecycle framework for WordPress — interface-driven components, three-pass boot dispatch.",
+            "description": "PSR-11-based plugin kernel and lifecycle framework for WordPress — interface-driven components, two-pass boot dispatch.",
             "homepage": "https://github.com/ahegyes/wordpress-framework",
             "keywords": [
                 "framework",
@@ -161,7 +158,7 @@
             "dist": {
                 "type": "path",
                 "url": "packages/settings",
-                "reference": "790c8cc1bb38065f29aaba2a4320b4326a28d522"
+                "reference": "e33f74f739baf1f52e8de46c6228c338e877b150"
             },
             "require": {
                 "ahegyes/wp-framework-shared": "^2.0@dev",
@@ -169,17 +166,13 @@
                 "php": ">=8.5",
                 "psr/log": "^3"
             },
-            "suggest": {
-                "wp-plugin/woocommerce": "Required at runtime by WordPressObjectFieldStore, which stores fields as WooCommerce order meta."
-            },
             "type": "library",
             "extra": {
                 "branch-alias": {
                     "dev-trunk": "2.0.x-dev"
                 },
                 "scoping-stubs": [
-                    "php-stubs/wordpress-stubs",
-                    "php-stubs/woocommerce-stubs"
+                    "php-stubs/wordpress-stubs"
                 ],
                 "changelogger": {
                     "versioning": "semver",
@@ -313,7 +306,7 @@
             "dist": {
                 "type": "path",
                 "url": "packages/storage",
-                "reference": "bca0455241dd8fdfa8de5995904a19341d5c1107"
+                "reference": "fe7985a381301804b0a851bb5f5dd8d392851b0f"
             },
             "require": {
                 "php": ">=8.5"
@@ -344,10 +337,7 @@
             "autoload": {
                 "psr-4": {
                     "DeepWebSolutions\\Framework\\Storage\\": "src/"
-                },
-                "files": [
-                    "functions.php"
-                ]
+                }
             },
             "autoload-dev": {
                 "psr-4": {
@@ -387,7 +377,7 @@
             "dist": {
                 "type": "path",
                 "url": "packages/utilities",
-                "reference": "274495096e66b5e9b1d0a7020c75f1318638eb10"
+                "reference": "02095b3ed758e1bd20507324f619f948ed18c1d3"
             },
             "require": {
                 "ahegyes/wp-framework-core": "^2.0@dev",
@@ -401,7 +391,8 @@
                     "dev-trunk": "2.0.x-dev"
                 },
                 "scoping-stubs": [
-                    "php-stubs/wordpress-stubs"
+                    "php-stubs/wordpress-stubs",
+                    "php-stubs/woocommerce-stubs:woocommerce-packages-stubs.php"
                 ],
                 "changelogger": {
                     "versioning": "semver",
@@ -8645,8 +8636,7 @@
         "ahegyes/wp-framework-shared": 20,
         "ahegyes/wp-framework-storage": 20,
         "ahegyes/wp-framework-utilities": 20,
-        "ahegyes/wp-framework-woocommerce": 20,
-        "johnpbloch/wordpress-core": 20
+        "ahegyes/wp-framework-woocommerce": 20
     },
     "prefer-stable": true,
     "prefer-lowest": false,
diff --git a/packages/bootstrap/functions.php b/packages/bootstrap/functions.php
index 33aa87c..7f12d11 100644
--- a/packages/bootstrap/functions.php
+++ b/packages/bootstrap/functions.php
@@ -1,11 +1,5 @@
 <?php
-/**
- * Pre-autoload aggregator for the bootstrap package. Requires the per-concern
- * function files below. Composer autoloads only this file via autoload-files.
- *
- * @since   2.0.0
- * @version 2.0.0
- */
+// Aggregator: requires this package's nested src/<namespace>/functions.php files (composer autoloads only this file).
 
 require_once __DIR__ . '/src/Environment/functions.php';
 require_once __DIR__ . '/src/Plugin/functions.php';
diff --git a/packages/bootstrap/src/Environment/functions.php b/packages/bootstrap/src/Environment/functions.php
index 52477af..fd9804a 100644
--- a/packages/bootstrap/src/Environment/functions.php
+++ b/packages/bootstrap/src/Environment/functions.php
@@ -23,8 +23,10 @@ function is_php_compatible( $min_php ) {
 
 /**
  * Returns whether the running WordPress version meets the given minimum.
- * WP-native helper is unavailable on WP < 5.2; the fallback strips the
- * beta/alpha suffix the way `wp_get_wp_version()` does.
+ * WP-native helper is unavailable on WP < 5.2; the fallback mirrors
+ * `is_wp_version_compatible()` — it strips the current version's beta/alpha
+ * suffix and drops a trailing `.0` from a 3-part minimum, so a 2-part current
+ * like `7.0` still satisfies a `7.0.0` minimum.
  *
  * @since   2.0.0
  * @version 2.0.0
@@ -39,7 +41,12 @@ function is_wp_compatible( $min_wp ) {
 	}
 
 	$current = isset( $GLOBALS['wp_version'] ) ? $GLOBALS['wp_version'] : '0';
-	$parts   = \explode( '-', $current );
+	$current = \explode( '-', $current );
+	$current = $current[0];
 
-	return \version_compare( $parts[0], $min_wp, '>=' );
+	if ( \substr_count( $min_wp, '.' ) > 1 && \substr( $min_wp, -2 ) === '.0' ) {
+		$min_wp = \substr( $min_wp, 0, -2 );
+	}
+
+	return \version_compare( $current, $min_wp, '>=' );
 }
diff --git a/packages/bootstrap/tests/Unit/IsCompatibleTest.php b/packages/bootstrap/tests/Unit/IsCompatibleTest.php
index 501049b..29a8a84 100644
--- a/packages/bootstrap/tests/Unit/IsCompatibleTest.php
+++ b/packages/bootstrap/tests/Unit/IsCompatibleTest.php
@@ -40,6 +40,19 @@ public function test_is_wp_compatible_strips_beta_suffix_in_fallback(): void {
 		}
 	}
 
+	public function test_is_wp_compatible_drops_trailing_zero_from_three_part_minimum_in_fallback(): void {
+		self::assertFalse( \function_exists( '\is_wp_version_compatible' ), 'WP must not be loaded for unit tests.' );
+
+		$GLOBALS['wp_version'] = '7.0';
+		try {
+			// A 2-part current satisfies a 3-part ".0" minimum, mirroring is_wp_version_compatible().
+			self::assertTrue( is_wp_compatible( '7.0.0' ) );
+			self::assertFalse( is_wp_compatible( '7.0.1' ) );
+		} finally {
+			unset( $GLOBALS['wp_version'] );
+		}
+	}
+
 	public function test_is_wp_compatible_treats_missing_wp_version_global_as_zero(): void {
 		self::assertFalse( \function_exists( '\is_wp_version_compatible' ), 'WP must not be loaded for unit tests.' );
 		self::assertArrayNotHasKey( 'wp_version', $GLOBALS );
diff --git a/packages/core/composer.json b/packages/core/composer.json
index b0e474b..72fb534 100644
--- a/packages/core/composer.json
+++ b/packages/core/composer.json
@@ -1,6 +1,6 @@
 {
   "name": "ahegyes/wp-framework-core",
-  "description": "PSR-11-based plugin kernel and lifecycle framework for WordPress — interface-driven components, three-pass boot dispatch.",
+  "description": "PSR-11-based plugin kernel and lifecycle framework for WordPress — interface-driven components, two-pass boot dispatch.",
   "type": "library",
   "license": "GPL-2.0-or-later",
   "homepage": "https://github.com/ahegyes/wordpress-framework",
@@ -30,10 +30,7 @@
   "autoload": {
     "psr-4": {
       "DeepWebSolutions\\Framework\\Core\\": "src/"
-    },
-    "files": [
-      "functions.php"
-    ]
+    }
   },
   "autoload-dev": {
     "psr-4": {
diff --git a/packages/core/functions.php b/packages/core/functions.php
deleted file mode 100644
index b78ff3c..0000000
--- a/packages/core/functions.php
+++ /dev/null
@@ -1,5 +0,0 @@
-<?php declare( strict_types=1 );
-
-// No namespace functions in core yet. This file exists for workspace-wide
-// consistency with the package-root functions.php aggregator pattern; when a
-// <namespace>/functions.php file is added under src/, require_once it here.
diff --git a/packages/core/src/PluginInterface.php b/packages/core/src/PluginInterface.php
index e51d41c..72bad82 100644
--- a/packages/core/src/PluginInterface.php
+++ b/packages/core/src/PluginInterface.php
@@ -28,7 +28,10 @@ public function get_plugin_file(): string;
 
 	/**
 	 * Typed wrapper around the plugin's main-file WP header. The get_plugin_ prefix
-	 * keeps it clear of WordPress's theme-template get_header().
+	 * keeps it clear of WordPress's theme-template get_header(). A consumer-facing
+	 * accessor for the plugin's own metadata (display name, version, text domain);
+	 * the kernel boot reads the version from the installer, not from here, so this
+	 * stays part of the contract even though the engine does not consult it.
 	 *
 	 * @since   2.0.0
 	 * @version 2.0.0
diff --git a/packages/settings/functions.php b/packages/settings/functions.php
index 8dfe40f..8b1ca5e 100644
--- a/packages/settings/functions.php
+++ b/packages/settings/functions.php
@@ -1,3 +1,5 @@
 <?php declare( strict_types=1 );
 
+// Aggregator: requires this package's nested src/<namespace>/functions.php files (composer autoloads only this file).
+
 require_once __DIR__ . '/src/Schema/functions.php';
diff --git a/packages/settings/src/Backend/SettingsBackendInterface.php b/packages/settings/src/Backend/SettingsBackendInterface.php
index 788b424..e4645e7 100644
--- a/packages/settings/src/Backend/SettingsBackendInterface.php
+++ b/packages/settings/src/Backend/SettingsBackendInterface.php
@@ -26,7 +26,8 @@ interface SettingsBackendInterface {
 	public function register_page( SettingsPage $page ): void;
 
 	/**
-	 * Retrieves a field's stored value, or the default if none is stored.
+	 * Retrieves a field's stored value, or $default_value when nothing is stored. The field's
+	 * declared default is a render-time concern, not a read-time fallback here.
 	 *
 	 * @since   2.0.0
 	 * @version 2.0.0
diff --git a/packages/shared/functions.php b/packages/shared/functions.php
index fd3cb6f..0bd42f8 100644
--- a/packages/shared/functions.php
+++ b/packages/shared/functions.php
@@ -1,3 +1,5 @@
 <?php declare( strict_types=1 );
 
+// Aggregator: requires this package's nested src/<namespace>/functions.php files (composer autoloads only this file).
+
 require_once __DIR__ . '/src/Reflection/functions.php';
diff --git a/packages/shared/src/Version/Version.php b/packages/shared/src/Version/Version.php
index b1f1d46..6b64d3c 100644
--- a/packages/shared/src/Version/Version.php
+++ b/packages/shared/src/Version/Version.php
@@ -24,7 +24,7 @@
 	 *
 	 * @param   string $value Pre-validated version string; the original representation supplied to the factory.
 	 */
-	protected function __construct(
+	private function __construct(
 		public string $value
 	) {}
 
diff --git a/packages/storage/composer.json b/packages/storage/composer.json
index 1c956b0..04ab83d 100644
--- a/packages/storage/composer.json
+++ b/packages/storage/composer.json
@@ -26,10 +26,7 @@
   "autoload": {
     "psr-4": {
       "DeepWebSolutions\\Framework\\Storage\\": "src/"
-    },
-    "files": [
-      "functions.php"
-    ]
+    }
   },
   "autoload-dev": {
     "psr-4": {
diff --git a/packages/storage/functions.php b/packages/storage/functions.php
deleted file mode 100644
index e626081..0000000
--- a/packages/storage/functions.php
+++ /dev/null
@@ -1,5 +0,0 @@
-<?php declare( strict_types=1 );
-
-// No namespace functions in storage. This file exists for workspace-wide
-// consistency with the package-root functions.php aggregator pattern; when a
-// <namespace>/functions.php file is added under src/, require_once it here.
diff --git a/packages/storage/src/KeyValueStoreInterface.php b/packages/storage/src/KeyValueStoreInterface.php
index fd50fa3..25f8ef6 100644
--- a/packages/storage/src/KeyValueStoreInterface.php
+++ b/packages/storage/src/KeyValueStoreInterface.php
@@ -9,9 +9,8 @@
  * and choose where they store it (in-memory per request, wp_options site-wide, user_meta
  * per-user, or any other backend that maps strings to values).
  *
- * Consumers compose stores by ID — e.g., a service holding `array<string, KeyValueStoreInterface>` —
- * letting plugins choose at construction whether their state is transient, cross-request,
- * or per-user without changing the consuming code.
+ * Callers supply valid keys: a store passes the given key through unchanged and performs no
+ * key sanitization of its own.
  *
  * @since   2.0.0
  * @version 2.0.0
diff --git a/packages/utilities/functions.php b/packages/utilities/functions.php
index 2b7ff1a..c9f4bf9 100644
--- a/packages/utilities/functions.php
+++ b/packages/utilities/functions.php
@@ -1,3 +1,5 @@
 <?php declare( strict_types=1 );
 
+// Aggregator: requires this package's nested src/<namespace>/functions.php files (composer autoloads only this file).
+
 require_once __DIR__ . '/src/Scheduling/functions.php';
diff --git a/packages/utilities/src/AdminNotices/AdminNoticesService.php b/packages/utilities/src/AdminNotices/AdminNoticesService.php
index f00f399..6c1674d 100644
--- a/packages/utilities/src/AdminNotices/AdminNoticesService.php
+++ b/packages/utilities/src/AdminNotices/AdminNoticesService.php
@@ -146,7 +146,7 @@ public function render_notices(): void {
 					continue;
 				}
 
-				$suppressed = $notice->is_persistent && $notice->dismissible
+				$suppressed = $notice->is_persistent && $notice->is_dismissible
 					&& true === $this->dismissals?->is_dismissed( $notice->id );
 				if ( ! $suppressed ) {
 					$this->render_one( $notice );
@@ -242,7 +242,7 @@ private function render_one( AdminNotice $notice ): void {
 		// The transport marker only goes on notices a dismissal would actually suppress (persistent +
 		// dismissible), so clicking a one-shot's dismiss never records a stale, never-consulted row.
 		if ( null !== $this->dismiss_action && null !== $this->dismissals
-			&& $notice->is_persistent && $notice->dismissible
+			&& $notice->is_persistent && $notice->is_dismissible
 		) {
 			$data_attributes['data-dismiss-action'] = $this->dismiss_action;
 		}
@@ -250,7 +250,7 @@ private function render_one( AdminNotice $notice ): void {
 		$attributes = array(
 			'id'             => 'dws-notice-' . $notice->id,
 			'type'           => $notice->type->value,
-			'dismissible'    => $notice->dismissible,
+			'dismissible'    => $notice->is_dismissible,
 			'paragraph_wrap' => true,
 			'attributes'     => $data_attributes,
 		);
@@ -263,7 +263,7 @@ private function render_one( AdminNotice $notice ): void {
 		// Dead at the WP 7.0 floor: wp_admin_notice() and its data-attribute support ship in WP 6.4, so
 		// the dismiss transport cannot run on the pre-6.4 path reached here.
 		$classes = 'notice notice-' . $notice->type->value;
-		if ( $notice->dismissible ) {
+		if ( $notice->is_dismissible ) {
 			$classes .= ' is-dismissible';
 		}
 		printf(
diff --git a/packages/utilities/src/AdminNotices/DependencyAdminNoticeRenderer.php b/packages/utilities/src/AdminNotices/DependencyAdminNoticeRenderer.php
index 0af8bd4..028ae07 100644
--- a/packages/utilities/src/AdminNotices/DependencyAdminNoticeRenderer.php
+++ b/packages/utilities/src/AdminNotices/DependencyAdminNoticeRenderer.php
@@ -118,7 +118,7 @@ private function build_notice( DependencyRequirement $requirement ): AdminNotice
 			id: $requirement->get_notice_id(),
 			message: $this->build_message( $requirement ),
 			type: $requirement->get_notice_type(),
-			dismissible: $requirement->is_dismissible(),
+			is_dismissible: $requirement->is_dismissible(),
 			is_persistent: $requirement->is_persistent(),
 			capability: $this->capability,
 		);
diff --git a/packages/utilities/src/AdminNotices/ValueObjects/NoticeType.php b/packages/utilities/src/AdminNotices/NoticeType.php
similarity index 81%
rename from packages/utilities/src/AdminNotices/ValueObjects/NoticeType.php
rename to packages/utilities/src/AdminNotices/NoticeType.php
index ef39f11..a20dbd8 100644
--- a/packages/utilities/src/AdminNotices/ValueObjects/NoticeType.php
+++ b/packages/utilities/src/AdminNotices/NoticeType.php
@@ -1,6 +1,6 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Utilities\AdminNotices\ValueObjects;
+namespace DeepWebSolutions\Framework\Utilities\AdminNotices;
 
 /**
  * Severity level for an admin notice.
diff --git a/packages/utilities/src/AdminNotices/ValueObjects/AdminNotice.php b/packages/utilities/src/AdminNotices/ValueObjects/AdminNotice.php
index a8dea7a..15b79ad 100644
--- a/packages/utilities/src/AdminNotices/ValueObjects/AdminNotice.php
+++ b/packages/utilities/src/AdminNotices/ValueObjects/AdminNotice.php
@@ -2,6 +2,8 @@
 
 namespace DeepWebSolutions\Framework\Utilities\AdminNotices\ValueObjects;
 
+use DeepWebSolutions\Framework\Utilities\AdminNotices\NoticeType;
+
 /**
  * Descriptor for a single WordPress admin notice.
  *
@@ -23,18 +25,18 @@
 	 * @since   2.0.0
 	 * @version 2.0.0
 	 *
-	 * @param   string     $id            Unique identifier (used for dismissal tracking, storage keying, and removal). Keep it sanitize_key-stable (lowercase a-z, 0-9, _, -) so AJAX dismissal round-trips.
-	 * @param   string     $message       Notice message (inline HTML allowed; sanitized and paragraph-wrapped at render time).
-	 * @param   NoticeType $type          Severity level. Defaults to NoticeType::Info.
-	 * @param   bool       $dismissible   Whether the notice shows a dismiss button. Defaults to true.
-	 * @param   bool       $is_persistent Whether the notice recurs across renders (true) or is consumed after rendering once (false). Defaults to false.
-	 * @param   string     $capability    Capability required to see the notice. Defaults to 'manage_options'.
+	 * @param   string     $id             Unique identifier (used for dismissal tracking, storage keying, and removal). Keep it sanitize_key-stable (lowercase a-z, 0-9, _, -) so AJAX dismissal round-trips.
+	 * @param   string     $message        Notice message (inline HTML allowed; sanitized and paragraph-wrapped at render time).
+	 * @param   NoticeType $type           Severity level. Defaults to NoticeType::Info.
+	 * @param   bool       $is_dismissible Whether the notice shows a dismiss button. Defaults to true.
+	 * @param   bool       $is_persistent  Whether the notice recurs across renders (true) or is consumed after rendering once (false). Defaults to false.
+	 * @param   string     $capability     Capability required to see the notice. Defaults to 'manage_options'.
 	 */
 	public function __construct(
 		public string $id,
 		public string $message,
 		public NoticeType $type = NoticeType::Info,
-		public bool $dismissible = true,
+		public bool $is_dismissible = true,
 		public bool $is_persistent = false,
 		public string $capability = 'manage_options',
 	) {}
@@ -53,12 +55,12 @@ public function __construct(
 	 */
 	public function to_array(): array {
 		return array(
-			'id'            => $this->id,
-			'message'       => $this->message,
-			'type'          => $this->type->value,
-			'dismissible'   => $this->dismissible,
-			'is_persistent' => $this->is_persistent,
-			'capability'    => $this->capability,
+			'id'             => $this->id,
+			'message'        => $this->message,
+			'type'           => $this->type->value,
+			'is_dismissible' => $this->is_dismissible,
+			'is_persistent'  => $this->is_persistent,
+			'capability'     => $this->capability,
 		);
 	}
 
@@ -86,7 +88,7 @@ public static function from_array( array $data ): self {
 			id: \is_string( $data['id'] ?? null ) ? $data['id'] : '',
 			message: \is_string( $data['message'] ?? null ) ? $data['message'] : '',
 			type: $type,
-			dismissible: \is_bool( $data['dismissible'] ?? null ) ? $data['dismissible'] : true,
+			is_dismissible: \is_bool( $data['is_dismissible'] ?? null ) ? $data['is_dismissible'] : true,
 			is_persistent: \is_bool( $data['is_persistent'] ?? null ) ? $data['is_persistent'] : false,
 			capability: \is_string( $data['capability'] ?? null ) ? $data['capability'] : 'manage_options',
 		);
diff --git a/packages/utilities/src/AdminNotices/ValueObjects/DependencyRequirement.php b/packages/utilities/src/AdminNotices/ValueObjects/DependencyRequirement.php
index 76ad015..6fb2a65 100644
--- a/packages/utilities/src/AdminNotices/ValueObjects/DependencyRequirement.php
+++ b/packages/utilities/src/AdminNotices/ValueObjects/DependencyRequirement.php
@@ -3,6 +3,7 @@
 namespace DeepWebSolutions\Framework\Utilities\AdminNotices\ValueObjects;
 
 use DeepWebSolutions\Framework\Core\Conditional\ConditionalInterface;
+use DeepWebSolutions\Framework\Utilities\AdminNotices\NoticeType;
 
 /**
  * Descriptor for a dependency a plugin declares for missing-dependency admin notices: the conditional
diff --git a/packages/utilities/tests/Integration/AdminNotices/AdminNoticesServiceTest.php b/packages/utilities/tests/Integration/AdminNotices/AdminNoticesServiceTest.php
index 4003bd0..33cf516 100644
--- a/packages/utilities/tests/Integration/AdminNotices/AdminNoticesServiceTest.php
+++ b/packages/utilities/tests/Integration/AdminNotices/AdminNoticesServiceTest.php
@@ -6,7 +6,7 @@
 use DeepWebSolutions\Framework\Utilities\AdminNotices\DismissedNoticesTracker;
 use DeepWebSolutions\Framework\Utilities\AdminNotices\NoticeStore;
 use DeepWebSolutions\Framework\Utilities\AdminNotices\ValueObjects\AdminNotice;
-use DeepWebSolutions\Framework\Utilities\AdminNotices\ValueObjects\NoticeType;
+use DeepWebSolutions\Framework\Utilities\AdminNotices\NoticeType;
 use DeepWebSolutions\Framework\Storage\MemoryStore;
 use DeepWebSolutions\Framework\Storage\OptionsStore;
 use DeepWebSolutions\Framework\Storage\UserMetaStore;
@@ -325,11 +325,11 @@ public function test_endpoint_dismissal_suppresses_the_notice_on_the_next_render
 	public function test_render_scopes_dismiss_action_only_for_sticky_notices(): void {
 		$service = $this->transport_service();
 		$service->add_notice(
-			new AdminNotice( 'sticky_dep', 'Sticky.', NoticeType::Warning, dismissible: true, is_persistent: true ),
+			new AdminNotice( 'sticky_dep', 'Sticky.', NoticeType::Warning, is_dismissible: true, is_persistent: true ),
 			'user-meta',
 		);
 		$service->add_notice(
-			new AdminNotice( 'flash_msg', 'Flash.', NoticeType::Info, dismissible: true, is_persistent: false ),
+			new AdminNotice( 'flash_msg', 'Flash.', NoticeType::Info, is_dismissible: true, is_persistent: false ),
 			'user-meta',
 		);
 
diff --git a/packages/utilities/tests/Integration/AdminNotices/DependencyAdminNoticeRendererTest.php b/packages/utilities/tests/Integration/AdminNotices/DependencyAdminNoticeRendererTest.php
index 994be66..f471abc 100644
--- a/packages/utilities/tests/Integration/AdminNotices/DependencyAdminNoticeRendererTest.php
+++ b/packages/utilities/tests/Integration/AdminNotices/DependencyAdminNoticeRendererTest.php
@@ -9,7 +9,7 @@
 use DeepWebSolutions\Framework\Utilities\AdminNotices\NoticeStore;
 use DeepWebSolutions\Framework\Utilities\AdminNotices\ValueObjects\AdminNotice;
 use DeepWebSolutions\Framework\Utilities\AdminNotices\ValueObjects\DependencyRequirement;
-use DeepWebSolutions\Framework\Utilities\AdminNotices\ValueObjects\NoticeType;
+use DeepWebSolutions\Framework\Utilities\AdminNotices\NoticeType;
 use DeepWebSolutions\Framework\Utilities\Conditionals\Dependencies\WPPluginActiveConditional;
 use DeepWebSolutions\Framework\Storage\MemoryStore;
 use DeepWebSolutions\Framework\Storage\OptionsStore;
@@ -76,7 +76,7 @@ public function test_unmet_required_dependency_queues_a_blocking_error(): void {
 
 		self::assertInstanceOf( AdminNotice::class, $notice );
 		self::assertSame( NoticeType::Error, $notice->type );
-		self::assertFalse( $notice->dismissible );
+		self::assertFalse( $notice->is_dismissible );
 		self::assertFalse( $notice->is_persistent );
 		self::assertSame( 'activate_plugins', $notice->capability );
 		self::assertSame( 'Linked Orders requires WooCommerce to be active.', $notice->message );
@@ -94,7 +94,7 @@ public function test_unmet_optional_dependency_queues_a_dismissible_warning(): v
 
 		self::assertInstanceOf( AdminNotice::class, $notice );
 		self::assertSame( NoticeType::Warning, $notice->type );
-		self::assertTrue( $notice->dismissible );
+		self::assertTrue( $notice->is_dismissible );
 		self::assertTrue( $notice->is_persistent );
 		self::assertSame( 'Jetpack is recommended for Linked Orders.', $notice->message );
 	}
diff --git a/packages/utilities/tests/Unit/AdminNotices/AdminNoticesServiceTest.php b/packages/utilities/tests/Unit/AdminNotices/AdminNoticesServiceTest.php
index 177fbc2..c573277 100644
--- a/packages/utilities/tests/Unit/AdminNotices/AdminNoticesServiceTest.php
+++ b/packages/utilities/tests/Unit/AdminNotices/AdminNoticesServiceTest.php
@@ -5,7 +5,7 @@
 use DeepWebSolutions\Framework\Utilities\AdminNotices\AdminNoticesService;
 use DeepWebSolutions\Framework\Utilities\AdminNotices\NoticeStore;
 use DeepWebSolutions\Framework\Utilities\AdminNotices\ValueObjects\AdminNotice;
-use DeepWebSolutions\Framework\Utilities\AdminNotices\ValueObjects\NoticeType;
+use DeepWebSolutions\Framework\Utilities\AdminNotices\NoticeType;
 use DeepWebSolutions\Framework\Storage\MemoryStore;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\UsesClass;
diff --git a/packages/utilities/tests/Unit/AdminNotices/NoticeStoreTest.php b/packages/utilities/tests/Unit/AdminNotices/NoticeStoreTest.php
index 519f587..8ae6975 100644
--- a/packages/utilities/tests/Unit/AdminNotices/NoticeStoreTest.php
+++ b/packages/utilities/tests/Unit/AdminNotices/NoticeStoreTest.php
@@ -4,7 +4,7 @@
 
 use DeepWebSolutions\Framework\Utilities\AdminNotices\NoticeStore;
 use DeepWebSolutions\Framework\Utilities\AdminNotices\ValueObjects\AdminNotice;
-use DeepWebSolutions\Framework\Utilities\AdminNotices\ValueObjects\NoticeType;
+use DeepWebSolutions\Framework\Utilities\AdminNotices\NoticeType;
 use DeepWebSolutions\Framework\Storage\MemoryStore;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\UsesClass;
diff --git a/packages/utilities/tests/Unit/AdminNotices/ValueObjects/AdminNoticeTest.php b/packages/utilities/tests/Unit/AdminNotices/ValueObjects/AdminNoticeTest.php
index bb6a8c1..a6b3acc 100644
--- a/packages/utilities/tests/Unit/AdminNotices/ValueObjects/AdminNoticeTest.php
+++ b/packages/utilities/tests/Unit/AdminNotices/ValueObjects/AdminNoticeTest.php
@@ -3,7 +3,7 @@
 namespace DeepWebSolutions\Framework\Utilities\Tests\Unit\AdminNotices\ValueObjects;
 
 use DeepWebSolutions\Framework\Utilities\AdminNotices\ValueObjects\AdminNotice;
-use DeepWebSolutions\Framework\Utilities\AdminNotices\ValueObjects\NoticeType;
+use DeepWebSolutions\Framework\Utilities\AdminNotices\NoticeType;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\UsesClass;
 use PHPUnit\Framework\TestCase;
@@ -17,7 +17,7 @@ public function test_constructs_with_required_arguments(): void {
 		self::assertSame( 'my-notice', $notice->id );
 		self::assertSame( 'Hello world.', $notice->message );
 		self::assertSame( NoticeType::Info, $notice->type );
-		self::assertTrue( $notice->dismissible );
+		self::assertTrue( $notice->is_dismissible );
 		self::assertFalse( $notice->is_persistent );
 		self::assertSame( 'manage_options', $notice->capability );
 	}
@@ -27,7 +27,7 @@ public function test_constructs_with_all_arguments(): void {
 			id: 'critical',
 			message: '<strong>Bad.</strong>',
 			type: NoticeType::Error,
-			dismissible: false,
+			is_dismissible: false,
 			is_persistent: true,
 			capability: 'activate_plugins',
 		);
@@ -35,7 +35,7 @@ public function test_constructs_with_all_arguments(): void {
 		self::assertSame( 'critical', $notice->id );
 		self::assertSame( '<strong>Bad.</strong>', $notice->message );
 		self::assertSame( NoticeType::Error, $notice->type );
-		self::assertFalse( $notice->dismissible );
+		self::assertFalse( $notice->is_dismissible );
 		self::assertTrue( $notice->is_persistent );
 		self::assertSame( 'activate_plugins', $notice->capability );
 	}
@@ -45,7 +45,7 @@ public function test_capability_is_the_sixth_positional_argument(): void {
 
 		self::assertSame( 'edit_posts', $notice->capability );
 		self::assertTrue( $notice->is_persistent );
-		self::assertFalse( $notice->dismissible );
+		self::assertFalse( $notice->is_dismissible );
 	}
 
 	public function test_to_array_emits_all_fields_with_type_as_backing_string(): void {
@@ -53,19 +53,19 @@ public function test_to_array_emits_all_fields_with_type_as_backing_string(): vo
 			id: 'id1',
 			message: 'msg',
 			type: NoticeType::Warning,
-			dismissible: false,
+			is_dismissible: false,
 			is_persistent: true,
 			capability: 'edit_posts',
 		);
 
 		self::assertSame(
 			array(
-				'id'            => 'id1',
-				'message'       => 'msg',
-				'type'          => 'warning',
-				'dismissible'   => false,
-				'is_persistent' => true,
-				'capability'    => 'edit_posts',
+				'id'             => 'id1',
+				'message'        => 'msg',
+				'type'           => 'warning',
+				'is_dismissible' => false,
+				'is_persistent'  => true,
+				'capability'     => 'edit_posts',
 			),
 			$notice->to_array(),
 		);
@@ -74,19 +74,19 @@ public function test_to_array_emits_all_fields_with_type_as_backing_string(): vo
 	public function test_from_array_reconstructs_notice(): void {
 		$notice = AdminNotice::from_array(
 			array(
-				'id'            => 'id1',
-				'message'       => 'msg',
-				'type'          => 'error',
-				'dismissible'   => false,
-				'is_persistent' => true,
-				'capability'    => 'manage_woocommerce',
+				'id'             => 'id1',
+				'message'        => 'msg',
+				'type'           => 'error',
+				'is_dismissible' => false,
+				'is_persistent'  => true,
+				'capability'     => 'manage_woocommerce',
 			),
 		);
 
 		self::assertSame( 'id1', $notice->id );
 		self::assertSame( 'msg', $notice->message );
 		self::assertSame( NoticeType::Error, $notice->type );
-		self::assertFalse( $notice->dismissible );
+		self::assertFalse( $notice->is_dismissible );
 		self::assertTrue( $notice->is_persistent );
 		self::assertSame( 'manage_woocommerce', $notice->capability );
 	}
@@ -96,7 +96,7 @@ public function test_to_array_from_array_round_trips_field_for_field(): void {
 			id: 'x',
 			message: '',
 			type: NoticeType::Success,
-			dismissible: false,
+			is_dismissible: false,
 			is_persistent: true,
 			capability: 'manage_woocommerce',
 		);
@@ -128,7 +128,7 @@ public function test_from_array_tolerates_non_string_type_without_error(): void
 	public function test_from_array_absent_flags_fall_back_to_constructor_defaults(): void {
 		$notice = AdminNotice::from_array( array( 'id' => 'x', 'message' => 'm' ) );
 
-		self::assertTrue( $notice->dismissible );
+		self::assertTrue( $notice->is_dismissible );
 		self::assertFalse( $notice->is_persistent );
 		self::assertSame( 'manage_options', $notice->capability );
 	}
@@ -138,14 +138,14 @@ public function test_from_array_falls_back_to_defaults_for_non_bool_flags(): voi
 		// (bool) cast would wrongly make the notice persistent. Non-bools fall back to the defaults.
 		$notice = AdminNotice::from_array(
 			array(
-				'id'            => 'x',
-				'message'       => 'm',
-				'dismissible'   => 0,
-				'is_persistent' => 'false',
+				'id'             => 'x',
+				'message'        => 'm',
+				'is_dismissible' => 0,
+				'is_persistent'  => 'false',
 			),
 		);
 
-		self::assertTrue( $notice->dismissible );
+		self::assertTrue( $notice->is_dismissible );
 		self::assertFalse( $notice->is_persistent );
 	}
 }
diff --git a/packages/utilities/tests/Unit/AdminNotices/ValueObjects/DependencyRequirementTest.php b/packages/utilities/tests/Unit/AdminNotices/ValueObjects/DependencyRequirementTest.php
index 6cfcf74..ea9dc6a 100644
--- a/packages/utilities/tests/Unit/AdminNotices/ValueObjects/DependencyRequirementTest.php
+++ b/packages/utilities/tests/Unit/AdminNotices/ValueObjects/DependencyRequirementTest.php
@@ -4,7 +4,7 @@
 
 use DeepWebSolutions\Framework\Core\Conditional\ConditionalInterface;
 use DeepWebSolutions\Framework\Utilities\AdminNotices\ValueObjects\DependencyRequirement;
-use DeepWebSolutions\Framework\Utilities\AdminNotices\ValueObjects\NoticeType;
+use DeepWebSolutions\Framework\Utilities\AdminNotices\NoticeType;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\UsesClass;
 use PHPUnit\Framework\TestCase;
diff --git a/packages/woocommerce/functions.php b/packages/woocommerce/functions.php
index aa8912f..4be39b8 100644
--- a/packages/woocommerce/functions.php
+++ b/packages/woocommerce/functions.php
@@ -1,3 +1,5 @@
 <?php declare( strict_types=1 );
 
+// Aggregator: requires this package's nested src/<namespace>/functions.php files (composer autoloads only this file).
+
 require_once __DIR__ . '/src/functions.php';
diff --git a/phpstan.dist.neon b/phpstan.dist.neon
index 117d2b9..e29ab99 100644
--- a/phpstan.dist.neon
+++ b/phpstan.dist.neon
@@ -17,10 +17,8 @@ parameters:
         - packages/shared/functions.php
         - packages/shared/src
         - packages/shared/tests
-        - packages/storage/functions.php
         - packages/storage/src
         - packages/storage/tests
-        - packages/core/functions.php
         - packages/core/src
         - packages/core/tests
         - packages/utilities/functions.php

From bc73d30c53f8e7b37bfdc9c261290d98b2c5d6f9 Mon Sep 17 00:00:00 2001
From: Tony Hegyes <a.hegyes@proton.me>
Date: Mon, 22 Jun 2026 14:11:41 +0200
Subject: [PATCH 11/21] fix(consumer-smoke): pin woocommerce-stubs to ^10.8
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The fixture's "*" stub constraints let wordpress-stubs float to 7.0, which forced
woocommerce-stubs down to v3.8.0 — a version without woocommerce-packages-stubs.php.
So the utilities scoping-stubs explicit-file entry
(php-stubs/woocommerce-stubs:woocommerce-packages-stubs.php) was silently skipped
and the as_* exclusions came incidentally from the old bundled stub, not the path
under test. Pin woocommerce-stubs to ^10.8 to match the framework, so it resolves
to 10.8.0 (which ships the packages-stubs file) and the explicit-file path is
exercised faithfully.

Verified after a clean reinstall (which also refreshes the path-repo mirrors that
composer update leaves stale): smoke passes, the collector no longer skips
woocommerce-packages-stubs.php, and 11 as_* functions land in
scoping-exclusions.json via the explicit-file path.

Assisted-by: Claude Code:claude-opus-4-8
---
 tests/Fixtures/consumer-smoke/composer.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/Fixtures/consumer-smoke/composer.json b/tests/Fixtures/consumer-smoke/composer.json
index cbe270e..f80b4cb 100644
--- a/tests/Fixtures/consumer-smoke/composer.json
+++ b/tests/Fixtures/consumer-smoke/composer.json
@@ -83,7 +83,7 @@
     "humbug/php-scoper": "^0.18",
     "php-di/php-di": "^7",
     "php-stubs/wordpress-stubs": "*",
-    "php-stubs/woocommerce-stubs": "*"
+    "php-stubs/woocommerce-stubs": "^10.8"
   },
 
   "minimum-stability": "dev",

From 856f3e1e5637ba09e1462afc30cead847a953193 Mon Sep 17 00:00:00 2001
From: Tony Hegyes <a.hegyes@proton.me>
Date: Mon, 22 Jun 2026 14:14:08 +0200
Subject: [PATCH 12/21] chore(deps): bump wordpress-configs to the merged
 explicit-file collector
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Pull the merged wordpress-configs trunk (9764855 -> 4431b7b) so the framework
vendors the explicit-file scoping-stubs collector (the package:file form +
realpath containment) and the doc cleanup. Lock-only: the shared QA configs the
framework's phpstan.dist.neon includes are unchanged, so the gates are
unaffected. The framework does not run the collector itself — this keeps the
vendored copy current for the consumer-smoke fixture and anyone working in the
repo.

Assisted-by: Claude Code:claude-opus-4-8
---
 composer.lock | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/composer.lock b/composer.lock
index 4ed18c7..a846185 100644
--- a/composer.lock
+++ b/composer.lock
@@ -643,12 +643,12 @@
             "source": {
                 "type": "git",
                 "url": "https://github.com/ahegyes/wordpress-configs.git",
-                "reference": "9764855f54d8c75941667f40326227a8434febbd"
+                "reference": "4431b7b9b44e09c516122c9fc7bcab74c0356b0c"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/ahegyes/wordpress-configs/zipball/9764855f54d8c75941667f40326227a8434febbd",
-                "reference": "9764855f54d8c75941667f40326227a8434febbd",
+                "url": "https://api.github.com/repos/ahegyes/wordpress-configs/zipball/4431b7b9b44e09c516122c9fc7bcab74c0356b0c",
+                "reference": "4431b7b9b44e09c516122c9fc7bcab74c0356b0c",
                 "shasum": ""
             },
             "require": {
@@ -752,7 +752,7 @@
                 "source": "https://github.com/ahegyes/wordpress-configs/tree/trunk",
                 "issues": "https://github.com/ahegyes/wordpress-configs/issues"
             },
-            "time": "2026-06-21T09:37:46+00:00"
+            "time": "2026-06-22T11:51:08+00:00"
         },
         {
             "name": "automattic/jetpack-changelogger",

From 99dcd8459e2079299883b0adc1cb6faeff43f03d Mon Sep 17 00:00:00 2001
From: Tony Hegyes <a.hegyes@proton.me>
Date: Mon, 22 Jun 2026 14:33:11 +0200
Subject: [PATCH 13/21] refactor(core): move self-dispatched markers from
 Lifecycle/ to Rendering/
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Finding #7. Lifecycle/ conflated two kinds of marker: kernel-dispatched ones the
PluginKernel calls (Hookable, Initializable) and self-dispatched ones invoked
from the component's own WP callback, not by the kernel (Outputtable, Renderable).
A reader seeing Lifecycle/Renderable wrongly assumes the kernel drives it.

Move Outputtable + Renderable (with their dormant Exceptions/) out to a new
Rendering/ peer concept, keeping the per-marker sub-folder structure that mirrors
Lifecycle/ (consistency over minimizing folders). Lifecycle/ now holds only the
kernel-dispatched Hookable + Initializable, where the name is accurate. Interface
and exception names are unchanged; the two interfaces' cross-references retarget
to the new namespace.

Pure namespace move (git mv, history preserved): no kernel, deptrac, composer, or
phpstan edits — PSR-4 maps the whole Core namespace, deptrac is a namespace-prefix
regex, phpstan analyses by directory. The never-thrown exceptions move as-is;
dropping them is a separate follow-up that would also cover InitializationException.

Gates: PHPStan clean, deptrac 0, Unit 418, Integration 303.

Assisted-by: Claude Code:claude-opus-4-8
---
 .../Outputtable/Exceptions/OutputException.php                | 2 +-
 .../{Lifecycle => Rendering}/Outputtable/Exceptions/index.php | 0
 .../Outputtable/OutputtableInterface.php                      | 4 ++--
 .../core/src/{Lifecycle => Rendering}/Outputtable/index.php   | 0
 .../Renderable/Exceptions/RenderingException.php              | 2 +-
 .../{Lifecycle => Rendering}/Renderable/Exceptions/index.php  | 0
 .../Renderable/RenderableInterface.php                        | 4 ++--
 .../core/src/{Lifecycle => Rendering}/Renderable/index.php    | 0
 packages/core/src/Rendering/index.php                         | 1 +
 .../Outputtable/OutputtableInterfaceContractTest.php          | 4 ++--
 .../Renderable/RenderableInterfaceContractTest.php            | 4 ++--
 11 files changed, 11 insertions(+), 10 deletions(-)
 rename packages/core/src/{Lifecycle => Rendering}/Outputtable/Exceptions/OutputException.php (82%)
 rename packages/core/src/{Lifecycle => Rendering}/Outputtable/Exceptions/index.php (100%)
 rename packages/core/src/{Lifecycle => Rendering}/Outputtable/OutputtableInterface.php (83%)
 rename packages/core/src/{Lifecycle => Rendering}/Outputtable/index.php (100%)
 rename packages/core/src/{Lifecycle => Rendering}/Renderable/Exceptions/RenderingException.php (82%)
 rename packages/core/src/{Lifecycle => Rendering}/Renderable/Exceptions/index.php (100%)
 rename packages/core/src/{Lifecycle => Rendering}/Renderable/RenderableInterface.php (83%)
 rename packages/core/src/{Lifecycle => Rendering}/Renderable/index.php (100%)
 create mode 100644 packages/core/src/Rendering/index.php
 rename packages/core/tests/Unit/{Lifecycle => Rendering}/Outputtable/OutputtableInterfaceContractTest.php (77%)
 rename packages/core/tests/Unit/{Lifecycle => Rendering}/Renderable/RenderableInterfaceContractTest.php (75%)

diff --git a/packages/core/src/Lifecycle/Outputtable/Exceptions/OutputException.php b/packages/core/src/Rendering/Outputtable/Exceptions/OutputException.php
similarity index 82%
rename from packages/core/src/Lifecycle/Outputtable/Exceptions/OutputException.php
rename to packages/core/src/Rendering/Outputtable/Exceptions/OutputException.php
index 7cfdd39..c50fb70 100644
--- a/packages/core/src/Lifecycle/Outputtable/Exceptions/OutputException.php
+++ b/packages/core/src/Rendering/Outputtable/Exceptions/OutputException.php
@@ -1,6 +1,6 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Core\Lifecycle\Outputtable\Exceptions;
+namespace DeepWebSolutions\Framework\Core\Rendering\Outputtable\Exceptions;
 
 use DeepWebSolutions\Framework\Shared\Exception\AbstractRuntimeException;
 
diff --git a/packages/core/src/Lifecycle/Outputtable/Exceptions/index.php b/packages/core/src/Rendering/Outputtable/Exceptions/index.php
similarity index 100%
rename from packages/core/src/Lifecycle/Outputtable/Exceptions/index.php
rename to packages/core/src/Rendering/Outputtable/Exceptions/index.php
diff --git a/packages/core/src/Lifecycle/Outputtable/OutputtableInterface.php b/packages/core/src/Rendering/Outputtable/OutputtableInterface.php
similarity index 83%
rename from packages/core/src/Lifecycle/Outputtable/OutputtableInterface.php
rename to packages/core/src/Rendering/Outputtable/OutputtableInterface.php
index 4ce98aa..faed724 100644
--- a/packages/core/src/Lifecycle/Outputtable/OutputtableInterface.php
+++ b/packages/core/src/Rendering/Outputtable/OutputtableInterface.php
@@ -1,12 +1,12 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Core\Lifecycle\Outputtable;
+namespace DeepWebSolutions\Framework\Core\Rendering\Outputtable;
 
 /**
  * A component that ECHOES user-visible output. For WP surfaces whose callback is
  * expected to print directly — a settings page render, an add_meta_box callback.
  * For surfaces whose callback must RETURN markup (block render_callback, shortcode)
- * use {@see \DeepWebSolutions\Framework\Core\Lifecycle\Renderable\RenderableInterface}.
+ * use {@see \DeepWebSolutions\Framework\Core\Rendering\Renderable\RenderableInterface}.
  * Invoked from the component's own WP callback, not by the kernel.
  *
  * @since   2.0.0
diff --git a/packages/core/src/Lifecycle/Outputtable/index.php b/packages/core/src/Rendering/Outputtable/index.php
similarity index 100%
rename from packages/core/src/Lifecycle/Outputtable/index.php
rename to packages/core/src/Rendering/Outputtable/index.php
diff --git a/packages/core/src/Lifecycle/Renderable/Exceptions/RenderingException.php b/packages/core/src/Rendering/Renderable/Exceptions/RenderingException.php
similarity index 82%
rename from packages/core/src/Lifecycle/Renderable/Exceptions/RenderingException.php
rename to packages/core/src/Rendering/Renderable/Exceptions/RenderingException.php
index d483d53..41f1f47 100644
--- a/packages/core/src/Lifecycle/Renderable/Exceptions/RenderingException.php
+++ b/packages/core/src/Rendering/Renderable/Exceptions/RenderingException.php
@@ -1,6 +1,6 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Core\Lifecycle\Renderable\Exceptions;
+namespace DeepWebSolutions\Framework\Core\Rendering\Renderable\Exceptions;
 
 use DeepWebSolutions\Framework\Shared\Exception\AbstractRuntimeException;
 
diff --git a/packages/core/src/Lifecycle/Renderable/Exceptions/index.php b/packages/core/src/Rendering/Renderable/Exceptions/index.php
similarity index 100%
rename from packages/core/src/Lifecycle/Renderable/Exceptions/index.php
rename to packages/core/src/Rendering/Renderable/Exceptions/index.php
diff --git a/packages/core/src/Lifecycle/Renderable/RenderableInterface.php b/packages/core/src/Rendering/Renderable/RenderableInterface.php
similarity index 83%
rename from packages/core/src/Lifecycle/Renderable/RenderableInterface.php
rename to packages/core/src/Rendering/Renderable/RenderableInterface.php
index 24e07c9..cbabf0b 100644
--- a/packages/core/src/Lifecycle/Renderable/RenderableInterface.php
+++ b/packages/core/src/Rendering/Renderable/RenderableInterface.php
@@ -1,11 +1,11 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Core\Lifecycle\Renderable;
+namespace DeepWebSolutions\Framework\Core\Rendering\Renderable;
 
 /**
  * A component that RETURNS user-visible markup as a string. For WP surfaces whose
  * callback must return (not echo) — a Gutenberg block render_callback, a shortcode
- * handler. For echo surfaces (settings page, metabox) use {@see \DeepWebSolutions\Framework\Core\Lifecycle\Outputtable\OutputtableInterface}.
+ * handler. For echo surfaces (settings page, metabox) use {@see \DeepWebSolutions\Framework\Core\Rendering\Outputtable\OutputtableInterface}.
  * Invoked from the component's own WP callback, not by the kernel.
  *
  * @since   2.0.0
diff --git a/packages/core/src/Lifecycle/Renderable/index.php b/packages/core/src/Rendering/Renderable/index.php
similarity index 100%
rename from packages/core/src/Lifecycle/Renderable/index.php
rename to packages/core/src/Rendering/Renderable/index.php
diff --git a/packages/core/src/Rendering/index.php b/packages/core/src/Rendering/index.php
new file mode 100644
index 0000000..f767346
--- /dev/null
+++ b/packages/core/src/Rendering/index.php
@@ -0,0 +1 @@
+<?php declare( strict_types=1 ); // Silence is golden.
diff --git a/packages/core/tests/Unit/Lifecycle/Outputtable/OutputtableInterfaceContractTest.php b/packages/core/tests/Unit/Rendering/Outputtable/OutputtableInterfaceContractTest.php
similarity index 77%
rename from packages/core/tests/Unit/Lifecycle/Outputtable/OutputtableInterfaceContractTest.php
rename to packages/core/tests/Unit/Rendering/Outputtable/OutputtableInterfaceContractTest.php
index 85b3486..ce6697e 100644
--- a/packages/core/tests/Unit/Lifecycle/Outputtable/OutputtableInterfaceContractTest.php
+++ b/packages/core/tests/Unit/Rendering/Outputtable/OutputtableInterfaceContractTest.php
@@ -1,8 +1,8 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Core\Tests\Unit\Lifecycle\Outputtable;
+namespace DeepWebSolutions\Framework\Core\Tests\Unit\Rendering\Outputtable;
 
-use DeepWebSolutions\Framework\Core\Lifecycle\Outputtable\OutputtableInterface;
+use DeepWebSolutions\Framework\Core\Rendering\Outputtable\OutputtableInterface;
 use PHPUnit\Framework\TestCase;
 
 final class OutputtableInterfaceContractTest extends TestCase {
diff --git a/packages/core/tests/Unit/Lifecycle/Renderable/RenderableInterfaceContractTest.php b/packages/core/tests/Unit/Rendering/Renderable/RenderableInterfaceContractTest.php
similarity index 75%
rename from packages/core/tests/Unit/Lifecycle/Renderable/RenderableInterfaceContractTest.php
rename to packages/core/tests/Unit/Rendering/Renderable/RenderableInterfaceContractTest.php
index a2b6bda..83fa96b 100644
--- a/packages/core/tests/Unit/Lifecycle/Renderable/RenderableInterfaceContractTest.php
+++ b/packages/core/tests/Unit/Rendering/Renderable/RenderableInterfaceContractTest.php
@@ -1,8 +1,8 @@
 <?php declare( strict_types=1 );
 
-namespace DeepWebSolutions\Framework\Core\Tests\Unit\Lifecycle\Renderable;
+namespace DeepWebSolutions\Framework\Core\Tests\Unit\Rendering\Renderable;
 
-use DeepWebSolutions\Framework\Core\Lifecycle\Renderable\RenderableInterface;
+use DeepWebSolutions\Framework\Core\Rendering\Renderable\RenderableInterface;
 use PHPUnit\Framework\TestCase;
 
 final class RenderableInterfaceContractTest extends TestCase {

From 768cf538bda02aef9e20f6f46687c3c4f0fe373b Mon Sep 17 00:00:00 2001
From: Tony Hegyes <a.hegyes@proton.me>
Date: Mon, 22 Jun 2026 15:14:35 +0200
Subject: [PATCH 14/21] fix(utilities): require a positive TTL on
 TransientCache (audit #5)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

set()/remember() defaulted expiration to 0 ("never expires"). WordPress
stores a no-expiry transient autoloaded and never garbage-collects it
(delete_expired_transients reclaims only rows whose _transient_timeout_
row has lapsed). Because flush() only bumps the generation suffix, a
0-expiry row stranded by a flush persisted forever — and autoloaded on
every request.

Make expiration a required positive argument: a non-positive value is
rejected via _doing_it_wrong() and the write skipped, mirroring the
over-long-key guard. Every stored row now carries a timeout and is
reclaimed by WordPress' daily cleanup, including a generation left
unreachable by a flush. flush() stays the O(1) suffix bump; the PAYLOAD
envelope and length guard are unchanged.

Assisted-by: Claude Code:claude-opus-4-8
---
 .../utilities/src/Caching/TransientCache.php  |  51 ++++++--
 .../Caching/TransientCacheTest.php            | 116 +++++++++++++-----
 2 files changed, 124 insertions(+), 43 deletions(-)

diff --git a/packages/utilities/src/Caching/TransientCache.php b/packages/utilities/src/Caching/TransientCache.php
index 0659532..f8b8521 100644
--- a/packages/utilities/src/Caching/TransientCache.php
+++ b/packages/utilities/src/Caching/TransientCache.php
@@ -9,8 +9,10 @@
  * {@see flush()} invalidates the whole group in one option write — no key enumeration. Stored values
  * are wrapped so a cached false/null/0/'' reads back as a hit rather than a transient miss. A key
  * whose full name would exceed WordPress' 172-character transient-name limit is skipped with a
- * _doing_it_wrong() notice; grouped caches should pass an $expiration so flushed rows are reclaimed
- * by WordPress' daily transient cleanup.
+ * _doing_it_wrong() notice. Every entry requires a positive expiration, so each row carries a timeout
+ * and is reclaimed by WordPress' daily transient cleanup once it lapses — including a prior generation
+ * left unreachable by a flush; the generation suffix gives instant group invalidation independent of
+ * that cleanup.
  *
  * @since   2.0.0
  * @version 2.0.0
@@ -80,16 +82,16 @@ public function get( string $key, mixed $default_value = null ): mixed {
 	}
 
 	/**
-	 * Stores a value under a key, optionally expiring it after a number of seconds.
+	 * Stores a value under a key, expiring it after a number of seconds.
 	 *
 	 * @since   2.0.0
 	 * @version 2.0.0
 	 *
 	 * @param   string $key        Key to store under.
 	 * @param   mixed  $value      Value to cache.
-	 * @param   int    $expiration Lifetime in seconds; 0 (default) never expires.
+	 * @param   int    $expiration Lifetime in seconds; must be positive — a non-positive value is rejected and the write skipped.
 	 */
-	public function set( string $key, mixed $value, int $expiration = 0 ): void {
+	public function set( string $key, mixed $value, int $expiration ): void {
 		$full_key = $this->full_key( $key );
 		if ( ! $this->is_within_length( $full_key ) ) {
 			return;
@@ -125,11 +127,11 @@ public function delete( string $key ): bool {
 	 *
 	 * @param   string   $key        Key to look up.
 	 * @param   callable $callback   Producer invoked only on a miss; its return is cached. A thrown exception propagates and caches nothing.
-	 * @param   int      $expiration Lifetime in seconds for a freshly computed value; 0 (default) never expires.
+	 * @param   int      $expiration Lifetime in seconds for a freshly computed value; must be positive — a non-positive value is rejected and the write skipped.
 	 *
 	 * @return  mixed
 	 */
-	public function remember( string $key, callable $callback, int $expiration = 0 ): mixed {
+	public function remember( string $key, callable $callback, int $expiration ): mixed {
 		// Resolve the key once so a concurrent flush() mid-call orphans the write cleanly instead of
 		// splitting the probe and the store across two generations.
 		$full_key = $this->full_key( $key );
@@ -169,13 +171,11 @@ public function flush(): void {
 	 *
 	 * @param   string $full_key   Resolved transient name.
 	 * @param   mixed  $value      Value to wrap and store.
-	 * @param   int    $expiration Lifetime in seconds; 0 never expires.
+	 * @param   int    $expiration Positive lifetime in seconds.
 	 */
 	private function store( string $full_key, mixed $value, int $expiration ): void {
-		if ( 0 === $expiration ) {
-			// WordPress' transient-update path leaves a prior timeout in place, so a no-expiry
-			// re-set would still expire; delete first to keep "0 = no expiry" honest.
-			\delete_transient( $full_key );
+		if ( ! $this->is_positive_expiration( $expiration ) ) {
+			return;
 		}
 
 		\set_transient( $full_key, array( self::PAYLOAD => $value ), $expiration );
@@ -272,5 +272,32 @@ private function is_within_length( string $full_key ): bool {
 		return false;
 	}
 
+	/**
+	 * Reports whether an expiration is positive, warning when it is not.
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 *
+	 * @param   int $expiration Lifetime in seconds.
+	 *
+	 * @return  bool
+	 */
+	private function is_positive_expiration( int $expiration ): bool {
+		if ( $expiration >= 1 ) {
+			return true;
+		}
+
+		\_doing_it_wrong(
+			__METHOD__,
+			\sprintf(
+				'A transient for prefix "%s" needs a positive expiration; %d given, so caching is skipped.',
+				$this->key_prefix,
+				$expiration
+			),
+			'2.0.0'
+		);
+		return false;
+	}
+
 	// endregion
 }
diff --git a/packages/utilities/tests/Integration/Caching/TransientCacheTest.php b/packages/utilities/tests/Integration/Caching/TransientCacheTest.php
index 37128b2..6cd58ea 100644
--- a/packages/utilities/tests/Integration/Caching/TransientCacheTest.php
+++ b/packages/utilities/tests/Integration/Caching/TransientCacheTest.php
@@ -28,7 +28,7 @@ protected function tearDown(): void {
 
 	public function test_set_then_get_round_trips_an_array_payload(): void {
 		$cache = new TransientCache( self::PREFIX );
-		$cache->set( 'k', array( 'a' => 1, 'b' => 2 ) );
+		$cache->set( 'k', array( 'a' => 1, 'b' => 2 ), HOUR_IN_SECONDS );
 
 		self::assertSame( array( 'a' => 1, 'b' => 2 ), $cache->get( 'k' ) );
 	}
@@ -52,7 +52,7 @@ public static function falsy_values(): array {
 	#[DataProvider( 'falsy_values' )]
 	public function test_get_returns_a_stored_falsy_value_as_a_hit( mixed $value ): void {
 		$cache = new TransientCache( self::PREFIX );
-		$cache->set( 'k', $value );
+		$cache->set( 'k', $value, HOUR_IN_SECONDS );
 
 		self::assertSame( $value, $cache->get( 'k', 'sentinel' ) );
 	}
@@ -67,42 +67,93 @@ public function test_get_treats_a_foreign_raw_transient_as_a_miss(): void {
 	public function test_get_unwraps_exactly_one_envelope_layer(): void {
 		$cache  = new TransientCache( self::PREFIX );
 		$shaped = array( TransientCache::PAYLOAD => 'inner' );
-		$cache->set( 'k', $shaped );
+		$cache->set( 'k', $shaped, HOUR_IN_SECONDS );
 
 		self::assertSame( $shaped, $cache->get( 'k' ) );
 	}
 
 	public function test_set_overwrites_an_existing_value(): void {
 		$cache = new TransientCache( self::PREFIX );
-		$cache->set( 'k', 'a' );
-		$cache->set( 'k', 'b' );
+		$cache->set( 'k', 'a', HOUR_IN_SECONDS );
+		$cache->set( 'k', 'b', HOUR_IN_SECONDS );
 
 		self::assertSame( 'b', $cache->get( 'k' ) );
 	}
 
-	public function test_set_with_zero_expiration_clears_a_prior_timeout(): void {
+	public function test_set_with_a_positive_ttl_writes_a_timeout_row(): void {
 		$cache = new TransientCache( self::PREFIX );
-		$cache->set( 'k', 'v', 3600 );
-		self::assertNotFalse( \get_option( '_transient_timeout_' . self::PREFIX . '/k__1' ) );
+		$cache->set( 'ttl', 'v', HOUR_IN_SECONDS );
 
-		$cache->set( 'k', 'v2', 0 );
+		self::assertNotFalse( \get_option( '_transient_timeout_' . self::PREFIX . '/ttl__1' ) );
+	}
 
-		self::assertFalse( \get_option( '_transient_timeout_' . self::PREFIX . '/k__1' ) );
-		self::assertSame( 'v2', $cache->get( 'k' ) );
+	/**
+	 * @return array<string, array{int}>
+	 */
+	public static function non_positive_expirations(): array {
+		return array(
+			'zero'     => array( 0 ),
+			'negative' => array( -1 ),
+		);
 	}
 
-	public function test_set_writes_a_timeout_for_a_ttl_and_none_for_zero(): void {
-		$cache = new TransientCache( self::PREFIX );
-		$cache->set( 'ttl', 'v', 3600 );
-		$cache->set( 'forever', 'v', 0 );
+	#[DataProvider( 'non_positive_expirations' )]
+	public function test_set_with_a_non_positive_expiration_warns_and_stores_nothing( int $expiration ): void {
+		$fired = 0;
+		$spy   = static function () use ( &$fired ) {
+			++$fired;
+		};
+		\add_filter( 'doing_it_wrong_trigger_error', '__return_false' );
+		\add_action( 'doing_it_wrong_run', $spy );
 
-		self::assertNotFalse( \get_option( '_transient_timeout_' . self::PREFIX . '/ttl__1' ) );
-		self::assertFalse( \get_option( '_transient_timeout_' . self::PREFIX . '/forever__1' ) );
+		try {
+			$cache = new TransientCache( self::PREFIX );
+
+			$cache->set( 'k', 'v', $expiration );
+
+			// The write is skipped, so the transient never lands and a read is a miss.
+			self::assertFalse( \get_transient( self::PREFIX . '/k__1' ) );
+			self::assertSame( 'default', $cache->get( 'k', 'default' ) );
+			self::assertGreaterThan( 0, $fired );
+		} finally {
+			\remove_action( 'doing_it_wrong_run', $spy );
+			\remove_filter( 'doing_it_wrong_trigger_error', '__return_false' );
+		}
+	}
+
+	public function test_remember_with_a_non_positive_expiration_runs_once_warns_and_caches_nothing(): void {
+		$fired = 0;
+		$spy   = static function () use ( &$fired ) {
+			++$fired;
+		};
+		\add_filter( 'doing_it_wrong_trigger_error', '__return_false' );
+		\add_action( 'doing_it_wrong_run', $spy );
+
+		try {
+			$cache  = new TransientCache( self::PREFIX );
+			$calls  = 0;
+			$result = $cache->remember(
+				'k',
+				static function () use ( &$calls ) {
+					++$calls;
+					return 'fresh';
+				},
+				0
+			);
+
+			self::assertSame( 'fresh', $result );
+			self::assertSame( 1, $calls );
+			self::assertGreaterThan( 0, $fired );
+			self::assertSame( 'miss', $cache->get( 'k', 'miss' ) );
+		} finally {
+			\remove_action( 'doing_it_wrong_run', $spy );
+			\remove_filter( 'doing_it_wrong_trigger_error', '__return_false' );
+		}
 	}
 
 	public function test_get_returns_default_after_expiry_and_remember_recomputes(): void {
 		$cache = new TransientCache( self::PREFIX );
-		$cache->set( 'k', 'v', 3600 );
+		$cache->set( 'k', 'v', HOUR_IN_SECONDS );
 
 		// Backdate the timeout so the next read sees an expired transient (no real sleep).
 		\update_option( '_transient_timeout_' . self::PREFIX . '/k__1', \time() - 1 );
@@ -114,7 +165,8 @@ public function test_get_returns_default_after_expiry_and_remember_recomputes():
 			static function () use ( &$calls ) {
 				++$calls;
 				return 'fresh';
-			}
+			},
+			HOUR_IN_SECONDS
 		);
 
 		self::assertSame( 'fresh', $result );
@@ -123,7 +175,7 @@ static function () use ( &$calls ) {
 
 	public function test_delete_returns_true_when_present_and_false_when_absent(): void {
 		$cache = new TransientCache( self::PREFIX );
-		$cache->set( 'k', 'v' );
+		$cache->set( 'k', 'v', HOUR_IN_SECONDS );
 
 		self::assertTrue( $cache->delete( 'k' ) );
 		self::assertSame( 'gone', $cache->get( 'k', 'gone' ) );
@@ -139,7 +191,8 @@ public function test_remember_runs_the_callback_once_on_a_miss(): void {
 			static function () use ( &$calls ) {
 				++$calls;
 				return 'computed';
-			}
+			},
+			HOUR_IN_SECONDS
 		);
 
 		self::assertSame( 'computed', $result );
@@ -155,8 +208,8 @@ public function test_remember_does_not_rerun_the_callback_on_a_hit(): void {
 			return 'v';
 		};
 
-		$cache->remember( 'k', $callback );
-		$cache->remember( 'k', $callback );
+		$cache->remember( 'k', $callback, HOUR_IN_SECONDS );
+		$cache->remember( 'k', $callback, HOUR_IN_SECONDS );
 
 		self::assertSame( 1, $calls );
 	}
@@ -169,8 +222,8 @@ public function test_remember_caches_a_falsy_result_without_rerunning(): void {
 			return false;
 		};
 
-		self::assertFalse( $cache->remember( 'k', $callback ) );
-		self::assertFalse( $cache->remember( 'k', $callback ) );
+		self::assertFalse( $cache->remember( 'k', $callback, HOUR_IN_SECONDS ) );
+		self::assertFalse( $cache->remember( 'k', $callback, HOUR_IN_SECONDS ) );
 		self::assertSame( 1, $calls );
 	}
 
@@ -182,7 +235,8 @@ public function test_remember_propagates_a_callback_exception_and_caches_nothing
 				'k',
 				static function (): never {
 					throw new \RuntimeException( 'boom' );
-				}
+				},
+				HOUR_IN_SECONDS
 			);
 			self::fail( 'Expected the callback exception to propagate.' );
 		} catch ( \RuntimeException $e ) {
@@ -194,7 +248,7 @@ static function (): never {
 
 	public function test_flush_bumps_the_suffix_and_invalidates_the_group(): void {
 		$cache = new TransientCache( self::PREFIX );
-		$cache->set( 'k', 'v' );
+		$cache->set( 'k', 'v', HOUR_IN_SECONDS );
 
 		// Fresh prefix: the suffix defaults to 1 lazily, so no option row exists yet.
 		self::assertFalse( \get_option( self::PREFIX . '_cache_invalidation_suffix' ) );
@@ -210,7 +264,7 @@ public function test_a_corrupt_suffix_degrades_to_generation_one(): void {
 		\update_option( self::PREFIX . '_cache_invalidation_suffix', 'foo' );
 
 		$cache = new TransientCache( self::PREFIX );
-		$cache->set( 'k', 'v' );
+		$cache->set( 'k', 'v', HOUR_IN_SECONDS );
 
 		self::assertNotFalse( \get_transient( self::PREFIX . '/k__1' ) );
 		self::assertSame( 'v', $cache->get( 'k' ) );
@@ -220,10 +274,10 @@ public function test_prefixes_are_isolated_from_each_other(): void {
 		$a = new TransientCache( self::PREFIX );
 		$b = new TransientCache( self::PREFIX2 );
 
-		$a->set( 'k', 'from-a' );
+		$a->set( 'k', 'from-a', HOUR_IN_SECONDS );
 		self::assertSame( 'none', $b->get( 'k', 'none' ) );
 
-		$b->set( 'k', 'from-b' );
+		$b->set( 'k', 'from-b', HOUR_IN_SECONDS );
 		$a->flush();
 
 		self::assertSame( 'from-b', $b->get( 'k', 'none' ) );
@@ -242,7 +296,7 @@ public function test_an_over_long_key_triggers_the_guard_and_skips_caching(): vo
 			$cache = new TransientCache( self::PREFIX );
 			$long  = \str_repeat( 'x', 300 );
 
-			$cache->set( $long, 'v' );
+			$cache->set( $long, 'v', HOUR_IN_SECONDS );
 
 			// set() must skip the write entirely — nothing is stored under the over-long name.
 			self::assertFalse( \get_transient( self::PREFIX . '/' . $long . '__1' ) );

From 7d503004067283ec4e2991dca35df46f5e1459a6 Mon Sep 17 00:00:00 2001
From: Tony Hegyes <a.hegyes@proton.me>
Date: Mon, 22 Jun 2026 15:42:33 +0200
Subject: [PATCH 15/21] refactor(shared): wire InvalidVersionException onto the
 VO-exception base (audit #3)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

InvalidValueObjectException was an abstract base with zero production
subclasses — even Version's invalidity exception extended the generic
AbstractInvalidArgumentException directly, leaving the base unused.

Adopt it as the value-object-exception family base instead of deleting
it: InvalidVersionException now extends it, supplying value_object_type
=> 'Version', so VO-invalidity exceptions share one message format and a
single catch (InvalidValueObjectException) point. Reword Version's two
throw reasons to read cleanly after the base's message prefix. Document
the convention and sanction the abstract in AGENTS.md — a family of
distinct catchable subtypes sharing message-building intrinsically needs
the subtype hierarchy; descriptor-invalidity exceptions still extend the
generic bases directly.

Assisted-by: Claude Code:claude-opus-4-8
---
 AGENTS.md                                        |  3 +++
 .../Exceptions/InvalidValueObjectException.php   |  4 ++++
 .../Exceptions/InvalidVersionException.php       | 16 ++++++++++++++--
 packages/shared/src/Version/Version.php          |  4 ++--
 .../shared/tests/Unit/Version/VersionTest.php    | 12 ++++++++++++
 5 files changed, 35 insertions(+), 4 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 70cf1b0..757039e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -193,6 +193,7 @@ Exception, narrow and verified: patterns whose value depends on abstract-base sc
 
 1. **Sealed-type simulation.** `Result<TValue, TError>` requires `abstract AbstractResult` + `final Success` + `final Failure` to fake a union type PHP doesn't natively support. Substituting pure interfaces drops `match()` ergonomics and the shared `is_success`/`is_failure` derivation.
 2. **Reflection-driven shared behavior.** `AbstractValueObject::equals()` walks public properties via reflection and works for ANY subclass without each subclass reimplementing equality. Pure interface + per-class implementation forces every VO to duplicate equality logic — defeating the point of the base.
+3. **Exception-family subtyping.** `InvalidValueObjectException` (`shared/ValueObject/Exceptions/`) is the abstract base each value object's invalidity exception extends (`InvalidVersionException` supplies its `value_object_type`), so the family shares one message format and a single `catch ( InvalidValueObjectException )` point. The abstract is intrinsic: exceptions dispatch by type, so a family of distinct catchable subtypes sharing message-building needs the subtype hierarchy — a lone `final` class collapses the subtypes, and composition yields no catchable type. Descriptors are not value objects, so their invalidity exceptions extend the generic `Abstract{InvalidArgument,Runtime}Exception` bases directly.
 
 These exceptions live in `wp-framework-shared` (runtime-WP-aware substrate; the only legitimate home for abstract-base scaffolding). Consumer plugins MAY extend these abstract bases (e.g., `PluginHeader extends AbstractValueObject`); they MUST NOT introduce new abstract base hierarchies of their own without similar intrinsic-requirement justification.
 
@@ -373,3 +374,5 @@ One rule replaces three improvised conventions. An interface lives at the ROOT o
 ### Component grammar — value object vs descriptor (2026-06-21)
 
 `ValueObjects/` folders hold immutable carriers of two kinds; the folder name is kept, and the kinds are distinguished by base class + docblock, not by a marker interface. **Value object** — extends `Shared\ValueObject\AbstractValueObject`; use ONLY when reflection-driven structural `equals()` / `jsonSerialize()` is actually consumed and every public property can participate safely in structural equality (`PluginHeader`, `Version`); its docblock opens "Value object …". **Descriptor** — a bare `final readonly` class with no base; the default immutable carrier, and REQUIRED when it holds closures/callables, runtime providers, or WordPress/WooCommerce objects (`SettingsField`, `SettingsPage`, `SettingsSection`, `ObjectMetaBox`, `AdminNotice`, `DependencyRequirement`); its docblock opens "Descriptor for …". A marker `DescriptorInterface` is deferred until real code must typehint a polymorphic descriptor collection — a taxonomy-only marker is ceremony (service interfaces only on plurality).
+
+**Invalidity exceptions follow the same split.** A value object's invalidity exception extends `Shared\ValueObject\Exceptions\InvalidValueObjectException` (the VO-exception-family base), supplying its `value_object_type` — e.g. `InvalidVersionException` for `Version`. A descriptor's invalidity exception extends the generic `Abstract{InvalidArgument,Runtime}Exception` base directly (`InvalidSettingsFieldException`, …) — it is not a value object. The base is the one sanctioned abstract-exception family (see the abstract-base-classes block).
diff --git a/packages/shared/src/ValueObject/Exceptions/InvalidValueObjectException.php b/packages/shared/src/ValueObject/Exceptions/InvalidValueObjectException.php
index 4be0593..28264cb 100644
--- a/packages/shared/src/ValueObject/Exceptions/InvalidValueObjectException.php
+++ b/packages/shared/src/ValueObject/Exceptions/InvalidValueObjectException.php
@@ -7,6 +7,10 @@
 /**
  * Base class for exceptions raised when a value object invariant is violated.
  *
+ * Each value object's invalidity exception extends this and supplies its
+ * `value_object_type`, so the family shares one message format and a single
+ * catch point (`catch ( InvalidValueObjectException )`).
+ *
  * @since   2.0.0
  * @version 2.0.0
  */
diff --git a/packages/shared/src/Version/Exceptions/InvalidVersionException.php b/packages/shared/src/Version/Exceptions/InvalidVersionException.php
index c4caedb..6e8a61b 100644
--- a/packages/shared/src/Version/Exceptions/InvalidVersionException.php
+++ b/packages/shared/src/Version/Exceptions/InvalidVersionException.php
@@ -2,7 +2,7 @@
 
 namespace DeepWebSolutions\Framework\Shared\Version\Exceptions;
 
-use DeepWebSolutions\Framework\Shared\Exception\AbstractInvalidArgumentException;
+use DeepWebSolutions\Framework\Shared\ValueObject\Exceptions\InvalidValueObjectException;
 
 /**
  * Thrown when a string cannot be parsed into a valid Version value object.
@@ -10,4 +10,16 @@
  * @since   2.0.0
  * @version 2.0.0
  */
-final class InvalidVersionException extends AbstractInvalidArgumentException {}
+final class InvalidVersionException extends InvalidValueObjectException {
+	/**
+	 * Identifies the owning value object in invalidity messages.
+	 *
+	 * @since   2.0.0
+	 * @version 2.0.0
+	 *
+	 * @var     string
+	 */
+	protected string $value_object_type {
+		get => 'Version';
+	}
+}
diff --git a/packages/shared/src/Version/Version.php b/packages/shared/src/Version/Version.php
index 6b64d3c..5a1c1c9 100644
--- a/packages/shared/src/Version/Version.php
+++ b/packages/shared/src/Version/Version.php
@@ -109,7 +109,7 @@ public static function from_string( string $value ): self {
 		$pattern = '/^\d+(\.\d+){0,2}(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$/';
 		if ( 1 !== \preg_match( $pattern, $value ) ) {
 			// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- framework-internal exception; never reaches an HTML output context unescaped.
-			throw new InvalidVersionException( "Invalid version string: '$value'" );
+			throw new InvalidVersionException( "'$value' does not parse as a version" );
 		}
 
 		return new self( $value );
@@ -136,7 +136,7 @@ public static function from_string( string $value ): self {
 	 */
 	public static function from_parts( int $major, ?int $minor = null, ?int $patch = null, ?string $prerelease = null, ?string $build = null ): self {
 		if ( null === $minor && null !== $patch ) {
-			throw new InvalidVersionException( 'Patch version requires a minor version.' );
+			throw new InvalidVersionException( 'a patch version requires a minor version' );
 		}
 
 		$value  = (string) $major;
diff --git a/packages/shared/tests/Unit/Version/VersionTest.php b/packages/shared/tests/Unit/Version/VersionTest.php
index b937149..d8ed0a7 100644
--- a/packages/shared/tests/Unit/Version/VersionTest.php
+++ b/packages/shared/tests/Unit/Version/VersionTest.php
@@ -3,6 +3,7 @@
 namespace DeepWebSolutions\Framework\Shared\Tests\Unit\Version;
 
 use DeepWebSolutions\Framework\Shared\ValueObject\AbstractValueObject;
+use DeepWebSolutions\Framework\Shared\ValueObject\Exceptions\InvalidValueObjectException;
 use DeepWebSolutions\Framework\Shared\Version\Version;
 use DeepWebSolutions\Framework\Shared\Version\Exceptions\InvalidVersionException;
 use PHPUnit\Framework\Attributes\CoversClass;
@@ -12,6 +13,7 @@
 
 #[CoversClass( Version::class )]
 #[UsesClass( InvalidVersionException::class )]
+#[UsesClass( InvalidValueObjectException::class )]
 #[UsesClass( AbstractValueObject::class )]
 #[UsesFunction( 'DeepWebSolutions\Framework\Shared\Reflection\get_public_property_names' )]
 final class VersionTest extends TestCase {
@@ -109,4 +111,14 @@ public function test_equals_inherited_from_abstract_value_object(): void {
 		$b = Version::from_string( '2.0.0' );
 		self::assertTrue( $a->equals( $b ) );
 	}
+
+	public function test_invalid_version_exception_is_a_value_object_exception_naming_the_type(): void {
+		try {
+			Version::from_string( 'not-a-version' );
+			self::fail( 'Expected InvalidVersionException.' );
+		} catch ( InvalidVersionException $e ) {
+			self::assertInstanceOf( InvalidValueObjectException::class, $e );
+			self::assertStringContainsString( 'Version', $e->getMessage() );
+		}
+	}
 }

From a1317c4858ab37d0eb186693de422558958d23f7 Mon Sep 17 00:00:00 2001
From: Tony Hegyes <a.hegyes@proton.me>
Date: Mon, 22 Jun 2026 16:32:04 +0200
Subject: [PATCH 16/21] docs(framework): record contested audit resolutions #2
 + #24
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

#2 — DeprecatedHooksDispatcher is kept as a recorded speculative exception
(zero consumers, no v1 precedent, closed ecosystem), so the build-ahead
boundary stays principled rather than arbitrary.

#24 — Error/ErrorInterface is kept distinct, not folded into Result/: it is
load-bearing via SchedulingError, the TError bound across AbstractResult /
Failure, and the counterpart to ExceptionInterface in the error-vs-exception
split. Folding would couple a backend-agnostic error marker to the Result
carrier and collapse that boundary.

Assisted-by: Claude Code:claude-opus-4-8
---
 AGENTS.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 757039e..88b520e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -376,3 +376,11 @@ One rule replaces three improvised conventions. An interface lives at the ROOT o
 `ValueObjects/` folders hold immutable carriers of two kinds; the folder name is kept, and the kinds are distinguished by base class + docblock, not by a marker interface. **Value object** — extends `Shared\ValueObject\AbstractValueObject`; use ONLY when reflection-driven structural `equals()` / `jsonSerialize()` is actually consumed and every public property can participate safely in structural equality (`PluginHeader`, `Version`); its docblock opens "Value object …". **Descriptor** — a bare `final readonly` class with no base; the default immutable carrier, and REQUIRED when it holds closures/callables, runtime providers, or WordPress/WooCommerce objects (`SettingsField`, `SettingsPage`, `SettingsSection`, `ObjectMetaBox`, `AdminNotice`, `DependencyRequirement`); its docblock opens "Descriptor for …". A marker `DescriptorInterface` is deferred until real code must typehint a polymorphic descriptor collection — a taxonomy-only marker is ceremony (service interfaces only on plurality).
 
 **Invalidity exceptions follow the same split.** A value object's invalidity exception extends `Shared\ValueObject\Exceptions\InvalidValueObjectException` (the VO-exception-family base), supplying its `value_object_type` — e.g. `InvalidVersionException` for `Version`. A descriptor's invalidity exception extends the generic `Abstract{InvalidArgument,Runtime}Exception` base directly (`InvalidSettingsFieldException`, …) — it is not a value object. The base is the one sanctioned abstract-exception family (see the abstract-base-classes block).
+
+### DeprecatedHooksDispatcher: speculative-by-choice (2026-06-22)
+
+`utilities/Hooks/DeprecatedHooksDispatcher` (fires a current hook plus a deprecated legacy alias in lock-step via WP's `do_action_deprecated()` / `apply_filters_deprecated()`) has zero consumers and no v1 precedent — it does NOT clear the demand-certain build-ahead bar (no archive call sites; the closed ecosystem has no third-party hook consumers a legacy alias would serve). It is KEPT as a deliberate, recorded speculative exception, not an oversight: a v2 plugin that renames a public hook is the obvious consumer, the primitive is self-contained and tested, and recording it keeps the build-ahead boundary principled rather than arbitrary. This is the one consciously-speculative utility in the framework.
+
+### Error/ErrorInterface: kept distinct, not folded into Result/ (2026-06-22)
+
+Considered folding `shared/Error/ErrorInterface` into `Result/` (it reads as a single-file folder). KEPT. It is load-bearing beyond `Result`: `utilities/Scheduling/Errors/SchedulingError` implements it, it is the `TError` bound across `AbstractResult` / `Failure`, and it is the deliberate counterpart to `Exception/ExceptionInterface` — the error-vs-exception split (errors are expected-failure-as-data carried by `Failure`; exceptions are unexpected and propagate via throw/catch). Folding it into `Result/` would couple a backend-agnostic error marker to the Result carrier (forcing `SchedulingError` to depend on `Result/`) and collapse that semantic boundary. The folder mirrors `Exception/` and earns its place.

From cda3713e1b246c65f255204b7df1c9a80b776ef0 Mon Sep 17 00:00:00 2001
From: Tony Hegyes <a.hegyes@proton.me>
Date: Mon, 22 Jun 2026 16:40:23 +0200
Subject: [PATCH 17/21] refactor(framework): default to protected over private
 (audit #21)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The standard prefers protected over private — on final classes the two are
behaviorally identical, and protected forward-designs against a later
un-final (no need to remember to widen visibility, and there is no perf
cost). The src had drifted to private throughout; flip all 160 private
member declarations across packages/*/src to protected.

Visibility-only: every changed line is exactly private -> protected, with
no logic/name/signature/docblock change (verified line-by-line). The two
private(set) asymmetric-visibility write-guards (HooksService::$handlers,
AdminNoticesService::$stores) are deliberate and left as-is.

Assisted-by: Claude Code:claude-opus-4-8
---
 packages/core/src/PluginKernel.php            | 20 +++++-----
 .../src/Backend/WordPressSettingsBackend.php  | 28 ++++++-------
 .../settings/src/Schema/FieldProcessor.php    | 12 +++---
 .../settings/src/Schema/FieldRenderer.php     | 20 +++++-----
 packages/shared/src/Result/Failure.php        |  2 +-
 packages/shared/src/Result/Success.php        |  2 +-
 packages/shared/src/Version/Version.php       |  2 +-
 packages/storage/src/MemoryStore.php          |  2 +-
 packages/storage/src/OptionsStore.php         |  8 ++--
 packages/storage/src/UserMetaStore.php        |  8 ++--
 .../src/AdminNotices/AdminNoticesService.php  |  6 +--
 .../DependencyAdminNoticeRenderer.php         | 16 ++++----
 .../AdminNotices/DismissedNoticesTracker.php  |  2 +-
 .../src/AdminNotices/NoticeStore.php          |  4 +-
 .../utilities/src/Caching/TransientCache.php  | 18 ++++-----
 .../Context/CurrentUserCanConditional.php     |  2 +-
 .../PHPExtensionLoadedConditional.php         |  2 +-
 .../PHPFunctionExistsConditional.php          |  2 +-
 .../Dependencies/PHPIniSizeConditional.php    |  4 +-
 .../Dependencies/PHPVersionConditional.php    |  2 +-
 .../WPPluginActiveConditional.php             |  2 +-
 .../Dependencies/WPVersionConditional.php     |  2 +-
 .../Hooks/Handlers/BufferedHookHandler.php    |  4 +-
 .../src/Hooks/Handlers/DirectHookHandler.php  |  4 +-
 .../src/Hooks/Handlers/ScopedHookHandler.php  |  8 ++--
 packages/utilities/src/Hooks/HookRegistry.php |  6 +--
 packages/utilities/src/Hooks/HooksService.php |  2 +-
 .../Backends/ActionSchedulerBackend.php       |  8 ++--
 .../src/Scheduling/Backends/WPCronBackend.php | 16 ++++----
 .../utilities/src/Scheduling/Scheduler.php    |  2 +-
 .../DescriptorBackedWCSettingsPage.php        |  6 +--
 .../src/Backend/WCSettingsBuilder.php         | 12 +++---
 .../Backend/WooCommerceSettingsBackend.php    | 12 +++---
 .../src/OrderData/OrderFieldStore.php         | 28 ++++++-------
 .../ProductData/ProductDataFieldRenderer.php  |  6 +--
 .../src/ProductData/ProductDataFieldStore.php | 40 +++++++++----------
 36 files changed, 160 insertions(+), 160 deletions(-)

diff --git a/packages/core/src/PluginKernel.php b/packages/core/src/PluginKernel.php
index 2466726..daee222 100644
--- a/packages/core/src/PluginKernel.php
+++ b/packages/core/src/PluginKernel.php
@@ -37,7 +37,7 @@ final class PluginKernel {
 	 *
 	 * @var     bool
 	 */
-	private bool $booted = false;
+	protected bool $booted = false;
 
 	// endregion
 
@@ -53,8 +53,8 @@ final class PluginKernel {
 	 * @param   LoggerInterface|null $logger Optional logger; names each Feature or component the kernel gates out and reports a failed installer routine.
 	 */
 	public function __construct(
-		private readonly PluginInterface $plugin,
-		private readonly ?LoggerInterface $logger = null,
+		protected readonly PluginInterface $plugin,
+		protected readonly ?LoggerInterface $logger = null,
 	) {}
 
 	// endregion
@@ -169,7 +169,7 @@ public function boot(): void {
 	 *
 	 * @return  bool True when the boot may proceed; false when the routine failed.
 	 */
-	private function run_installer(): bool {
+	protected function run_installer(): bool {
 		$installer = $this->plugin->get_installer();
 
 		try {
@@ -211,7 +211,7 @@ private function run_installer(): bool {
 	 *
 	 * @return  bool
 	 */
-	private function are_conditionals_met( string $feature_class, ContainerInterface $container ): bool {
+	protected function are_conditionals_met( string $feature_class, ContainerInterface $container ): bool {
 		foreach ( $feature_class::get_conditional_classes() as $conditional_class ) {
 			$conditional = $container->get( $conditional_class );
 
@@ -251,7 +251,7 @@ private function are_conditionals_met( string $feature_class, ContainerInterface
 	 *
 	 * @throws  FeatureException When a component class appears more than once in the graph.
 	 */
-	private function assert_unique_component_graph( array $features ): void {
+	protected function assert_unique_component_graph( array $features ): void {
 		/** @var array<class-string, true> $seen */
 		$seen = array();
 		foreach ( $features as $feature ) {
@@ -273,7 +273,7 @@ private function assert_unique_component_graph( array $features ): void {
 	 *
 	 * @throws  FeatureException When the class has already been seen.
 	 */
-	private function assert_component_not_duplicated( string $component_class, array &$seen ): void {
+	protected function assert_component_not_duplicated( string $component_class, array &$seen ): void {
 		if ( isset( $seen[ $component_class ] ) ) {
 			// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- framework-internal exception; never reaches an HTML output context unescaped.
 			throw new FeatureException( 'Component ' . $component_class . ' is registered more than once; a component may belong to a single parent.' );
@@ -300,7 +300,7 @@ private function assert_component_not_duplicated( string $component_class, array
 	 *
 	 * @return  list<object>
 	 */
-	private function collect_runnable_components( array $features, ContainerInterface $container ): array {
+	protected function collect_runnable_components( array $features, ContainerInterface $container ): array {
 		/** @var list<object> $runnable */
 		$runnable = array();
 		foreach ( $features as $feature ) {
@@ -323,7 +323,7 @@ private function collect_runnable_components( array $features, ContainerInterfac
 	 * @param   ContainerInterface $container       Plugin container.
 	 * @param   list<object>       $runnable        Accumulating runnable list, by reference.
 	 */
-	private function collect_runnable_subtree( string $component_class, ContainerInterface $container, array &$runnable ): void {
+	protected function collect_runnable_subtree( string $component_class, ContainerInterface $container, array &$runnable ): void {
 		/** @var object $component */
 		$component = $container->get( $component_class );
 
@@ -359,7 +359,7 @@ private function collect_runnable_subtree( string $component_class, ContainerInt
 	 *
 	 * @return  bool
 	 */
-	private function is_runnable( object $component ): bool {
+	protected function is_runnable( object $component ): bool {
 		if ( $component instanceof EnabledInterface && ! $component->is_enabled() ) {
 			return false;
 		}
diff --git a/packages/settings/src/Backend/WordPressSettingsBackend.php b/packages/settings/src/Backend/WordPressSettingsBackend.php
index b23a6b3..08530cf 100644
--- a/packages/settings/src/Backend/WordPressSettingsBackend.php
+++ b/packages/settings/src/Backend/WordPressSettingsBackend.php
@@ -37,7 +37,7 @@ final class WordPressSettingsBackend implements SettingsBackendInterface {
 	 *
 	 * @var     ?SettingsPage
 	 */
-	private ?SettingsPage $page = null;
+	protected ?SettingsPage $page = null;
 
 	/**
 	 * Map of field id to the id of the section that declares it.
@@ -47,7 +47,7 @@ final class WordPressSettingsBackend implements SettingsBackendInterface {
 	 *
 	 * @var     array<string, string>
 	 */
-	private array $field_section = array();
+	protected array $field_section = array();
 
 	/**
 	 * Per-section option-store cache, keyed by section id.
@@ -57,7 +57,7 @@ final class WordPressSettingsBackend implements SettingsBackendInterface {
 	 *
 	 * @var     array<string, OptionsStore<mixed>>
 	 */
-	private array $stores = array();
+	protected array $stores = array();
 
 	/**
 	 * Depth of in-progress programmatic writes; the backend's own writes, which may nest, bypass the form sanitizer.
@@ -67,7 +67,7 @@ final class WordPressSettingsBackend implements SettingsBackendInterface {
 	 *
 	 * @var     int
 	 */
-	private int $writing = 0;
+	protected int $writing = 0;
 
 	// endregion
 
@@ -84,9 +84,9 @@ final class WordPressSettingsBackend implements SettingsBackendInterface {
 	 * @param   FieldProcessor   $processor Processor for sanitizing submitted values.
 	 */
 	public function __construct(
-		private ?LoggerInterface $logger = null,
-		private FieldRenderer $renderer = new FieldRenderer(),
-		private FieldProcessor $processor = new FieldProcessor(),
+		protected ?LoggerInterface $logger = null,
+		protected FieldRenderer $renderer = new FieldRenderer(),
+		protected FieldProcessor $processor = new FieldProcessor(),
 	) {}
 
 	// endregion
@@ -184,7 +184,7 @@ public function delete( string $field_id ): bool {
 	 *
 	 * @return  array<string, string>
 	 */
-	private function map_fields( SettingsPage $page ): array {
+	protected function map_fields( SettingsPage $page ): array {
 		$map      = array();
 		$sections = array();
 		foreach ( $page->sections as $section ) {
@@ -218,7 +218,7 @@ private function map_fields( SettingsPage $page ): array {
 	 *
 	 * @return  OptionsStore<mixed>
 	 */
-	private function store_for( string $field_id ): OptionsStore {
+	protected function store_for( string $field_id ): OptionsStore {
 		if ( null === $this->page || ! \array_key_exists( $field_id, $this->field_section ) ) {
 			// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- framework-internal exception; never reaches an HTML output context unescaped.
 			throw new InvalidSettingsFieldException( "Settings field '$field_id' is not registered on this page." );
@@ -237,7 +237,7 @@ private function store_for( string $field_id ): OptionsStore {
 	 *
 	 * @param   SettingsPage $page Page to add.
 	 */
-	private function add_menu( SettingsPage $page ): void {
+	protected function add_menu( SettingsPage $page ): void {
 		// WordPress only wptexturizes the submenu menu_title before printing it (page_title is strip_tagged
 		// for the document title and escaped in render_page), so the menu title is escaped here.
 		\add_submenu_page(
@@ -258,7 +258,7 @@ private function add_menu( SettingsPage $page ): void {
 	 *
 	 * @param   SettingsPage $page Page whose sections to register.
 	 */
-	private function register_settings( SettingsPage $page ): void {
+	protected function register_settings( SettingsPage $page ): void {
 		foreach ( $page->sections as $section ) {
 			$option_name = $page->slug . '-' . $section->id;
 
@@ -283,7 +283,7 @@ private function register_settings( SettingsPage $page ): void {
 	 *
 	 * @param   SettingsPage $page Page to render.
 	 */
-	private function render_page( SettingsPage $page ): void {
+	protected function render_page( SettingsPage $page ): void {
 		echo '<div class="wrap"><h1>' . \esc_html( $page->page_title ) . '</h1>';
 
 		foreach ( $page->sections as $section ) {
@@ -318,7 +318,7 @@ private function render_page( SettingsPage $page ): void {
 	 * @param   string        $option_name Section option the field persists into.
 	 * @param   SettingsField $field       Field to render.
 	 */
-	private function render_field( string $option_name, SettingsField $field ): void {
+	protected function render_field( string $option_name, SettingsField $field ): void {
 		$stored = \get_option( $option_name, array() );
 		$value  = \is_array( $stored ) && \array_key_exists( $field->id, $stored ) ? $stored[ $field->id ] : $field->default;
 
@@ -344,7 +344,7 @@ private function render_field( string $option_name, SettingsField $field ): void
 	 *
 	 * @return  mixed
 	 */
-	private function sanitize( SettingsSection $section, string $option_name, mixed $input ): mixed {
+	protected function sanitize( SettingsSection $section, string $option_name, mixed $input ): mixed {
 		if ( $this->writing > 0 ) {
 			return $input;
 		}
diff --git a/packages/settings/src/Schema/FieldProcessor.php b/packages/settings/src/Schema/FieldProcessor.php
index 6648044..734ebad 100644
--- a/packages/settings/src/Schema/FieldProcessor.php
+++ b/packages/settings/src/Schema/FieldProcessor.php
@@ -36,8 +36,8 @@ final class FieldProcessor {
 	 * @param   array<string, CustomFieldType> $custom_types Registry of types outside the taxonomy whose submissions are accepted, keyed by type token.
 	 */
 	public function __construct(
-		private OptionsResolver $resolver = new OptionsResolver(),
-		private array $custom_types = array(),
+		protected OptionsResolver $resolver = new OptionsResolver(),
+		protected array $custom_types = array(),
 	) {}
 
 	// endregion
@@ -116,7 +116,7 @@ public function process( SettingsField $field, array $input ): mixed {
 	 *
 	 * @return  mixed
 	 */
-	private function process_custom( SettingsField $field, array $input ): mixed {
+	protected function process_custom( SettingsField $field, array $input ): mixed {
 		if ( ! \array_key_exists( $field->id, $input ) ) {
 			return $field->default;
 		}
@@ -144,7 +144,7 @@ private function process_custom( SettingsField $field, array $input ): mixed {
 	 *
 	 * @return  mixed
 	 */
-	private function sanitize_and_validate( SettingsField $field, mixed $value, mixed $rejected ): mixed {
+	protected function sanitize_and_validate( SettingsField $field, mixed $value, mixed $rejected ): mixed {
 		if ( null !== $field->sanitize ) {
 			$value = ( $field->sanitize )( $value );
 		}
@@ -166,7 +166,7 @@ private function sanitize_and_validate( SettingsField $field, mixed $value, mixe
 	 *
 	 * @return  bool
 	 */
-	private function is_option( mixed $value, SettingsField $field ): bool {
+	protected function is_option( mixed $value, SettingsField $field ): bool {
 		return ( \is_string( $value ) || \is_int( $value ) )
 			&& \array_key_exists( $value, $this->resolver->resolve( $field->options ) );
 	}
@@ -182,7 +182,7 @@ private function is_option( mixed $value, SettingsField $field ): bool {
 	 *
 	 * @return  list<int|string>
 	 */
-	private function filter_to_options( mixed $value, SettingsField $field ): array {
+	protected function filter_to_options( mixed $value, SettingsField $field ): array {
 		$options = $this->resolver->resolve( $field->options );
 		$values  = \is_array( $value ) ? $value : array();
 
diff --git a/packages/settings/src/Schema/FieldRenderer.php b/packages/settings/src/Schema/FieldRenderer.php
index 86abbaf..99f4d8f 100644
--- a/packages/settings/src/Schema/FieldRenderer.php
+++ b/packages/settings/src/Schema/FieldRenderer.php
@@ -35,8 +35,8 @@ final class FieldRenderer {
 	 * @param   array<string, CustomFieldType> $custom_types Registry of render seams for types outside the taxonomy, keyed by type token.
 	 */
 	public function __construct(
-		private OptionsResolver $resolver = new OptionsResolver(),
-		private array $custom_types = array(),
+		protected OptionsResolver $resolver = new OptionsResolver(),
+		protected array $custom_types = array(),
 	) {}
 
 	// endregion
@@ -96,7 +96,7 @@ public function render( SettingsField $field, mixed $value, string $name ): stri
 	 *
 	 * @return  string
 	 */
-	private function render_input( SettingsField $field, mixed $value, string $name, FieldType $type ): string {
+	protected function render_input( SettingsField $field, mixed $value, string $name, FieldType $type ): string {
 		return \sprintf(
 			'<input type="%s" name="%s" value="%s"%s />',
 			\esc_attr( $type->value ),
@@ -118,7 +118,7 @@ private function render_input( SettingsField $field, mixed $value, string $name,
 	 *
 	 * @return  string
 	 */
-	private function render_textarea( SettingsField $field, mixed $value, string $name ): string {
+	protected function render_textarea( SettingsField $field, mixed $value, string $name ): string {
 		return \sprintf(
 			'<textarea name="%s"%s>%s</textarea>',
 			\esc_attr( $name ),
@@ -139,7 +139,7 @@ private function render_textarea( SettingsField $field, mixed $value, string $na
 	 *
 	 * @return  string
 	 */
-	private function render_checkbox( SettingsField $field, mixed $value, string $name ): string {
+	protected function render_checkbox( SettingsField $field, mixed $value, string $name ): string {
 		return \sprintf(
 			'<input type="checkbox" name="%s" value="1"%s%s />',
 			\esc_attr( $name ),
@@ -161,7 +161,7 @@ private function render_checkbox( SettingsField $field, mixed $value, string $na
 	 *
 	 * @return  string
 	 */
-	private function render_select( SettingsField $field, mixed $value, string $name, bool $multiple ): string {
+	protected function render_select( SettingsField $field, mixed $value, string $name, bool $multiple ): string {
 		$selected = array();
 		foreach ( $multiple ? ( \is_array( $value ) ? $value : array() ) : array( $value ) as $selected_value ) {
 			$selected[] = $this->stringify( $selected_value );
@@ -198,7 +198,7 @@ private function render_select( SettingsField $field, mixed $value, string $name
 	 *
 	 * @return  string
 	 */
-	private function render_radio( SettingsField $field, mixed $value, string $name ): string {
+	protected function render_radio( SettingsField $field, mixed $value, string $name ): string {
 		$current  = $this->stringify( $value );
 		$rendered = '';
 		foreach ( $this->resolver->resolve( $field->options ) as $option_value => $label ) {
@@ -225,7 +225,7 @@ private function render_radio( SettingsField $field, mixed $value, string $name
 	 *
 	 * @return  string
 	 */
-	private function render_attributes( array $attributes ): string {
+	protected function render_attributes( array $attributes ): string {
 		$rendered = '';
 		foreach ( filter_field_attributes( $attributes ) as $attribute => $attribute_value ) {
 			$rendered .= \sprintf( ' %s="%s"', \esc_attr( $attribute ), \esc_attr( (string) $attribute_value ) );
@@ -244,7 +244,7 @@ private function render_attributes( array $attributes ): string {
 	 *
 	 * @return  string
 	 */
-	private function stringify( mixed $value ): string {
+	protected function stringify( mixed $value ): string {
 		return \is_scalar( $value ) ? (string) $value : '';
 	}
 
@@ -258,7 +258,7 @@ private function stringify( mixed $value ): string {
 	 *
 	 * @return  string
 	 */
-	private function render_description( SettingsField $field ): string {
+	protected function render_description( SettingsField $field ): string {
 		if ( null === $field->description ) {
 			return '';
 		}
diff --git a/packages/shared/src/Result/Failure.php b/packages/shared/src/Result/Failure.php
index 81d4e2b..4bb9745 100644
--- a/packages/shared/src/Result/Failure.php
+++ b/packages/shared/src/Result/Failure.php
@@ -24,7 +24,7 @@ final class Failure extends AbstractResult {
 	 *
 	 * @param   ErrorInterface $error Error payload carried by the failure.
 	 */
-	private function __construct(
+	protected function __construct(
 		public readonly ErrorInterface $error
 	) {
 		parent::__construct();
diff --git a/packages/shared/src/Result/Success.php b/packages/shared/src/Result/Success.php
index f979cf0..52c90e1 100644
--- a/packages/shared/src/Result/Success.php
+++ b/packages/shared/src/Result/Success.php
@@ -22,7 +22,7 @@ final class Success extends AbstractResult {
 	 *
 	 * @param   mixed $value Return value carried by the success.
 	 */
-	private function __construct(
+	protected function __construct(
 		public readonly mixed $value
 	) {
 		parent::__construct();
diff --git a/packages/shared/src/Version/Version.php b/packages/shared/src/Version/Version.php
index 5a1c1c9..caa1bd8 100644
--- a/packages/shared/src/Version/Version.php
+++ b/packages/shared/src/Version/Version.php
@@ -24,7 +24,7 @@
 	 *
 	 * @param   string $value Pre-validated version string; the original representation supplied to the factory.
 	 */
-	private function __construct(
+	protected function __construct(
 		public string $value
 	) {}
 
diff --git a/packages/storage/src/MemoryStore.php b/packages/storage/src/MemoryStore.php
index f7a6a2c..a302825 100644
--- a/packages/storage/src/MemoryStore.php
+++ b/packages/storage/src/MemoryStore.php
@@ -26,7 +26,7 @@ final class MemoryStore implements KeyValueStoreInterface {
 	 *
 	 * @var     array<string, T>
 	 */
-	private array $entries = array();
+	protected array $entries = array();
 
 	// endregion
 
diff --git a/packages/storage/src/OptionsStore.php b/packages/storage/src/OptionsStore.php
index 989e80c..80a17ed 100644
--- a/packages/storage/src/OptionsStore.php
+++ b/packages/storage/src/OptionsStore.php
@@ -30,8 +30,8 @@
 	 * @param   ?bool  $autoload   Autoload policy for the option row: true/false to force, null to let WordPress decide.
 	 */
 	public function __construct(
-		private string $option_key,
-		private ?bool $autoload = null,
+		protected string $option_key,
+		protected ?bool $autoload = null,
 	) {}
 
 	// endregion
@@ -120,7 +120,7 @@ public function clear(): void {
 	 *
 	 * @return  array<string, T>
 	 */
-	private function load(): array {
+	protected function load(): array {
 		$value = \get_option( $this->option_key, array() );
 		return \is_array( $value ) ? $value : array();
 	}
@@ -133,7 +133,7 @@ private function load(): array {
 	 *
 	 * @param   array<string, T> $entries Entries to persist.
 	 */
-	private function save( array $entries ): void {
+	protected function save( array $entries ): void {
 		\update_option( $this->option_key, $entries, $this->autoload );
 	}
 
diff --git a/packages/storage/src/UserMetaStore.php b/packages/storage/src/UserMetaStore.php
index 57d8ed5..cbeacfc 100644
--- a/packages/storage/src/UserMetaStore.php
+++ b/packages/storage/src/UserMetaStore.php
@@ -36,7 +36,7 @@
 	 * @param   string $meta_key User_meta key under which all entries for this store live.
 	 */
 	public function __construct(
-		private string $meta_key,
+		protected string $meta_key,
 	) {}
 
 	// endregion
@@ -177,7 +177,7 @@ public function clear( int $user_id = 0 ): void {
 	 *
 	 * @return  int
 	 */
-	private function resolve_user_id( int $user_id ): int {
+	protected function resolve_user_id( int $user_id ): int {
 		return 0 === $user_id ? \get_current_user_id() : $user_id;
 	}
 
@@ -192,7 +192,7 @@ private function resolve_user_id( int $user_id ): int {
 	 *
 	 * @return  array<string, T>
 	 */
-	private function load( int $user_id ): array {
+	protected function load( int $user_id ): array {
 		$value = \get_user_meta( $user_id, $this->meta_key, true );
 		return \is_array( $value ) ? $value : array();
 	}
@@ -206,7 +206,7 @@ private function load( int $user_id ): array {
 	 * @param   int              $user_id User ID to persist entries for.
 	 * @param   array<string, T> $entries Entries to persist.
 	 */
-	private function save( int $user_id, array $entries ): void {
+	protected function save( int $user_id, array $entries ): void {
 		// update_user_meta() runs the value through wp_unslash(); slash first so backslashes survive the round-trip.
 		\update_user_meta( $user_id, $this->meta_key, \wp_slash( $entries ) );
 	}
diff --git a/packages/utilities/src/AdminNotices/AdminNoticesService.php b/packages/utilities/src/AdminNotices/AdminNoticesService.php
index 6c1674d..ab8e966 100644
--- a/packages/utilities/src/AdminNotices/AdminNoticesService.php
+++ b/packages/utilities/src/AdminNotices/AdminNoticesService.php
@@ -56,8 +56,8 @@ final class AdminNoticesService {
 	 */
 	public function __construct(
 		?array $stores = null,
-		private ?DismissedNoticesTracker $dismissals = null,
-		private ?string $dismiss_action = null,
+		protected ?DismissedNoticesTracker $dismissals = null,
+		protected ?string $dismiss_action = null,
 	) {
 		$this->stores = $stores ?? array( self::DEFAULT_STORE => new NoticeStore( new MemoryStore() ) );
 	}
@@ -237,7 +237,7 @@ public function handle_dismiss(): void {
 	 *
 	 * @param   AdminNotice $notice Notice to render.
 	 */
-	private function render_one( AdminNotice $notice ): void {
+	protected function render_one( AdminNotice $notice ): void {
 		$data_attributes = array( 'data-notice-id' => $notice->id );
 		// The transport marker only goes on notices a dismissal would actually suppress (persistent +
 		// dismissible), so clicking a one-shot's dismiss never records a stale, never-consulted row.
diff --git a/packages/utilities/src/AdminNotices/DependencyAdminNoticeRenderer.php b/packages/utilities/src/AdminNotices/DependencyAdminNoticeRenderer.php
index 028ae07..7e0e3ef 100644
--- a/packages/utilities/src/AdminNotices/DependencyAdminNoticeRenderer.php
+++ b/packages/utilities/src/AdminNotices/DependencyAdminNoticeRenderer.php
@@ -47,11 +47,11 @@ final class DependencyAdminNoticeRenderer {
 	 * @param   string                      $capability   Capability required to see the notices. Defaults to DEFAULT_CAPABILITY.
 	 */
 	public function __construct(
-		private AdminNoticesService $service,
-		private array $requirements,
-		private ?string $source = null,
-		private string $store = AdminNoticesService::DEFAULT_STORE,
-		private string $capability = self::DEFAULT_CAPABILITY,
+		protected AdminNoticesService $service,
+		protected array $requirements,
+		protected ?string $source = null,
+		protected string $store = AdminNoticesService::DEFAULT_STORE,
+		protected string $capability = self::DEFAULT_CAPABILITY,
 	) {}
 
 	// endregion
@@ -94,7 +94,7 @@ public function render(): void {
 	 *
 	 * @return  bool
 	 */
-	private function is_met( DependencyRequirement $requirement ): bool {
+	protected function is_met( DependencyRequirement $requirement ): bool {
 		try {
 			return $requirement->conditional->is_met();
 		} catch ( \Throwable ) {
@@ -113,7 +113,7 @@ private function is_met( DependencyRequirement $requirement ): bool {
 	 *
 	 * @return  AdminNotice
 	 */
-	private function build_notice( DependencyRequirement $requirement ): AdminNotice {
+	protected function build_notice( DependencyRequirement $requirement ): AdminNotice {
 		return new AdminNotice(
 			id: $requirement->get_notice_id(),
 			message: $this->build_message( $requirement ),
@@ -134,7 +134,7 @@ private function build_notice( DependencyRequirement $requirement ): AdminNotice
 	 *
 	 * @return  string
 	 */
-	private function build_message( DependencyRequirement $requirement ): string {
+	protected function build_message( DependencyRequirement $requirement ): string {
 		if ( $requirement->required ) {
 			$subject = $this->source ?? \__( 'This plugin', 'wp-framework-utilities' );
 			/* translators: 1: plugin or feature name, 2: required dependency label. */
diff --git a/packages/utilities/src/AdminNotices/DismissedNoticesTracker.php b/packages/utilities/src/AdminNotices/DismissedNoticesTracker.php
index 0f7bdad..efdb187 100644
--- a/packages/utilities/src/AdminNotices/DismissedNoticesTracker.php
+++ b/packages/utilities/src/AdminNotices/DismissedNoticesTracker.php
@@ -25,7 +25,7 @@
 	 * @param   UserMetaStore<bool> $store Per-user backend the dismissed IDs are recorded in.
 	 */
 	public function __construct(
-		private UserMetaStore $store,
+		protected UserMetaStore $store,
 	) {}
 
 	// endregion
diff --git a/packages/utilities/src/AdminNotices/NoticeStore.php b/packages/utilities/src/AdminNotices/NoticeStore.php
index eaec65d..8070b71 100644
--- a/packages/utilities/src/AdminNotices/NoticeStore.php
+++ b/packages/utilities/src/AdminNotices/NoticeStore.php
@@ -26,7 +26,7 @@
 	 * @param   KeyValueStoreInterface<array<string, mixed>> $store Backend the notices are persisted through.
 	 */
 	public function __construct(
-		private KeyValueStoreInterface $store,
+		protected KeyValueStoreInterface $store,
 	) {}
 
 	// endregion
@@ -132,7 +132,7 @@ public function clear(): void {
 	 *
 	 * @return  AdminNotice|null
 	 */
-	private function from_row( string $key, mixed $row ): ?AdminNotice {
+	protected function from_row( string $key, mixed $row ): ?AdminNotice {
 		if ( ! \is_array( $row ) ) {
 			return null;
 		}
diff --git a/packages/utilities/src/Caching/TransientCache.php b/packages/utilities/src/Caching/TransientCache.php
index f8b8521..eaa8122 100644
--- a/packages/utilities/src/Caching/TransientCache.php
+++ b/packages/utilities/src/Caching/TransientCache.php
@@ -38,7 +38,7 @@
 	 *
 	 * @var     int
 	 */
-	private const MAX_KEY_LENGTH = 172;
+	protected const MAX_KEY_LENGTH = 172;
 
 	// endregion
 
@@ -53,7 +53,7 @@
 	 * @param   string $key_prefix Per-plugin namespace prepended to every key (a safe slug).
 	 */
 	public function __construct(
-		private string $key_prefix,
+		protected string $key_prefix,
 	) {}
 
 	// endregion
@@ -173,7 +173,7 @@ public function flush(): void {
 	 * @param   mixed  $value      Value to wrap and store.
 	 * @param   int    $expiration Positive lifetime in seconds.
 	 */
-	private function store( string $full_key, mixed $value, int $expiration ): void {
+	protected function store( string $full_key, mixed $value, int $expiration ): void {
 		if ( ! $this->is_positive_expiration( $expiration ) ) {
 			return;
 		}
@@ -191,7 +191,7 @@ private function store( string $full_key, mixed $value, int $expiration ): void
 	 *
 	 * @return  array{hit: bool, value: mixed}
 	 */
-	private function probe( string $full_key ): array {
+	protected function probe( string $full_key ): array {
 		$raw = \get_transient( $full_key );
 		if ( \is_array( $raw ) && \array_key_exists( self::PAYLOAD, $raw ) && \count( $raw ) === 1 ) {
 			return array(
@@ -216,7 +216,7 @@ private function probe( string $full_key ): array {
 	 *
 	 * @return  string
 	 */
-	private function full_key( string $key ): string {
+	protected function full_key( string $key ): string {
 		return $this->key_prefix . '/' . $key . '__' . $this->suffix();
 	}
 
@@ -228,7 +228,7 @@ private function full_key( string $key ): string {
 	 *
 	 * @return  int
 	 */
-	private function suffix(): int {
+	protected function suffix(): int {
 		return \max( 1, (int) \get_option( $this->suffix_key(), 1 ) );
 	}
 
@@ -240,7 +240,7 @@ private function suffix(): int {
 	 *
 	 * @return  string
 	 */
-	private function suffix_key(): string {
+	protected function suffix_key(): string {
 		return $this->key_prefix . '_cache_invalidation_suffix';
 	}
 
@@ -254,7 +254,7 @@ private function suffix_key(): string {
 	 *
 	 * @return  bool
 	 */
-	private function is_within_length( string $full_key ): bool {
+	protected function is_within_length( string $full_key ): bool {
 		if ( \strlen( $full_key ) <= self::MAX_KEY_LENGTH ) {
 			return true;
 		}
@@ -282,7 +282,7 @@ private function is_within_length( string $full_key ): bool {
 	 *
 	 * @return  bool
 	 */
-	private function is_positive_expiration( int $expiration ): bool {
+	protected function is_positive_expiration( int $expiration ): bool {
 		if ( $expiration >= 1 ) {
 			return true;
 		}
diff --git a/packages/utilities/src/Conditionals/Context/CurrentUserCanConditional.php b/packages/utilities/src/Conditionals/Context/CurrentUserCanConditional.php
index 57ea0e7..4512639 100644
--- a/packages/utilities/src/Conditionals/Context/CurrentUserCanConditional.php
+++ b/packages/utilities/src/Conditionals/Context/CurrentUserCanConditional.php
@@ -22,7 +22,7 @@ final class CurrentUserCanConditional implements ConditionalInterface {
 	 * @param   string $capability WordPress capability slug (e.g., `manage_options`).
 	 */
 	public function __construct(
-		private readonly string $capability,
+		protected readonly string $capability,
 	) {}
 
 	// endregion
diff --git a/packages/utilities/src/Conditionals/Dependencies/PHPExtensionLoadedConditional.php b/packages/utilities/src/Conditionals/Dependencies/PHPExtensionLoadedConditional.php
index ba292cf..d94d47e 100644
--- a/packages/utilities/src/Conditionals/Dependencies/PHPExtensionLoadedConditional.php
+++ b/packages/utilities/src/Conditionals/Dependencies/PHPExtensionLoadedConditional.php
@@ -22,7 +22,7 @@ final class PHPExtensionLoadedConditional implements ConditionalInterface {
 	 * @param   string $extension PHP extension name (e.g., `json`, `mbstring`).
 	 */
 	public function __construct(
-		private readonly string $extension,
+		protected readonly string $extension,
 	) {}
 
 	// endregion
diff --git a/packages/utilities/src/Conditionals/Dependencies/PHPFunctionExistsConditional.php b/packages/utilities/src/Conditionals/Dependencies/PHPFunctionExistsConditional.php
index d2fb571..61ce058 100644
--- a/packages/utilities/src/Conditionals/Dependencies/PHPFunctionExistsConditional.php
+++ b/packages/utilities/src/Conditionals/Dependencies/PHPFunctionExistsConditional.php
@@ -22,7 +22,7 @@ final class PHPFunctionExistsConditional implements ConditionalInterface {
 	 * @param   string $function_name Fully-qualified function name to check.
 	 */
 	public function __construct(
-		private readonly string $function_name,
+		protected readonly string $function_name,
 	) {}
 
 	// endregion
diff --git a/packages/utilities/src/Conditionals/Dependencies/PHPIniSizeConditional.php b/packages/utilities/src/Conditionals/Dependencies/PHPIniSizeConditional.php
index 7513a05..a3fbabd 100644
--- a/packages/utilities/src/Conditionals/Dependencies/PHPIniSizeConditional.php
+++ b/packages/utilities/src/Conditionals/Dependencies/PHPIniSizeConditional.php
@@ -26,8 +26,8 @@ final class PHPIniSizeConditional implements ConditionalInterface {
 	 * @param   string $minimum Minimum size as byte shorthand (e.g., `128M`, `1G`).
 	 */
 	public function __construct(
-		private readonly string $setting,
-		private readonly string $minimum,
+		protected readonly string $setting,
+		protected readonly string $minimum,
 	) {}
 
 	// endregion
diff --git a/packages/utilities/src/Conditionals/Dependencies/PHPVersionConditional.php b/packages/utilities/src/Conditionals/Dependencies/PHPVersionConditional.php
index d87959e..41be1f7 100644
--- a/packages/utilities/src/Conditionals/Dependencies/PHPVersionConditional.php
+++ b/packages/utilities/src/Conditionals/Dependencies/PHPVersionConditional.php
@@ -23,7 +23,7 @@ final class PHPVersionConditional implements ConditionalInterface {
 	 * @param   Version $minimum Minimum PHP version that satisfies the gate.
 	 */
 	public function __construct(
-		private readonly Version $minimum,
+		protected readonly Version $minimum,
 	) {}
 
 	// endregion
diff --git a/packages/utilities/src/Conditionals/Dependencies/WPPluginActiveConditional.php b/packages/utilities/src/Conditionals/Dependencies/WPPluginActiveConditional.php
index e2c84c3..d184e21 100644
--- a/packages/utilities/src/Conditionals/Dependencies/WPPluginActiveConditional.php
+++ b/packages/utilities/src/Conditionals/Dependencies/WPPluginActiveConditional.php
@@ -23,7 +23,7 @@ final class WPPluginActiveConditional implements ConditionalInterface {
 	 * @param   string $plugin_basename WordPress plugin basename (e.g., `woocommerce/woocommerce.php`).
 	 */
 	public function __construct(
-		private readonly string $plugin_basename,
+		protected readonly string $plugin_basename,
 	) {}
 
 	// endregion
diff --git a/packages/utilities/src/Conditionals/Dependencies/WPVersionConditional.php b/packages/utilities/src/Conditionals/Dependencies/WPVersionConditional.php
index 51f1ff7..a0468fb 100644
--- a/packages/utilities/src/Conditionals/Dependencies/WPVersionConditional.php
+++ b/packages/utilities/src/Conditionals/Dependencies/WPVersionConditional.php
@@ -23,7 +23,7 @@ final class WPVersionConditional implements ConditionalInterface {
 	 * @param   Version $minimum Minimum WordPress version that satisfies the gate.
 	 */
 	public function __construct(
-		private readonly Version $minimum,
+		protected readonly Version $minimum,
 	) {}
 
 	// endregion
diff --git a/packages/utilities/src/Hooks/Handlers/BufferedHookHandler.php b/packages/utilities/src/Hooks/Handlers/BufferedHookHandler.php
index b3a718a..403ee91 100644
--- a/packages/utilities/src/Hooks/Handlers/BufferedHookHandler.php
+++ b/packages/utilities/src/Hooks/Handlers/BufferedHookHandler.php
@@ -36,8 +36,8 @@
 	 * @param   HookRegistry $registry  Internal record store. Defaults to a fresh HookRegistry.
 	 */
 	public function __construct(
-		private string $id = 'buffered',
-		private HookRegistry $registry = new HookRegistry(),
+		protected string $id = 'buffered',
+		protected HookRegistry $registry = new HookRegistry(),
 	) {}
 
 	// endregion
diff --git a/packages/utilities/src/Hooks/Handlers/DirectHookHandler.php b/packages/utilities/src/Hooks/Handlers/DirectHookHandler.php
index a97f95a..61e4c5b 100644
--- a/packages/utilities/src/Hooks/Handlers/DirectHookHandler.php
+++ b/packages/utilities/src/Hooks/Handlers/DirectHookHandler.php
@@ -39,8 +39,8 @@
 	 * @param   HookRegistry $registry  Internal record store. Defaults to a fresh HookRegistry.
 	 */
 	public function __construct(
-		private string $id = self::DEFAULT_ID,
-		private HookRegistry $registry = new HookRegistry(),
+		protected string $id = self::DEFAULT_ID,
+		protected HookRegistry $registry = new HookRegistry(),
 	) {}
 
 	// endregion
diff --git a/packages/utilities/src/Hooks/Handlers/ScopedHookHandler.php b/packages/utilities/src/Hooks/Handlers/ScopedHookHandler.php
index 3c6a6f6..543546b 100644
--- a/packages/utilities/src/Hooks/Handlers/ScopedHookHandler.php
+++ b/packages/utilities/src/Hooks/Handlers/ScopedHookHandler.php
@@ -37,10 +37,10 @@
 	 * @param   BufferedHookHandler $buffer      Underlying buffered handler. Defaults to a fresh BufferedHookHandler with id "scoped-buffer".
 	 */
 	public function __construct(
-		private string $id,
-		private string $start_hook,
-		private string $end_hook = '',
-		private BufferedHookHandler $buffer = new BufferedHookHandler( 'scoped-buffer', new HookRegistry() ),
+		protected string $id,
+		protected string $start_hook,
+		protected string $end_hook = '',
+		protected BufferedHookHandler $buffer = new BufferedHookHandler( 'scoped-buffer', new HookRegistry() ),
 	) {}
 
 	// endregion
diff --git a/packages/utilities/src/Hooks/HookRegistry.php b/packages/utilities/src/Hooks/HookRegistry.php
index 1e27c59..4e00b67 100644
--- a/packages/utilities/src/Hooks/HookRegistry.php
+++ b/packages/utilities/src/Hooks/HookRegistry.php
@@ -26,7 +26,7 @@ final class HookRegistry {
 	 *
 	 * @var     list<array{hook: string, callback: callable, priority: int, accepted_args: int}>
 	 */
-	private array $actions = array();
+	protected array $actions = array();
 
 	/**
 	 * Filter registration records.
@@ -36,7 +36,7 @@ final class HookRegistry {
 	 *
 	 * @var     list<array{hook: string, callback: callable, priority: int, accepted_args: int}>
 	 */
-	private array $filters = array();
+	protected array $filters = array();
 
 	// endregion
 
@@ -179,7 +179,7 @@ public function get_filters(): array {
 	 *
 	 * @return  bool                                                                                        True if a record was removed.
 	 */
-	private function forget_from( array &$records, string $hook, callable $callback, int $priority ): bool {
+	protected function forget_from( array &$records, string $hook, callable $callback, int $priority ): bool {
 		foreach ( $records as $index => $record ) {
 			if ( $record['hook'] === $hook && $record['callback'] === $callback && $record['priority'] === $priority ) {
 				array_splice( $records, $index, 1 );
diff --git a/packages/utilities/src/Hooks/HooksService.php b/packages/utilities/src/Hooks/HooksService.php
index 47cad12..40e91b1 100644
--- a/packages/utilities/src/Hooks/HooksService.php
+++ b/packages/utilities/src/Hooks/HooksService.php
@@ -193,7 +193,7 @@ public function remove_all_filters( string $handler_id = DirectHookHandler::DEFA
 	 *
 	 * @throws  OutOfBoundsException When no handler is registered under $id.
 	 */
-	private function resolve_handler( string $id ): HookHandlerInterface {
+	protected function resolve_handler( string $id ): HookHandlerInterface {
 		$handler = $this->get_handler( $id );
 		if ( null === $handler ) {
 			// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- framework-internal exception; never reaches an HTML output context unescaped.
diff --git a/packages/utilities/src/Scheduling/Backends/ActionSchedulerBackend.php b/packages/utilities/src/Scheduling/Backends/ActionSchedulerBackend.php
index 2dc58fb..54051e4 100644
--- a/packages/utilities/src/Scheduling/Backends/ActionSchedulerBackend.php
+++ b/packages/utilities/src/Scheduling/Backends/ActionSchedulerBackend.php
@@ -34,7 +34,7 @@ final class ActionSchedulerBackend implements SchedulerBackendInterface {
 	 * @param   LoggerInterface|null $logger Optional PSR-3 logger for the absent-scheduler condition.
 	 */
 	public function __construct(
-		private ?LoggerInterface $logger = null,
+		protected ?LoggerInterface $logger = null,
 	) {}
 
 	// endregion
@@ -142,7 +142,7 @@ public function get_next_scheduled( string $hook, array $args = array(), string
 	 *
 	 * @return  bool
 	 */
-	private function is_available(): bool {
+	protected function is_available(): bool {
 		return \function_exists( 'as_schedule_recurring_action' );
 	}
 
@@ -154,7 +154,7 @@ private function is_available(): bool {
 	 *
 	 * @return  Failure<SchedulingError>
 	 */
-	private function unavailable(): Failure {
+	protected function unavailable(): Failure {
 		$message = 'Action Scheduler is not loaded; cannot schedule the action.';
 		$this->logger?->error( $message );
 
@@ -174,7 +174,7 @@ private function unavailable(): Failure {
 	 *
 	 * @return  Success<true>|Failure<SchedulingError> Success, or a failure when the id is zero.
 	 */
-	private function result_for_action_id( int $action_id, string $hook ): AbstractResult {
+	protected function result_for_action_id( int $action_id, string $hook ): AbstractResult {
 		if ( 0 === $action_id ) {
 			return Failure::from(
 				new SchedulingError(
diff --git a/packages/utilities/src/Scheduling/Backends/WPCronBackend.php b/packages/utilities/src/Scheduling/Backends/WPCronBackend.php
index 4d1511f..b9af596 100644
--- a/packages/utilities/src/Scheduling/Backends/WPCronBackend.php
+++ b/packages/utilities/src/Scheduling/Backends/WPCronBackend.php
@@ -36,7 +36,7 @@ final class WPCronBackend implements SchedulerBackendInterface {
 	 *
 	 * @var     LoggerInterface|null
 	 */
-	private ?LoggerInterface $logger;
+	protected ?LoggerInterface $logger;
 
 	/**
 	 * Intervals (in seconds) for which a synthetic schedule has been registered, used as a set.
@@ -46,7 +46,7 @@ final class WPCronBackend implements SchedulerBackendInterface {
 	 *
 	 * @var     array<int, bool>
 	 */
-	private array $registered_intervals = array();
+	protected array $registered_intervals = array();
 
 	/**
 	 * Whether the 'cron_schedules' filter callback has been wired this request.
@@ -56,7 +56,7 @@ final class WPCronBackend implements SchedulerBackendInterface {
 	 *
 	 * @var     bool
 	 */
-	private bool $schedules_filter_registered = false;
+	protected bool $schedules_filter_registered = false;
 
 	// endregion
 
@@ -216,7 +216,7 @@ public function register_synthetic_schedules( array $schedules ): array {
 	 *
 	 * @return  Failure<SchedulingError>|null A failure when the group is non-empty, null when it is empty.
 	 */
-	private function reject_group( string $group ): ?Failure {
+	protected function reject_group( string $group ): ?Failure {
 		if ( '' === $group ) {
 			return null;
 		}
@@ -243,7 +243,7 @@ private function reject_group( string $group ): ?Failure {
 	 *
 	 * @return  string
 	 */
-	private function ensure_schedule( int $interval ): string {
+	protected function ensure_schedule( int $interval ): string {
 		$this->registered_intervals[ $interval ] = true;
 		if ( ! $this->schedules_filter_registered ) {
 			\add_filter( 'cron_schedules', array( $this, 'register_synthetic_schedules' ) );
@@ -263,7 +263,7 @@ private function ensure_schedule( int $interval ): string {
 	 *
 	 * @return  string
 	 */
-	private function schedule_name( int $interval ): string {
+	protected function schedule_name( int $interval ): string {
 		return 'dws_every_' . $interval . 's';
 	}
 
@@ -278,7 +278,7 @@ private function schedule_name( int $interval ): string {
 	 *
 	 * @return  Success<true>|Failure<SchedulingError> Success, or a failure on a false / WP_Error return.
 	 */
-	private function result_for_schedule( bool|WP_Error $scheduled, string $hook ): AbstractResult {
+	protected function result_for_schedule( bool|WP_Error $scheduled, string $hook ): AbstractResult {
 		if ( true === $scheduled ) {
 			return Success::from( true );
 		}
@@ -311,7 +311,7 @@ private function result_for_schedule( bool|WP_Error $scheduled, string $hook ):
 	 *
 	 * @return  Success<true>|Failure<SchedulingError> Success on an int count, a failure on a WP_Error / non-int return.
 	 */
-	private function result_for_unschedule( int|WP_Error $cleared, string $hook ): AbstractResult {
+	protected function result_for_unschedule( int|WP_Error $cleared, string $hook ): AbstractResult {
 		if ( \is_int( $cleared ) ) {
 			return Success::from( true );
 		}
diff --git a/packages/utilities/src/Scheduling/Scheduler.php b/packages/utilities/src/Scheduling/Scheduler.php
index 2f4b3a9..037392a 100644
--- a/packages/utilities/src/Scheduling/Scheduler.php
+++ b/packages/utilities/src/Scheduling/Scheduler.php
@@ -27,7 +27,7 @@ final class Scheduler implements SchedulerBackendInterface {
 	 * @param   SchedulerBackendInterface $backend Backend that performs the scheduling.
 	 */
 	public function __construct(
-		private SchedulerBackendInterface $backend,
+		protected SchedulerBackendInterface $backend,
 	) {}
 
 	// endregion
diff --git a/packages/woocommerce/src/Backend/DescriptorBackedWCSettingsPage.php b/packages/woocommerce/src/Backend/DescriptorBackedWCSettingsPage.php
index 4625be2..3cd42ad 100644
--- a/packages/woocommerce/src/Backend/DescriptorBackedWCSettingsPage.php
+++ b/packages/woocommerce/src/Backend/DescriptorBackedWCSettingsPage.php
@@ -30,7 +30,7 @@ abstract class DescriptorBackedWCSettingsPage extends \WC_Settings_Page {
 	 *
 	 * @var     array<class-string<self>, SettingsPage>
 	 */
-	private static array $descriptors = array();
+	protected static array $descriptors = array();
 
 	// endregion
 
@@ -111,7 +111,7 @@ public static function bind( string $page_class, SettingsPage $page ): void {
 	 *
 	 * @return  SettingsPage
 	 */
-	private function descriptor(): SettingsPage {
+	protected function descriptor(): SettingsPage {
 		return self::$descriptors[ static::class ]
 			// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- framework-internal exception; never reaches an HTML output context unescaped.
 			?? throw new UnboundSettingsPageException( 'No settings descriptor is bound to ' . static::class . '.' );
@@ -128,7 +128,7 @@ private function descriptor(): SettingsPage {
 	 *
 	 * @return  SettingsPage
 	 */
-	private function editable_page(): SettingsPage {
+	protected function editable_page(): SettingsPage {
 		$descriptor = $this->descriptor();
 
 		$sections = array();
diff --git a/packages/woocommerce/src/Backend/WCSettingsBuilder.php b/packages/woocommerce/src/Backend/WCSettingsBuilder.php
index cbadf7e..d904fb0 100644
--- a/packages/woocommerce/src/Backend/WCSettingsBuilder.php
+++ b/packages/woocommerce/src/Backend/WCSettingsBuilder.php
@@ -33,7 +33,7 @@ final class WCSettingsBuilder {
 	 * @param   OptionsResolver $options_resolver Resolves a field's option source to a value-to-label map.
 	 */
 	public function __construct(
-		private OptionsResolver $options_resolver = new OptionsResolver(),
+		protected OptionsResolver $options_resolver = new OptionsResolver(),
 	) {}
 
 	// endregion
@@ -93,7 +93,7 @@ public function build( SettingsPage $page ): array {
 	 *
 	 * @return  array<string, mixed>
 	 */
-	private function build_field( string $slug, SettingsField $field ): array {
+	protected function build_field( string $slug, SettingsField $field ): array {
 		$entry = array(
 			'id'    => $slug . '_' . $field->id,
 			'type'  => $field->type,
@@ -127,7 +127,7 @@ private function build_field( string $slug, SettingsField $field ): array {
 	 *
 	 * @return  mixed
 	 */
-	private function map_default( SettingsField $field ): mixed {
+	protected function map_default( SettingsField $field ): mixed {
 		return match ( $field->type ) {
 			FieldType::Checkbox->value    => to_yes_no( $field->default ),
 			// WooCommerce matches multiselect selections with a strict (string) in_array, so the set must be strings.
@@ -146,7 +146,7 @@ private function map_default( SettingsField $field ): mixed {
 	 *
 	 * @return  bool
 	 */
-	private function expects_options( string $type ): bool {
+	protected function expects_options( string $type ): bool {
 		return \in_array(
 			$type,
 			array( FieldType::Select->value, FieldType::Multiselect->value, FieldType::Radio->value ),
@@ -167,7 +167,7 @@ private function expects_options( string $type ): bool {
 	 *
 	 * @return  array<array-key, string>
 	 */
-	private function stringify_labels( array $options ): array {
+	protected function stringify_labels( array $options ): array {
 		$labels = array();
 		foreach ( $options as $value => $label ) {
 			$labels[ $value ] = \is_scalar( $label ) ? (string) $label : '';
@@ -186,7 +186,7 @@ private function stringify_labels( array $options ): array {
 	 *
 	 * @return  array<array-key, string>
 	 */
-	private function stringify_selected( mixed $default ): array {
+	protected function stringify_selected( mixed $default ): array {
 		if ( ! \is_array( $default ) ) {
 			return array();
 		}
diff --git a/packages/woocommerce/src/Backend/WooCommerceSettingsBackend.php b/packages/woocommerce/src/Backend/WooCommerceSettingsBackend.php
index 3490944..94653e4 100644
--- a/packages/woocommerce/src/Backend/WooCommerceSettingsBackend.php
+++ b/packages/woocommerce/src/Backend/WooCommerceSettingsBackend.php
@@ -36,7 +36,7 @@ final class WooCommerceSettingsBackend implements SettingsBackendInterface {
 	 *
 	 * @var     ?SettingsPage
 	 */
-	private ?SettingsPage $page = null;
+	protected ?SettingsPage $page = null;
 
 	/**
 	 * Registered fields keyed by id, for option-key routing and validation.
@@ -46,7 +46,7 @@ final class WooCommerceSettingsBackend implements SettingsBackendInterface {
 	 *
 	 * @var     array<string, SettingsField>
 	 */
-	private array $fields = array();
+	protected array $fields = array();
 
 	// endregion
 
@@ -61,7 +61,7 @@ final class WooCommerceSettingsBackend implements SettingsBackendInterface {
 	 * @param   class-string<DescriptorBackedWCSettingsPage> $page_class Consumer subclass that renders the page as a WooCommerce tab.
 	 */
 	public function __construct(
-		private string $page_class,
+		protected string $page_class,
 	) {}
 
 	// endregion
@@ -154,7 +154,7 @@ public function delete( string $field_id ): bool {
 	 *
 	 * @return  array<string, SettingsField>
 	 */
-	private function map_fields( SettingsPage $page ): array {
+	protected function map_fields( SettingsPage $page ): array {
 		$map = array();
 		foreach ( $page->sections as $section ) {
 			foreach ( $section->fields as $field ) {
@@ -177,7 +177,7 @@ private function map_fields( SettingsPage $page ): array {
 	 *
 	 * @param   SettingsPage $page Page whose fields' filters to wire.
 	 */
-	private function register_field_filters( SettingsPage $page ): void {
+	protected function register_field_filters( SettingsPage $page ): void {
 		foreach ( $this->fields as $field_id => $field ) {
 			if ( null === $field->sanitize && null === $field->capability ) {
 				continue;
@@ -216,7 +216,7 @@ static function ( mixed $value ) use ( $key, $sanitize, $field ): mixed {
 	 *
 	 * @return  string
 	 */
-	private function option_key( string $field_id ): string {
+	protected function option_key( string $field_id ): string {
 		if ( null === $this->page || ! \array_key_exists( $field_id, $this->fields ) ) {
 			// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- framework-internal exception; never reaches an HTML output context unescaped.
 			throw new InvalidSettingsFieldException( "Settings field '$field_id' is not registered on this page." );
diff --git a/packages/woocommerce/src/OrderData/OrderFieldStore.php b/packages/woocommerce/src/OrderData/OrderFieldStore.php
index 05fc977..4e1d1ea 100644
--- a/packages/woocommerce/src/OrderData/OrderFieldStore.php
+++ b/packages/woocommerce/src/OrderData/OrderFieldStore.php
@@ -43,7 +43,7 @@ final class OrderFieldStore implements ObjectFieldStoreInterface {
 	 *
 	 * @var     string
 	 */
-	private const ORDER_SCREEN = 'shop_order';
+	protected const ORDER_SCREEN = 'shop_order';
 
 	/**
 	 * HPOS order edit screen, where the box must register when custom order tables are authoritative.
@@ -53,7 +53,7 @@ final class OrderFieldStore implements ObjectFieldStoreInterface {
 	 *
 	 * @var     string
 	 */
-	private const HPOS_ORDER_SCREEN = 'woocommerce_page_wc-orders';
+	protected const HPOS_ORDER_SCREEN = 'woocommerce_page_wc-orders';
 
 	/**
 	 * HPOS order edit screen for a user who cannot view the WooCommerce menu (the page falls under admin.php).
@@ -63,7 +63,7 @@ final class OrderFieldStore implements ObjectFieldStoreInterface {
 	 *
 	 * @var     string
 	 */
-	private const HPOS_ORDER_SCREEN_RESTRICTED = 'admin_page_wc-orders';
+	protected const HPOS_ORDER_SCREEN_RESTRICTED = 'admin_page_wc-orders';
 
 	// endregion
 
@@ -79,8 +79,8 @@ final class OrderFieldStore implements ObjectFieldStoreInterface {
 	 * @param   FieldProcessor $processor Processor for sanitizing submitted values.
 	 */
 	public function __construct(
-		private FieldRenderer $renderer = new FieldRenderer(),
-		private FieldProcessor $processor = new FieldProcessor(),
+		protected FieldRenderer $renderer = new FieldRenderer(),
+		protected FieldProcessor $processor = new FieldProcessor(),
 	) {}
 
 	// endregion
@@ -191,7 +191,7 @@ public function delete( int $object_id, string $meta_key ): bool {
 	 *
 	 * @return  list<string>
 	 */
-	private function resolve_screens( string $screen ): array {
+	protected function resolve_screens( string $screen ): array {
 		if ( self::ORDER_SCREEN !== $screen ) {
 			// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- framework-internal exception; never reaches an HTML output context unescaped.
 			throw new InvalidObjectMetaBoxException( "OrderFieldStore registers meta boxes on the WooCommerce order screen ('shop_order') only; got '$screen'." );
@@ -212,7 +212,7 @@ private function resolve_screens( string $screen ): array {
 	 * @param   ObjectMetaBox $box    Box to add.
 	 * @param   string        $screen Resolved screen the box renders on.
 	 */
-	private function add_box( ObjectMetaBox $box, string $screen ): void {
+	protected function add_box( ObjectMetaBox $box, string $screen ): void {
 		$priority = match ( $box->priority ) {
 			'core', 'high', 'low' => $box->priority,
 			default               => 'default',
@@ -237,7 +237,7 @@ private function add_box( ObjectMetaBox $box, string $screen ): void {
 	 * @param   ObjectMetaBox $box    Box being rendered.
 	 * @param   mixed         $object Screen object WordPress passes the callback (a WooCommerce order or WP_Post).
 	 */
-	private function render_box( ObjectMetaBox $box, mixed $object ): void {
+	protected function render_box( ObjectMetaBox $box, mixed $object ): void {
 		$object_id = $this->object_id_of( $object );
 
 		// Emitted for every box, bespoke renderer included: save_box() verifies this nonce before it runs
@@ -276,7 +276,7 @@ private function render_box( ObjectMetaBox $box, mixed $object ): void {
 	 * @param   ObjectMetaBox $box       Box being saved.
 	 * @param   int           $object_id Order whose meta to write.
 	 */
-	private function save_box( ObjectMetaBox $box, int $object_id ): void {
+	protected function save_box( ObjectMetaBox $box, int $object_id ): void {
 		$name = $this->nonce_name( $box );
 		// phpcs:ignore WordPress.Security.NonceVerification.Missing -- nonce read here and verified on the next line.
 		$nonce = isset( $_POST[ $name ] ) ? \sanitize_text_field( \wp_unslash( $_POST[ $name ] ) ) : '';
@@ -346,7 +346,7 @@ private function save_box( ObjectMetaBox $box, int $object_id ): void {
 	 *
 	 * @return  list<SettingsField>
 	 */
-	private function fields_of( ObjectMetaBox $box, int $object_id ): array {
+	protected function fields_of( ObjectMetaBox $box, int $object_id ): array {
 		/** @var list<SettingsField> $fields */
 		$fields = ( $box->fields_provider )( $object_id );
 
@@ -372,7 +372,7 @@ private function fields_of( ObjectMetaBox $box, int $object_id ): array {
 	 *
 	 * @return  int
 	 */
-	private function object_id_of( mixed $object ): int {
+	protected function object_id_of( mixed $object ): int {
 		if ( $object instanceof \WC_Abstract_Order ) {
 			return $object->get_id();
 		}
@@ -395,7 +395,7 @@ private function object_id_of( mixed $object ): int {
 	 *
 	 * @return  bool
 	 */
-	private function should_store( mixed $value ): bool {
+	protected function should_store( mixed $value ): bool {
 		return false !== $value && '' !== $value && array() !== $value;
 	}
 
@@ -411,7 +411,7 @@ private function should_store( mixed $value ): bool {
 	 *
 	 * @return  string
 	 */
-	private function nonce_action( ObjectMetaBox $box, int $object_id ): string {
+	protected function nonce_action( ObjectMetaBox $box, int $object_id ): string {
 		return 'dws_object_field_' . $box->id . '_' . $object_id;
 	}
 
@@ -425,7 +425,7 @@ private function nonce_action( ObjectMetaBox $box, int $object_id ): string {
 	 *
 	 * @return  string
 	 */
-	private function nonce_name( ObjectMetaBox $box ): string {
+	protected function nonce_name( ObjectMetaBox $box ): string {
 		return 'dws_object_field_' . $box->id . '_nonce';
 	}
 
diff --git a/packages/woocommerce/src/ProductData/ProductDataFieldRenderer.php b/packages/woocommerce/src/ProductData/ProductDataFieldRenderer.php
index 4d686f8..b06999b 100644
--- a/packages/woocommerce/src/ProductData/ProductDataFieldRenderer.php
+++ b/packages/woocommerce/src/ProductData/ProductDataFieldRenderer.php
@@ -33,7 +33,7 @@ final class ProductDataFieldRenderer {
 	 * @param   OptionsResolver $options_resolver Resolver for choice fields' option sets.
 	 */
 	public function __construct(
-		private OptionsResolver $options_resolver = new OptionsResolver(),
+		protected OptionsResolver $options_resolver = new OptionsResolver(),
 	) {}
 
 	// endregion
@@ -155,7 +155,7 @@ public function render( SettingsField $field, mixed $value, string $meta_key ):
 	 *
 	 * @return  array<array-key, string>
 	 */
-	private function stringify_labels( array $options ): array {
+	protected function stringify_labels( array $options ): array {
 		$labels = array();
 		foreach ( $options as $value => $label ) {
 			$labels[ $value ] = \is_scalar( $label ) ? (string) $label : '';
@@ -174,7 +174,7 @@ private function stringify_labels( array $options ): array {
 	 *
 	 * @return  string
 	 */
-	private function stringify( mixed $value ): string {
+	protected function stringify( mixed $value ): string {
 		return \is_scalar( $value ) ? (string) $value : '';
 	}
 
diff --git a/packages/woocommerce/src/ProductData/ProductDataFieldStore.php b/packages/woocommerce/src/ProductData/ProductDataFieldStore.php
index f7a4d58..5b9b449 100644
--- a/packages/woocommerce/src/ProductData/ProductDataFieldStore.php
+++ b/packages/woocommerce/src/ProductData/ProductDataFieldStore.php
@@ -34,7 +34,7 @@ final class ProductDataFieldStore {
 	 *
 	 * @var     ?ProductDataTab
 	 */
-	private ?ProductDataTab $tab = null;
+	protected ?ProductDataTab $tab = null;
 
 	/**
 	 * Registered fields keyed by their resolved meta key, for default injection and the save sweep.
@@ -44,7 +44,7 @@ final class ProductDataFieldStore {
 	 *
 	 * @var     array<string, SettingsField>
 	 */
-	private array $by_meta_key = array();
+	protected array $by_meta_key = array();
 
 	/**
 	 * Resolved meta key keyed by "section_id\0field_id", for CRUD addressing.
@@ -54,7 +54,7 @@ final class ProductDataFieldStore {
 	 *
 	 * @var     array<string, string>
 	 */
-	private array $by_address = array();
+	protected array $by_address = array();
 
 	// endregion
 
@@ -70,8 +70,8 @@ final class ProductDataFieldStore {
 	 * @param   FieldProcessor           $processor Processor for sanitizing submitted taxonomy-typed values.
 	 */
 	public function __construct(
-		private ProductDataFieldRenderer $renderer = new ProductDataFieldRenderer(),
-		private FieldProcessor $processor = new FieldProcessor(),
+		protected ProductDataFieldRenderer $renderer = new ProductDataFieldRenderer(),
+		protected FieldProcessor $processor = new FieldProcessor(),
 	) {}
 
 	// endregion
@@ -251,7 +251,7 @@ public function meta_keys(): array {
 	 *
 	 * @return  array<string, mixed>
 	 */
-	private function register_tab_filter( array $tabs ): array {
+	protected function register_tab_filter( array $tabs ): array {
 		global $thepostid;
 		$product_id = (int) $thepostid;
 		if ( ! $this->is_supported( $product_id ) ) {
@@ -275,7 +275,7 @@ private function register_tab_filter( array $tabs ): array {
 	 * @since   2.0.0
 	 * @version 2.0.0
 	 */
-	private function render_panel(): void {
+	protected function render_panel(): void {
 		global $thepostid;
 		$product_id = (int) $thepostid;
 		if ( ! $this->is_supported( $product_id ) ) {
@@ -320,7 +320,7 @@ private function render_panel(): void {
 	 *
 	 * @param   int $product_id Product being saved.
 	 */
-	private function save( int $product_id ): void {
+	protected function save( int $product_id ): void {
 		if ( ! $this->is_supported( $product_id ) ) {
 			return;
 		}
@@ -354,7 +354,7 @@ private function save( int $product_id ): void {
 	 *
 	 * @return  mixed
 	 */
-	private function inject_default( mixed $value, int $object_id, string $meta_key ): mixed {
+	protected function inject_default( mixed $value, int $object_id, string $meta_key ): mixed {
 		$field = $this->by_meta_key[ $meta_key ] ?? null;
 		if ( null === $field ) {
 			return $value;
@@ -377,7 +377,7 @@ private function inject_default( mixed $value, int $object_id, string $meta_key
 	 *
 	 * @return  array<int, object>
 	 */
-	private function inject_default_bulk( array $meta_data, object $object ): array {
+	protected function inject_default_bulk( array $meta_data, object $object ): array {
 		if ( ! $object instanceof \WC_Product || ! $this->is_supported( $object->get_id() ) ) {
 			return $meta_data;
 		}
@@ -410,7 +410,7 @@ private function inject_default_bulk( array $meta_data, object $object ): array
 	 *
 	 * @throws  DuplicateSettingsFieldException If two fields resolve to the same meta key.
 	 */
-	private function index_fields( ProductDataTab $tab ): void {
+	protected function index_fields( ProductDataTab $tab ): void {
 		$this->by_meta_key = array();
 		$this->by_address  = array();
 
@@ -438,7 +438,7 @@ private function index_fields( ProductDataTab $tab ): void {
 	 *
 	 * @return  string
 	 */
-	private function meta_key_for( string $section_id, SettingsField $field ): string {
+	protected function meta_key_for( string $section_id, SettingsField $field ): string {
 		return $field->meta_key ?? ( $this->tab()->meta_key_prefix . $section_id . '_' . $field->id );
 	}
 
@@ -455,7 +455,7 @@ private function meta_key_for( string $section_id, SettingsField $field ): strin
 	 *
 	 * @return  string
 	 */
-	private function require_meta_key( string $section_id, string $field_id ): string {
+	protected function require_meta_key( string $section_id, string $field_id ): string {
 		$address = $this->address( $section_id, $field_id );
 		if ( ! isset( $this->by_address[ $address ] ) ) {
 			// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- framework-internal exception; never reaches an HTML output context unescaped.
@@ -476,7 +476,7 @@ private function require_meta_key( string $section_id, string $field_id ): strin
 	 *
 	 * @return  string
 	 */
-	private function address( string $section_id, string $field_id ): string {
+	protected function address( string $section_id, string $field_id ): string {
 		return $section_id . "\0" . $field_id;
 	}
 
@@ -492,7 +492,7 @@ private function address( string $section_id, string $field_id ): string {
 	 *
 	 * @return  mixed
 	 */
-	private function submitted_value( SettingsField $field, string $meta_key ): mixed {
+	protected function submitted_value( SettingsField $field, string $meta_key ): mixed {
 		$type = FieldType::tryFrom( $field->type );
 
 		if ( FieldType::Checkbox === $type ) {
@@ -525,7 +525,7 @@ private function submitted_value( SettingsField $field, string $meta_key ): mixe
 	 *
 	 * @return  mixed
 	 */
-	private function sanitize_and_validate( SettingsField $field, mixed $value, mixed $rejected ): mixed {
+	protected function sanitize_and_validate( SettingsField $field, mixed $value, mixed $rejected ): mixed {
 		if ( null !== $field->sanitize ) {
 			$value = ( $field->sanitize )( $value );
 		}
@@ -546,7 +546,7 @@ private function sanitize_and_validate( SettingsField $field, mixed $value, mixe
 	 *
 	 * @return  mixed
 	 */
-	private function default_value( SettingsField $field ): mixed {
+	protected function default_value( SettingsField $field ): mixed {
 		return FieldType::Checkbox === FieldType::tryFrom( $field->type )
 			? to_yes_no( $field->default )
 			: $field->default;
@@ -562,7 +562,7 @@ private function default_value( SettingsField $field ): mixed {
 	 *
 	 * @return  bool
 	 */
-	private function is_supported( int $product_id ): bool {
+	protected function is_supported( int $product_id ): bool {
 		// Product existence is the non-overridable floor: the global default filters must never inject into a
 		// non-product post. A consumer's gate only narrows the set of products further.
 		if ( false === \WC_Product_Factory::get_product_type( $product_id ) ) {
@@ -584,7 +584,7 @@ private function is_supported( int $product_id ): bool {
 	 *
 	 * @return  list<string>
 	 */
-	private function tab_classes( int $product_id ): array {
+	protected function tab_classes( int $product_id ): array {
 		$classes = $this->tab()->classes;
 
 		return \is_array( $classes ) ? \array_values( $classes ) : \array_values( (array) $classes( $product_id ) );
@@ -598,7 +598,7 @@ private function tab_classes( int $product_id ): array {
 	 *
 	 * @return  ProductDataTab
 	 */
-	private function tab(): ProductDataTab {
+	protected function tab(): ProductDataTab {
 		\assert( $this->tab instanceof ProductDataTab );
 
 		return $this->tab;

From 4313b054f40f7fbf358b0168c66b0df6cc0c14a6 Mon Sep 17 00:00:00 2001
From: Tony Hegyes <a.hegyes@proton.me>
Date: Mon, 22 Jun 2026 16:51:09 +0200
Subject: [PATCH 18/21] refactor(utilities): widen the two private(set)
 write-guards to protected(set) (audit #21)

Completes the protected-over-private sweep: HooksService::$handlers and
AdminNoticesService::$stores used PHP 8.4 asymmetric visibility with a
private setter. Widen the set-visibility to protected so a future un-final
subclass can mutate them too, matching the protected-default standard. Read
visibility (public) is unchanged, and behavior is identical on these final
classes.

Assisted-by: Claude Code:claude-opus-4-8
---
 packages/utilities/src/AdminNotices/AdminNoticesService.php | 2 +-
 packages/utilities/src/Hooks/HooksService.php               | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/utilities/src/AdminNotices/AdminNoticesService.php b/packages/utilities/src/AdminNotices/AdminNoticesService.php
index ab8e966..1381dfd 100644
--- a/packages/utilities/src/AdminNotices/AdminNoticesService.php
+++ b/packages/utilities/src/AdminNotices/AdminNoticesService.php
@@ -38,7 +38,7 @@ final class AdminNoticesService {
 	 *
 	 * @var     array<string, NoticeStore>
 	 */
-	private(set) array $stores;
+	protected(set) array $stores;
 
 	// endregion
 
diff --git a/packages/utilities/src/Hooks/HooksService.php b/packages/utilities/src/Hooks/HooksService.php
index 40e91b1..38b7e89 100644
--- a/packages/utilities/src/Hooks/HooksService.php
+++ b/packages/utilities/src/Hooks/HooksService.php
@@ -31,7 +31,7 @@ final class HooksService {
 	 *
 	 * @var     array<string, HookHandlerInterface>
 	 */
-	private(set) array $handlers = array();
+	protected(set) array $handlers = array();
 
 	// endregion
 

From 363738a834dd20798031062f516e5b469a549f55 Mon Sep 17 00:00:00 2001
From: Tony Hegyes <a.hegyes@proton.me>
Date: Sat, 27 Jun 2026 11:06:51 +0200
Subject: [PATCH 19/21] refactor(framework): restore aggregator docblocks +
 empty package aggregators

Revisits three cleanups from this branch the owner wanted partially undone:

- Restore the file-level docblock (description + @since/@version) on every
  package-root functions.php aggregator, replacing the terse one-line comment.
  The @since/@version pair traces when a file changed; applied uniformly across
  all seven packages so the set stays consistent.
- Recreate the empty core/ + storage/ aggregator placeholders and their
  autoload.files entries (composer.json + composer.lock snapshots) for parity
  with the packages that carry namespace functions.
- Drop the bootstrap AggregatorTest: all four concern functions have dedicated
  Integration coverage (CheckRequirements/GetPluginMetadata/OutputRequirementsError/
  IsCompatible), so the unit-level function_exists smoke was redundant.

Assisted-by: Claude Code:claude-opus-4-8
---
 composer.lock                                    | 10 ++++++++--
 packages/bootstrap/functions.php                 |  7 ++++++-
 packages/bootstrap/tests/Unit/AggregatorTest.php | 14 --------------
 packages/core/composer.json                      |  5 ++++-
 packages/core/functions.php                      |  7 +++++++
 packages/settings/functions.php                  |  8 ++++++--
 packages/shared/functions.php                    |  8 ++++++--
 packages/storage/composer.json                   |  5 ++++-
 packages/storage/functions.php                   |  7 +++++++
 packages/utilities/functions.php                 |  8 ++++++--
 packages/woocommerce/functions.php               |  8 ++++++--
 11 files changed, 60 insertions(+), 27 deletions(-)
 delete mode 100644 packages/bootstrap/tests/Unit/AggregatorTest.php
 create mode 100644 packages/core/functions.php
 create mode 100644 packages/storage/functions.php

diff --git a/composer.lock b/composer.lock
index a846185..530c8b1 100644
--- a/composer.lock
+++ b/composer.lock
@@ -118,7 +118,10 @@
             "autoload": {
                 "psr-4": {
                     "DeepWebSolutions\\Framework\\Core\\": "src/"
-                }
+                },
+                "files": [
+                    "functions.php"
+                ]
             },
             "autoload-dev": {
                 "psr-4": {
@@ -337,7 +340,10 @@
             "autoload": {
                 "psr-4": {
                     "DeepWebSolutions\\Framework\\Storage\\": "src/"
-                }
+                },
+                "files": [
+                    "functions.php"
+                ]
             },
             "autoload-dev": {
                 "psr-4": {
diff --git a/packages/bootstrap/functions.php b/packages/bootstrap/functions.php
index 7f12d11..d893340 100644
--- a/packages/bootstrap/functions.php
+++ b/packages/bootstrap/functions.php
@@ -1,5 +1,10 @@
 <?php
-// Aggregator: requires this package's nested src/<namespace>/functions.php files (composer autoloads only this file).
+/**
+ * Aggregates the bootstrap package's per-concern function files. Composer autoloads only this file.
+ *
+ * @since   2.0.0
+ * @version 2.0.0
+ */
 
 require_once __DIR__ . '/src/Environment/functions.php';
 require_once __DIR__ . '/src/Plugin/functions.php';
diff --git a/packages/bootstrap/tests/Unit/AggregatorTest.php b/packages/bootstrap/tests/Unit/AggregatorTest.php
deleted file mode 100644
index ca0f761..0000000
--- a/packages/bootstrap/tests/Unit/AggregatorTest.php
+++ /dev/null
@@ -1,14 +0,0 @@
-<?php declare( strict_types=1 );
-
-namespace DeepWebSolutions\Framework\Bootstrap\Tests\Unit;
-
-use PHPUnit\Framework\TestCase;
-
-final class AggregatorTest extends TestCase {
-	public function test_aggregator_wires_every_concern_file(): void {
-		self::assertTrue( \function_exists( 'DeepWebSolutions\Framework\Bootstrap\Environment\is_php_compatible' ) );
-		self::assertTrue( \function_exists( 'DeepWebSolutions\Framework\Bootstrap\Plugin\get_plugin_metadata' ) );
-		self::assertTrue( \function_exists( 'DeepWebSolutions\Framework\Bootstrap\Requirements\check_requirements' ) );
-		self::assertTrue( \function_exists( 'DeepWebSolutions\Framework\Bootstrap\Notice\output_requirements_error' ) );
-	}
-}
diff --git a/packages/core/composer.json b/packages/core/composer.json
index 72fb534..55ad617 100644
--- a/packages/core/composer.json
+++ b/packages/core/composer.json
@@ -30,7 +30,10 @@
   "autoload": {
     "psr-4": {
       "DeepWebSolutions\\Framework\\Core\\": "src/"
-    }
+    },
+    "files": [
+      "functions.php"
+    ]
   },
   "autoload-dev": {
     "psr-4": {
diff --git a/packages/core/functions.php b/packages/core/functions.php
new file mode 100644
index 0000000..9be9c96
--- /dev/null
+++ b/packages/core/functions.php
@@ -0,0 +1,7 @@
+<?php declare( strict_types=1 );
+/**
+ * Aggregates this package's nested src/<namespace>/functions.php files. Composer autoloads only this file.
+ *
+ * @since   2.0.0
+ * @version 2.0.0
+ */
diff --git a/packages/settings/functions.php b/packages/settings/functions.php
index 8b1ca5e..5745fb6 100644
--- a/packages/settings/functions.php
+++ b/packages/settings/functions.php
@@ -1,5 +1,9 @@
 <?php declare( strict_types=1 );
-
-// Aggregator: requires this package's nested src/<namespace>/functions.php files (composer autoloads only this file).
+/**
+ * Aggregates this package's nested src/<namespace>/functions.php files. Composer autoloads only this file.
+ *
+ * @since   2.0.0
+ * @version 2.0.0
+ */
 
 require_once __DIR__ . '/src/Schema/functions.php';
diff --git a/packages/shared/functions.php b/packages/shared/functions.php
index 0bd42f8..bf33356 100644
--- a/packages/shared/functions.php
+++ b/packages/shared/functions.php
@@ -1,5 +1,9 @@
 <?php declare( strict_types=1 );
-
-// Aggregator: requires this package's nested src/<namespace>/functions.php files (composer autoloads only this file).
+/**
+ * Aggregates this package's nested src/<namespace>/functions.php files. Composer autoloads only this file.
+ *
+ * @since   2.0.0
+ * @version 2.0.0
+ */
 
 require_once __DIR__ . '/src/Reflection/functions.php';
diff --git a/packages/storage/composer.json b/packages/storage/composer.json
index 04ab83d..1c956b0 100644
--- a/packages/storage/composer.json
+++ b/packages/storage/composer.json
@@ -26,7 +26,10 @@
   "autoload": {
     "psr-4": {
       "DeepWebSolutions\\Framework\\Storage\\": "src/"
-    }
+    },
+    "files": [
+      "functions.php"
+    ]
   },
   "autoload-dev": {
     "psr-4": {
diff --git a/packages/storage/functions.php b/packages/storage/functions.php
new file mode 100644
index 0000000..9be9c96
--- /dev/null
+++ b/packages/storage/functions.php
@@ -0,0 +1,7 @@
+<?php declare( strict_types=1 );
+/**
+ * Aggregates this package's nested src/<namespace>/functions.php files. Composer autoloads only this file.
+ *
+ * @since   2.0.0
+ * @version 2.0.0
+ */
diff --git a/packages/utilities/functions.php b/packages/utilities/functions.php
index c9f4bf9..2f71ec2 100644
--- a/packages/utilities/functions.php
+++ b/packages/utilities/functions.php
@@ -1,5 +1,9 @@
 <?php declare( strict_types=1 );
-
-// Aggregator: requires this package's nested src/<namespace>/functions.php files (composer autoloads only this file).
+/**
+ * Aggregates this package's nested src/<namespace>/functions.php files. Composer autoloads only this file.
+ *
+ * @since   2.0.0
+ * @version 2.0.0
+ */
 
 require_once __DIR__ . '/src/Scheduling/functions.php';
diff --git a/packages/woocommerce/functions.php b/packages/woocommerce/functions.php
index 4be39b8..6c906ae 100644
--- a/packages/woocommerce/functions.php
+++ b/packages/woocommerce/functions.php
@@ -1,5 +1,9 @@
 <?php declare( strict_types=1 );
-
-// Aggregator: requires this package's nested src/<namespace>/functions.php files (composer autoloads only this file).
+/**
+ * Aggregates this package's nested src/<namespace>/functions.php files. Composer autoloads only this file.
+ *
+ * @since   2.0.0
+ * @version 2.0.0
+ */
 
 require_once __DIR__ . '/src/functions.php';

From 6a4ada7c1255d3aeb93379d959834547e63972e4 Mon Sep 17 00:00:00 2001
From: Tony Hegyes <a.hegyes@proton.me>
Date: Sat, 27 Jun 2026 11:48:09 +0200
Subject: [PATCH 20/21] fix(framework): make PHPCS clean (errors + warnings)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The strict PHPCS gate was red across the branch (and trunk). Resolved every
finding so the phpcs job — which exits non-zero on warnings too — passes:

Code fixes:
- Wrap the _doing_it_wrong() messages in TransientCache + AdminNoticesService
  in esc_html() (WordPress.Security.EscapeOutput), keeping the sniff active.
- Flip a non-Yoda comparison in AdminNoticesService.
- Rename the reserved-keyword params: SettingsField::$default -> $default_value
  (incl. every reader + named-arg call site), the WCSettingsBuilder local, and
  the $object params -> $wc_object across the order/product stores.

False positives suppressed per-line, with justification:
- Inline /** @var */ PHPStan hints flagged for a missing short description.
- A PHP 8.4 property hook misread as removed curly-brace array access.
- A core WooCommerce capability (edit_shop_orders) WPCS does not know.
- A dynamically-registered cron interval WPCS cannot read statically.

Also re-adds the core/storage functions.php paths to phpstan.dist.neon and
trims its rot-prone stub comment.

Companion: the generic-type docblock allowance (class-string<X>/list<X>) lands
in the shared wordpress-configs ruleset, not here.

Assisted-by: Claude Code:claude-opus-4-8
---
 packages/core/src/PluginKernel.php            |  8 +++----
 .../src/Backend/WordPressSettingsBackend.php  |  2 +-
 .../settings/src/Schema/FieldProcessor.php    |  6 ++---
 .../src/Schema/ValueObjects/SettingsField.php |  4 ++--
 .../WordPressSettingsBackendTest.php          |  2 +-
 .../tests/Unit/FieldProcessorTest.php         |  8 +++----
 .../settings/tests/Unit/SettingsFieldTest.php |  6 ++---
 .../Exceptions/InvalidVersionException.php    |  2 +-
 .../src/AdminNotices/AdminNoticesService.php  |  4 ++--
 .../utilities/src/Caching/TransientCache.php  | 22 ++++++++++-------
 .../src/Scheduling/Backends/WPCronBackend.php |  2 +-
 .../src/Backend/WCSettingsBuilder.php         | 16 ++++++-------
 .../src/OrderData/OrderFieldStore.php         | 24 +++++++++----------
 .../src/ProductData/ProductDataFieldStore.php | 14 +++++------
 .../OrderData/OrderFieldStoreTest.php         |  2 +-
 .../Integration/ProductDataFieldStoreTest.php |  4 ++--
 .../tests/Unit/WCSettingsBuilderTest.php      | 18 +++++++-------
 phpstan.dist.neon                             |  7 +++---
 18 files changed, 77 insertions(+), 74 deletions(-)

diff --git a/packages/core/src/PluginKernel.php b/packages/core/src/PluginKernel.php
index daee222..315af8b 100644
--- a/packages/core/src/PluginKernel.php
+++ b/packages/core/src/PluginKernel.php
@@ -132,7 +132,7 @@ public function boot(): void {
 		$surviving_features = array();
 		foreach ( $this->plugin->get_feature_classes() as $feature_class ) {
 			if ( $this->are_conditionals_met( $feature_class, $container ) ) {
-				/** @var FeatureInterface $feature */
+				/** @var FeatureInterface $feature */ // phpcs:ignore Generic.Commenting.DocComment.MissingShort -- inline @var type assertion, no description applies.
 				$feature              = $container->get( $feature_class );
 				$surviving_features[] = $feature;
 			}
@@ -252,7 +252,7 @@ protected function are_conditionals_met( string $feature_class, ContainerInterfa
 	 * @throws  FeatureException When a component class appears more than once in the graph.
 	 */
 	protected function assert_unique_component_graph( array $features ): void {
-		/** @var array<class-string, true> $seen */
+		/** @var array<class-string, true> $seen */ // phpcs:ignore Generic.Commenting.DocComment.MissingShort -- inline @var type assertion, no description applies.
 		$seen = array();
 		foreach ( $features as $feature ) {
 			foreach ( $feature->get_component_classes() as $component_class ) {
@@ -301,7 +301,7 @@ protected function assert_component_not_duplicated( string $component_class, arr
 	 * @return  list<object>
 	 */
 	protected function collect_runnable_components( array $features, ContainerInterface $container ): array {
-		/** @var list<object> $runnable */
+		/** @var list<object> $runnable */ // phpcs:ignore Generic.Commenting.DocComment.MissingShort -- inline @var type assertion, no description applies.
 		$runnable = array();
 		foreach ( $features as $feature ) {
 			foreach ( $feature->get_component_classes() as $component_class ) {
@@ -324,7 +324,7 @@ protected function collect_runnable_components( array $features, ContainerInterf
 	 * @param   list<object>       $runnable        Accumulating runnable list, by reference.
 	 */
 	protected function collect_runnable_subtree( string $component_class, ContainerInterface $container, array &$runnable ): void {
-		/** @var object $component */
+		/** @var object $component */ // phpcs:ignore Generic.Commenting.DocComment.MissingShort -- inline @var type assertion, no description applies.
 		$component = $container->get( $component_class );
 
 		if ( ! $this->is_runnable( $component ) ) {
diff --git a/packages/settings/src/Backend/WordPressSettingsBackend.php b/packages/settings/src/Backend/WordPressSettingsBackend.php
index 08530cf..8ec2505 100644
--- a/packages/settings/src/Backend/WordPressSettingsBackend.php
+++ b/packages/settings/src/Backend/WordPressSettingsBackend.php
@@ -320,7 +320,7 @@ protected function render_page( SettingsPage $page ): void {
 	 */
 	protected function render_field( string $option_name, SettingsField $field ): void {
 		$stored = \get_option( $option_name, array() );
-		$value  = \is_array( $stored ) && \array_key_exists( $field->id, $stored ) ? $stored[ $field->id ] : $field->default;
+		$value  = \is_array( $stored ) && \array_key_exists( $field->id, $stored ) ? $stored[ $field->id ] : $field->default_value;
 
 		// phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- FieldRenderer returns markup already escaped at each interpolation point.
 		echo $this->renderer->render( $field, $value, $option_name . '[' . $field->id . ']' );
diff --git a/packages/settings/src/Schema/FieldProcessor.php b/packages/settings/src/Schema/FieldProcessor.php
index 734ebad..a953c9f 100644
--- a/packages/settings/src/Schema/FieldProcessor.php
+++ b/packages/settings/src/Schema/FieldProcessor.php
@@ -118,7 +118,7 @@ public function process( SettingsField $field, array $input ): mixed {
 	 */
 	protected function process_custom( SettingsField $field, array $input ): mixed {
 		if ( ! \array_key_exists( $field->id, $input ) ) {
-			return $field->default;
+			return $field->default_value;
 		}
 
 		$value = $input[ $field->id ];
@@ -126,10 +126,10 @@ protected function process_custom( SettingsField $field, array $input ): mixed {
 		// A custom type is treated as scalar: a tampered array submission would fatal a scalar sanitizer
 		// (e.g. trim), so coerce a non-scalar to the field's default — mirroring the built-in scalar guard.
 		if ( ! \is_scalar( $value ) ) {
-			return $field->default;
+			return $field->default_value;
 		}
 
-		return $this->sanitize_and_validate( $field, $value, $field->default );
+		return $this->sanitize_and_validate( $field, $value, $field->default_value );
 	}
 
 	/**
diff --git a/packages/settings/src/Schema/ValueObjects/SettingsField.php b/packages/settings/src/Schema/ValueObjects/SettingsField.php
index 1c2b62e..9afc333 100644
--- a/packages/settings/src/Schema/ValueObjects/SettingsField.php
+++ b/packages/settings/src/Schema/ValueObjects/SettingsField.php
@@ -56,7 +56,7 @@
 	 * @param   string                                                            $id Page-unique field identifier; a lowercase token matching the field-id charset.
 	 * @param   string                                                            $type Field-type token resolved against the framework taxonomy when rendered or processed.
 	 * @param   string                                                            $label Human-readable field label.
-	 * @param   mixed                                                             $default Default value used when nothing is stored.
+	 * @param   mixed                                                             $default_value Default value used when nothing is stored.
 	 * @param   ?callable                                                         $sanitize Sanitizer for the submitted value; stored as a Closure.
 	 * @param   ?callable                                                         $validate Validator for the sanitized value; stored as a Closure.
 	 * @param   ?string                                                           $capability Capability required to edit the field; null inherits the section/page capability.
@@ -73,7 +73,7 @@ public function __construct(
 		public string $id,
 		public string $type,
 		public string $label,
-		public mixed $default = null,
+		public mixed $default_value = null,
 		?callable $sanitize = null,
 		?callable $validate = null,
 		public ?string $capability = null,
diff --git a/packages/settings/tests/Integration/WordPressSettingsBackendTest.php b/packages/settings/tests/Integration/WordPressSettingsBackendTest.php
index 2afb79a..cd49fac 100644
--- a/packages/settings/tests/Integration/WordPressSettingsBackendTest.php
+++ b/packages/settings/tests/Integration/WordPressSettingsBackendTest.php
@@ -364,7 +364,7 @@ public function test_a_custom_field_type_falls_back_to_its_default_when_validati
 							id: 'home_page',
 							type: 'single_select_page',
 							label: 'Home Page',
-							default: '7',
+							default_value: '7',
 							validate: static fn ( mixed $value ): bool => false,
 						),
 					),
diff --git a/packages/settings/tests/Unit/FieldProcessorTest.php b/packages/settings/tests/Unit/FieldProcessorTest.php
index f1dfabb..3195259 100644
--- a/packages/settings/tests/Unit/FieldProcessorTest.php
+++ b/packages/settings/tests/Unit/FieldProcessorTest.php
@@ -48,7 +48,7 @@ public function test_a_registered_custom_type_with_no_submission_returns_the_def
 		$processor = new FieldProcessor(
 			custom_types: array( 'color_picker' => $this->custom_type( 'color_picker' ) ),
 		);
-		$field     = new SettingsField( id: 'shade', type: 'color_picker', label: 'Shade', default: '#000' );
+		$field     = new SettingsField( id: 'shade', type: 'color_picker', label: 'Shade', default_value: '#000' );
 
 		self::assertSame( '#000', $processor->process( $field, array() ) );
 	}
@@ -61,7 +61,7 @@ public function test_a_registered_custom_type_failing_validation_returns_the_def
 			id: 'shade',
 			type: 'color_picker',
 			label: 'Shade',
-			default: '#fallback',
+			default_value: '#fallback',
 			validate: static fn ( mixed $value ): bool => false,
 		);
 
@@ -77,7 +77,7 @@ public function test_a_registered_custom_type_applies_sanitize_before_validate()
 			id: 'shade',
 			type: 'color_picker',
 			label: 'Shade',
-			default: '#fallback',
+			default_value: '#fallback',
 			sanitize: 'trim',
 			validate: static fn ( mixed $value ): bool => '#abc' === $value,
 		);
@@ -91,7 +91,7 @@ public function test_a_registered_custom_type_with_a_non_scalar_submission_retur
 		$processor = new FieldProcessor(
 			custom_types: array( 'color_picker' => $this->custom_type( 'color_picker' ) ),
 		);
-		$field     = new SettingsField( id: 'shade', type: 'color_picker', label: 'Shade', default: '#000', sanitize: 'trim' );
+		$field     = new SettingsField( id: 'shade', type: 'color_picker', label: 'Shade', default_value: '#000', sanitize: 'trim' );
 
 		self::assertSame( '#000', $processor->process( $field, array( 'shade' => array( 'x' ) ) ) );
 	}
diff --git a/packages/settings/tests/Unit/SettingsFieldTest.php b/packages/settings/tests/Unit/SettingsFieldTest.php
index 8026ce1..a092253 100644
--- a/packages/settings/tests/Unit/SettingsFieldTest.php
+++ b/packages/settings/tests/Unit/SettingsFieldTest.php
@@ -17,7 +17,7 @@ public function test_minimal_construction_exposes_documented_defaults(): void {
 		self::assertSame( 'my_field', $field->id );
 		self::assertSame( 'text', $field->type );
 		self::assertSame( 'My Field', $field->label );
-		self::assertNull( $field->default );
+		self::assertNull( $field->default_value );
 		self::assertNull( $field->sanitize );
 		self::assertNull( $field->validate );
 		self::assertNull( $field->capability );
@@ -35,7 +35,7 @@ public function test_full_construction_round_trips_every_value(): void {
 			id: 'field-2',
 			type: 'select',
 			label: 'Field 2',
-			default: 'a',
+			default_value: 'a',
 			sanitize: 'trim',
 			validate: 'is_string',
 			capability: 'manage_options',
@@ -47,7 +47,7 @@ public function test_full_construction_round_trips_every_value(): void {
 			description: 'Helpful hint',
 		);
 
-		self::assertSame( 'a', $field->default );
+		self::assertSame( 'a', $field->default_value );
 		self::assertSame( 'manage_options', $field->capability );
 		self::assertTrue( $field->show_in_rest );
 		self::assertSame( 5, $field->position );
diff --git a/packages/shared/src/Version/Exceptions/InvalidVersionException.php b/packages/shared/src/Version/Exceptions/InvalidVersionException.php
index 6e8a61b..4b9bc6e 100644
--- a/packages/shared/src/Version/Exceptions/InvalidVersionException.php
+++ b/packages/shared/src/Version/Exceptions/InvalidVersionException.php
@@ -19,7 +19,7 @@ final class InvalidVersionException extends InvalidValueObjectException {
 	 *
 	 * @var     string
 	 */
-	protected string $value_object_type {
+	protected string $value_object_type { // phpcs:ignore PHPCompatibility.Syntax.RemovedCurlyBraceArrayAccess.Removed -- PHP 8.4 property hook, not array access.
 		get => 'Version';
 	}
 }
diff --git a/packages/utilities/src/AdminNotices/AdminNoticesService.php b/packages/utilities/src/AdminNotices/AdminNoticesService.php
index 1381dfd..b4a8e80 100644
--- a/packages/utilities/src/AdminNotices/AdminNoticesService.php
+++ b/packages/utilities/src/AdminNotices/AdminNoticesService.php
@@ -95,7 +95,7 @@ public function add_notice( AdminNotice $notice, string $store = self::DEFAULT_S
 		if ( ! isset( $this->stores[ $store ] ) ) {
 			\_doing_it_wrong(
 				__METHOD__,
-				\sprintf( 'Unknown notice store "%s"; the notice was not queued.', $store ),
+				\esc_html( \sprintf( 'Unknown notice store "%s"; the notice was not queued.', $store ) ),
 				'2.0.0'
 			);
 			return;
@@ -215,7 +215,7 @@ public function handle_dismiss(): void {
 			$posted = \is_string( $posted ) ? \wp_unslash( $posted ) : '';
 			// Accept the posted ID only when it is already sanitize_key-stable, so it matches the stored
 			// notice ID exactly; reject (do not lossily normalize) anything else.
-			$id = ( \is_string( $posted ) && $posted === \sanitize_key( $posted ) ) ? $posted : '';
+			$id = ( \is_string( $posted ) && \sanitize_key( $posted ) === $posted ) ? $posted : '';
 			if ( '' !== $id ) {
 				$this->dismissals->dismiss( $id );
 			}
diff --git a/packages/utilities/src/Caching/TransientCache.php b/packages/utilities/src/Caching/TransientCache.php
index eaa8122..181837c 100644
--- a/packages/utilities/src/Caching/TransientCache.php
+++ b/packages/utilities/src/Caching/TransientCache.php
@@ -261,11 +261,13 @@ protected function is_within_length( string $full_key ): bool {
 
 		\_doing_it_wrong(
 			__METHOD__,
-			\sprintf(
-				'A transient key for prefix "%s" is %d characters, over the %d-character limit; caching is skipped.',
-				$this->key_prefix,
-				\strlen( $full_key ),
-				self::MAX_KEY_LENGTH
+			\esc_html(
+				\sprintf(
+					'A transient key for prefix "%s" is %d characters, over the %d-character limit; caching is skipped.',
+					$this->key_prefix,
+					\strlen( $full_key ),
+					self::MAX_KEY_LENGTH
+				)
 			),
 			'2.0.0'
 		);
@@ -289,10 +291,12 @@ protected function is_positive_expiration( int $expiration ): bool {
 
 		\_doing_it_wrong(
 			__METHOD__,
-			\sprintf(
-				'A transient for prefix "%s" needs a positive expiration; %d given, so caching is skipped.',
-				$this->key_prefix,
-				$expiration
+			\esc_html(
+				\sprintf(
+					'A transient for prefix "%s" needs a positive expiration; %d given, so caching is skipped.',
+					$this->key_prefix,
+					$expiration
+				)
 			),
 			'2.0.0'
 		);
diff --git a/packages/utilities/src/Scheduling/Backends/WPCronBackend.php b/packages/utilities/src/Scheduling/Backends/WPCronBackend.php
index b9af596..aa5c765 100644
--- a/packages/utilities/src/Scheduling/Backends/WPCronBackend.php
+++ b/packages/utilities/src/Scheduling/Backends/WPCronBackend.php
@@ -246,7 +246,7 @@ protected function reject_group( string $group ): ?Failure {
 	protected function ensure_schedule( int $interval ): string {
 		$this->registered_intervals[ $interval ] = true;
 		if ( ! $this->schedules_filter_registered ) {
-			\add_filter( 'cron_schedules', array( $this, 'register_synthetic_schedules' ) );
+			\add_filter( 'cron_schedules', array( $this, 'register_synthetic_schedules' ) ); // phpcs:ignore WordPress.WP.CronInterval.ChangeDetected -- synthetic intervals are registered dynamically; each is a positive int validated before scheduling.
 			$this->schedules_filter_registered = true;
 		}
 
diff --git a/packages/woocommerce/src/Backend/WCSettingsBuilder.php b/packages/woocommerce/src/Backend/WCSettingsBuilder.php
index d904fb0..d923574 100644
--- a/packages/woocommerce/src/Backend/WCSettingsBuilder.php
+++ b/packages/woocommerce/src/Backend/WCSettingsBuilder.php
@@ -100,7 +100,7 @@ protected function build_field( string $slug, SettingsField $field ): array {
 			'title' => $field->label,
 		);
 
-		if ( null !== $field->default ) {
+		if ( null !== $field->default_value ) {
 			$entry['default'] = $this->map_default( $field );
 		}
 
@@ -129,10 +129,10 @@ protected function build_field( string $slug, SettingsField $field ): array {
 	 */
 	protected function map_default( SettingsField $field ): mixed {
 		return match ( $field->type ) {
-			FieldType::Checkbox->value    => to_yes_no( $field->default ),
+			FieldType::Checkbox->value    => to_yes_no( $field->default_value ),
 			// WooCommerce matches multiselect selections with a strict (string) in_array, so the set must be strings.
-			FieldType::Multiselect->value => $this->stringify_selected( $field->default ),
-			default                       => $field->default,
+			FieldType::Multiselect->value => $this->stringify_selected( $field->default_value ),
+			default                       => $field->default_value,
 		};
 	}
 
@@ -182,18 +182,18 @@ protected function stringify_labels( array $options ): array {
 	 * @since   2.0.0
 	 * @version 2.0.0
 	 *
-	 * @param   mixed $default Field default to coerce into a list of selected string values.
+	 * @param   mixed $default_value Field default to coerce into a list of selected string values.
 	 *
 	 * @return  array<array-key, string>
 	 */
-	protected function stringify_selected( mixed $default ): array {
-		if ( ! \is_array( $default ) ) {
+	protected function stringify_selected( mixed $default_value ): array {
+		if ( ! \is_array( $default_value ) ) {
 			return array();
 		}
 
 		return \array_map(
 			static fn ( mixed $value ): string => \is_scalar( $value ) ? (string) $value : '',
-			$default,
+			$default_value,
 		);
 	}
 
diff --git a/packages/woocommerce/src/OrderData/OrderFieldStore.php b/packages/woocommerce/src/OrderData/OrderFieldStore.php
index 4e1d1ea..1b716f6 100644
--- a/packages/woocommerce/src/OrderData/OrderFieldStore.php
+++ b/packages/woocommerce/src/OrderData/OrderFieldStore.php
@@ -221,7 +221,7 @@ protected function add_box( ObjectMetaBox $box, string $screen ): void {
 		\add_meta_box(
 			$box->id,
 			\esc_html( $box->title ),
-			fn ( mixed $object ) => $this->render_box( $box, $object ),
+			fn ( mixed $wc_object ) => $this->render_box( $box, $wc_object ),
 			$screen,
 			$box->context,
 			$priority,
@@ -235,10 +235,10 @@ protected function add_box( ObjectMetaBox $box, string $screen ): void {
 	 * @version 2.0.0
 	 *
 	 * @param   ObjectMetaBox $box    Box being rendered.
-	 * @param   mixed         $object Screen object WordPress passes the callback (a WooCommerce order or WP_Post).
+	 * @param   mixed         $wc_object Screen object WordPress passes the callback (a WooCommerce order or WP_Post).
 	 */
-	protected function render_box( ObjectMetaBox $box, mixed $object ): void {
-		$object_id = $this->object_id_of( $object );
+	protected function render_box( ObjectMetaBox $box, mixed $wc_object ): void {
+		$object_id = $this->object_id_of( $wc_object );
 
 		// Emitted for every box, bespoke renderer included: save_box() verifies this nonce before it runs
 		// the bespoke save handler, so a bespoke renderer must not have to reimplement the convention.
@@ -283,7 +283,7 @@ protected function save_box( ObjectMetaBox $box, int $object_id ): void {
 		if ( false === \wp_verify_nonce( $nonce, $this->nonce_action( $box, $object_id ) ) ) {
 			return;
 		}
-		if ( ! \current_user_can( 'edit_shop_orders' ) ) {
+		if ( ! \current_user_can( 'edit_shop_orders' ) ) { // phpcs:ignore WordPress.WP.Capabilities.Unknown -- edit_shop_orders is a core WooCommerce capability.
 			return;
 		}
 
@@ -347,7 +347,7 @@ protected function save_box( ObjectMetaBox $box, int $object_id ): void {
 	 * @return  list<SettingsField>
 	 */
 	protected function fields_of( ObjectMetaBox $box, int $object_id ): array {
-		/** @var list<SettingsField> $fields */
+		/** @var list<SettingsField> $fields */ // phpcs:ignore Generic.Commenting.DocComment.MissingShort -- inline @var type assertion, no description applies.
 		$fields = ( $box->fields_provider )( $object_id );
 
 		$seen = array();
@@ -368,16 +368,16 @@ protected function fields_of( ObjectMetaBox $box, int $object_id ): array {
 	 * @since   2.0.0
 	 * @version 2.0.0
 	 *
-	 * @param   mixed $object Screen object (a WooCommerce order or WP_Post), or anything else.
+	 * @param   mixed $wc_object Screen object (a WooCommerce order or WP_Post), or anything else.
 	 *
 	 * @return  int
 	 */
-	protected function object_id_of( mixed $object ): int {
-		if ( $object instanceof \WC_Abstract_Order ) {
-			return $object->get_id();
+	protected function object_id_of( mixed $wc_object ): int {
+		if ( $wc_object instanceof \WC_Abstract_Order ) {
+			return $wc_object->get_id();
 		}
-		if ( $object instanceof \WP_Post ) {
-			return $object->ID;
+		if ( $wc_object instanceof \WP_Post ) {
+			return $wc_object->ID;
 		}
 
 		return 0;
diff --git a/packages/woocommerce/src/ProductData/ProductDataFieldStore.php b/packages/woocommerce/src/ProductData/ProductDataFieldStore.php
index 5b9b449..5f5ee73 100644
--- a/packages/woocommerce/src/ProductData/ProductDataFieldStore.php
+++ b/packages/woocommerce/src/ProductData/ProductDataFieldStore.php
@@ -96,7 +96,7 @@ public function register_tab( ProductDataTab $tab ): void {
 		\add_action( 'woocommerce_product_data_panels', fn () => $this->render_panel() );
 		\add_action( 'woocommerce_process_product_meta', fn ( int $product_id ) => $this->save( $product_id ) );
 		\add_filter( 'default_post_metadata', fn ( mixed $value, int $object_id, string $meta_key ): mixed => $this->inject_default( $value, $object_id, $meta_key ), 99, 3 );
-		\add_filter( 'woocommerce_data_store_wp_post_read_meta', fn ( array $meta_data, object $object ): array => $this->inject_default_bulk( $meta_data, $object ), 99, 2 );
+		\add_filter( 'woocommerce_data_store_wp_post_read_meta', fn ( array $meta_data, object $wc_object ): array => $this->inject_default_bulk( $meta_data, $wc_object ), 99, 2 );
 	}
 
 	/**
@@ -373,12 +373,12 @@ protected function inject_default( mixed $value, int $object_id, string $meta_ke
 	 * @version 2.0.0
 	 *
 	 * @param   array<int, object> $meta_data Raw meta rows WooCommerce read for the object.
-	 * @param   object             $object    Object the meta was read for.
+	 * @param   object             $wc_object    Object the meta was read for.
 	 *
 	 * @return  array<int, object>
 	 */
-	protected function inject_default_bulk( array $meta_data, object $object ): array {
-		if ( ! $object instanceof \WC_Product || ! $this->is_supported( $object->get_id() ) ) {
+	protected function inject_default_bulk( array $meta_data, object $wc_object ): array {
+		if ( ! $wc_object instanceof \WC_Product || ! $this->is_supported( $wc_object->get_id() ) ) {
 			return $meta_data;
 		}
 
@@ -507,7 +507,7 @@ protected function submitted_value( SettingsField $field, string $meta_key ): mi
 
 		if ( null === $type ) {
 			// A custom type has no taxonomy processor; run its own sanitize/validate, falling back to the default.
-			return $this->sanitize_and_validate( $field, $raw, $field->default );
+			return $this->sanitize_and_validate( $field, $raw, $field->default_value );
 		}
 
 		return $this->processor->process( $field, null === $raw ? array() : array( $field->id => $raw ) );
@@ -548,8 +548,8 @@ protected function sanitize_and_validate( SettingsField $field, mixed $value, mi
 	 */
 	protected function default_value( SettingsField $field ): mixed {
 		return FieldType::Checkbox === FieldType::tryFrom( $field->type )
-			? to_yes_no( $field->default )
-			: $field->default;
+			? to_yes_no( $field->default_value )
+			: $field->default_value;
 	}
 
 	/**
diff --git a/packages/woocommerce/tests/Integration/OrderData/OrderFieldStoreTest.php b/packages/woocommerce/tests/Integration/OrderData/OrderFieldStoreTest.php
index 6e10a57..498e501 100644
--- a/packages/woocommerce/tests/Integration/OrderData/OrderFieldStoreTest.php
+++ b/packages/woocommerce/tests/Integration/OrderData/OrderFieldStoreTest.php
@@ -304,7 +304,7 @@ public function test_clearing_a_field_with_a_default_revokes_it_without_restorin
 			context: 'side',
 			priority: 'default',
 			fields_provider: static fn ( int $object_id ): array => array(
-				new SettingsField( id: 'note', type: 'text', label: 'Note', default: 'preset' ),
+				new SettingsField( id: 'note', type: 'text', label: 'Note', default_value: 'preset' ),
 			),
 		);
 		$store = new OrderFieldStore();
diff --git a/packages/woocommerce/tests/Integration/ProductDataFieldStoreTest.php b/packages/woocommerce/tests/Integration/ProductDataFieldStoreTest.php
index 4429d68..f13c9c4 100644
--- a/packages/woocommerce/tests/Integration/ProductDataFieldStoreTest.php
+++ b/packages/woocommerce/tests/Integration/ProductDataFieldStoreTest.php
@@ -216,7 +216,7 @@ public function test_save_runs_sanitize_and_validate_on_a_custom_field(): void {
 					id: 'span',
 					type: 'dws_custom',
 					label: 'Span',
-					default: 'fallback',
+					default_value: 'fallback',
 					sanitize: static fn ( mixed $v ): string => \trim( (string) $v ),
 					validate: static fn ( mixed $v ): bool => 'reject' !== $v,
 				),
@@ -501,7 +501,7 @@ private function tab( ?\Closure $supports = null, array|\Closure $classes = arra
 					'general',
 					'General',
 					array(
-						new SettingsField( id: 'warranty-type', type: 'select', label: 'Type', default: 'global', options: array( 'global' => 'Global', 'addon' => 'Add-on' ) ),
+						new SettingsField( id: 'warranty-type', type: 'select', label: 'Type', default_value: 'global', options: array( 'global' => 'Global', 'addon' => 'Add-on' ) ),
 						new SettingsField( id: 'code', type: 'text', label: 'Code' ),
 					),
 				),
diff --git a/packages/woocommerce/tests/Unit/WCSettingsBuilderTest.php b/packages/woocommerce/tests/Unit/WCSettingsBuilderTest.php
index 713ea3e..e4afefb 100644
--- a/packages/woocommerce/tests/Unit/WCSettingsBuilderTest.php
+++ b/packages/woocommerce/tests/Unit/WCSettingsBuilderTest.php
@@ -110,7 +110,7 @@ public function test_custom_attributes_are_omitted_when_empty(): void {
 
 	public function test_a_truthy_checkbox_default_maps_to_the_wc_yes_string(): void {
 		$page = $this->page_with_field(
-			new SettingsField( id: 'flag', type: 'checkbox', label: 'Flag', default: true ),
+			new SettingsField( id: 'flag', type: 'checkbox', label: 'Flag', default_value: true ),
 		);
 
 		$row = $this->row_by_id( ( new WCSettingsBuilder() )->build( $page ), 'dws-shop_flag' );
@@ -120,7 +120,7 @@ public function test_a_truthy_checkbox_default_maps_to_the_wc_yes_string(): void
 
 	public function test_a_falsy_checkbox_default_maps_to_the_wc_no_string(): void {
 		$page = $this->page_with_field(
-			new SettingsField( id: 'flag', type: 'checkbox', label: 'Flag', default: false ),
+			new SettingsField( id: 'flag', type: 'checkbox', label: 'Flag', default_value: false ),
 		);
 
 		$row = $this->row_by_id( ( new WCSettingsBuilder() )->build( $page ), 'dws-shop_flag' );
@@ -130,7 +130,7 @@ public function test_a_falsy_checkbox_default_maps_to_the_wc_no_string(): void {
 
 	public function test_a_truthy_non_boolean_checkbox_default_maps_to_the_wc_yes_string(): void {
 		$page = $this->page_with_field(
-			new SettingsField( id: 'flag', type: 'checkbox', label: 'Flag', default: 1 ),
+			new SettingsField( id: 'flag', type: 'checkbox', label: 'Flag', default_value: 1 ),
 		);
 
 		$row = $this->row_by_id( ( new WCSettingsBuilder() )->build( $page ), 'dws-shop_flag' );
@@ -140,7 +140,7 @@ public function test_a_truthy_non_boolean_checkbox_default_maps_to_the_wc_yes_st
 
 	public function test_a_string_yes_checkbox_default_maps_to_the_wc_yes_string(): void {
 		$page = $this->page_with_field(
-			new SettingsField( id: 'flag', type: 'checkbox', label: 'Flag', default: 'yes' ),
+			new SettingsField( id: 'flag', type: 'checkbox', label: 'Flag', default_value: 'yes' ),
 		);
 
 		$row = $this->row_by_id( ( new WCSettingsBuilder() )->build( $page ), 'dws-shop_flag' );
@@ -151,7 +151,7 @@ public function test_a_string_yes_checkbox_default_maps_to_the_wc_yes_string():
 	public function test_a_string_no_checkbox_default_maps_to_the_wc_no_string(): void {
 		// Canonical rule: 'no' is unchecked. The superseded (bool) cast mapped the truthy 'no' to 'yes'.
 		$page = $this->page_with_field(
-			new SettingsField( id: 'flag', type: 'checkbox', label: 'Flag', default: 'no' ),
+			new SettingsField( id: 'flag', type: 'checkbox', label: 'Flag', default_value: 'no' ),
 		);
 
 		$row = $this->row_by_id( ( new WCSettingsBuilder() )->build( $page ), 'dws-shop_flag' );
@@ -162,7 +162,7 @@ public function test_a_string_no_checkbox_default_maps_to_the_wc_no_string(): vo
 	public function test_an_arbitrary_string_checkbox_default_maps_to_the_wc_no_string(): void {
 		// Canonical rule: any non-canonical string is unchecked. The superseded (bool) cast mapped it to 'yes'.
 		$page = $this->page_with_field(
-			new SettingsField( id: 'flag', type: 'checkbox', label: 'Flag', default: 'anything' ),
+			new SettingsField( id: 'flag', type: 'checkbox', label: 'Flag', default_value: 'anything' ),
 		);
 
 		$row = $this->row_by_id( ( new WCSettingsBuilder() )->build( $page ), 'dws-shop_flag' );
@@ -247,7 +247,7 @@ public function test_options_are_not_emitted_for_a_non_choice_field(): void {
 
 	public function test_multiselect_default_values_are_stringified(): void {
 		$page = $this->page_with_field(
-			new SettingsField( id: 'tags', type: 'multiselect', label: 'Tags', default: array( 1, 2 ), options: array( 1 => 'One', 2 => 'Two' ) ),
+			new SettingsField( id: 'tags', type: 'multiselect', label: 'Tags', default_value: array( 1, 2 ), options: array( 1 => 'One', 2 => 'Two' ) ),
 		);
 
 		$row = $this->row_by_id( ( new WCSettingsBuilder() )->build( $page ), 'dws-shop_tags' );
@@ -257,7 +257,7 @@ public function test_multiselect_default_values_are_stringified(): void {
 
 	public function test_a_non_array_multiselect_default_becomes_an_empty_array(): void {
 		$page = $this->page_with_field(
-			new SettingsField( id: 'tags', type: 'multiselect', label: 'Tags', default: 'oops', options: array( 'a' => 'A' ) ),
+			new SettingsField( id: 'tags', type: 'multiselect', label: 'Tags', default_value: 'oops', options: array( 'a' => 'A' ) ),
 		);
 
 		$row = $this->row_by_id( ( new WCSettingsBuilder() )->build( $page ), 'dws-shop_tags' );
@@ -288,7 +288,7 @@ private function page(): SettingsPage {
 					'general',
 					'General',
 					array(
-						new SettingsField( id: 'store_name', type: 'text', label: 'Store Name', default: 'Acme' ),
+						new SettingsField( id: 'store_name', type: 'text', label: 'Store Name', default_value: 'Acme' ),
 						new SettingsField( id: 'gateway', type: 'select', label: 'Gateway', options: array( 'stripe' => 'Stripe', 'paypal' => 'PayPal' ) ),
 					),
 				),
diff --git a/phpstan.dist.neon b/phpstan.dist.neon
index e29ab99..8d8f90d 100644
--- a/phpstan.dist.neon
+++ b/phpstan.dist.neon
@@ -2,10 +2,7 @@ includes:
     - vendor/ahegyes/wordpress-configs/php/quality-assurance/phpstan.dist.neon
 
 parameters:
-    # WooCommerce symbols (OrderUtil, WC_Order, wc_get_order) used by the woocommerce
-    # package's order-field store and settings page; the shared config only wires the WordPress stubs.
-    # The packages-stubs file additionally defines the Action Scheduler as_* functions the
-    # utilities scheduling backend calls (woocommerce-stubs.php does not).
+    # The shared config wires only the WordPress stubs; the packages-stubs file adds Action Scheduler's as_* functions (the woocommerce-stubs file does not).
     bootstrapFiles:
         - vendor/php-stubs/woocommerce-stubs/woocommerce-stubs.php
         - vendor/php-stubs/woocommerce-stubs/woocommerce-packages-stubs.php
@@ -17,8 +14,10 @@ parameters:
         - packages/shared/functions.php
         - packages/shared/src
         - packages/shared/tests
+        - packages/storage/functions.php
         - packages/storage/src
         - packages/storage/tests
+        - packages/core/functions.php
         - packages/core/src
         - packages/core/tests
         - packages/utilities/functions.php

From 5b8c331666f0bf7d3903c83d7ee7ed3ea4e65d6f Mon Sep 17 00:00:00 2001
From: Tony Hegyes <a.hegyes@proton.me>
Date: Sat, 27 Jun 2026 11:56:50 +0200
Subject: [PATCH 21/21] update packages

---
 composer.lock     | 162 ++++++++++++------------
 package-lock.json | 313 +++++++++++++++++++++++-----------------------
 package.json      |   2 +-
 3 files changed, 243 insertions(+), 234 deletions(-)

diff --git a/composer.lock b/composer.lock
index 530c8b1..440ce48 100644
--- a/composer.lock
+++ b/composer.lock
@@ -83,7 +83,7 @@
             "dist": {
                 "type": "path",
                 "url": "packages/core",
-                "reference": "85894d9c704a66a1b2b6f0464eb7bd91512d1224"
+                "reference": "6ada2f7b74e4fe22320638482e438f2936245dfe"
             },
             "require": {
                 "ahegyes/wp-framework-bootstrap": "^2.0@dev",
@@ -309,7 +309,7 @@
             "dist": {
                 "type": "path",
                 "url": "packages/storage",
-                "reference": "fe7985a381301804b0a851bb5f5dd8d392851b0f"
+                "reference": "bca0455241dd8fdfa8de5995904a19341d5c1107"
             },
             "require": {
                 "php": ">=8.5"
@@ -649,12 +649,12 @@
             "source": {
                 "type": "git",
                 "url": "https://github.com/ahegyes/wordpress-configs.git",
-                "reference": "4431b7b9b44e09c516122c9fc7bcab74c0356b0c"
+                "reference": "501f26d1d8398deea4fe6829e7871432a4f46a6b"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/ahegyes/wordpress-configs/zipball/4431b7b9b44e09c516122c9fc7bcab74c0356b0c",
-                "reference": "4431b7b9b44e09c516122c9fc7bcab74c0356b0c",
+                "url": "https://api.github.com/repos/ahegyes/wordpress-configs/zipball/501f26d1d8398deea4fe6829e7871432a4f46a6b",
+                "reference": "501f26d1d8398deea4fe6829e7871432a4f46a6b",
                 "shasum": ""
             },
             "require": {
@@ -758,7 +758,7 @@
                 "source": "https://github.com/ahegyes/wordpress-configs/tree/trunk",
                 "issues": "https://github.com/ahegyes/wordpress-configs/issues"
             },
-            "time": "2026-06-22T11:51:08+00:00"
+            "time": "2026-06-27T09:52:42+00:00"
         },
         {
             "name": "automattic/jetpack-changelogger",
@@ -2498,16 +2498,16 @@
         },
         {
             "name": "php-stubs/woocommerce-stubs",
-            "version": "v10.8.0",
+            "version": "v10.9.1",
             "source": {
                 "type": "git",
                 "url": "https://github.com/php-stubs/woocommerce-stubs.git",
-                "reference": "9d59e65dcabc18153c243cb9acd85fc88ef40589"
+                "reference": "e6d583b9fa05b3f5ff67f86c939b45a0c35b8444"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/php-stubs/woocommerce-stubs/zipball/9d59e65dcabc18153c243cb9acd85fc88ef40589",
-                "reference": "9d59e65dcabc18153c243cb9acd85fc88ef40589",
+                "url": "https://api.github.com/repos/php-stubs/woocommerce-stubs/zipball/e6d583b9fa05b3f5ff67f86c939b45a0c35b8444",
+                "reference": "e6d583b9fa05b3f5ff67f86c939b45a0c35b8444",
                 "shasum": ""
             },
             "require": {
@@ -2536,9 +2536,9 @@
             ],
             "support": {
                 "issues": "https://github.com/php-stubs/woocommerce-stubs/issues",
-                "source": "https://github.com/php-stubs/woocommerce-stubs/tree/v10.8.0"
+                "source": "https://github.com/php-stubs/woocommerce-stubs/tree/v10.9.1"
             },
-            "time": "2026-05-27T11:46:50+00:00"
+            "time": "2026-06-25T10:47:57+00:00"
         },
         {
             "name": "php-stubs/wordpress-stubs",
@@ -3997,12 +3997,12 @@
             "source": {
                 "type": "git",
                 "url": "https://github.com/Roave/SecurityAdvisories.git",
-                "reference": "bfdbd26a02c71b3b00586f056c8cf5efea22a27a"
+                "reference": "36ba91e82e1b493faef2c13277d6bd2669ea9f31"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/Roave/SecurityAdvisories/zipball/bfdbd26a02c71b3b00586f056c8cf5efea22a27a",
-                "reference": "bfdbd26a02c71b3b00586f056c8cf5efea22a27a",
+                "url": "https://api.github.com/repos/Roave/SecurityAdvisories/zipball/36ba91e82e1b493faef2c13277d6bd2669ea9f31",
+                "reference": "36ba91e82e1b493faef2c13277d6bd2669ea9f31",
                 "shasum": ""
             },
             "conflict": {
@@ -4019,6 +4019,7 @@
                 "aimeos/aimeos-core": ">=2022.04.1,<2022.10.17|>=2023.04.1,<2023.10.17|>=2024.04.1,<2024.04.7",
                 "aimeos/aimeos-laravel": "==2021.10",
                 "aimeos/aimeos-typo3": "<19.10.12|>=20,<20.10.5",
+                "aimeos/pagible": "<0.10.4",
                 "airesvsg/acf-to-rest-api": "<=3.1",
                 "akaunting/akaunting": "<2.1.13",
                 "akeneo/pim-community-dev": "<5.0.119|>=6,<6.0.53",
@@ -4104,7 +4105,7 @@
                 "cachethq/cachet": "<2.5.1",
                 "cadmium-org/cadmium-cms": "<=0.4.9",
                 "cakephp/authentication": "<3.3.6|>=4,<4.1.1",
-                "cakephp/cakephp": "<3.10.3|>=4,<4.0.10|>=4.1,<4.1.4|>=4.2,<4.2.12|>=4.3,<4.3.11|>=4.4,<4.4.10|>=5.2.10,<5.2.12|==5.3",
+                "cakephp/cakephp": "<4.5.11|>=4.6,<4.6.4|>=5,<5.1.7|>=5.2,<5.2.13|>=5.3,<5.3.6",
                 "cakephp/database": ">=4.2,<4.2.12|>=4.3,<4.3.11|>=4.4,<4.4.10",
                 "cardgate/magento2": "<2.0.33",
                 "cardgate/woocommerce": "<=3.1.15",
@@ -4136,7 +4137,7 @@
                 "commerceteam/commerce": ">=0.9.6,<0.9.9",
                 "components/jquery": ">=1.0.3,<3.5",
                 "composer/composer": "<2.2.28|>=2.3,<2.9.8",
-                "concrete5/concrete5": "<9.4.8",
+                "concrete5/concrete5": "<9.5.1",
                 "concrete5/core": "<8.5.8|>=9,<9.1",
                 "contao-components/mediaelement": ">=2.14.2,<2.21.1",
                 "contao/comments-bundle": ">=2,<4.13.40|>=5.0.0.0-RC1-dev,<5.3.4",
@@ -4281,10 +4282,10 @@
                 "feehi/feehicms": "<=2.1.1",
                 "fenom/fenom": "<=2.12.1",
                 "filament/actions": ">=3.2,<3.2.123|>=4,<=4.11.3|>=5,<=5.6.3",
-                "filament/filament": ">=4,<4.3.1",
+                "filament/filament": ">=3,<=3.3.51|>=4,<4.11.5|>=5,<5.6.5",
                 "filament/forms": ">=3,<=3.3.52",
-                "filament/infolists": ">=3,<3.2.115",
-                "filament/tables": ">=3,<=3.3.50|>=4,<4.8.5|>=5,<5.3.5",
+                "filament/infolists": ">=3,<3.2.115|>=4,<=4.11.4|>=5,<=5.6.4",
+                "filament/tables": ">=3,<=3.3.50|>=4,<=4.11.4|>=5,<=5.6.4",
                 "filegator/filegator": "<7.8",
                 "filp/whoops": "<2.1.13",
                 "fineuploader/php-traditional-server": "<=1.2.2",
@@ -4613,6 +4614,7 @@
                 "paragonie/random_compat": "<2",
                 "paragonie/sodium_compat": "<1.24|>=2,<2.5",
                 "passbolt/passbolt_api": "<4.6.2",
+                "paymenter/paymenter": "<1.5",
                 "paypal/adaptivepayments-sdk-php": "<=3.9.2",
                 "paypal/invoice-sdk-php": "<=3.9",
                 "paypal/merchant-sdk-php": "<3.12",
@@ -4630,13 +4632,15 @@
                 "phenx/php-svg-lib": "<0.5.2",
                 "php-censor/php-censor": "<2.0.13|>=2.1,<2.1.5",
                 "php-mod/curl": "<2.3.2",
+                "php-standard-library/h2": ">=6.1,<6.1.2|>=6.2,<6.2.1",
+                "php-standard-library/php-standard-library": ">=6.1,<6.1.2|>=6.2,<6.2.1",
                 "phpbb/phpbb": "<3.3.16|==4.0.0.0-alpha1",
                 "phpems/phpems": ">=6,<=6.1.3",
                 "phpfastcache/phpfastcache": "<6.1.5|>=7,<7.1.2|>=8,<8.0.7",
                 "phpmailer/phpmailer": "<6.5",
                 "phpmussel/phpmussel": ">=1,<1.6",
                 "phpmyadmin/phpmyadmin": "<5.2.2",
-                "phpmyfaq/phpmyfaq": "<4.1.3",
+                "phpmyfaq/phpmyfaq": "<4.1.4",
                 "phpoffice/common": "<0.2.9",
                 "phpoffice/math": "<=0.2",
                 "phpoffice/phpexcel": "<=1.8.2",
@@ -4666,6 +4670,7 @@
                 "pocketmine/bedrock-protocol": "<8.0.2",
                 "pocketmine/pocketmine-mp": "<5.42.1",
                 "pocketmine/raklib": ">=0.14,<0.14.6|>=0.15,<0.15.1",
+                "pontedilana/php-weasyprint": "<=2.5.1",
                 "poweradmin/poweradmin": "<4.2.4|>=4.3,<4.3.3",
                 "pressbooks/pressbooks": "<5.18",
                 "prestashop/autoupgrade": ">=4,<4.10.1",
@@ -4744,10 +4749,10 @@
                 "silverstripe-australia/advancedreports": ">=1,<=2",
                 "silverstripe/admin": "<1.13.19|>=2,<2.1.8",
                 "silverstripe/assets": "<2.4.5|>=3,<3.1.3",
-                "silverstripe/cms": "<4.11.3",
+                "silverstripe/cms": "<6.2.1",
                 "silverstripe/comments": ">=1.3,<3.1.1",
                 "silverstripe/forum": "<0.6.2|>=0.7,<0.7.4",
-                "silverstripe/framework": "<5.3.23",
+                "silverstripe/framework": "<6.2.2",
                 "silverstripe/graphql": ">=2,<2.0.5|>=3,<3.8.2|>=4,<4.3.7|>=5,<5.1.3",
                 "silverstripe/hybridsessions": ">=1,<2.4.1|>=2.5,<2.5.1",
                 "silverstripe/recipe-cms": ">=4.5,<4.5.3",
@@ -4757,7 +4762,8 @@
                 "silverstripe/silverstripe-omnipay": "<2.5.2|>=3,<3.0.2|>=3.1,<3.1.4|>=3.2,<3.2.1",
                 "silverstripe/subsites": ">=2,<2.6.1",
                 "silverstripe/taxonomy": ">=1.3,<1.3.1|>=2,<2.0.1",
-                "silverstripe/userforms": "<3|>=5,<5.4.2",
+                "silverstripe/userforms": "<6.4.9|>=7,<7.0.7|>=7.1,<7.1.1",
+                "silverstripe/versioned": "<3.2.1",
                 "silverstripe/versioned-admin": ">=1,<1.11.1",
                 "simogeo/filemanager": "<=2.5",
                 "simple-updates/phpwhois": "<=1",
@@ -4776,12 +4782,13 @@
                 "sjbr/sr-freecap": "<2.4.6|>=2.5,<2.5.3",
                 "sjbr/static-info-tables": "<2.3.1",
                 "slim/psr7": "<1.4.1|>=1.5,<1.5.1|>=1.6,<1.6.1",
-                "slim/slim": "<2.6",
+                "slim/slim": "<2.6|>=4.4,<=4.15.1",
                 "slub/slub-events": "<3.0.3",
                 "smarty/smarty": "<4.5.3|>=5,<5.1.1",
-                "snipe/snipe-it": "<8.4.1",
+                "snipe/snipe-it": "<=8.6.1",
                 "socalnick/scn-social-auth": "<1.15.2",
                 "socialiteproviders/steam": "<1.1",
+                "solidinvoice/solidinvoice": "<=2.3.15",
                 "solspace/craft-freeform": "<4.1.29|>=5,<=5.14.6",
                 "soosyze/soosyze": "<=2",
                 "spatie/browsershot": "<5.0.5",
@@ -4799,7 +4806,7 @@
                 "starcitizentools/short-description": ">=4,<4.0.1",
                 "starcitizentools/tabber-neue": ">=1.9.1,<2.7.2|>=3,<3.1.1",
                 "starcitizenwiki/embedvideo": "<=4",
-                "statamic/cms": "<5.73.22|>=6,<6.18.1",
+                "statamic/cms": "<5.74|>=6,<6.20.3",
                 "stormpath/sdk": "<9.9.99",
                 "studio-42/elfinder": "<=2.1.67",
                 "studiomitte/friendlycaptcha": "<0.1.4",
@@ -4819,6 +4826,7 @@
                 "sylius/paypal-plugin": "<1.6.2|>=1.7,<1.7.2|>=2,<2.0.2",
                 "sylius/resource-bundle": ">=1,<1.3.14|>=1.4,<1.4.7|>=1.5,<1.5.2|>=1.6,<1.6.4",
                 "sylius/sylius": "<1.9.12|>=1.10,<1.10.16|>=1.11,<1.11.17|>=1.12,<=1.12.22|>=1.13,<=1.13.14|>=1.14,<=1.14.17|>=2,<=2.0.15|>=2.1,<=2.1.11|>=2.2,<=2.2.2",
+                "symbiote/silverstripe-advancedworkflow": "<6.4.5|>=7,<7.1.3|>=7.2,<7.2.1",
                 "symbiote/silverstripe-multivaluefield": ">=3,<3.1",
                 "symbiote/silverstripe-queuedjobs": ">=3,<3.0.2|>=3.1,<3.1.4|>=4,<4.0.7|>=4.1,<4.1.2|>=4.2,<4.2.4|>=4.3,<4.3.3|>=4.4,<4.4.3|>=4.5,<4.5.1|>=4.6,<4.6.4",
                 "symbiote/silverstripe-seed": "<6.0.3",
@@ -4886,7 +4894,7 @@
                 "thelia/thelia": ">=2.1,<2.1.3",
                 "theonedemon/phpwhois": "<=4.2.5",
                 "thinkcmf/thinkcmf": "<6.0.8",
-                "thorsten/phpmyfaq": "<4.1.3",
+                "thorsten/phpmyfaq": "<4.1.4",
                 "tikiwiki/tiki-manager": "<=17.1",
                 "timber/timber": ">=0.16.6,<1.23.1|>=1.24,<1.24.1|>=2,<2.1",
                 "tinymce/tinymce": "<7.9.3|>=8,<8.5.1",
@@ -4966,7 +4974,7 @@
                 "wapplersystems/a21glossary": "<=0.4.10",
                 "web-auth/webauthn-framework": ">=3.3,<3.3.4|>=4.5,<4.9|>=5.2,<5.2.4|>=5.3,<5.3.1",
                 "web-auth/webauthn-lib": ">=4.5,<4.9|>=5.2,<5.2.4",
-                "web-auth/webauthn-symfony-bundle": ">=5.2,<5.2.4",
+                "web-auth/webauthn-symfony-bundle": "<5.3.4",
                 "web-feet/coastercms": "==5.5",
                 "web-token/jwt-experimental": "<=4.1.6",
                 "web-token/jwt-framework": "<=4.2.99",
@@ -5096,7 +5104,7 @@
                     "type": "tidelift"
                 }
             ],
-            "time": "2026-06-19T21:28:22+00:00"
+            "time": "2026-06-26T23:29:05+00:00"
         },
         {
             "name": "sanmai/di-container",
@@ -6595,16 +6603,16 @@
         },
         {
             "name": "symfony/config",
-            "version": "v8.1.0",
+            "version": "v8.1.1",
             "source": {
                 "type": "git",
                 "url": "https://github.com/symfony/config.git",
-                "reference": "429783a0c649696f2058ea5ab5315f082dba6de9"
+                "reference": "c18ae45733f9a5006ba81a13047d08a93e0dea1c"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/symfony/config/zipball/429783a0c649696f2058ea5ab5315f082dba6de9",
-                "reference": "429783a0c649696f2058ea5ab5315f082dba6de9",
+                "url": "https://api.github.com/repos/symfony/config/zipball/c18ae45733f9a5006ba81a13047d08a93e0dea1c",
+                "reference": "c18ae45733f9a5006ba81a13047d08a93e0dea1c",
                 "shasum": ""
             },
             "require": {
@@ -6649,7 +6657,7 @@
             "description": "Helps you find, load, combine, autofill and validate configuration values of any kind",
             "homepage": "https://symfony.com",
             "support": {
-                "source": "https://github.com/symfony/config/tree/v8.1.0"
+                "source": "https://github.com/symfony/config/tree/v8.1.1"
             },
             "funding": [
                 {
@@ -6669,20 +6677,20 @@
                     "type": "tidelift"
                 }
             ],
-            "time": "2026-05-29T05:06:50+00:00"
+            "time": "2026-06-09T10:54:51+00:00"
         },
         {
             "name": "symfony/console",
-            "version": "v7.4.13",
+            "version": "v7.4.14",
             "source": {
                 "type": "git",
                 "url": "https://github.com/symfony/console.git",
-                "reference": "85095d2573eaefaf35e40b9513a9bf09f72cd217"
+                "reference": "92f58bc4bf97a92ed1b9f367f0cd44f20bde0e87"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/symfony/console/zipball/85095d2573eaefaf35e40b9513a9bf09f72cd217",
-                "reference": "85095d2573eaefaf35e40b9513a9bf09f72cd217",
+                "url": "https://api.github.com/repos/symfony/console/zipball/92f58bc4bf97a92ed1b9f367f0cd44f20bde0e87",
+                "reference": "92f58bc4bf97a92ed1b9f367f0cd44f20bde0e87",
                 "shasum": ""
             },
             "require": {
@@ -6747,7 +6755,7 @@
                 "terminal"
             ],
             "support": {
-                "source": "https://github.com/symfony/console/tree/v7.4.13"
+                "source": "https://github.com/symfony/console/tree/v7.4.14"
             },
             "funding": [
                 {
@@ -6767,20 +6775,20 @@
                     "type": "tidelift"
                 }
             ],
-            "time": "2026-05-24T08:56:14+00:00"
+            "time": "2026-06-16T11:50:14+00:00"
         },
         {
             "name": "symfony/dependency-injection",
-            "version": "v8.1.0",
+            "version": "v8.1.1",
             "source": {
                 "type": "git",
                 "url": "https://github.com/symfony/dependency-injection.git",
-                "reference": "b6ba1f45127106885de4b77558c5ecca8feb1e1b"
+                "reference": "99ced9d6305c43b25a7d48fe6a7d169df275a597"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/symfony/dependency-injection/zipball/b6ba1f45127106885de4b77558c5ecca8feb1e1b",
-                "reference": "b6ba1f45127106885de4b77558c5ecca8feb1e1b",
+                "url": "https://api.github.com/repos/symfony/dependency-injection/zipball/99ced9d6305c43b25a7d48fe6a7d169df275a597",
+                "reference": "99ced9d6305c43b25a7d48fe6a7d169df275a597",
                 "shasum": ""
             },
             "require": {
@@ -6828,7 +6836,7 @@
             "description": "Allows you to standardize and centralize the way objects are constructed in your application",
             "homepage": "https://symfony.com",
             "support": {
-                "source": "https://github.com/symfony/dependency-injection/tree/v8.1.0"
+                "source": "https://github.com/symfony/dependency-injection/tree/v8.1.1"
             },
             "funding": [
                 {
@@ -6848,7 +6856,7 @@
                     "type": "tidelift"
                 }
             ],
-            "time": "2026-05-29T05:06:50+00:00"
+            "time": "2026-06-27T06:18:14+00:00"
         },
         {
             "name": "symfony/deprecation-contracts",
@@ -6923,16 +6931,16 @@
         },
         {
             "name": "symfony/event-dispatcher",
-            "version": "v8.1.0",
+            "version": "v8.1.1",
             "source": {
                 "type": "git",
                 "url": "https://github.com/symfony/event-dispatcher.git",
-                "reference": "f249ae3f680958b6f1f9dd76e5747cf0695b4102"
+                "reference": "abd6c11dc468725d1627302ad10f6cd486e9e3d0"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/symfony/event-dispatcher/zipball/f249ae3f680958b6f1f9dd76e5747cf0695b4102",
-                "reference": "f249ae3f680958b6f1f9dd76e5747cf0695b4102",
+                "url": "https://api.github.com/repos/symfony/event-dispatcher/zipball/abd6c11dc468725d1627302ad10f6cd486e9e3d0",
+                "reference": "abd6c11dc468725d1627302ad10f6cd486e9e3d0",
                 "shasum": ""
             },
             "require": {
@@ -6985,7 +6993,7 @@
             "description": "Provides tools that allow your application components to communicate with each other by dispatching events and listening to them",
             "homepage": "https://symfony.com",
             "support": {
-                "source": "https://github.com/symfony/event-dispatcher/tree/v8.1.0"
+                "source": "https://github.com/symfony/event-dispatcher/tree/v8.1.1"
             },
             "funding": [
                 {
@@ -7005,7 +7013,7 @@
                     "type": "tidelift"
                 }
             ],
-            "time": "2026-05-29T05:06:50+00:00"
+            "time": "2026-06-09T12:28:30+00:00"
         },
         {
             "name": "symfony/event-dispatcher-contracts",
@@ -7160,16 +7168,16 @@
         },
         {
             "name": "symfony/finder",
-            "version": "v8.1.0",
+            "version": "v8.1.1",
             "source": {
                 "type": "git",
                 "url": "https://github.com/symfony/finder.git",
-                "reference": "58d2e767a66052c1487356f953445634a8194c64"
+                "reference": "e2989e762c70f9490fa3a00a0ac0fae5aa97a531"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/symfony/finder/zipball/58d2e767a66052c1487356f953445634a8194c64",
-                "reference": "58d2e767a66052c1487356f953445634a8194c64",
+                "url": "https://api.github.com/repos/symfony/finder/zipball/e2989e762c70f9490fa3a00a0ac0fae5aa97a531",
+                "reference": "e2989e762c70f9490fa3a00a0ac0fae5aa97a531",
                 "shasum": ""
             },
             "require": {
@@ -7204,7 +7212,7 @@
             "description": "Finds files and directories via an intuitive fluent interface",
             "homepage": "https://symfony.com",
             "support": {
-                "source": "https://github.com/symfony/finder/tree/v8.1.0"
+                "source": "https://github.com/symfony/finder/tree/v8.1.1"
             },
             "funding": [
                 {
@@ -7224,7 +7232,7 @@
                     "type": "tidelift"
                 }
             ],
-            "time": "2026-05-29T05:06:50+00:00"
+            "time": "2026-06-27T09:05:56+00:00"
         },
         {
             "name": "symfony/polyfill-ctype",
@@ -7972,22 +7980,22 @@
         },
         {
             "name": "symfony/var-exporter",
-            "version": "v8.1.0",
+            "version": "v8.1.1",
             "source": {
                 "type": "git",
                 "url": "https://github.com/symfony/var-exporter.git",
-                "reference": "2dd18582c5f6c024db9fc0ff9c76d873af726f34"
+                "reference": "75b74315b4e4be40e5534cf9c5cc30dd0907ed71"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/symfony/var-exporter/zipball/2dd18582c5f6c024db9fc0ff9c76d873af726f34",
-                "reference": "2dd18582c5f6c024db9fc0ff9c76d873af726f34",
+                "url": "https://api.github.com/repos/symfony/var-exporter/zipball/75b74315b4e4be40e5534cf9c5cc30dd0907ed71",
+                "reference": "75b74315b4e4be40e5534cf9c5cc30dd0907ed71",
                 "shasum": ""
             },
             "require": {
                 "php": ">=8.4.1",
                 "symfony/deprecation-contracts": "^2.5|^3",
-                "symfony/polyfill-deepclone": "^1.37"
+                "symfony/polyfill-deepclone": "^1.40"
             },
             "require-dev": {
                 "symfony/property-access": "^7.4|^8.0",
@@ -8031,7 +8039,7 @@
                 "serialize"
             ],
             "support": {
-                "source": "https://github.com/symfony/var-exporter/tree/v8.1.0"
+                "source": "https://github.com/symfony/var-exporter/tree/v8.1.1"
             },
             "funding": [
                 {
@@ -8051,20 +8059,20 @@
                     "type": "tidelift"
                 }
             ],
-            "time": "2026-05-29T05:06:50+00:00"
+            "time": "2026-06-27T09:05:56+00:00"
         },
         {
             "name": "symfony/yaml",
-            "version": "v8.1.0",
+            "version": "v8.1.1",
             "source": {
                 "type": "git",
                 "url": "https://github.com/symfony/yaml.git",
-                "reference": "efb42bd2c6f4f3ccfd4683583449938b5fc146b0"
+                "reference": "8e4cdd4311683516be06944f4b85244063cdb886"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/symfony/yaml/zipball/efb42bd2c6f4f3ccfd4683583449938b5fc146b0",
-                "reference": "efb42bd2c6f4f3ccfd4683583449938b5fc146b0",
+                "url": "https://api.github.com/repos/symfony/yaml/zipball/8e4cdd4311683516be06944f4b85244063cdb886",
+                "reference": "8e4cdd4311683516be06944f4b85244063cdb886",
                 "shasum": ""
             },
             "require": {
@@ -8107,7 +8115,7 @@
             "description": "Loads and dumps YAML files",
             "homepage": "https://symfony.com",
             "support": {
-                "source": "https://github.com/symfony/yaml/tree/v8.1.0"
+                "source": "https://github.com/symfony/yaml/tree/v8.1.1"
             },
             "funding": [
                 {
@@ -8127,7 +8135,7 @@
                     "type": "tidelift"
                 }
             ],
-            "time": "2026-05-29T05:06:50+00:00"
+            "time": "2026-06-09T11:06:24+00:00"
         },
         {
             "name": "szepeviktor/phpstan-wordpress",
@@ -8602,15 +8610,15 @@
         },
         {
             "name": "wp-plugin/woocommerce",
-            "version": "10.8.1",
+            "version": "10.9.1",
             "source": {
                 "type": "svn",
                 "url": "https://plugins.svn.wordpress.org/woocommerce/",
-                "reference": "tags/10.8.1"
+                "reference": "tags/10.9.1"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://downloads.wordpress.org/plugin/woocommerce.10.8.1.zip"
+                "url": "https://downloads.wordpress.org/plugin/woocommerce.10.9.1.zip"
             },
             "require": {
                 "composer/installers": "~1.0|~2.0"
@@ -8629,7 +8637,7 @@
                 "issues": "https://wordpress.org/support/plugin/woocommerce",
                 "source": "https://plugins.svn.wordpress.org/woocommerce"
             },
-            "time": "2026-06-15T14:01:01+00:00"
+            "time": "2026-06-24T19:16:29+00:00"
         }
     ],
     "aliases": [],
diff --git a/package-lock.json b/package-lock.json
index 97c3e11..0f789d3 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -7,7 +7,7 @@
             "name": "@ahegyes/wordpress-framework",
             "license": "GPL-2.0-or-later",
             "devDependencies": {
-                "@wordpress/env": "^11.8.1"
+                "@wordpress/env": "^11.9.0"
             },
             "engines": {
                 "node": ">=26",
@@ -1058,13 +1058,13 @@
             "license": "MIT"
         },
         "node_modules/@php-wasm/cli-util": {
-            "version": "3.1.40",
-            "resolved": "https://registry.npmjs.org/@php-wasm/cli-util/-/cli-util-3.1.40.tgz",
-            "integrity": "sha512-G2XALTuzUfCHbBwmeQz3vTLIYQ+Vlemr+UzONQlo2Om2cvPbtlfkaGsm4URgj6WSybFTsshZ1ZxppbMB7CBjBA==",
+            "version": "3.1.42",
+            "resolved": "https://registry.npmjs.org/@php-wasm/cli-util/-/cli-util-3.1.42.tgz",
+            "integrity": "sha512-zDeNLoLqTRhRnrYbg5uXjcwYyk23XGi3PMMbmQ2NYRmmGMBW1xsUhZ9Ep/iLqCjLpdv+7XUzE9qykjUcPKUhHg==",
             "dev": true,
             "license": "GPL-2.0-or-later",
             "dependencies": {
-                "@php-wasm/util": "3.1.40",
+                "@php-wasm/util": "3.1.42",
                 "fast-xml-parser": "^5.8.0",
                 "jsonc-parser": "3.3.1"
             },
@@ -1074,9 +1074,9 @@
             }
         },
         "node_modules/@php-wasm/logger": {
-            "version": "3.1.40",
-            "resolved": "https://registry.npmjs.org/@php-wasm/logger/-/logger-3.1.40.tgz",
-            "integrity": "sha512-6YXbBgNRpLt7wmyx5nwWixQjjzvsWNGAl7CCLc2ltiju88ORZGV68sPcaruI6SSQz0RE7A/KrL6QrIUwTLneVA==",
+            "version": "3.1.42",
+            "resolved": "https://registry.npmjs.org/@php-wasm/logger/-/logger-3.1.42.tgz",
+            "integrity": "sha512-TwgNpmd01ftr7Jf0gsEfjgzSU7Jb0nipFizuk5AeUpWLRNnhf63wnpglKbvls27PLBjU1ONBBK4e/EppWaEkYg==",
             "dev": true,
             "license": "GPL-2.0-or-later",
             "engines": {
@@ -1085,24 +1085,24 @@
             }
         },
         "node_modules/@php-wasm/node": {
-            "version": "3.1.40",
-            "resolved": "https://registry.npmjs.org/@php-wasm/node/-/node-3.1.40.tgz",
-            "integrity": "sha512-LNm3e2OqAfJoQ6V4FIXZviZ0VdXEqX8tXjiJNe1QtJLy7dDr4mLMvN/Hv+DzYh8ZAHhAxCYS0hzbTM/J/ynmJA==",
+            "version": "3.1.42",
+            "resolved": "https://registry.npmjs.org/@php-wasm/node/-/node-3.1.42.tgz",
+            "integrity": "sha512-689JSPuW7WFuYW8BDscJya6v5aK4ZGHn30N4LyN2Q0cQl+z69ebMEU8IjvrJF0EGWJ8pSWU98+E78aAAi20Iww==",
             "dev": true,
             "license": "GPL-2.0-or-later",
             "dependencies": {
-                "@php-wasm/cli-util": "3.1.40",
-                "@php-wasm/logger": "3.1.40",
-                "@php-wasm/node-5-2": "3.1.40",
-                "@php-wasm/node-7-4": "3.1.40",
-                "@php-wasm/node-8-0": "3.1.40",
-                "@php-wasm/node-8-1": "3.1.40",
-                "@php-wasm/node-8-2": "3.1.40",
-                "@php-wasm/node-8-3": "3.1.40",
-                "@php-wasm/node-8-4": "3.1.40",
-                "@php-wasm/node-8-5": "3.1.40",
-                "@php-wasm/universal": "3.1.40",
-                "@php-wasm/util": "3.1.40",
+                "@php-wasm/cli-util": "3.1.42",
+                "@php-wasm/logger": "3.1.42",
+                "@php-wasm/node-5-2": "3.1.42",
+                "@php-wasm/node-7-4": "3.1.42",
+                "@php-wasm/node-8-0": "3.1.42",
+                "@php-wasm/node-8-1": "3.1.42",
+                "@php-wasm/node-8-2": "3.1.42",
+                "@php-wasm/node-8-3": "3.1.42",
+                "@php-wasm/node-8-4": "3.1.42",
+                "@php-wasm/node-8-5": "3.1.42",
+                "@php-wasm/universal": "3.1.42",
+                "@php-wasm/util": "3.1.42",
                 "fs-ext-extra-prebuilt": "2.2.7",
                 "wasm-feature-detect": "1.8.0",
                 "ws": "8.21.0"
@@ -1113,13 +1113,13 @@
             }
         },
         "node_modules/@php-wasm/node-5-2": {
-            "version": "3.1.40",
-            "resolved": "https://registry.npmjs.org/@php-wasm/node-5-2/-/node-5-2-3.1.40.tgz",
-            "integrity": "sha512-/+2UBudip0D/eCyfe/QJoNg/+NXE8YyAjunvQ4LzzrnvttBoH3O7lX8sswimtsHQ8LX+k/3gq8p2b3hN7cU44Q==",
+            "version": "3.1.42",
+            "resolved": "https://registry.npmjs.org/@php-wasm/node-5-2/-/node-5-2-3.1.42.tgz",
+            "integrity": "sha512-v0XbYbjYV+DQvNt4IZuuqMzSZyUSP/KqogwlD7hxt628PUF/pcCvQovvSrWQbO1iQ/y6y/Ibt/gXZCEHXIRxuA==",
             "dev": true,
             "license": "GPL-2.0-or-later",
             "dependencies": {
-                "@php-wasm/universal": "3.1.40",
+                "@php-wasm/universal": "3.1.42",
                 "wasm-feature-detect": "1.8.0"
             },
             "engines": {
@@ -1128,13 +1128,13 @@
             }
         },
         "node_modules/@php-wasm/node-7-4": {
-            "version": "3.1.40",
-            "resolved": "https://registry.npmjs.org/@php-wasm/node-7-4/-/node-7-4-3.1.40.tgz",
-            "integrity": "sha512-xcYpz9mlicYsct/P7RpGL+SFlqQyg8fZGvfLJ4yqQt2+41Duhui3EaBZz3vyCIZl1M1oL9H1IJcMu4HDk1xmSQ==",
+            "version": "3.1.42",
+            "resolved": "https://registry.npmjs.org/@php-wasm/node-7-4/-/node-7-4-3.1.42.tgz",
+            "integrity": "sha512-IsIaHZSjC5mAaOdjTU/LPJg0ew2Lhtnjdc1pac+S1vs50VBvZ6PidTflhdkxBqe+OnpyZNUnRTdKFFdB1+UTWw==",
             "dev": true,
             "license": "GPL-2.0-or-later",
             "dependencies": {
-                "@php-wasm/universal": "3.1.40",
+                "@php-wasm/universal": "3.1.42",
                 "wasm-feature-detect": "1.8.0"
             },
             "engines": {
@@ -1143,13 +1143,13 @@
             }
         },
         "node_modules/@php-wasm/node-8-0": {
-            "version": "3.1.40",
-            "resolved": "https://registry.npmjs.org/@php-wasm/node-8-0/-/node-8-0-3.1.40.tgz",
-            "integrity": "sha512-DrbOj6vNKTouWpkjSP7tJ1P8uWYpAz7DfGs8tuv4T5S+0W3wAcJBt9WW3SKyRdMVMSlBpCYvtR10CPfkTXESLQ==",
+            "version": "3.1.42",
+            "resolved": "https://registry.npmjs.org/@php-wasm/node-8-0/-/node-8-0-3.1.42.tgz",
+            "integrity": "sha512-QtG95esIWEIk4JdezdMBsewqQzokXExIXX+HNOFvs98e2qhGCprXQAVi5n5kbIbhh3C+yB7BrwfB2Fjeoan4hA==",
             "dev": true,
             "license": "GPL-2.0-or-later",
             "dependencies": {
-                "@php-wasm/universal": "3.1.40",
+                "@php-wasm/universal": "3.1.42",
                 "wasm-feature-detect": "1.8.0"
             },
             "engines": {
@@ -1158,13 +1158,13 @@
             }
         },
         "node_modules/@php-wasm/node-8-1": {
-            "version": "3.1.40",
-            "resolved": "https://registry.npmjs.org/@php-wasm/node-8-1/-/node-8-1-3.1.40.tgz",
-            "integrity": "sha512-tbm6EonR/9Ibb3M3yUwFIXDyPVWkhYbmB+GJhgpsSZlZwVxZpvLiLkHWzHrUbTsZUxgMHhzf6qQWYkh48s9dlg==",
+            "version": "3.1.42",
+            "resolved": "https://registry.npmjs.org/@php-wasm/node-8-1/-/node-8-1-3.1.42.tgz",
+            "integrity": "sha512-uTG0EFiultyp+FvTdWL4DgmjMtJMtvOZm6xpaNRtsxE6XsBj7d81HZjS7Amp0Jvt3/wOCqB0uW4MDou31KE1QA==",
             "dev": true,
             "license": "GPL-2.0-or-later",
             "dependencies": {
-                "@php-wasm/universal": "3.1.40",
+                "@php-wasm/universal": "3.1.42",
                 "wasm-feature-detect": "1.8.0"
             },
             "engines": {
@@ -1173,13 +1173,13 @@
             }
         },
         "node_modules/@php-wasm/node-8-2": {
-            "version": "3.1.40",
-            "resolved": "https://registry.npmjs.org/@php-wasm/node-8-2/-/node-8-2-3.1.40.tgz",
-            "integrity": "sha512-D0fdZ7X0C1YI+ancJIpyjmOUiDB7g4s9QYgMu/admF/69lzInlmrctdaAda3hl5izhoDrVEy1Or39AT6brWKNQ==",
+            "version": "3.1.42",
+            "resolved": "https://registry.npmjs.org/@php-wasm/node-8-2/-/node-8-2-3.1.42.tgz",
+            "integrity": "sha512-qlHnmqbrgjtSA49Xx1wlVZZOumeKjgJnlvJLHrxcpgbHZRAhmWy1/w9nva4awE94KXrQHlKDrpXteYiNktV3mg==",
             "dev": true,
             "license": "GPL-2.0-or-later",
             "dependencies": {
-                "@php-wasm/universal": "3.1.40",
+                "@php-wasm/universal": "3.1.42",
                 "wasm-feature-detect": "1.8.0"
             },
             "engines": {
@@ -1188,13 +1188,13 @@
             }
         },
         "node_modules/@php-wasm/node-8-3": {
-            "version": "3.1.40",
-            "resolved": "https://registry.npmjs.org/@php-wasm/node-8-3/-/node-8-3-3.1.40.tgz",
-            "integrity": "sha512-PFfpq10tM3p394TFJuJl9/sx7l3lab8HdgBzptH1ZFTQ8zva3RsQeZMhyZA8DXIQVu23JDWvLGb7KcRol1zIsA==",
+            "version": "3.1.42",
+            "resolved": "https://registry.npmjs.org/@php-wasm/node-8-3/-/node-8-3-3.1.42.tgz",
+            "integrity": "sha512-OJA9bt9l9it4KCmBixh0rOZTbU1UQnyxdJFV9zFLx+P1e+kKWX9oTTRu+h3sT2riNMxF+ZWfYiJ/qPl2feevxQ==",
             "dev": true,
             "license": "GPL-2.0-or-later",
             "dependencies": {
-                "@php-wasm/universal": "3.1.40",
+                "@php-wasm/universal": "3.1.42",
                 "wasm-feature-detect": "1.8.0"
             },
             "engines": {
@@ -1203,13 +1203,13 @@
             }
         },
         "node_modules/@php-wasm/node-8-4": {
-            "version": "3.1.40",
-            "resolved": "https://registry.npmjs.org/@php-wasm/node-8-4/-/node-8-4-3.1.40.tgz",
-            "integrity": "sha512-dJ5nvqTJ4fYK7b7kRq8o41rkZu2tu2j0oOCrg0TZrBlkTSiy2uH4kDJJbC9gURA0ieEQ3fizRAXN0XhA3te8GQ==",
+            "version": "3.1.42",
+            "resolved": "https://registry.npmjs.org/@php-wasm/node-8-4/-/node-8-4-3.1.42.tgz",
+            "integrity": "sha512-EnntRhHArwLFJhlEVPHqB6B/jI9RVLB0zVy6qcHVGBSEL8xO6ZiM59RTJTyKgsnYJqvb4UyzbVzosH/xx1kq/g==",
             "dev": true,
             "license": "GPL-2.0-or-later",
             "dependencies": {
-                "@php-wasm/universal": "3.1.40",
+                "@php-wasm/universal": "3.1.42",
                 "wasm-feature-detect": "1.8.0"
             },
             "engines": {
@@ -1218,13 +1218,13 @@
             }
         },
         "node_modules/@php-wasm/node-8-5": {
-            "version": "3.1.40",
-            "resolved": "https://registry.npmjs.org/@php-wasm/node-8-5/-/node-8-5-3.1.40.tgz",
-            "integrity": "sha512-SfanxbPNi001LMxeD1bPxNhxAsMvScnMjUczfWtoixeProZgY42VzY1JKIqmagNify/IP+M/89Ig+APGBh2d5w==",
+            "version": "3.1.42",
+            "resolved": "https://registry.npmjs.org/@php-wasm/node-8-5/-/node-8-5-3.1.42.tgz",
+            "integrity": "sha512-bSJlm2IF8r7lOoFo1bIxndQeeB1PUwsFck4SUKSTqZe05duWiVv1nC0fsEh+7/JczC4fx108J4D7D4US56XcBQ==",
             "dev": true,
             "license": "GPL-2.0-or-later",
             "dependencies": {
-                "@php-wasm/universal": "3.1.40",
+                "@php-wasm/universal": "3.1.42",
                 "wasm-feature-detect": "1.8.0"
             },
             "engines": {
@@ -1233,13 +1233,13 @@
             }
         },
         "node_modules/@php-wasm/progress": {
-            "version": "3.1.40",
-            "resolved": "https://registry.npmjs.org/@php-wasm/progress/-/progress-3.1.40.tgz",
-            "integrity": "sha512-XUCM4v4eKbyOsFUNk02O9Crb/ZKlkLfYi43TAc9ctw1o6pyf7K5eeVxZKXVNqxR1hb0Jo5JpCKENSbP0NRUiIg==",
+            "version": "3.1.42",
+            "resolved": "https://registry.npmjs.org/@php-wasm/progress/-/progress-3.1.42.tgz",
+            "integrity": "sha512-rYhTRmISxgEhxIvD+Oytr9a38RhsMGIC//i18Q5ht0STCyvGRO2cfylACg0ObV0C9HFwQKU/DFGFUzxCOTvZaA==",
             "dev": true,
             "license": "GPL-2.0-or-later",
             "dependencies": {
-                "@php-wasm/logger": "3.1.40"
+                "@php-wasm/logger": "3.1.42"
             },
             "engines": {
                 "node": ">=20.10.0",
@@ -1247,9 +1247,9 @@
             }
         },
         "node_modules/@php-wasm/scopes": {
-            "version": "3.1.40",
-            "resolved": "https://registry.npmjs.org/@php-wasm/scopes/-/scopes-3.1.40.tgz",
-            "integrity": "sha512-qRqh4Khng/iSOzJJl7blNmIoINFkgRyaR24b4SUctFsOUu0emiYbJ2DMEWHcr57KWbyjlSnbpI/c/yZnjkgrMw==",
+            "version": "3.1.42",
+            "resolved": "https://registry.npmjs.org/@php-wasm/scopes/-/scopes-3.1.42.tgz",
+            "integrity": "sha512-FiPXH+Ra6imzdmCvxLYrCu7Cynt2mYO/74pJ9E9aKt+qJnD89CDw2h6Qb+B5ZN78wr4wSzIiXNW+CBPTXIF8Iw==",
             "dev": true,
             "license": "GPL-2.0-or-later",
             "engines": {
@@ -1258,26 +1258,26 @@
             }
         },
         "node_modules/@php-wasm/stream-compression": {
-            "version": "3.1.40",
-            "resolved": "https://registry.npmjs.org/@php-wasm/stream-compression/-/stream-compression-3.1.40.tgz",
-            "integrity": "sha512-57CVWtoze3WJy4gupoahwFsTcA8Q3sWZY7/SrlTSj0dsqhC1sdOmvVe0pwkaurX1psTZeIynA9Gd/iyobVeayw==",
+            "version": "3.1.42",
+            "resolved": "https://registry.npmjs.org/@php-wasm/stream-compression/-/stream-compression-3.1.42.tgz",
+            "integrity": "sha512-OGcO5vJ/t5wGOBYLMK13plVepAacdDABbDdud9bsNkb9vm24eLoqWu2gowC5IaBxtJkHUsvBUw63BywdKetOIg==",
             "dev": true,
             "license": "GPL-2.0-or-later",
             "dependencies": {
-                "@php-wasm/util": "3.1.40"
+                "@php-wasm/util": "3.1.42"
             }
         },
         "node_modules/@php-wasm/universal": {
-            "version": "3.1.40",
-            "resolved": "https://registry.npmjs.org/@php-wasm/universal/-/universal-3.1.40.tgz",
-            "integrity": "sha512-uDbTdhrvFCR1fz3T7dQp5KH8GmBzndf0l6selKEQNrWxM0CSaGYbnpI7Vb/wICZgDR7rz5ghdyUkeERVD6LC1A==",
+            "version": "3.1.42",
+            "resolved": "https://registry.npmjs.org/@php-wasm/universal/-/universal-3.1.42.tgz",
+            "integrity": "sha512-SuDKfW1S8KDr/S3a3tTokmDfjiTZk7rvKQyo/PH7Zl0UokZ/mxBZR0dvVqPcWzDgNg/ZQ0/Dpj8dZI0sW+6rfg==",
             "dev": true,
             "license": "GPL-2.0-or-later",
             "dependencies": {
-                "@php-wasm/logger": "3.1.40",
-                "@php-wasm/progress": "3.1.40",
-                "@php-wasm/stream-compression": "3.1.40",
-                "@php-wasm/util": "3.1.40",
+                "@php-wasm/logger": "3.1.42",
+                "@php-wasm/progress": "3.1.42",
+                "@php-wasm/stream-compression": "3.1.42",
+                "@php-wasm/util": "3.1.42",
                 "ini": "4.1.2"
             },
             "engines": {
@@ -1286,9 +1286,9 @@
             }
         },
         "node_modules/@php-wasm/util": {
-            "version": "3.1.40",
-            "resolved": "https://registry.npmjs.org/@php-wasm/util/-/util-3.1.40.tgz",
-            "integrity": "sha512-U2xzEEmW7JRaAEuFErF3tt8uW4WJTYWm7vQO2LURLijDoMCUUXIGRz0mNirJRxI8DMB/zCmsWuIMduZ5WYp6kw==",
+            "version": "3.1.42",
+            "resolved": "https://registry.npmjs.org/@php-wasm/util/-/util-3.1.42.tgz",
+            "integrity": "sha512-rUkLsyqirsDKPgKzN8BudFaNzDH7SMwZtbhb82yn8jgB/buD4J6r0l8PDLuYNqLGZIFYfrqb7CV8b/VJ8/Zn7A==",
             "dev": true,
             "engines": {
                 "node": ">=20.10.0",
@@ -1296,14 +1296,14 @@
             }
         },
         "node_modules/@php-wasm/web-service-worker": {
-            "version": "3.1.40",
-            "resolved": "https://registry.npmjs.org/@php-wasm/web-service-worker/-/web-service-worker-3.1.40.tgz",
-            "integrity": "sha512-JwkTG+2yZ25BKH2nX0J9f2pf4+oyO4vM2Gp3h7qCotWeSngLpWKLmVYt6pfO+EEeEPHxN6G//wjCgCpzGiAZlA==",
+            "version": "3.1.42",
+            "resolved": "https://registry.npmjs.org/@php-wasm/web-service-worker/-/web-service-worker-3.1.42.tgz",
+            "integrity": "sha512-F/Gu7fwmq7r2sMtloemnXzQS8KDlwZi0YFoE34SNF97l9Muh5DLGQf+pUfQcSkmd9BTh+3zFNS1Rtl2kNXqGRQ==",
             "dev": true,
             "license": "GPL-2.0-or-later",
             "dependencies": {
-                "@php-wasm/scopes": "3.1.40",
-                "@php-wasm/universal": "3.1.40"
+                "@php-wasm/scopes": "3.1.42",
+                "@php-wasm/universal": "3.1.42"
             },
             "engines": {
                 "node": ">=20.10.0",
@@ -1311,14 +1311,14 @@
             }
         },
         "node_modules/@php-wasm/xdebug-bridge": {
-            "version": "3.1.40",
-            "resolved": "https://registry.npmjs.org/@php-wasm/xdebug-bridge/-/xdebug-bridge-3.1.40.tgz",
-            "integrity": "sha512-s+TLw2CrovrkWH4ZSkrgQwvBYn4HU+QUlE8sF/grHkWIIN9E0EDFj2gC3DXC8FJRWyC31FQtUPataHK1+6odjg==",
+            "version": "3.1.42",
+            "resolved": "https://registry.npmjs.org/@php-wasm/xdebug-bridge/-/xdebug-bridge-3.1.42.tgz",
+            "integrity": "sha512-zXvtYHLqZ3uSlBKeMzbhIsKfgQyi28Y+oVfjsmEA+mqhIw1QZZDj5FHiFm61G8CYSaKUNPWzDmP+H49iziVlZQ==",
             "dev": true,
             "license": "GPL-2.0-or-later",
             "dependencies": {
-                "@php-wasm/logger": "3.1.40",
-                "@php-wasm/universal": "3.1.40",
+                "@php-wasm/logger": "3.1.42",
+                "@php-wasm/universal": "3.1.42",
                 "ws": "8.21.0",
                 "xml2js": "0.6.2",
                 "yargs": "17.7.2"
@@ -1489,9 +1489,9 @@
             "license": "MIT"
         },
         "node_modules/@types/node": {
-            "version": "26.0.0",
-            "resolved": "https://registry.npmjs.org/@types/node/-/node-26.0.0.tgz",
-            "integrity": "sha512-vf2YFi1iY9lHGwNJMs01biZFbKJkrZR1T6/MlzjhJLPdntOHLhTrDSnSVcdtvjihi4VQNlrFRIxLsDBlQpAipA==",
+            "version": "26.0.1",
+            "resolved": "https://registry.npmjs.org/@types/node/-/node-26.0.1.tgz",
+            "integrity": "sha512-fc3KiUoBt6kie0N9bIW3E47vZsuaMf0PM2AaUpLCLT0s/LvX1nxAim6Fc049cNxODPpGm6qRAuUOB86SkRuPQw==",
             "dev": true,
             "license": "MIT",
             "dependencies": {
@@ -1509,9 +1509,9 @@
             }
         },
         "node_modules/@wordpress/env": {
-            "version": "11.8.1",
-            "resolved": "https://registry.npmjs.org/@wordpress/env/-/env-11.8.1.tgz",
-            "integrity": "sha512-wboYnQNPfMfcgYgiNDbrGGZj8RkdeZtaz2UvmAVUrhOgAvHFpZXsKuXuLdCCSv7JdcHGG5xLWMYhvRLTGOcQ1g==",
+            "version": "11.9.0",
+            "resolved": "https://registry.npmjs.org/@wordpress/env/-/env-11.9.0.tgz",
+            "integrity": "sha512-PtPqrWONclS6dXZLQztZiiFIpqAuoJRBOpPMS85QJiKzkDlvbVmUk3CicmxQbGpktS6mXtVyV5ySPCXqV8OD1g==",
             "dev": true,
             "license": "GPL-2.0-or-later",
             "dependencies": {
@@ -1538,20 +1538,20 @@
             }
         },
         "node_modules/@wp-playground/blueprints": {
-            "version": "3.1.40",
-            "resolved": "https://registry.npmjs.org/@wp-playground/blueprints/-/blueprints-3.1.40.tgz",
-            "integrity": "sha512-xFIymqqJc2rF9mutQQyiqsvTM3CU2SjqQHL4Rw1qIa41K4hfO0FXcUkfMQh6FCMwSo2roHiCra+R+Y9trYBNRQ==",
-            "dev": true,
-            "dependencies": {
-                "@php-wasm/logger": "3.1.40",
-                "@php-wasm/progress": "3.1.40",
-                "@php-wasm/stream-compression": "3.1.40",
-                "@php-wasm/universal": "3.1.40",
-                "@php-wasm/util": "3.1.40",
-                "@php-wasm/web-service-worker": "3.1.40",
-                "@wp-playground/common": "3.1.40",
-                "@wp-playground/storage": "3.1.40",
-                "@wp-playground/wordpress": "3.1.40",
+            "version": "3.1.42",
+            "resolved": "https://registry.npmjs.org/@wp-playground/blueprints/-/blueprints-3.1.42.tgz",
+            "integrity": "sha512-kr82GmVljh6Y7y5/dilvI8WtCQDEqZ5B9gwQdBNC/Rb7r4eKvQQ+CTBqWQ716yfknH+coEAZBbHBS/sIkx7DaQ==",
+            "dev": true,
+            "dependencies": {
+                "@php-wasm/logger": "3.1.42",
+                "@php-wasm/progress": "3.1.42",
+                "@php-wasm/stream-compression": "3.1.42",
+                "@php-wasm/universal": "3.1.42",
+                "@php-wasm/util": "3.1.42",
+                "@php-wasm/web-service-worker": "3.1.42",
+                "@wp-playground/common": "3.1.42",
+                "@wp-playground/storage": "3.1.42",
+                "@wp-playground/wordpress": "3.1.42",
                 "ajv": "8.18.0"
             },
             "engines": {
@@ -1560,24 +1560,24 @@
             }
         },
         "node_modules/@wp-playground/cli": {
-            "version": "3.1.40",
-            "resolved": "https://registry.npmjs.org/@wp-playground/cli/-/cli-3.1.40.tgz",
-            "integrity": "sha512-Fn1BfvqORHLAVrtUjgGv11oo9q9OOCWrNXZy1mQq6mpPZ+0K57HnckDZHGFgZfouadheKL6WrNcTJXEJ+Lh3Zg==",
+            "version": "3.1.42",
+            "resolved": "https://registry.npmjs.org/@wp-playground/cli/-/cli-3.1.42.tgz",
+            "integrity": "sha512-dO9xJAANH0sY1fCQx4rlfscl8WGEKqhT6lVQQLizqA/jDxsQNY3LAq34X1ro1P71TU5k/7WSf0d+xIHh4G2sMg==",
             "dev": true,
             "license": "GPL-2.0-or-later",
             "dependencies": {
-                "@php-wasm/cli-util": "3.1.40",
-                "@php-wasm/logger": "3.1.40",
-                "@php-wasm/node": "3.1.40",
-                "@php-wasm/progress": "3.1.40",
-                "@php-wasm/universal": "3.1.40",
-                "@php-wasm/util": "3.1.40",
-                "@php-wasm/xdebug-bridge": "3.1.40",
-                "@wp-playground/blueprints": "3.1.40",
-                "@wp-playground/common": "3.1.40",
-                "@wp-playground/storage": "3.1.40",
-                "@wp-playground/tools": "3.1.40",
-                "@wp-playground/wordpress": "3.1.40",
+                "@php-wasm/cli-util": "3.1.42",
+                "@php-wasm/logger": "3.1.42",
+                "@php-wasm/node": "3.1.42",
+                "@php-wasm/progress": "3.1.42",
+                "@php-wasm/universal": "3.1.42",
+                "@php-wasm/util": "3.1.42",
+                "@php-wasm/xdebug-bridge": "3.1.42",
+                "@wp-playground/blueprints": "3.1.42",
+                "@wp-playground/common": "3.1.42",
+                "@wp-playground/storage": "3.1.42",
+                "@wp-playground/tools": "3.1.42",
+                "@wp-playground/wordpress": "3.1.42",
                 "express": "4.22.2",
                 "fs-extra": "11.1.1",
                 "tmp-promise": "3.0.3",
@@ -1630,14 +1630,14 @@
             }
         },
         "node_modules/@wp-playground/common": {
-            "version": "3.1.40",
-            "resolved": "https://registry.npmjs.org/@wp-playground/common/-/common-3.1.40.tgz",
-            "integrity": "sha512-4oQXGmDjNbxuc3FAir2cWQQ4EY/2UJMz3cGrUc+m2h+aQ3HncO7WMh0dKtNir4BgUbCblX7qXUnWMaTYMLR/3A==",
+            "version": "3.1.42",
+            "resolved": "https://registry.npmjs.org/@wp-playground/common/-/common-3.1.42.tgz",
+            "integrity": "sha512-T3HAoVghas11/vBrM0BEUPdwor+5MRRSG9/ZqjzhL7qsORAnU7KgVp+IvYO5kasmXI21l71wZIK9IPPiktEV/g==",
             "dev": true,
             "license": "GPL-2.0-or-later",
             "dependencies": {
-                "@php-wasm/universal": "3.1.40",
-                "@php-wasm/util": "3.1.40"
+                "@php-wasm/universal": "3.1.42",
+                "@php-wasm/util": "3.1.42"
             },
             "engines": {
                 "node": ">=20.10.0",
@@ -1645,15 +1645,15 @@
             }
         },
         "node_modules/@wp-playground/storage": {
-            "version": "3.1.40",
-            "resolved": "https://registry.npmjs.org/@wp-playground/storage/-/storage-3.1.40.tgz",
-            "integrity": "sha512-9GAdEMzyKmEs8c7hMFXz2Cg/HwIiw5JKN5nBBO+yFVoEC+kH/g6We73N/mV82/IUcWFVFUDQS5YYl7cN9YHJSw==",
+            "version": "3.1.42",
+            "resolved": "https://registry.npmjs.org/@wp-playground/storage/-/storage-3.1.42.tgz",
+            "integrity": "sha512-M3FxveZ+XlzNxS70khfFzbB9e1M7RioEV82tUBVZUyuCVeEnJMLB/dvpAJVbWqAePO8JPndHIVESvmbPoG0T+g==",
             "dev": true,
             "license": "GPL-2.0-or-later",
             "dependencies": {
-                "@php-wasm/stream-compression": "3.1.40",
-                "@php-wasm/universal": "3.1.40",
-                "@php-wasm/util": "3.1.40",
+                "@php-wasm/stream-compression": "3.1.42",
+                "@php-wasm/universal": "3.1.42",
+                "@php-wasm/util": "3.1.42",
                 "@zip.js/zip.js": "2.7.57",
                 "isomorphic-git": "1.37.6",
                 "octokit": "3.1.2",
@@ -1661,13 +1661,13 @@
             }
         },
         "node_modules/@wp-playground/tools": {
-            "version": "3.1.40",
-            "resolved": "https://registry.npmjs.org/@wp-playground/tools/-/tools-3.1.40.tgz",
-            "integrity": "sha512-Z4yTBCN4zpfUoLhRzP0OTUJBcuuTi9INZT8yg6sauHwehOqCamhGWpK2ZwfbiMJrsD48ZCh+JcYg7eXApI1VYw==",
+            "version": "3.1.42",
+            "resolved": "https://registry.npmjs.org/@wp-playground/tools/-/tools-3.1.42.tgz",
+            "integrity": "sha512-BIryjMjXARsF7tfZTuMQWpZuSR7K4LJa9PFk01oIXGc/StgP4TPvVpijN+trKb3abvMZCVFHOOHFW8RMw0pVWA==",
             "dev": true,
             "license": "GPL-2.0-or-later",
             "dependencies": {
-                "@wp-playground/blueprints": "3.1.40"
+                "@wp-playground/blueprints": "3.1.42"
             },
             "engines": {
                 "node": ">=20.10.0",
@@ -1675,16 +1675,16 @@
             }
         },
         "node_modules/@wp-playground/wordpress": {
-            "version": "3.1.40",
-            "resolved": "https://registry.npmjs.org/@wp-playground/wordpress/-/wordpress-3.1.40.tgz",
-            "integrity": "sha512-PMgWcua0vTx+VScV2sSjzTX1OVZ6xmlUxj1xlXaY7iSuJPfUOA3PMoDqQvsmPxajs6sY+RbuWyvpmoPPkpZruw==",
+            "version": "3.1.42",
+            "resolved": "https://registry.npmjs.org/@wp-playground/wordpress/-/wordpress-3.1.42.tgz",
+            "integrity": "sha512-xYoeYmNVDWTA6UUWTTBjpXOxsk1Ijgzpk7nxXlWXquQxg8g0C4n3L2GkqCv/37MkspqutkyMTAdvMFg29ZNskg==",
             "dev": true,
             "license": "GPL-2.0-or-later",
             "dependencies": {
-                "@php-wasm/logger": "3.1.40",
-                "@php-wasm/universal": "3.1.40",
-                "@php-wasm/util": "3.1.40",
-                "@wp-playground/common": "3.1.40"
+                "@php-wasm/logger": "3.1.42",
+                "@php-wasm/universal": "3.1.42",
+                "@php-wasm/util": "3.1.42",
+                "@wp-playground/common": "3.1.42"
             },
             "engines": {
                 "node": ">=20.10.0",
@@ -3283,9 +3283,9 @@
             }
         },
         "node_modules/js-yaml": {
-            "version": "3.14.2",
-            "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.14.2.tgz",
-            "integrity": "sha512-PMSmkqxr106Xa156c2M265Z+FTrPl+oxd/rgOQy2tijQeK5TxQ43psO1ZCwhVOSdnn+RzkzlRz/eY4BgJBYVpg==",
+            "version": "3.15.0",
+            "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.15.0.tgz",
+            "integrity": "sha512-ttBQIIQPDeLjpPOohtUdXuXUVoA2uIB6fEH9HyJ7234s5mBJ5wTx20njxplLZQgLaOfpmPQA7X2t5AX6tIPbog==",
             "dev": true,
             "license": "MIT",
             "dependencies": {
@@ -3704,9 +3704,9 @@
             }
         },
         "node_modules/nan": {
-            "version": "2.27.0",
-            "resolved": "https://registry.npmjs.org/nan/-/nan-2.27.0.tgz",
-            "integrity": "sha512-hC+0LidcL3XE4rp1C4H54KujgXKzbfyTngZTwBByQxsOxCEKZT0MPQ4hOKUH2jU1OYstqdDH4onyHPDzcV0XdQ==",
+            "version": "2.28.0",
+            "resolved": "https://registry.npmjs.org/nan/-/nan-2.28.0.tgz",
+            "integrity": "sha512-fTsDz99OTq2sVePhGdp4qQhggZFtKr64ZNVyVajRKtMOkJxYekplBh577PiJB12v/D3s2E5cGtOI45LWp6rnLQ==",
             "dev": true,
             "license": "MIT"
         },
@@ -3886,9 +3886,9 @@
             }
         },
         "node_modules/path-expression-matcher": {
-            "version": "1.6.0",
-            "resolved": "https://registry.npmjs.org/path-expression-matcher/-/path-expression-matcher-1.6.0.tgz",
-            "integrity": "sha512-e5y7RCLHKjemsgQ4eqGJtPyr10ILz25HO7flzxhTV8bgvd5yHx98DGtCAtbVW9f2TqnYI/gEVZd+vz7snrdPTw==",
+            "version": "1.6.1",
+            "resolved": "https://registry.npmjs.org/path-expression-matcher/-/path-expression-matcher-1.6.1.tgz",
+            "integrity": "sha512-h7bxdzhHk8Knyc4Tj+jMaa7fEEoUJy7p1qtbVgkYg1Uhpe5Np5VuGXCRZnkZvU+Q42M1vStt0ifa3ueykRJPmQ==",
             "dev": true,
             "funding": [
                 {
@@ -3998,13 +3998,14 @@
             }
         },
         "node_modules/qs": {
-            "version": "6.15.2",
-            "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.2.tgz",
-            "integrity": "sha512-Rzq0KEyX/w/tEybncDgdkZrJgVUsUMk3xjh3t5bv3S1HTAtg+uOYt72+ZfwiQwKdysThkTBdL/rTi6HDmX9Ddw==",
+            "version": "6.15.3",
+            "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.3.tgz",
+            "integrity": "sha512-O9gl3zCl5h5blw1KGUzQKhA5oUXSl8rwUIM5o0S3nCXMliSvy5Dzx7/DJcI+SwgICv+IneSZwhBh1oSyEHA71A==",
             "dev": true,
             "license": "BSD-3-Clause",
             "dependencies": {
-                "side-channel": "^1.1.0"
+                "es-define-property": "^1.0.1",
+                "side-channel": "^1.1.1"
             },
             "engines": {
                 "node": ">=0.6"
diff --git a/package.json b/package.json
index 6ed042f..2cef2b7 100644
--- a/package.json
+++ b/package.json
@@ -13,7 +13,7 @@
         "npm": ">=11"
     },
     "devDependencies": {
-        "@wordpress/env": "^11.8.1"
+        "@wordpress/env": "^11.9.0"
     },
     "scripts": {
         "setup": "npm run packages-install:all && npm run wp-env:start",