Skip to content

Epic: The infrastructure honours its design principles and absorbs fixes proven in production #18

Open
22 of 27 issues completed

Description

@schlessera

Outcome

The scaffold's infrastructure does what docs/design-principles.md says it does: services register reliably in any order, every lifecycle-aware service takes part in the lifecycle events it declares, exceptions never reach end users, the injector builds any valid object graph, views are safe by default, and the lifecycle points that production plugins needed (multisite, uninstall, WP-CLI, assets) exist as capability interfaces.

Why now

An architecture review on 2026-10-22, run when the design principles were written down, found that several parts of the infrastructure contradict them. At that review, live failures included a fatal sample on singular views and services skipped silently during registration. #19 is now closed through merged PR #63: the composition root supplies the current post and the view escapes its fields. The original sample fatal and #20 registration defect are now fixed; this paragraph records the review history, not live failures.

A comparison with three plugins built on this scaffold, including Google's AMP and Web Stories plugins, showed which of these bugs production use had already run into and fixed. It also showed which lifecycle points those plugins had to add themselves, and where their fixes introduced new problems. That gives a field-tested basis for each change.

Shared context

Source anchors at main 15cac4c2: src/Infrastructure/ServiceBasedPlugin.php:1242-1422 (registration/normalization), :414-524 (legacy/scoped activation/deactivation), src/Infrastructure/Injector/SimpleInjector.php:387-420 (named-type injection), and src/Infrastructure/View/SimpleView.php:119-175 (rendering).

Constraints and non-goals

  • PHP 7.4 stays the floor; Composer stays optional at runtime (principle 1).
  • No static service locator. All three downstream plugins added one; this epic removes the need for it instead (sub-issue on injecting the injector).
  • No lenient "silently drop invalid configuration" behaviour (principles 9 and 10).
  • Interface changes that break generated plugins carry the breaking label and need a ruling before code.

Breakdown

The native child list is the authoritative plan: 27 children, 22 closed and five open (#35, #37, #143, #149, #153). The original 22 children have 20 closed and two open (#35 and #37). Follow-ups #143, #149 and #153 remain unresolved; #156 and #173 are closed through #174 and #176, providing isolated template scopes and per-render presenters.

#38/#163 implemented optional registration history and Query Monitor. #37's asset capability is now merged through #177 and present on main, including sample assets. #37 remains open because #177 explicitly leaves the acceptance test for registration after the footer print pass unmet; its Refs #37 is deliberate. Do not treat it as missing asset infrastructure or close it from this reconciliation.

The scoped lifecycle interfaces (#34), view-failure policy (#27/#30), dependency/injector hardening and original architecture/testing fixes have landed. Scoped lifecycle failures deliberately propagate under the maintainer's #34 exception; the general callback boundary remains #143. No blanket "exceptions never escape" implementation is claimed.

Definition of done

  • Every sub-issue is closed.
  • The lifecycle table in docs/design-principles.md lists every capability interface the infrastructure orchestrates.
  • No statement in the design principles is contradicted by the infrastructure, re-checked by a fresh review of src/Infrastructure/ against the document.

Verification

For each implementation, run composer test and composer lint in the supported CI environment. On completion, review every sub-issue and re-check the lifecycle table and infrastructure against all design principles.

Impact on generated plugins

Behaviour fixes and approved capability additions propagate into generated plugins. Every changed public contract retains its own compatibility/migration ruling; this epic grants no additional exception. The tracker remains open for the five children above and never receives agent-ready. Original sample success/missing-post tests are in tests/php/Integration/SampleLoopServiceTest.php; the current sample now uses the per-render PostHeader presenter introduced by #173/#176.

Updated 2026-10-23: Reconciled original child completion and remaining work at 1133d65, repaired moved source anchors, and attached the general boundary and three concrete follow-up bugs. Preserved all prior policy rulings; 18/26 children closed, tracking epic remains open.

Updated 2026-10-23: Reconciled merged #38/#163 and #167 at main 61a9b00, repaired registration/lifecycle/sample anchors, and updated native child completion to 19/26. Seven children remain open; existing rulings are unchanged.

Updated 2026-10-24: #42 merged and closed #10 after PHP 7.4/8.3 tests, PHP 8.3 lint and both autoloading paths in WordPress passed. Updated completion to 20/26; six children remain open. Existing rulings are unchanged.

Updated 2026-10-24: Reconciled 27 native children (22 closed, five open), merged template/presenter and asset work, the deliberately unmet #37 footer-print test, and current source anchors. The epic remains open and never agent-ready. Reviewed origin/main 15cac4c2.

Activity

  1. added
    type: fixSomething is broken and must behave the way it is documented.
    area: infrastructuresrc/Infrastructure: services, injector, views, autoloader. What generated plugins build on.
    epicA tracking issue. The work lives in its sub-issues; never coded directly.
    on Oct 22, 2026
  2. 7 remaining items

  3. schlessera commented on Oct 22, 2026

    @schlessera
    MemberAuthor

    Triage (2026-10-22): Checked all 22 native sub-issues and the existing parent links. Added source anchors, verification and generated-plugin impact. Retained p1 because the epic groups live failures already identified in its body; it remains a tracking epic, never agent-ready.

  4. schlessera commented on Oct 22, 2026

    @schlessera
    MemberAuthor

    Triage (2026-10-22): Reconciled the declined providers ruling (#7 and exploratory PR #8 are closed) and verified all 22 native sub-issues. Runtime citations still match main; this remains a p1 tracking epic, never agent-ready.

  5. schlessera commented on Oct 23, 2026

    @schlessera
    MemberAuthor

    Triage (2026-10-23): Verified #19 closed through merged PR #63 and checked the delegation, escaping and integration-test source in main. Removed the fixed sample fatal from current failures and recorded one closed plus 21 open sub-issues. Kept p1 and epic; no readiness change.

  6. schlessera commented on Oct 23, 2026

    @schlessera
    MemberAuthor

    Triage (2026-10-23): Reconciled original child completion and remaining work at 1133d65, repaired moved source anchors, and attached the general boundary and three concrete follow-up bugs. Preserved all prior policy rulings; 18/26 children closed, tracking epic remains open.

  7. schlessera commented on Oct 23, 2026

    @schlessera
    MemberAuthor

    Triage (2026-10-23): Reconciled merged #38/#163 and #167 at main 61a9b00, repaired registration/lifecycle/sample anchors, and updated native child completion to 19/26. Seven children remain open; existing rulings are unchanged.

  8. schlessera commented on Oct 24, 2026

    @schlessera
    MemberAuthor

    Triage (2026-10-24): Reconciled 27 native children (22 closed, five open), merged template/presenter and asset work, the deliberately unmet #37 footer-print test, and current source anchors. The epic remains open and never agent-ready.

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    area: infrastructuresrc/Infrastructure: services, injector, views, autoloader. What generated plugins build on.epicA tracking issue. The work lives in its sub-issues; never coded directly.priority: p1Next up.type: fixSomething is broken and must behave the way it is documented.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions