Skip to content

infrastructure: services cannot choose the priority of their delayed registration #36

Closed

Description

@schlessera

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 lint

Verify 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

  1. added
    type: featA new capability or a change in behaviour.
    area: infrastructuresrc/Infrastructure: services, injector, views, autoloader. What generated plugins build on.
    priority: p3Someday. Needs a driving use case before it starts.
    agent-readyContext and acceptance criteria are complete enough for an agent to take this unattended.
    on Oct 22, 2026
  2. self-assigned this
    on Oct 23, 2026
  3. schlessera commented on Oct 23, 2026

    @schlessera
    MemberAuthor

    Claiming this. The interface shape is not ruled on, so the first deliverable is a design proposal (no branch yet).

  4. schlessera commented on Oct 23, 2026

    @schlessera
    MemberAuthor

    Design proposal: registration priority for Delayed services

    Citation check (2026-10-23)

    The issue cites ServiceBasedPlugin.php:302-309; that range is now register(). The hard-coded priority 10 lives in schedule_potential_service_registration() (around lines 690-709). Correction to be folded into the body once a ruling lands.

    Already decided

    • Delayed stays unchanged (acceptance criterion, principle 4, interface segregation).
    • Priorities for non-delayed services are out of scope.
    • Capability interfaces are small, one concern each, with static accessors that are read before the service is built (as Delayed::get_registration_action() and Conditional::is_needed() are), so lazy instantiation (principle 5) still holds.

    Findings relevant to the design

    • Dependents of delayed services already register after them on the same action: register_pending_services() resumes at PHP_INT_MAX on each awaited action, and by then did_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.
    • A priority is only meaningful relative to the registration action's own callbacks (the plugin's, other plugins', core's), which is the use case in the issue.

    Options

    1. New interface HasRegistrationPriority (static get_registration_priority(): int), read in schedule_potential_service_registration() when the class implements it, otherwise 10. Mirrors Delayed, additive, trivial to explain. Trade-off: it is only meaningful together with Delayed; an architecture rule (like the existing capabilitiesOnServices checks) could flag it on a non-delayed service, and Delayed services without it keep the default (principle 3).
    2. Extend Delayed with the method. Rejected by the issue: breaks every existing delayed service.
    3. Interface extending 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.
    4. Return [ action, priority ] from a new method. Overlaps Delayed, rejected.

    Questions for the maintainer

    1. Option 1 or 3?
    2. The interface name (HasRegistrationPriority, Prioritized, DelayedWithPriority), and the method name (get_registration_priority(), by analogy with get_registration_action()).
    3. Should an architecture rule flag the interface on a service that is not Delayed? (Recommended: yes, since it would silently do nothing.)
    4. Is documenting that a dependent waiting on delayed dependencies ignores its own priority enough, or should that combination be rejected?

    Recommendation (not approval)

    Option 1: interface HasRegistrationPriority { public static function get_registration_priority(): int; }, used only when scheduling a Delayed service, plus an architecture rule for the no-op combination, a pattern entry in docs/patterns.md, and a test registering a service at a non-default priority. Nothing in Delayed changes.

  5. added
    needs: decisionBlocked on a maintainer ruling, not on code. State the question and options.
    and removed
    agent-readyContext and acceptance criteria are complete enough for an agent to take this unattended.
    on Oct 23, 2026
  6. removed their assignment
    on Oct 23, 2026
  7. added
    breakingChanges an interface or convention generated plugins rely on. Needs a ruling before code.
    on Oct 23, 2026
  8. schlessera commented on Oct 23, 2026

    @schlessera
    MemberAuthor

    Decision (maintainer, 2026-10-23): Add static get_registration_priority(): int directly to Delayed and supply DefaultRegistrationPriority, 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. Added breaking; needs: decision remains for the dependency-wait/priority interaction.

  9. added
    agent-readyContext and acceptance criteria are complete enough for an agent to take this unattended.
    and removed
    needs: decisionBlocked on a maintainer ruling, not on code. State the question and options.
    on Oct 23, 2026
  10. schlessera commented on Oct 23, 2026

    @schlessera
    MemberAuthor

    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, restored agent-ready, and retained breaking for the approved Delayed method migration.

  11. self-assigned this
    on Oct 23, 2026
  12. schlessera commented on Oct 23, 2026

    @schlessera
    MemberAuthor

    Claiming this for implementation now that all rulings are recorded. Branch: feat/36-delayed-registration-priority.

  13. schlessera commented on Oct 23, 2026

    @schlessera
    MemberAuthor

    Necessary unplanned change found while implementing: architecture.dependencyDirection only lets a subsystem depend on infrastructure interfaces, so the sample's use 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 in docs/architecture-rules.md. The gate is not weakened for anything else.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

agent-readyContext and acceptance criteria are complete enough for an agent to take this unattended.area: infrastructuresrc/Infrastructure: services, injector, views, autoloader. What generated plugins build on.breakingChanges an interface or convention generated plugins rely on. Needs a ruling before code.priority: p3Someday. Needs a driving use case before it starts.type: featA new capability or a change in behaviour.

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions