Runtime Laravel Package

Technical Evaluation

Architecture fit

• v1.0.0 reframes gcego/runtime from a mixed execution+rendering package into a single-purpose execution kernel. This is a net positive for architectural clarity: one entry point (Runtime::execute()) for actions, queries, form submissions and package-defined operation categories, rather than ad-hoc controllers/Livewire calls scattered across the app.
• The package now sits at the centre of a four-package constellation (gcego/core, gcego/registry, gcego/blueprints, plus the new gcego/rendering). Our dependency graph gains a mandatory node and, more importantly, a new release-coupling obligation: runtime 1.x cannot ship independently of core 1.x, registry 1.1.x and blueprints 1.0.x.
• The Operation value object (immutable, identifier-only targets, data-only input) is the right shape for a TPM-governed platform: it makes operations inspectable, loggable and testable, and it structurally prevents callers from smuggling objects or closures into an execution path.
• Trusted ExecutionContext built from the guard plus TenantResolver/PanelResolver contracts — explicitly never from request input — is a strong multi-tenant and authorization posture. This is the single most valuable property in the release from a risk perspective.
• Fail-closed authorization via GateExecutionAuthorizer (ability gcego-runtime.execute) is the correct default. It also gives us a familiar Laravel lever (Gates/policies) for governance, audit and per-tenant enablement.
• Diagnostic surface (RuntimeInspector, RuntimeReport::$handlers, RuntimeDiagnostic, gcego-runtime.execution Core diagnostic) is unusually good for a package at this maturity and materially lowers our support cost.

Integration feasibility

• Feasible, but gated on two hard prerequisites: PHP 8.3+ and Laravel 13. Laravel 13 as a hard floor means every host application must already be on it; this is a platform-wide upgrade decision, not a package decision. Any app still on Laravel 11/12 cannot adopt this at all.
• The removal of livewire/livewire, illuminate/view and gcego/components from runtime's dependency set is a genuine win — the kernel is now headless and can be adopted by API-first services that have no view layer.
• Adoption requires implementing or binding TenantResolver and PanelResolver (or accepting defaults). For a multi-tenant SaaS these are non-trivial implementations and must be treated as part of the integration scope, not an afterthought.
• Handler registration via typed HandlerRegistry (categories action, query, form, plus package-defined) is straightforward; the Bootable::bootPackage() + Extensions\ExecutionExtension path means our Core extensions can register middleware and handlers declaratively rather than in service providers.

Technical risk

• Rendering split (highest migration risk). Everything render-related moved to gcego/rendering with a different namespace and renamed symbols: Runtime::render(), renderAuthorized(), identityOf(), canRender() → Gcego\Rendering\RenderEngine; hostedBlueprint() → authorizedBlueprint(); Blade component <x-gcego-runtime::render> → <x-gcego-rendering::render>; config namespace gcego-runtime.rendering.* / .authorization.* → gcego-rendering.*; ability gcego-runtime.render → gcego-rendering.render. Every existing Blade template, gate check and published config file is affected.
• Silent authorization drift. The ability rename is the dangerous one. A Gate registered against the old gcego-runtime.render string will simply never match, and depending on how GateRenderAuthorizer behaves, this can fail open or produce confusing denials. Must be verified explicitly in test coverage, not assumed.
• Removed rendering surface: Rendering\BlueprintRenderer, Livewire\BlueprintHost, renderers.blueprint / hosts.blueprint views, gcego-runtime.livewire.* config, and the runtime.livewire capability. There is no drop-in equivalent for blueprint-as-component rendering, because blueprints 1.0 no longer models blueprints as components. Any screen relying on <x-gcego-runtime::...> blueprint hosting needs a redesign, not a rename.
• Pipeline ordering needs written confirmation. As documented, the pipeline reads resolve → authorize → handler → handler authorization → validation → middleware → handler, which places two authorization steps around the handler and validation after handler resolution (and the handler twice). Whether this is deliberate (coarse gate, then handler-specific policy) or a documentation artefact must be settled before we depend on it. Security review should not sign off on a sequence we can't state precisely.
• RuntimeInspector::inspect() signature change (no target argument) and RuntimeReport losing renderers/missingRenderers will break any internal health-check or admin dashboard we build on it.
• RuntimeConfig now throwing InvalidConfigurationException and holding execution settings only means config files must be republished, not merged. Stale config keys will be silently inert.
• Fail-closed behaviour plus execution.max_depth nesting limit plus "refusal to execute before Core has booted" are all correct, but they convert misconfiguration into hard runtime failures — good for safety, but they raise the bar on our pre-deployment validation.

Key questions

