Repository navigation
Description
Decisions (maintainer, 2026-10-23)
Add public static function get_registration_priority(): int directly to Delayed, rather than introducing a separate optional priority capability or an interface extending Delayed. This explicitly supersedes the earlier "Delayed itself is unchanged" requirement and the old proposal's compatibility rejection.
Provide a DefaultRegistrationPriority trait implementing that method by returning 10. Services that use the default add use DefaultRegistrationPriority;; services needing a different priority may implement or override the method. The interface itself supplies no default implementation. Existing implementations must add the trait or method before they can load against the new interface.
Compatibility ruling: approve this required-interface-method migration and retain breaking. Update all scaffold implementations, fixtures and migration guidance. Also approve the narrow naming-policy exception for the trait DefaultRegistrationPriority: its name describes the default behaviour it supplies, not a generic implementation kind. Document that exception to principle 8's broad Default-prefix guidance; do not allow Default-prefixed types generally or weaken a gate.
Context
src/Infrastructure/ServiceBasedPlugin.php:690-709 schedules a Delayed service; :697-704 installs its registration callback at hard-coded priority 10. src/Infrastructure/Delayed.php:25-33 currently exposes only get_registration_action(). The scheduler already calls static capability accessors before constructing services, which is also the right time to read the new priority.
ServiceBasedPlugin.php:448-484 resumes services awaiting delayed dependencies at PHP_INT_MAX. If a dependent's own registration action has already fired, the scheduler registers it immediately rather than scheduling at an earlier priority. The dependency-priority ruling below specifies how the new accessor interacts with that existing wait; the old proposal is recorded here.
Scope
- Extend Delayed with the required static priority accessor and provide the named default trait returning 10.
- Use the accessor when installing a delayed service's registration callback.
- Migrate shipped implementations and fixtures, document the breaking change and the narrow naming exception, and add regression coverage.
- Preserve dependency ordering under the approved readiness-before-priority policy, without premature registration or retroactive action/priority execution.
Out of scope
- Priorities for non-delayed services.
- Additional priority capability interfaces or a new pairing architecture rule; priority is now part of Delayed itself.
- General Default-prefix naming exceptions, runtime dependencies, broad ignores or lowered analysis levels.
Dependency-priority decision (maintainer, 2026-10-23)
Choose A: dependency readiness takes precedence over the requested registration priority. A service never registers before its dependencies merely to meet its priority. If the service's own registration action/priority has already passed by the time its dependencies are ready, register at the existing dependency-resumption point and document that the requested priority cannot be honoured retroactively. Do not reject an otherwise valid dependency combination, invent a priority-bumping policy, or rerun an action to simulate an earlier hook slot.
When the service's own registration action has not fired yet, continue scheduling it on that action at its declared priority after dependencies become ready. Keep priority tied to the service's own action; resolving dependencies earlier does not authorize premature registration.
Acceptance criteria
- Delayed declares the approved static int-returning accessor; DefaultRegistrationPriority supplies 10 and can be overridden by a consuming class.
- All shipped Delayed implementations and relevant fixtures satisfy the new contract. Tests cover the default trait and an explicit non-default priority, without constructing a service just to read its priority.
- The scheduler passes the declared priority to add_action for an action that has not yet fired; normal conditional/delayed/dependency registration regressions remain covered.
- Tests cover a dependent whose requested priority has passed: it waits for dependency readiness and then registers without rejecting the valid graph. Cover same-action late priorities and dependencies resolved after the dependent’s action, plus the case where the dependent’s own action is still in the future and must still be awaited. No dependency is bypassed, action rerun or arbitrary priority bump introduced. Document that dependency waits can override the requested priority.
- Migration guidance shows both adding
use DefaultRegistrationPriority;and implementing a custom priority method; it explains that existing unmodified classes will fail the expanded interface contract. - Principle 8's naming guidance permits this one explicitly approved trait name while keeping the general naming policy intact. Update any checked API snapshot through its documented review workflow.
Verification
composer test
composer lintVerify default/custom-priority registration and trait override behaviour, then the selected dependency-wait policy. Preserve PHP 7.4 compatibility and all quality gates. This triage records the ruling and brief; no PHP implementation is made here.
Impact on generated plugins
Approved breaking interface change: every existing Delayed implementation needs the new method or the trait. Returning 10 preserves its previous requested priority; dependency readiness takes precedence over a requested priority that has passed, as explicitly ruled above. Additive trait supply does not make the interface extension backward compatible.
Priority remains p3. The issue is agent-ready for implementation: interface shape, method, default trait, migration, naming exception and dependency-priority policy are settled.
Updated 2026-10-23: maintainer chose the method on Delayed plus DefaultRegistrationPriority returning 10; recorded the breaking and naming rulings, repaired scheduling citations and retained the final dependency-priority decision.
Updated 2026-10-23: maintainer chose A for dependency readiness over missed priority slots; folded the scheduling rule and regression cases into the brief and cleared the final decision blocker.
Activity
schlessera commentedon Oct 23, 2026
Claiming this. The interface shape is not ruled on, so the first deliverable is a design proposal (no branch yet).
schlessera commentedon Oct 23, 2026
Design proposal: registration priority for
DelayedservicesCitation check (2026-10-23)
The issue cites
ServiceBasedPlugin.php:302-309; that range is nowregister(). The hard-coded priority10lives inschedule_potential_service_registration()(around lines 690-709). Correction to be folded into the body once a ruling lands.Already decided
Delayedstays unchanged (acceptance criterion, principle 4, interface segregation).Delayed::get_registration_action()andConditional::is_needed()are), so lazy instantiation (principle 5) still holds.Findings relevant to the design
register_pending_services()resumes atPHP_INT_MAXon each awaited action, and by thendid_action()is true, so the dependent registers immediately. The second scope bullet therefore already holds for the default case. The open question is only how it interacts with a declared priority: a dependent's own priority is moot when it waits on a delayed dependency, because it is registered at the resumption point regardless. The docs should say so.Options
HasRegistrationPriority(staticget_registration_priority(): int), read inschedule_potential_service_registration()when the class implements it, otherwise10. MirrorsDelayed, additive, trivial to explain. Trade-off: it is only meaningful together withDelayed; an architecture rule (like the existingcapabilitiesOnServiceschecks) could flag it on a non-delayed service, andDelayedservices without it keep the default (principle 3).Delayedwith the method. Rejected by the issue: breaks every existing delayed service.Delayed(e.g.PrioritizedDelayed), so the priority cannot exist without the action. Trade-off: the type itself guarantees the pairing and needs no rule, but the services' capability set becomes a hierarchy,is_a( ..., Delayed::class )checks keep working, and it is a less composable shape than the other capability interfaces, which are all flat.[ action, priority ]from a new method. OverlapsDelayed, rejected.Questions for the maintainer
HasRegistrationPriority,Prioritized,DelayedWithPriority), and the method name (get_registration_priority(), by analogy withget_registration_action()).Delayed? (Recommended: yes, since it would silently do nothing.)Recommendation (not approval)
Option 1:
interface HasRegistrationPriority { public static function get_registration_priority(): int; }, used only when scheduling aDelayedservice, plus an architecture rule for the no-op combination, a pattern entry indocs/patterns.md, and a test registering a service at a non-default priority. Nothing inDelayedchanges.schlessera commentedon Oct 23, 2026
Decision (maintainer, 2026-10-23): Add static
get_registration_priority(): intdirectly to Delayed and supplyDefaultRegistrationPriority, returning 10. Existing classes add the trait or implement the method; approve that breaking migration, replacing the old unchanged-Delayed criterion. Approve this one descriptive trait name as a narrow exception to the Default-prefix documentation rule. Updated scope, source anchors, migration and tests; no separate capability or pairing rule. Addedbreaking;needs: decisionremains for the dependency-wait/priority interaction.schlessera commentedon Oct 23, 2026
Decision (maintainer, 2026-10-23): A — dependency readiness takes precedence when a requested priority has passed. Register at the dependency-resumption point rather than reject an otherwise valid graph or simulate an earlier slot. If the dependent’s own action is still in the future, keep waiting for it at the declared priority. Updated documentation/test criteria, including late same-action ordering. All #36 decisions are settled; removed
needs: decision, restoredagent-ready, and retainedbreakingfor the approved Delayed method migration.schlessera commentedon Oct 23, 2026
Claiming this for implementation now that all rulings are recorded. Branch:
feat/36-delayed-registration-priority.schlessera commentedon Oct 23, 2026
Necessary unplanned change found while implementing:
architecture.dependencyDirectiononly lets a subsystem depend on infrastructure interfaces, so the sample'suse DefaultRegistrationPriority;(required by the ruling) was reported. The branch narrows the rule's allowance rather than suppressing it: a subsystem class may use an infrastructure trait only if every method of the trait belongs to an infrastructure interface the class implements. Any other infrastructure trait is still reported, with its own fix message. Covered by new rule fixtures and documented indocs/architecture-rules.md. The gate is not weakened for anything else.