1. Is Laravel 13 a released/supportable target for our estate today, and if not, what is the runtime package's backport or support-window stance?
2. What is the intended semantics of the documented pipeline order — specifically, why does handler resolution precede validation, and why does authorization appear at two points?
3. Does GateExecutionAuthorizer fail closed when no Gate is defined for gcego-runtime.execute (deny-all), or does it fall through? Same question for gcego-rendering.render.
4. What is the prescribed replacement for BlueprintHost / Livewire\BlueprintHost — is there a documented pattern, or is blueprint hosting now explicitly the host application's responsibility?
5. Is gcego/rendering versioned and released in lockstep with runtime, and does it have its own support policy?
6. Are there published upgrade notes / Rector rules for the namespace and facade moves, or is migration manual?
7. What is the deprecation/support commitment for the 0.x line during our migration window?

Integration Approach

Stack fit

• Target state: PHP 8.3+, Laravel 13, gcego/core ^1.0, gcego/registry ^1.1, gcego/blueprints ^1.0, gcego/runtime ^1.0, and — for any app with a UI — gcego/rendering (newly added to the dependency list, at whatever version its README specifies).
• The headless kernel fits cleanly into API-first and service-layer architectures. For existing Livewire-rendered surfaces, gcego/rendering becomes a first-class dependency rather than an implicit one.
• Pin all five packages to explicit caret ranges in composer.json and add a CI job that resolves the constraint set on a clean install; the four-way coupling is the most likely source of "works on my machine" breakage.

Migration path

1. Inventory before touching composer. Grep the codebase for: Runtime::render, renderAuthorized, identityOf, canRender, hostedBlueprint, Gcego\Runtime\Rendering, Blade\BladeRenderer, Styling\, State\, RendererInterface, StylingResolver, RenderAuthorizer, StatefulComponent, Security\GateRenderAuthorizer, x-gcego-runtime::render, gcego-runtime.rendering, gcego-runtime.authorization, gcego-runtime.render, gcego-runtime.livewire, RuntimeInspector::inspect(, RuntimeReport->renderers, ->missingRenderers. This list is the migration backlog.
2. Config republish. Publish gcego-rendering config for UI apps; prune gcego-runtime.rendering.*, .authorization.* and .livewire.* blocks. Add gcego-runtime.execution.{ability,middleware,max_depth}.
3. Authorize before you render. Migrate Gate definitions and seeders from gcego-runtime.render to gcego-rendering.render in the same commit as the package bump. Write a test that asserts the old ability grants nothing and the new one grants correctly.
4. Rehome the rendering call sites onto Gcego\Rendering\RenderEngine, with the hostedBlueprint() → authorizedBlueprint() rename called out as a distinct, reviewable change.
5. Explicitly re-scope blueprint-as-component screens. These have no mechanical migration; treat them as product workstreams with their own estimates, not as part of the dependency bump.
6. Kernel adoption (can be deferred): register handlers in HandlerRegistry, implement TenantResolver/PanelResolver, bind GateExecutionAuthorizer, then begin routing new features through Runtime::execute().

Compatibility

• Hard breaks: framework floor (PHP 8.3 / Laravel 13), all rendering namespaces and class locations, the Blade component prefix, the render ability string, both config namespaces, RuntimeInspector::inspect() arity, RuntimeReport shape, removal of Rendering\BlueprintRenderer and Livewire\BlueprintHost, removal of runtime.livewire capability.
• Soft breaks: RuntimeConfig throwing InvalidConfigurationException will surface stale config as a boot-time failure; Bootable::bootPackage() refusing execution before Core boots may change startup ordering assumptions in existing service providers.
• Anything consuming RuntimeReport->renderers / ->missingRenderers (health checks, admin panels) breaks silently in the type sense — audit these deliberately.
• No compatibility shim is described; assume none exists and plan a coordinated cutover.

Sequencing

• Phase 0 — Decision gate. Confirm Laravel 13 is viable for the affected applications. If not, stop; there is no partial adoption of this release.
• Phase 1 — Spike/pilot on one non-critical UI app. Prove the rendering split and the ability rename end to end, including a negative authorization test.
• Phase 2 — Platform prep. Publish the gcego/rendering dependency and config baseline, standardise the new ability names, and land TenantResolver/PanelResolver implementations once for reuse.
• Phase 3 — Fan out the mechanical migration (namespace moves, component prefix, config keys) with a shared checklist and a codemod if the pilot shows the pattern is uniform.
• Phase 4 — Handle blueprint-hosting screens as bespoke redesign work with product sign-off.
• Phase 5 — Adopt the execution kernel for new features; migrate existing endpoints opportunistically rather than in a big bang.
• Keep gcego/rendering and gcego/runtime bumps in the same PR; splitting them creates a window where rendering call sites exist with no rendering package.

Operational Impact

Maintenance

• Four-to-five tightly versioned packages from a single vendor means our dependency maintenance cadence is now set by their release cadence. Budget recurring effort for coordinated bumps; a single-package upgrade is no longer a realistic unit of work.
• The rendering split does reduce long-term maintenance surface for headless services (no Livewire, no illuminate/view), which partially offsets the added package count.
• Config drift is the standing hazard: RuntimeConfig is execution-only and throws on invalid config, so stale published config becomes a boot failure rather than a warning. Add config validation to CI.
• Vendor concentration risk is real and unmitigated by anything in this release: execution, registry, blueprints and rendering are all gcego/*. We should document an exit cost for each.

Support

• First-line support needs a reliable way to answer "why did this operation fail". The release gives us that: ExecutionTrace, the three lifecycle events (OperationExecuting/OperationExecuted/OperationFailed), and ExecutionException subclasses each carrying an ErrorCategory with an HTTP status and a public message. Build a triage runbook that maps ErrorCategory → cause → owner.
• RuntimeInspector / RuntimeReport is the go-to diagnostic for "handler not registered", "override shadowing", "wrong middleware order". Expose it in a support-facing command or admin endpoint, and account for the new no-argument signature.
• Support scripts and docs must be scrubbed of pre-1.0 vocabulary (render, hostedBlueprint, gcego-runtime.render) or the first ticket after cutover will go down the wrong path.

Scaling

• Handler-category registry plus immutable Operation objects scale well horizontally: operations are cheap value objects, resolution is a registry lookup, and there is no rendering tree in the hot path for API workloads.
• execution.max_depth bounds nested operations, which is the right guardrail — but nested execution inside a single request is a latency multiplier. Instrument depth and pipeline duration before raising the limit; treat the default as a budget, not a suggestion.
• Scoped ExecutionScope keeps contexts isolated per request, so context bleed across nested or long-running operations is contained. Confirm behaviour under queue workers and Octane-style long-lived processes, where "scoped" and "singleton" are meaningfully different.
• The trusted-context design (guard-derived, never request-derived) is exactly what we want for tenant isolation at scale — it removes a whole class of injection risk that a request-input-derived context would have introduced.
• Rendering scaling is now gcego/rendering's problem plus Livewire's; decoupling means a rendering regression can no longer take down the execution kernel, which is a real availability improvement.

Failure modes

• Fail-closed authorization. Missing or misregistered ability → all operations denied. Loud and safe, but a full outage if we get the Gate wrong. Pair with a synthetic canary operation that must succeed post-deploy.
• Silent ability rename. Old gcego-runtime.render grants nothing; new gcego-rendering.render unvalidated. Highest-probability, lowest-visibility failure in this release. Cover with an explicit deny test.
• Boot-order refusal. "Refusal to execute before Core has booted" turns a provider-registration mistake into a hard startup failure. Good in production, disruptive in test suites and artisan commands — verify in CI early.
• Missing rendering package. If the runtime bump ships without gcego/rendering, any render call site fatals at class-not-found. Mitigated by shipping both together.
• Removed blueprint hosting. Screens using the old blueprint components fail at compile/lookup time after cutover. Enumerate them pre-migration so the failure is planned, not discovered.
• Deep nesting. Exceeding max_depth throws ContextViolationException/InvalidOperationException depending on the path; nested features that previously worked implicitly may start failing. Load-test with realistic nesting.
• Handler-failure ambiguity. HandlerFailedException plus OperationFailed events must not leak internal messages into the public ErrorCategory message. Verify the public/internal message split before exposing to clients.
• Config exception at boot. InvalidConfigurationException on every request if config is stale — effectively a total outage from a mis-merge. Config linting in CI is the cheapest mitigation available.

Ramp-up

• Engineers need to internalise: Runtime::execute() as the single entry point, the immutable Operation (identifier-only target, data-only input), the trusted ExecutionContext and the rule that context never comes from request input, the seven handler contracts, and the ErrorCategory model.
• The hardest cultural shift is not the API — it's the discipline of "authorize before resolve, never trust the request, fail closed". Ramp-up effort should go into that concept, with the API surface as the easy part.
• Suggested enablement: one reference implementation per handler category (action, query, form, package-defined) checked into the platform repo; a short internal note on the pipeline and its ordering; a migration runbook from the Phase 0 inventory list; and a "first operation" walkthrough that takes an engineer from Operation::make() to a traced ExecutionResult in under an hour.
• Expect the rendering-split migration to be the actual cost centre for UI teams, not the kernel. Staff and estimate accordingly — the kernel is a new capability, the rendering split is mandatory rework.