#What the repository actually implements

DGLab is a PHP 8.4 monorepo/framework built around a six-ring dependency architecture:

Outer Rim       UI / public entrypoints
     ↓
Outer Spokes    external adapters / bridges
     ↓
Inner Rim       HTTP/API pipeline
     ↓
Inner Spokes    application services
     ↓
Hub             aggregates / orchestration
     ↓
Core            framework primitives

The repository explicitly requires dependencies to point inward. The implementation largely follows this model. (GitHub) The important distinction is that the architecture is currently more mature than the application layer. Core infrastructure has substantial implementation, while several Hub/Bridge/Spoke components remain depth-1/2 or stub-level. The README itself contains contradictory status statements, so repository code/tests should be treated as the source of truth. (GitHub)

#Actual request path

The current implementation is approximately:

Caddy
  │
  ▼
Tengine
  │
  ▼
FrankenPHP worker
  │
  ▼
public/index.php
  │
  ├── Kernel boot ────────────────┐
  │                              │
  │     Container                │
  │     EventDispatcher          │
  │     Logger                   │
  │     ErrorHandler             │
  │     Router                   │
  │                              │
  ▼                              │
Kernel.handle(request)            │
  │                              │
  ▼                              │
RequestReceivedEvent              │
  │                              │
  ▼                              │
MiddlewarePipeline                │
  │                              │
  ▼                              │
Vanguard / outer adapter          │
  │                              │
  ▼                              │
FinalRequestHandler               │
  │                              │
  ▼                              │
Router                            │
  │                              │
  ▼                              │
Controller                        │
  │                              │
  ▼                              │
ResponseReadyEvent ◄─────────────┘
  │
  ▼
HTTP response

This isn't merely conceptual: Kernel, MiddlewarePipeline, PerRequestHandler, Router, HttpBootstrapper, and public/index.php implement these stages. (GitHub)

#Particularly good architectural decisions

1. Worker/request state separation

This is probably the most important design decision in the current code.

The Kernel is deliberately worker-scoped, while the middleware cursor and DI pulse() instances are request/Fiber-scoped. The container uses WeakMap<Fiber, ...> so request state can disappear with the Fiber rather than accumulating inside a long-running FrankenPHP worker. (GitHub) That is exactly the sort of issue that normally breaks PHP applications when moving from PHP-FPM to persistent workers.

2. Frozen infrastructure

Router registration freezes after the first match, and middleware registration freezes after the first request. This prevents runtime mutation of the request graph. (GitHub) 3. Per-request middleware cursor

The previous shared-cursor design was replaced with PerRequestHandler, giving every request its own cursor. This is important for Fiber concurrency and re-entrant middleware. (GitHub) 4. Explicit Kernel lifecycle

Unbooted
   │
   ▼
Booting ──failure──► Terminated
   │
   ▼
Booted
   │
   ▼
Handling
   │
   ▼
Booted
   │
   ▼
Terminating
   │
   ▼
Terminated

#Architectural issues I would carry into the final SPEC

A. public/index.php is currently doing too much

The public entrypoint directly constructs:

• Container
• Event dispatcher
• Logger
• Error handler
• Vanguard
• Contract registry
• WAF
• Kernel
• bootstrappers
• routes
• controller bindings

That means the Outer Rim is currently also a composition root.

It works for a walking skeleton, but I would not preserve this structure for the production architecture.

The eventual composition should be closer to:

public/index.php
       │
       ▼
ApplicationFactory
       │
       ▼
Kernel
       │
       ├── Core services
       ├── Hub services
       ├── Bridges
       ├── Spokes
       └── application routes

This becomes particularly important once database, cache, encryption, authentication, authorization and multiple adapters arrive.

B. The architecture has a potentially dangerous distinction between worker-scoped singleton and request-scoped service

The container explicitly supports both:

singleton → worker lifetime
pulse      → Fiber/request lifetime
transient  → construction lifetime

That is powerful, but it creates a major architectural invariant:

A worker-scoped service must never retain request-specific state.

This needs to become a formal architecture rule and preferably a testable architectural fitness function. The current code has the mechanisms, but the application architecture still needs to enforce their correct usage. (GitHub)

C. The "six rings" aren't yet fully represented in code

The Core is concrete and substantial.

The upper layers are still emerging. For example, the current public bootstrap explicitly describes JWT, rate limiting and audit functionality as pass-through stubs. (GitHub) So I would describe the current architecture as:

A well-developed Core runtime with a partially realized concentric application architecture.

Rather than calling the whole six-ring architecture production-complete.

D. There is already evidence of documentation/state drift

The README says the walking skeleton and full Pulse trace have been completed, but its Milestone 0 table simultaneously lists HUB-01, BRIDGE-01, ISPOKE-09, and ESPOKE-01 as not started. It also contains historical text saying public/index.php was a 503 placeholder despite later showing an implemented entrypoint. (GitHub) For a contractor-facing architecture, I would introduce a single machine-verifiable architecture status source rather than allowing README, blueprints, ADRs, worklogs and implementation status to diverge.

#My proposed conclusion for this area

Architecture assessment: the fundamental direction is sound, particularly the worker/Fiber lifecycle model and dependency inwardness. The main architectural work now is not replacing the Wheel; it is making the Wheel enforceable, especially around composition roots, request-scoped state, layer boundaries, and architecture/status verification.

Assumption: I will preserve the Wheel architecture unless the implementation analysis shows that one of its boundaries creates a concrete technical problem.

Please confirm/reject this Area 1 assessment.

For Area 2, I’ll trace the DI → bootstrap → middleware → router → controller → response lifecycle, including concrete coupling problems and failure paths.

you asked

Proceed

chatgpt response

The lifecycle is coherent, but there is an important architectural distinction: the Kernel is becoming the runtime orchestrator, while public/index.php is still the application composition root. That is acceptable for the walking skeleton but should be resolved before the framework grows.

#2.1 Boot sequence

The effective boot sequence is:

                Worker starts
                     │
                     ▼
              public/index.php
                     │
                     ▼
              Create Container
                     │
        ┌────────────┼────────────┐
        ▼            ▼            ▼
     Events       Logging      ErrorHandler
        │
        ▼
   Infrastructure
   registrations
        │
        ▼
    Bootstrappers
        │
        ├── HTTP
        ├── Routing
        ├── Middleware
        ├── Vanguard
        └── Application
        │
        ▼
       Kernel
        │
        ▼
     READY

The important architectural property is that boot happens once per worker, not once per request.

That is essential for FrankenPHP.

The container has three useful lifetimes:

The pulse mechanism is the particularly interesting part.

Conceptually:

Worker
 │
 ├── Singleton Container
 │      ├── Router
 │      ├── EventDispatcher
 │      ├── Logger
 │      └── Configuration
 │
 ├── Fiber #1
 │      └── Pulse instances
 │
 ├── Fiber #2
 │      └── Pulse instances
 │
 └── Fiber #3
        └── Pulse instances

This is substantially better than a conventional PHP-FPM assumption where every process/request starts fresh.

#Architectural rule I recommend adding

RULE-DI-001

A singleton MUST NOT retain request-derived state.

A pulse-scoped service MAY retain request-derived state.

A transient service MUST NOT assume either worker or request lifetime.

This should become an automated architecture test rather than merely documentation.

2.3 Middleware execution

The middleware model is effectively:

Request
   │
   ▼
┌──────────────────────┐
│ Middleware #1        │
│ Vanguard/WAF/etc.    │
└──────────┬───────────┘
           │ next()
           ▼
┌──────────────────────┐
│ Middleware #2        │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│ Middleware #N        │
└──────────┬───────────┘
           │
           ▼
     Final Handler

The significant implementation decision is that the cursor isn't globally shared.

Instead:

Request A → Cursor A
Request B → Cursor B
Request C → Cursor C

rather than:

Request A ─┐
Request B ─┼──► shared cursor  ❌
Request C ─┘

That is exactly what you want with concurrent Fibers.

#One thing I would strengthen

Middleware should have an explicit classification:

GLOBAL
REQUEST
RESPONSE
ERROR

For example:

CorrelationIdMiddleware   REQUEST
AuthenticationMiddleware  REQUEST
AuthorizationMiddleware   REQUEST
RateLimitMiddleware       REQUEST
CompressionMiddleware     RESPONSE
AuditMiddleware           RESPONSE
ExceptionMiddleware       ERROR

Without this classification, middleware ordering will eventually become implicit tribal knowledge.

2.4 Router

The router is intentionally frozen after application startup/first use.

That gives:

BOOT
 │
 ├── register route A
 ├── register route B
 ├── register route C
 │
 ▼
FREEZE
 │
 ▼
MATCH × N requests

rather than:

Request
 │
 └── mutate routing table

This is the correct model for a persistent worker.

I would go one step further and make the route table compiled during boot:

Route definitions
       │
       ▼
Route compiler
       │
       ▼
Immutable route table
       │
       ▼
Fast request matching

That makes the worker's runtime path independent of registration logic.

2.5 Controller resolution

The final handler effectively bridges:

HTTP Request
     │
     ▼
Router
     │
     ├── path parameters
     ├── route metadata
     └── controller reference
              │
              ▼
        DI resolution
              │
              ▼
          Controller
              │
              ▼
          Response

This is an appropriate boundary.

However, I would enforce one architectural rule:

Controllers should be adapters, not business-logic containers.

So:

Controller
    │
    ▼
Application Service
    │
    ▼
Domain/Aggregate

not:

Controller
    │
    ├── database
    ├── validation
    ├── business rules
    ├── external HTTP
    └── response formatting

That distinction becomes critical when the Hub and Spokes are populated.

2.6 Event lifecycle

The event mechanism gives the runtime a useful observable lifecycle:

Request
  │
  ▼
RequestReceived
  │
  ▼
Middleware
  │
  ▼
Controller/Application
  │
  ▼
ResponseReady
  │
  ▼
Response

This is useful for:

• metrics
• tracing
• audit
• logging
• request timing
• security events

But I would not use events as the primary mechanism for business control flow.

Good:

RequestCompleted
       │
       ├── metrics listener
       ├── tracing listener
       └── audit listener

Risky:

OrderCreated
       │
       ├── listener A modifies order
       ├── listener B modifies payment
       └── listener C modifies inventory

For business orchestration, explicit application services are easier to reason about and test.

2.7 Failure paths

This is where the architecture needs more specification.

The desired lifecycle should be:

                       ┌──────────────┐
                       │    Request   │
                       └──────┬───────┘
                              │
                              ▼
                       RequestReceived
                              │
                              ▼
                         Middleware
                              │
                    ┌─────────┴─────────┐
                    │                   │
                  error                success
                    │                   │
                    ▼                   ▼
             ErrorHandler            Router
                    │                   │
                    │             ┌─────┴─────┐
                    │             │           │
                    │           404         Handler
                    │             │           │
                    │             │           ▼
                    │             │      Application
                    │             │           │
                    │             │      ┌────┴────┐
                    │             │    error    success
                    │             │      │          │
                    └─────────────┴──────┤          │
                                         ▼          ▼
                                    ErrorResponse ResponseReady
                                         │          │
                                         └────┬─────┘
                                              ▼
                                           Response

The critical requirement is:

Every failure must eventually become a controlled HTTP response or a worker-terminating condition.

No exception should accidentally escape into the persistent worker and poison subsequent requests.

2.8 Most important lifecycle risk

The architecture's hardest problem isn't HTTP.

It's state contamination across requests.

Consider:

final class BadService
{
    private ?User $currentUser = null;

    public function setUser(User $user): void
    {
        $this->currentUser = $user;
    }
}

If BadService is registered as a singleton:

Request A
  user = Alice
      │
      ▼
singleton.currentUser = Alice
      │
      ▼
Request B
  user = Bob
      │
      └── potentially observes Alice ❌

This is the kind of bug that persistent PHP workers make dramatically more dangerous.

Therefore the architecture should establish:

                  ┌──────────────────────┐
                  │ Worker-scoped object  │
                  └──────────┬───────────┘
                             │
                  MUST BE STATE-INDEPENDENT
                             │
                             ▼
                  ┌──────────────────────┐
                  │ Request/Fiber object │
                  └──────────┬───────────┘
                             │
                  MAY contain request state

I'd make this one of the highest-priority architecture tests.

Area 2 conclusion

The runtime lifecycle is fundamentally sound:

Boot once → create isolated request context → execute immutable middleware/router infrastructure → resolve application handler → emit response lifecycle events → return response.

The main improvements I recommend are:

1. Move composition into an ApplicationFactory/bootstrap layer.
2. Formalize worker vs request lifetime rules.
3. Classify middleware by lifecycle responsibility.
4. Compile/freeze routes during boot.
5. Keep controllers thin.
6. Keep events primarily for observability/integration rather than hidden business orchestration.
7. Add explicit persistent-worker contamination tests.
8. Specify failure/exception semantics as an architectural contract.

I would therefore retain the existing runtime model rather than replace it.

Area 2 assessment: confirmed, with the above hardening requirements.

#Next: Area 3 — Component & data architecture

I'll next map the actual Core → Hub → Inner Spokes → Bridges → Outer Spokes → UI components, identify which are implemented versus stubs, and derive the database/data ownership model. This is where we'll determine whether the six-ring architecture actually provides useful boundaries or is currently mostly organizational.

you asked

Proceed

chatgpt response

The repository makes an important architectural claim: Core → Hub → Spoke → Bridge → UI are dependency rings, not simply folders. The current repository structure supports that intention, but the implementation is still heavily concentrated in Core. (GitHub)

#3.1 Current component distribution

                         APPLICATION
                              │
                              ▼
                    ┌──────────────────┐
                    │   Outer Rim/UI   │
                    │  application tier│
                    └────────┬─────────┘
                             │
                             ▼
                    ┌──────────────────┐
                    │ Outer Spokes     │
                    │ external adapters│
                    └────────┬─────────┘
                             │
                             ▼
                    ┌──────────────────┐
                    │ Inner Rim / API  │
                    │ HTTP/application │
                    └────────┬─────────┘
                             │
                             ▼
                    ┌──────────────────┐
                    │ Inner Spokes     │
                    │ application svcs │
                    └────────┬─────────┘
                             │
                             ▼
                    ┌──────────────────┐
                    │ Hub              │
                    │ aggregates/config│
                    └────────┬─────────┘
                             │
                             ▼
                    ┌──────────────────┐
                    │ Core             │
                    │ framework        │
                    └──────────────────┘

The repository currently has 8 implemented Core packages covering DI, events, HTTP messages, middleware, router, configuration, logging and error handling. It also has blueprints for 31 Hub and 45 Spoke components, but those blueprints substantially exceed what is currently implemented. (GitHub) That distinction matters.

#Current maturity

So the Wheel is currently asymmetric:

                 UI       ░░
              Adapters   ░░░
                 API     ██
              Services  ░░░
                Hub     ░░
                Core    ██████████

That isn't inherently bad. In fact, for a framework being built from the bottom upward, it is expected.

But it means we should not yet infer that the proposed domain architecture has been validated simply because the Core architecture works.

3.2 The Hub is the critical boundary

The README describes the Hub as:

Aggregates

That is a potentially good choice, but it needs to be made much more precise.

I recommend defining the Hub as:

Hub =
    Domain entities
  + Value objects
  + Aggregates
  + Domain services
  + Domain events
  + Repository interfaces

and not:

Hub =
    database models
  + controllers
  + HTTP clients
  + framework services

The latter would turn the Hub into a "god layer."

The dependency should therefore be:

                 Inner Spoke
                     │
                     ▼
              Application Service
                     │
                     ▼
                  Aggregate
                     │
             ┌───────┴────────┐
             ▼                ▼
        Domain Event     Repository
                              │
                              ▼
                       Infrastructure

The repository interface belongs inward.

The implementation belongs outward.

3.3 Data architecture

This is the biggest area where the current repository needs further definition.

The current Core contains infrastructure primitives but does not yet establish a production persistence architecture. The README explicitly identifies CORE-19 DBAL, CORE-15 Cache, CORE-14 Filesystem and CORE-16 Encryption as the next persistence-oriented Core packages. (GitHub) Therefore I would not invent a database schema for DGLab yet.

Instead, the architecture should establish ownership first.

#Recommended data ownership

                    ┌────────────────────┐
                    │     Application    │
                    └─────────┬──────────┘
                              │
                              ▼
                    Application Services
                              │
                              ▼
                         Aggregates
                              │
                              ▼
                      Repository Ports
                              │
                ┌─────────────┴─────────────┐
                │                           │
                ▼                           ▼
          SQL Repository              Cache Repository
                │                           │
                ▼                           ▼
           PostgreSQL                   Redis/etc.

The important rule is:

No application/domain component should depend directly on PDO, Redis, filesystem APIs or vendor SDKs.

Those should be infrastructure implementations of inward-facing contracts.

3.4 Database boundary

When CORE-19 arrives, I would structure the persistence subsystem approximately as:

packages/core/dbal/
    src/
        Connection/
        Transaction/
        Query/
        Migration/
        Exception/

Then application-specific persistence should not live inside Core.

For example:

app/
  Domain/
    User/
      User.php
      UserRepository.php

  Infrastructure/
    Persistence/
      PostgreSQL/
        PostgreSQLUserRepository.php

Dependency:

UserRepository
      ▲
      │ implements
      │
PostgreSQLUserRepository

rather than:

User
 │
 └── PostgreSQLConnection ❌

This keeps Core generic and the domain portable.

3.5 Aggregates and transaction boundaries

Once the Hub becomes real, aggregate boundaries need to correspond to transaction boundaries.

For example:

┌──────────────────────────────┐
│          Account             │
│                              │
│  AccountId                   │
│  Status                      │
│  Balance                     │
│  Limits                      │
│                              │
│  deposit()                   │
│  withdraw()                  │
│  suspend()                   │
└──────────────┬───────────────┘
               │
               ▼
          Repository
               │
               ▼
          Transaction

The application service should own the transaction:

Command
   │
   ▼
Application Service
   │
   ├── begin transaction
   │
   ├── load aggregate
   ├── invoke domain operation
   ├── persist aggregate
   ├── publish domain events
   │
   └── commit

That gives us a clean place to implement consistency.

3.6 Events need two distinct categories

The current event infrastructure should not be confused with domain events.

I recommend explicitly distinguishing:

#Framework/runtime events

RequestReceived
ResponseReady
KernelBooted
KernelTerminated
BootstrapperFailed

These belong to Core/runtime.

#Domain events

UserRegistered
OrderCreated
PaymentCaptured
AccountSuspended

These belong to Hub/domain.

And potentially:

#Integration events

UserRegistered.v1
PaymentCaptured.v1

These belong at the Bridge/Spoke boundary.

So:

Core
 └── Runtime events

Hub
 └── Domain events

Spokes/Bridges
 └── Integration events

This prevents the event dispatcher from becoming an undifferentiated global message bus.

3.7 External adapters

The Outer Spokes should follow an anti-corruption boundary:

             External API
                  │
                  ▼
        ┌─────────────────────┐
        │ External Adapter    │
        │                     │
        │ vendor DTO          │
        │ auth                │
        │ retry               │
        │ timeout             │
        │ error translation   │
        └──────────┬──────────┘
                   │
                   ▼
             Internal Port
                   │
                   ▼
               Domain

This is especially important if DGLab intends to retain "full control over every layer," as stated by the repository. (GitHub) Vendor-specific concepts should stop at the adapter boundary.

3.8 The six rings should therefore become six dependency contracts

I'd formalize the architecture as:

┌─────────────────────────────────────────────────────────────┐
│ OUTER RIM                                                   │
│ Presentation / HTTP / CLI                                  │
│                                                             │
│   MAY depend on → Inner Rim, Inner Spokes                  │
├─────────────────────────────────────────────────────────────┤
│ OUTER SPOKES                                                │
│ External system adapters                                    │
│                                                             │
│   MAY depend on → inward contracts                          │
├─────────────────────────────────────────────────────────────┤
│ INNER RIM                                                   │
│ HTTP/API/application boundary                               │
│                                                             │
│   MAY depend on → Inner Spokes, Hub                         │
├─────────────────────────────────────────────────────────────┤
│ INNER SPOKES                                                │
│ Use cases / application services                            │
│                                                             │
│   MAY depend on → Hub                                       │
├─────────────────────────────────────────────────────────────┤
│ HUB                                                         │
│ Domain / aggregates / ports                                 │
│                                                             │
│   MUST NOT depend on → outer layers                         │
├─────────────────────────────────────────────────────────────┤
│ CORE                                                        │
│ Runtime primitives                                          │
│                                                             │
│   MUST NOT depend on → any application layer                │
└─────────────────────────────────────────────────────────────┘

That is considerably more useful than merely saying "dependencies point inward."

3.9 The biggest architectural smell I see

The risk is architecture-by-blueprint.

There are 105 blueprints and 19 ADRs, while implementation is still concentrated in Core. The project has a sophisticated architectural governance system—Spiral Deepening, interface freezes, ADR-gated changes and the Nuclear-Grade Doctrine. (GitHub) That's valuable, but it introduces a second failure mode:

The architecture can become more complete on paper than in executable code.

The remedy isn't less architecture documentation.

It is architecture tests.

For every ring:

Core
 ├── may import PSR dependencies
 └── MUST NOT import App/

Hub
 ├── may import Core contracts
 └── MUST NOT import HTTP/controller/vendor packages

Spoke
 ├── may import Hub
 └── may import external infrastructure

UI
 └── may import application contracts

Then CI verifies the rules.

Area 3 assessment

#What I would keep

• Six-ring Wheel.
• Core as framework/runtime foundation.
• Hub as inward-facing domain boundary.
• Spokes as application/integration services.
• Bridges/adapters for external technology.
• Monorepo.
• Blueprint/ADR governance.

#What I would change

1. Define Hub precisely as domain ownership.
2. Separate domain, runtime and integration events.
3. Introduce repository ports before persistence implementations.
4. Keep database/cache/filesystem implementations outside the domain.
5. Make aggregate boundaries explicit transaction boundaries.
6. Treat adapters as anti-corruption layers.
7. Turn ring rules into automated architecture tests.
8. Track implemented depth independently from blueprint existence.

#Current data architecture conclusion

There is not enough implemented persistence infrastructure yet to justify a concrete production database schema. CORE-19 and the associated persistence packages are explicitly the next architectural stage. (GitHub) So I recommend that we do not prematurely design tables until we inspect those persistence specifications and the first Hub domain components.

Area 3 assessment: confirmed with these boundary refinements.

The next piece is especially important because DGLab's runtime isn't a conventional PHP deployment. It uses:

Caddy → Tengine → FrankenPHP → persistent workers → Fibers

and the repository calls this the Anvil three-tier deployment stack. (GitHub) I'll analyze whether that topology is justified, its failure modes, scaling model, health checks, deployment/rollback behavior, and whether Tengine is actually earning its place between Caddy and FrankenPHP.

you asked

Proceed

chatgpt response

The deployment architecture is one of the more opinionated parts of DGLab. The repository describes an Anvil stack built around persistent PHP workers, with Caddy/Tengine at the edge and FrankenPHP as the PHP runtime. I’ll separate what the architecture is trying to achieve from what should be retained as production infrastructure.

#4.1 Current topology

                    Internet
                       │
                       ▼
                ┌─────────────┐
                │    Caddy    │
                │ TLS / Edge  │
                └──────┬──────┘
                       │
                       ▼
                ┌─────────────┐
                │   Tengine   │
                │ HTTP proxy  │
                └──────┬──────┘
                       │
                       ▼
             ┌──────────────────┐
             │    FrankenPHP    │
             │ persistent PHP   │
             │     workers      │
             └────────┬─────────┘
                      │
               ┌──────┴──────┐
               ▼             ▼
           Worker #1      Worker #N
               │             │
               ▼             ▼
             Kernel        Kernel

The significant architectural choice is persistent workers.

Traditional PHP:

request → process → PHP application → response → process discarded

DGLab:

worker
  │
  ├── boot framework
  │
  ├── request A
  ├── request B
  ├── request C
  ├── ...
  │
  └── terminate worker

That makes the application behave more like a conventional long-running server.

4.2 Why persistent workers change the architecture

The obvious benefit is avoiding repeated initialization:

Traditional PHP/FPM

Request
  ├── load framework
  ├── construct container
  ├── construct router
  ├── configure application
  ├── execute
  └── exit

versus:

FrankenPHP worker

Worker boot
  ├── construct container
  ├── construct router
  ├── configure application
  └── freeze

Requests
  ├── execute
  ├── execute
  ├── execute
  └── execute

DGLab's Core lifecycle architecture is specifically designed around this model.

That is why the previous Area 2 finding about singleton/request state is not a minor implementation detail. It is a fundamental production requirement.

4.3 The most important operational invariant

A persistent worker must be considered potentially immortal.

Therefore:

Anything allocated at worker scope
        │
        ├── MUST be reusable
        ├── MUST be bounded
        ├── MUST be concurrency-safe
        └── MUST NOT contain request state

For example, these are dangerous as singletons:

CurrentUser
Request
RequestHeaders
RequestBody
Response
AuthenticationContext
Request-specific cache
Request correlation ID

Whereas these are reasonable candidates:

Router
Configuration
Logger
Database connection manager
HTTP client pool
Event dispatcher
Compiled route table

with the caveat that the implementation of each must itself be safe for the chosen concurrency model.

4.4 Worker recycling is mandatory

I would not design DGLab around the assumption that a worker should live forever.

Even correctly written applications can accumulate:

• native/library allocations
• fragmentation
• accidental static state
• third-party library state
• connection degradation
• memory retained by caches
• leaks in extensions

Therefore the production policy should be:

Worker
  │
  ├── serve requests
  │
  ├── monitor memory
  │
  ├── monitor request count
  │
  ├── monitor fatal errors
  │
  └── graceful recycle

The thresholds should be configurable rather than hard-coded into application logic.

I'd use at least:

MAX_REQUESTS_PER_WORKER
MAX_WORKER_MEMORY
MAX_WORKER_LIFETIME
MAX_CONSECUTIVE_FAILURES

with graceful drain before termination.

4.5 Caddy → Tengine → FrankenPHP

This is the infrastructure component I would challenge most strongly.

The question isn't whether the topology works.

It is:

What architectural responsibility does each proxy uniquely provide?

A reasonable separation could be:

Caddy
 ├── TLS termination
 ├── certificate management
 ├── public edge
 └── coarse rate limiting

Tengine
 ├── connection management
 ├── advanced proxy policies
 ├── buffering
 └── internal traffic routing

FrankenPHP
 ├── PHP execution
 ├── application workers
 └── application HTTP lifecycle

But if Tengine merely forwards HTTP:

Caddy
  │
  ▼
Tengine
  │
  ▼
FrankenPHP

then it introduces another:

• process
• configuration
• network hop
• failure domain
• health check
• security boundary
• operational dependency

without necessarily producing an architectural benefit.

4.6 My recommendation for the deployment decision

The architecture should explicitly support two profiles.

#Minimal deployment

Internet
   │
   ▼
 Caddy
   │
   ▼
FrankenPHP
   │
   ▼
DGLab

#Advanced deployment

Internet
   │
   ▼
 Caddy
   │
   ▼
 Tengine
   │
   ▼
FrankenPHP cluster
   │
   ├── Worker
   ├── Worker
   └── Worker

Tengine should only be enabled when a documented operational requirement demands it.

That gives the architecture a clean complexity budget.

4.7 Health checks

I recommend three different health concepts.

#Liveness

GET /health/live

Answers:

Is this worker/process alive?

No database call.

Expected:

{"status":"ok"}

#Readiness

GET /health/ready

Answers:

Can this instance receive traffic?

Potential checks:

Kernel booted
Router frozen
Required configuration loaded
Critical dependencies available

#Dependency health

Do not make liveness depend on PostgreSQL/Redis/etc.

Instead expose internal dependency telemetry:

DB      healthy
Cache   healthy
Queue   degraded

This avoids a database outage causing every instance to appear "dead" and triggering a restart storm.

4.8 Graceful shutdown

Persistent workers require explicit shutdown semantics.

Desired sequence:

SIGTERM
   │
   ▼
STOP ACCEPTING NEW REQUESTS
   │
   ▼
WAIT FOR ACTIVE REQUESTS
   │
   ▼
FLUSH TELEMETRY
   │
   ▼
CLOSE DB / CACHE / HTTP CONNECTIONS
   │
   ▼
Kernel terminate
   │
   ▼
EXIT

There should be a hard deadline:

graceful_shutdown_timeout = configurable

After the deadline:

force terminate

Otherwise a stuck request can prevent deployment indefinitely.

4.9 Deployment strategy

The deployment architecture should assume immutable application images.

Git commit
    │
    ▼
CI
    │
    ├── unit tests
    ├── integration tests
    ├── architecture tests
    ├── static analysis
    ├── security checks
    └── build image
          │
          ▼
       Registry
          │
          ▼
     Deployment
          │
          ▼
     New version
          │
          ▼
      Readiness
          │
          ▼
      Traffic shift
          │
          ▼
    Drain old version

This fits the repository's emphasis on deterministic infrastructure and its Anvil deployment layer.

4.10 Rollback

Rollback must not require rebuilding anything.

v1 ──────► v2
            │
            │ failure
            ▼
v1 ◄────────┘

The infrastructure should retain the previous image and configuration.

The application should additionally expose a version/build identifier:

{
  "service": "dglab",
  "version": "2026.09.24",
  "commit": "abc123"
}

That makes incident correlation considerably easier.

4.11 Observability

The architecture already places considerable emphasis on events/logging.

Production telemetry should be standardized around:

Request
 │
 ├── trace_id
 ├── request_id
 ├── worker_id
 ├── route
 ├── status
 ├── duration
 └── memory_delta

Then:

              ┌─────────────┐
              │ Application │
              └──────┬──────┘
                     │
          ┌──────────┼───────────┐
          ▼          ▼           ▼
       Logs       Metrics      Traces

The crucial addition for DGLab is worker-specific metrics:

worker_requests_total
worker_memory_bytes
worker_restarts_total
worker_fatal_errors_total
worker_request_duration

These aren't particularly useful in a short-lived FPM model, but they become first-class operational signals in a persistent-worker architecture.

4.12 Security boundaries

The deployment architecture should enforce:

Internet
   │
   ▼
TLS
   │
   ▼
Edge
   │
   ├── reject malformed traffic
   ├── request size limits
   ├── connection limits
   └── basic abuse protection
   │
   ▼
Application
   │
   ├── authentication
   ├── authorization
   ├── validation
   └── domain rules

Don't rely on the application WAF alone.

Conversely, don't put application authorization into Caddy/Tengine.

The rule should be:

Infrastructure protects infrastructure; application code protects application semantics.

4.13 Area 4 assessment

#Keep

• FrankenPHP persistent workers.
• Explicit Kernel lifecycle.
• Worker/request lifetime separation.
• Containerized/immutable deployment.
• Health/readiness concepts.
• Graceful shutdown.
• Worker recycling.
• Strong observability.

#Challenge

Tengine should be justified by an explicit requirement.

If it isn't providing a capability unavailable or undesirable in Caddy/FrankenPHP, the default production architecture should be:

Caddy → FrankenPHP

rather than:

Caddy → Tengine → FrankenPHP

That reduces operational complexity without changing the application architecture.

#New architectural requirements

INFRA-001  Persistent workers MUST support graceful recycling.

INFRA-002  Worker-scoped services MUST be request-state independent.

INFRA-003  Liveness MUST NOT depend on external databases.

INFRA-004  Readiness MUST prevent traffic reaching an unbooted worker.

INFRA-005  Deployment MUST support zero/low-downtime replacement.

INFRA-006  Rollback MUST select an existing immutable artifact.

INFRA-007  Worker memory/request/error metrics MUST be observable.

INFRA-008  Every reverse-proxy layer MUST have an explicitly documented responsibility.

Area 4 assessment: the runtime architecture is appropriate, but the three-tier proxy topology needs justification rather than being treated as inherently necessary.

At this point we've established:

1. Wheel architecture — fundamentally viable.
2. Runtime lifecycle — strong, particularly Fiber/request isolation.
3. Component/data boundaries — good direction, but Hub/persistence need formal contracts.
4. Infrastructure — persistent-worker model is coherent; proxy layering needs simplification/justification.

Next I'll : implemented vs partial vs blueprint vs architectural risk, .

you asked

Proceed

chatgpt response

The repository's strongest characteristic is that it has a real architectural kernel, not just a collection of PHP packages. The main issue is that the maturity of the implementation is uneven: runtime infrastructure is considerably ahead of the application/domain architecture.

#5.1 Implementation maturity matrix

The repository itself identifies the next major Core capabilities as DBAL, encryption, filesystem and cache, reinforcing that persistence/infrastructure isn't yet at the same maturity as the runtime.

5.2 Gap #1 — Architecture enforcement

This is the highest-leverage improvement.

The architecture currently says:

dependencies → inward

That should become a CI-enforced property.

#Proposed architecture test

                 ┌─────────────┐
                 │     UI      │
                 └──────┬──────┘
                        │
                 allowed ↓
                 ┌─────────────┐
                 │ Outer Spoke │
                 └──────┬──────┘
                        │
                 allowed ↓
                 ┌─────────────┐
                 │ Inner Rim   │
                 └──────┬──────┘
                        │
                 allowed ↓
                 ┌─────────────┐
                 │ Inner Spoke │
                 └──────┬──────┘
                        │
                 allowed ↓
                 ┌─────────────┐
                 │    Hub      │
                 └──────┬──────┘
                        │
                 allowed ↓
                 ┌─────────────┐
                 │    Core     │
                 └─────────────┘

Forbidden:
Core → Hub
Core → Spoke
Hub → UI
Hub → HTTP adapter
Domain → vendor SDK

The test should inspect Composer dependency graphs and PHP namespaces.

A contractor adding:

use App\Http\Controller\OrderController;

inside a Hub aggregate should fail CI.

5.3 Gap #2 — Composition root

Current application startup puts substantial wiring into public/index.php.

I'd introduce:

public/index.php
      │
      ▼
ApplicationFactory
      │
      ├── createContainer()
      ├── registerCore()
      ├── registerApplication()
      ├── registerAdapters()
      ├── registerRoutes()
      └── createKernel()

Then:

$application = ApplicationFactory::create();
$application->run();

The public entrypoint becomes infrastructure glue rather than the place where the architecture is assembled.

5.4 Gap #3 — Configuration needs explicit lifecycle semantics

Persistent workers make configuration fundamentally different from traditional PHP.

I recommend:

Environment
    │
    ▼
Configuration loader
    │
    ▼
Validated immutable Config
    │
    ▼
Container

Configuration should be immutable after boot.

Bad:

$config->set('database.host', $host);

Good:

$config->database()->host();

with immutable configuration objects.

This eliminates another category of cross-request mutation.

5.5 Gap #4 — Persistence architecture

When DBAL is implemented, I recommend ports and adapters, not a generic active-record layer.

                  DOMAIN
                    │
                    ▼
             UserRepository
                 interface
                    ▲
                    │
                    │ implements
                    │
           PostgreSQLUserRepository
                    │
                    ▼
                  DBAL
                    │
                    ▼
               PostgreSQL

The domain should never know whether persistence is:

• PostgreSQL
• MySQL
• SQLite
• an API
• an event store

unless the application's requirements explicitly demand such knowledge.

5.6 Gap #5 — Transaction ownership

A common mistake would be allowing repositories to silently own transactions.

I recommend:

Application Service
      │
      ├── BEGIN
      │
      ├── repository.load()
      │
      ├── aggregate.change()
      │
      ├── repository.save()
      │
      ├── domain events
      │
      └── COMMIT

This makes the application service the unit-of-work boundary.

For cross-aggregate operations, the service explicitly defines whether the operation is:

• one transaction,
• eventually consistent,
• or distributed.

5.7 Gap #6 — Domain events vs runtime events

This should become an explicit package-level boundary.

packages/core/events/
    Runtime events

packages/hub/domain/
    Domain events

packages/spokes/
    Integration events

The same PSR-14 mechanism can potentially carry all three, but their semantic ownership must remain separate.

That distinction will become extremely valuable when asynchronous processing is introduced.

5.8 Gap #7 — Asynchronous work

I don't recommend immediately introducing a queue just because the architecture has events.

Instead:

Synchronous application flow
          │
          ▼
      transaction
          │
          ▼
      commit
          │
          ▼
  integration event
          │
          ▼
      async queue

If integration events eventually become asynchronous, the system will need an outbox.

Recommended future structure:

┌─────────────────────────┐
│ Business transaction    │
│                         │
│ Aggregate               │
│ Domain state            │
│ Outbox event            │
└────────────┬────────────┘
             │ COMMIT
             ▼
       Outbox table
             │
             ▼
       Publisher worker
             │
             ▼
       Message broker
             │
        ┌────┴─────┐
        ▼          ▼
    Consumer A  Consumer B

This prevents:

DB COMMIT succeeds
      │
      ├── event publish fails ❌
      │
      └── system becomes inconsistent

5.9 Gap #8 — Error taxonomy

The current error handling foundation should evolve into a formal error taxonomy.

I'd define:

Throwable
   │
   ├── DomainException
   │
   ├── ApplicationException
   │
   ├── InfrastructureException
   │
   ├── AuthenticationException
   │
   ├── AuthorizationException
   │
   ├── ValidationException
   │
   └── HttpException

Then map these to HTTP responses centrally.

For example:

ValidationException      → 422
AuthenticationException  → 401
AuthorizationException   → 403
NotFound                 → 404
Conflict                 → 409
Unhandled exception      → 500

The exact API error format should be standardized before application services proliferate.

5.10 Gap #9 — Observability contract

Logging exists, but I recommend defining an application-wide structured event schema.

Every request should have:

{
  "trace_id": "...",
  "request_id": "...",
  "worker_id": "...",
  "method": "GET",
  "route": "/example",
  "status": 200,
  "duration_ms": 12.4
}

Then application events add:

{
  "event": "OrderCreated",
  "aggregate_id": "...",
  "trace_id": "..."
}

The trace ID should cross:

HTTP
 │
 ▼
Application service
 │
 ▼
DB
 │
 ▼
Event
 │
 ▼
External adapter

That is particularly important once the Spokes and Bridges become real.

5.11 Gap #10 — Testing strategy

The project should have four distinct testing layers.

                ┌──────────────────────┐
                │   Architecture tests │
                └──────────┬───────────┘
                           │
                ┌──────────▼───────────┐
                │   Integration tests  │
                └──────────┬───────────┘
                           │
                ┌──────────▼───────────┐
                │   Component tests    │
                └──────────┬───────────┘
                           │
                ┌──────────▼───────────┐
                │      Unit tests      │
                └──────────────────────┘

#Particularly important tests for DGLab

Persistent-worker tests

request A
  ↓
mutate request state
  ↓
request B
  ↓
assert no state leaked

Fiber concurrency tests

Fiber A ───────┐
               ├── Container
Fiber B ───────┘

Verify each gets independent pulse state.

Freeze tests

Attempt route/middleware mutation after freeze and verify deterministic failure.

Architecture tests

Verify namespace/package dependency rules.

Worker recycling tests

Verify graceful termination doesn't abandon active requests.

5.12 Gap #11 — Documentation governance

The existing ADR/blueprint system is ambitious.

The problem is status fragmentation.

I'd replace manually maintained implementation status with machine-generated status:

Blueprint
    │
    ▼
Metadata
    │
    ├── specified
    ├── scaffolded
    ├── implemented
    ├── tested
    └── production-ready

CI can then generate:

ARCHITECTURE_STATUS.md

instead of developers manually updating several documents.

This directly addresses the status inconsistencies already visible in the repository documentation.

5.13 Recommended target architecture

Putting Areas 1–5 together:

                         ┌───────────────────────┐
                         │      Caddy / Edge     │
                         └───────────┬───────────┘
                                     │
                              ┌──────▼──────┐
                              │ FrankenPHP  │
                              │  Workers    │
                              └──────┬──────┘
                                     │
                           ┌─────────▼─────────┐
                           │ ApplicationFactory │
                           └─────────┬─────────┘
                                     │
              ┌──────────────────────▼─────────────────────┐
              │                  Outer Rim                  │
              │          HTTP / CLI / presentation         │
              └──────────────────────┬─────────────────────┘
                                     │
              ┌──────────────────────▼─────────────────────┐
              │              Inner Spokes                  │
              │          Application services              │
              └──────────────────────┬─────────────────────┘
                                     │
              ┌──────────────────────▼─────────────────────┐
              │                    Hub                     │
              │ Domain / Aggregates / Ports / Events       │
              └───────────────┬───────────────┬────────────┘
                              │               │
                       repository             │
                           ports              │
                              │               │
               ┌──────────────▼──────┐       │
               │ Infrastructure      │       │
               │ DB/cache/files/etc. │       │
               └─────────────────────┘       │
                                              │
                                  ┌───────────▼───────────┐
                                  │ Bridges / Outer Spokes│
                                  │ external integrations │
                                  └────────────────────────┘

                         CORE sits underneath
                    all inward-facing abstractions

Overall architectural assessment so far

Across the five areas we've examined:

#My central conclusion

I would not replace the Wheel architecture.

I would evolve it into a more rigorously enforced architecture:

Immutable worker runtime + explicit request scope + inward dependency contracts + domain-owned state + infrastructure adapters + executable architecture rules.

That preserves the project's central architectural idea while removing the biggest sources of future coupling.

We've now gathered enough information to start assembling the requested document.

The remaining step is to convert these findings into the contractor-ready:

SPEC-001-DGLab-Sovereign-Stack-Architecture

with:

• Background
• MoSCoW requirements
• target architecture
• PlantUML component/dependency diagrams
• DI/request lifecycle
• persistence boundaries
• worker/concurrency model
• deployment architecture
• security/observability
• testing/architecture fitness functions
• concrete implementation steps
• milestones
• production evaluation criteria

I will also distinguish existing DGLab behavior from recommended target-state changes, so contractors don't mistake recommendations for functionality that already exists.

you asked

Proceed

chatgpt response

SPEC-001-DGLab-Sovereign-Stack-Architecture

DGLab is a PHP 8.4 monorepo/framework organized around a six-ring Wheel Architecture:

Outer Rim
   ↓
Outer Spokes
   ↓
Inner Rim
   ↓
Inner Spokes
   ↓
Hub
   ↓
Core

The repository already contains a substantial runtime Core implementing dependency injection, PSR HTTP abstractions, middleware, routing, events, configuration, logging, error handling, and Kernel lifecycle management. The application is designed for persistent FrankenPHP workers rather than traditional short-lived PHP-FPM processes.

The analysis identified a consistent architectural direction but also a maturity imbalance:

• Core/runtime infrastructure is considerably more mature than domain/application layers.
• Worker/request lifetime isolation is a central architectural concern.
• The six-ring dependency rule needs automated enforcement.
• Persistence and external integration boundaries require further implementation.
• public/index.php currently carries too much composition responsibility.
• The Caddy → Tengine → FrankenPHP topology should be justified by explicit operational requirements.
• Architecture documentation is extensive, but repository status can diverge from implementation.

The target architecture therefore retains the Wheel while making its boundaries executable, testable and suitable for contractor implementation.

#MUST

REQ-M01 — Six-ring dependency rule

Dependencies MUST flow inward according to the Wheel architecture.

UI
 ↓
Outer Spokes
 ↓
Inner Rim
 ↓
Inner Spokes
 ↓
Hub
 ↓
Core

Core MUST NOT depend on application layers.

Hub MUST NOT depend on HTTP, controllers or vendor-specific infrastructure.

REQ-M02 — Persistent-worker safety

All worker-scoped services MUST be independent of request-specific state.

Request state MUST be isolated by request/Fiber scope.

The system MUST test for cross-request state leakage.

REQ-M03 — Explicit dependency lifetimes

The DI system MUST distinguish:

• worker/singleton
• request/Fiber/pulse
• transient

Lifetime violations MUST be detectable through automated tests where practical.

REQ-M04 — Immutable runtime infrastructure

After application boot:

• middleware configuration MUST be frozen;
• routing configuration MUST be frozen;
• validated configuration MUST be immutable;
• worker-level service registration MUST NOT change during ordinary requests.

REQ-M05 — Application composition boundary

Application composition MUST be separated from the public HTTP entrypoint.

The target structure is:

public/index.php
       ↓
ApplicationFactory
       ↓
Kernel

REQ-M06 — Domain ownership

The Hub MUST own:

• entities;
• value objects;
• aggregates;
• domain services;
• domain events;
• repository interfaces.

Domain code MUST NOT directly access database drivers, caches, filesystem APIs or external SDKs.

REQ-M07 — Persistence ports

Persistence MUST use inward-facing repository contracts with outward-facing infrastructure implementations.

Domain Repository Interface
          ▲
          │
PostgreSQL Repository
          │
          ▼
         DBAL
          │
          ▼
      PostgreSQL

REQ-M08 — Transaction boundaries

Application services MUST explicitly define transaction boundaries.

Repositories MUST NOT silently create unrelated transaction scopes.

REQ-M09 — Error taxonomy

Application errors MUST have a defined mapping to HTTP/API responses.

At minimum:

Validation       → 422
Authentication   → 401
Authorization    → 403
Not Found        → 404
Conflict         → 409
Unhandled        → 500

REQ-M10 — Worker lifecycle

Workers MUST support:

• startup;
• readiness;
• graceful shutdown;
• graceful recycling;
• forced termination after shutdown deadline;
• worker health telemetry.

REQ-M11 — Health endpoints

The application MUST distinguish:

/health/live
/health/ready

Liveness MUST NOT require external databases or caches.

REQ-M12 — Observability

Requests MUST expose structured:

• request ID;
• trace ID;
• worker ID;
• route;
• status;
• duration;
• error information where applicable.

REQ-M13 — Architecture tests

CI MUST verify package/namespace dependency rules.

A component violating the Wheel MUST fail CI.

#SHOULD

REQ-S01 — Route compilation

Routes SHOULD be compiled/frozen during boot rather than dynamically modified during requests.

REQ-S02 — Domain/integration event separation

Runtime, domain and integration events SHOULD have separate ownership.

REQ-S03 — Outbox

If asynchronous integration events are introduced, an outbox pattern SHOULD be used.

REQ-S04 — Immutable deployment

Deployments SHOULD use immutable artifacts/images.

REQ-S05 — Worker recycling

Workers SHOULD support configurable recycling based on:

• maximum requests;
• maximum memory;
• maximum lifetime;
• fatal/consecutive failure thresholds.

REQ-S06 — Tengine optionality

Tengine SHOULD only exist in deployments where it provides a documented capability not adequately provided by the edge/runtime layer.

#COULD

REQ-C01

Support a simplified:

Caddy → FrankenPHP

deployment profile.

REQ-C02

Support an advanced:

Caddy → Tengine → FrankenPHP cluster

profile.

REQ-C03

Generate architecture-status documentation automatically from implementation metadata.

#WON'T

REQ-W01

The architecture will not introduce microservices merely because the Wheel contains multiple logical layers.

REQ-W02

The domain layer will not directly depend on vendor SDKs.

REQ-W03

Runtime events will not become an implicit replacement for explicit business orchestration.

Method

@startuml

actor Client

component Caddy
component Tengine
component FrankenPHP
component "Kernel" as Kernel
component "ApplicationFactory" as Factory
component "Middleware Pipeline" as MW
component Router
component Controller
component "Application Service" as Service
component Aggregate

Client --> Caddy

Caddy --> Tengine : optional
Tengine --> FrankenPHP

FrankenPHP --> Factory
Factory --> Kernel

Kernel --> MW
MW --> Router
Router --> Controller
Controller --> Service
Service --> Aggregate

Aggregate --> Service
Service --> Controller
Controller --> Router
Router --> MW
MW --> Kernel
Kernel --> FrankenPHP

@enduml

The default deployment SHOULD omit Tengine unless its operational responsibilities are explicitly required.

@startuml

component "Worker Container" as WC
component "Singleton Services" as S
component "Fiber Scope" as F
component "Transient Objects" as T

WC --> S
WC --> F
WC --> T

S --> "Router"
S --> "Event Dispatcher"
S --> "Configuration"
S --> "Logger"

F --> "Request"
F --> "Auth Context"
F --> "Request Metadata"

T --> "Short-lived Objects"

note bottom of S
Must NOT contain request state.
end note

@enduml

#Lifetime rules

Singleton
    ↓
Worker lifetime

Pulse/Fiber
    ↓
Request lifetime

Transient
    ↓
Resolution lifetime

A singleton that stores CurrentUser, request headers, request IDs or similar state is an architectural defect.

@startuml

package "Hub / Domain" {
    interface UserRepository
    class User
    class UserService
}

package "Infrastructure" {
    class PostgreSQLUserRepository
    class DBAL
    database PostgreSQL
}

UserService --> User
UserService --> UserRepository

PostgreSQLUserRepository ..|> UserRepository
PostgreSQLUserRepository --> DBAL
DBAL --> PostgreSQL

note right of UserRepository
Domain-owned port.
end note

@enduml

The database schema should be derived from actual domain aggregates rather than designed prematurely at the framework level.

Three semantic categories SHOULD be maintained:

Core
 └── Runtime events
      RequestReceived
      ResponseReady
      KernelBooted

Hub
 └── Domain events
      AggregateCreated
      EntityChanged
      BusinessOperationCompleted

Spokes/Bridges
 └── Integration events
      ExternalSystemUpdated
      NotificationRequested

The same underlying event infrastructure may be reused, but ownership and semantics remain distinct.

Where asynchronous processing becomes necessary:

@startuml

component "Application Service" as AS
database "Primary DB" as DB
database "Outbox" as O
component "Publisher" as P
queue "Message Broker" as Q
component "Consumer" as C
component "External System" as E

AS --> DB : transaction
AS --> O : same transaction

O --> P
P --> Q
Q --> C
C --> E

@enduml

The outbox ensures that committed domain state does not become inconsistent with an unsuccessfully published integration event.

CI SHOULD enforce rules such as:

Core → Core/PSR only

Hub → Hub + Core contracts

Inner Spokes → Hub + Core

Inner Rim → Inner Spokes + Hub + Core

Adapters → inward contracts + infrastructure

UI → application-facing interfaces

Forbidden:
Core → Hub
Core → UI
Hub → Controller
Hub → HTTP implementation
Hub → vendor SDK
Domain → database driver

This converts architectural intent into an executable constraint.

Implementation

1. Inventory every Core package.
2. Define public interfaces.
3. Freeze runtime APIs where required.
4. Add persistent-worker lifecycle tests.
5. Add Fiber isolation tests.
6. Add cross-request contamination tests.
7. Add route/middleware freeze tests.

#Deliverable

A Core that can safely run multiple requests through a persistent worker.

Create:

src/Application/ApplicationFactory.php

Responsibilities:

createContainer()
registerCore()
registerApplication()
registerInfrastructure()
registerRoutes()
registerMiddleware()
createKernel()

Reduce public/index.php to infrastructure entrypoint behavior.

Create domain packages according to bounded responsibilities.

Each domain should contain:

Domain/
  Entity/
  ValueObject/
  Aggregate/
  Service/
  Event/
  Repository/

No HTTP or infrastructure dependencies.

Implement DBAL.

Then implement application-specific repository adapters:

Hub Repository Interface
          ▲
          │
Infrastructure Repository
          │
          ▼
         DBAL

Add migrations and transaction handling.

Each Inner Spoke SHOULD correspond to a concrete use-case boundary.

Example:

CreateUser
AuthenticateUser
UpdateAccount
CreateOrder
CapturePayment

rather than generic "manager" classes.

For every external system:

Port
 ↓
Adapter
 ↓
Vendor SDK/API

Translate external DTOs/errors into internal representations.

Implement:

request_id
trace_id
worker_id
route
duration
status
exception
memory_delta

Provide structured logs and metrics.

Support initially:

Caddy
  ↓
FrankenPHP
  ↓
DGLab workers

Add Tengine only where a measurable requirement exists.

Implement:

• readiness;
• liveness;
• graceful shutdown;
• worker recycling;
• immutable artifact deployment;
• rollback.

CI pipeline:

@startuml

start

:Checkout;

:Install dependencies;

:Static analysis;

:Unit tests;

:Component tests;

:Integration tests;

:Architecture dependency tests;

:Persistent worker tests;

:Security checks;

if (all pass?) then (yes)
  :Build immutable artifact;
  :Publish artifact;
else (no)
  :Reject build;
endif

stop

@enduml

Milestones

Gathering Results

The architecture should be considered successfully implemented only when measurable criteria are met.

Test:

Request A → state mutation
Request B → verify clean state

Expected:

0 request-state leaks

Run the same test concurrently across multiple Fibers.

Measure separately:

cold worker startup
warm request latency
P50
P95
P99
throughput
memory/request
worker memory growth

The important persistent-worker metric is not merely latency.

It is:

memory growth per N requests

A worker whose memory continuously grows is not production-safe regardless of its initial throughput.

Test:

• database unavailable;
• cache unavailable;
• external API timeout;
• malformed HTTP request;
• controller exception;
• domain exception;
• worker termination;
• deployment during traffic;
• failed readiness;
• failed boot.

Expected behavior must be deterministic and documented.

Demonstrate:

v1 running
   ↓
deploy v2
   ↓
v2 becomes ready
   ↓
traffic moves to v2
   ↓
v1 drains
   ↓
v1 terminates

Then deliberately fail v2 and verify rollback to v1.

The final system should satisfy:

                 ┌─────────────────────────┐
                 │     Application/UI       │
                 └────────────┬────────────┘
                              │
                 ┌────────────▼────────────┐
                 │     Application Layer   │
                 └────────────┬────────────┘
                              │
                 ┌────────────▼────────────┐
                 │       Domain Hub        │
                 └────────────┬────────────┘
                              │
                    inward-facing ports
                              │
                 ┌────────────▼────────────┐
                 │    Infrastructure       │
                 └─────────────────────────┘

                 Core remains underneath
                 without knowing the domain.

The defining architectural test is therefore not whether DGLab contains six directories/rings. It is whether developers can add a new business capability without modifying Core, without leaking infrastructure into the domain, and without creating request-state contamination in the persistent worker.

That is the property I would use as the primary architecture acceptance criterion.

Please contact me at sammuti.com :)

you asked

From Z.ai:

Fully Analyze this against the repo.

Excellent — content finally landed. This is a 3-area architectural review from an external architect asking you to "Verify" each claim against the real DGLab repo. I'll do exactly that: cross-check every specific factual claim against the actual code/docs, flag what's accurate, what's outdated, what's wrong, and what's a defensible opinion.

Let me gather verification data in parallel. I have enough data. Writing the verification now.

Verification Report — DGLab Architecture Review

I cross-checked every specific factual claim in the architect's review against the actual repository at main HEAD (a4a3402). Verdict legend: ✅ Confirmed (matches repo) · ⚠️ Outdated (was true earlier, repo moved) · ❌ Wrong (doesn't match repo) · 💬 Opinion (engineering judgment, not a fact-checkable claim).

#Six-ring Wheel architecture

✅ Confirmed. README §"Architecture" shows the six rings verbatim (Outer Rim → Outer Spokes → Inner Rim → Inner Spokes → Hub → Core), and the inner-most ring is Core. INDEX.md declares itself "the single source of truth" for tier mapping.

#"Dependencies point inward"

✅ Confirmed. Sampled: App\Controller\HelloController imports SovereignStack\Core\Http\.... The Core packages (packages/core/*/src/) have zero use App\… or use SovereignStack\Hub\… imports. ADR-004 ("Tier enforcement DAG") codifies this.

#"Architecture is more mature than the application layer"

✅ Confirmed, and stronger than the architect stated. Current package distribution:

Core: 11 of 20 blueprints implemented (55%). Everything else: 4 of 81 (5%). The architect's "asymmetric Wheel" metaphor is exactly right.

#⚠️ "8 implemented Core packages" — OUTDATED

The architect said 8. Actual count is 11. The discrepancy is CORE-16 (Encryption, just merged in d0ab644), CORE-18 (Kernel), and CORE-19 (DBAL — has composer.json and source files at packages/core/dbal/src/). The README at line 30 also still claims "8 Core-tier packages" — same staleness vector.

#"README contains contradictory status statements"

✅ Confirmed, and worse than the architect flagged. Direct quotes from current README.md:

• Line 94: | 3 | CORE-18 (Kernel) | ✅ Complete — **5 of 8 Milestone 0 blueprints shipped** |
• Line 95: | 4 | HUB-01, BRIDGE-01, ISPOKE-09, ESPOKE-01 | ✅ Complete — **all 8 Milestone 0 blueprints shipped** |
• Line 115: "post-MUWV, Milestone 1 … MUWV flip was authorized on 2026-09-18 after all 8 Milestone 0 blueprints shipped"
• Line 211–214: HUB-01 ⬜ Not started / BRIDGE-01 ⬜ Not started / ISPOKE-09 ⬜ Not started / ESPOKE-01 ⬜ Not started
• Line 218: "public/index.php is still a 503 placeholder — the flip is NOT yet authorized"
• Line 200: "Pre-MUWV. … 5 of 8 blueprints shipped"

The README simultaneously claims (a) all 8 Milestone-0 blueprints shipped and the project is post-MUWV, (b) only 5 of 8 shipped and pre-MUWV, and (c) those 4 blueprints are "Not started" while also being "Complete." public/index.php is described as both a real implementation and a "503 placeholder." The architect's "documentation/state drift" finding is understated.

#Worker/request state separation (WeakMap<Fiber, …>)

✅ Confirmed. packages/core/container/src/Container.php lines 13, 65, 84 explicitly declare WeakMap<Fiber, array<string, mixed>> $pulseInstances and WeakMap<Fiber, …> $fiberResolving. Line 55: "WeakMap<Fiber, array<string, mixed>> — when a Fiber is garbage-collected, PHP automatically evicts its entries." ADR-017 ("Fiber-based cooperative runtime") is the binding ADR.

#Frozen infrastructure (router/middleware)

✅ Confirmed.

• Router.php line 19: private bool $frozen = false; line 49: $this->frozen = true; (after first match)
• MiddlewarePipeline.php line 14: "frozen after the first handle() call"; line 33: private bool $frozen = false; line 60: $this->frozen = true;

#PerRequestHandler

✅ Confirmed. packages/core/middleware/src/PerRequestHandler.php exists. The architect's claim that this "replaced the previous shared-cursor design" is consistent with the file's existence — though the previous design's removal happened before this HEAD.

#Explicit Kernel lifecycle (6 states)

✅ Confirmed. packages/core/kernel/src/KernelState.php:

Unbooted → Booting → Booted → Handling → Booted → Terminating → Terminated

Transitions strictly enforced via named constructors in KernelException.

#⚠️ "Kernel imposes boot/request/termination ceilings" — NOT in working tree

The architect's claim about resource ceilings (BOOTSTRAPPER_COUNT_CEILING, BOOT_AGGREGATE_TIMEOUT_SECONDS, etc.) does not match what's at HEAD. I grepped packages/core/kernel/ for CEILING, TIMEOUT, bootstrapper count — zero hits. However, git log --all -- packages/core/kernel/ shows:

0bf0703 feat(kernel): add resource ceilings per doctrine §4.5.5 (P3) (#253)
709a0a2 feat(kernel): add KernelLifecycleRecord audit feed per doctrine §4.5.6 (#256)
291d929 test(kernel): add 2 missing chaos tests … (#257)

These commits exist on some ref but are not on the linear HEAD history (HEAD is a4a3402 c47a40bb-…, a GUID-named commit above the proper feat(crypto) commit d0ab644). So either (a) the work was merged and then squashed/replayed out of the linear history, or (b) it lives on a feature branch not yet merged. Either way, the working tree the architect reviewed doesn't contain them.

#⚠️ "Kernel records lifecycle events" — NOT in working tree

Same situation. KernelLifecycleRecord.php does not exist at packages/core/kernel/src/. The architect's claim is consistent with the doctrine §4.5.6 intent, but the file isn't there.

#"JWT/rate-limiting/audit are pass-through stubs"

✅ Confirmed verbatim. public/index.php line 24–25:

"JWT verification, rate limiting, and HUB-06 audit are pass-through stubs. When HUB-02/HUB-04/HUB-06 land, the stubs are replaced — the chain order and public/index.php are unchanged."

#public/index.php is doing too much (composition-root critique)

✅ Confirmed. 274 lines, directly constructs: Container, ConfigRepository, ErrorHandler + PlainTextRenderer, EventDispatcher + ListenerProvider, Logger, Vanguard + ContractRegistry + WafInspector + DefaultDtoTransformer, ResponseFactory, Kernel + 5 factory closures, anonymous bootstrapper class, 2 Route instances, 2 controller bindings. This is exactly what the architect describes. The "Outer Rim is currently also a composition root" finding is accurate.

#Area 1 net verdict

Confirmed with two important corrections: (1) Core package count is 11, not 8. (2) The Kernel ceilings + lifecycle record feature, although nominally merged in PRs #253/#256/#257, is not present in the working tree at HEAD — either it's on an unmerged branch or got squashed out. The architect should be told. The architectural-direction claims (worker/Fiber model, frozen infra, dependency inwardness, README drift) are all solid.

#Boot sequence diagram

✅ Confirmed. public/index.php follows exactly: Container → EventDispatcher/Logger/ErrorHandler → container.instance() bindings → Vanguard construction → Kernel construction with bootstrappers → Kernel::boot(). Boot is once-per-worker (the file documents FrankenPHP worker-mode behavior at lines 17–21).

#Container three lifetimes

✅ Confirmed. Container.php exposes: bind() (with $singleton flag for worker scope), pulse() (line 134 — Fiber/WeakMap-backed), and transient (default make() behavior). The architect's table is accurate.

#RULE-DI-001 (singleton must not retain request-derived state)

💬 Sound recommendation, not yet enforced. The container provides the mechanism (pulse() exists precisely so request state doesn't bleed into singletons), but I find no automated fitness function / architecture test that enforces "singletons must not store User $currentUser" patterns. The architect's call to make this a CI test is on point.

#PerRequestHandler (one cursor per request)

✅ Confirmed. packages/core/middleware/src/PerRequestHandler.php exists. The architect's diagram of "Request A → Cursor A, Request B → Cursor B (not shared)" matches the design intent.

#Middleware classification (GLOBAL/REQUEST/RESPONSE/ERROR)

💬 Sound recommendation, currently absent. I see no middleware classification enum or interface in packages/core/middleware/src/. The pipeline just accepts ordered middleware. As middleware grows, the implicit ordering knowledge problem the architect describes will materialize.

#Router frozen after first match

✅ Confirmed (see Area 1 above).

#Route compilation during boot

💬 Sound recommendation, partially implemented. packages/core/router/src/CompiledRoute.php and RouteCompiler.php exist — so compilation does happen. Whether it's during boot vs lazy on first match I'd need to trace further, but the architect's recommendation is already partially in code.

#Controllers as adapters

💬 Sound recommendation, current code is clean. HelloController and HealthController are 30-ish lines each, do only: parse request → return Response. No DB, no validation, no business rules. The pattern the architect advocates is already being followed — the recommendation is to keep it that way as complexity grows.

#Event lifecycle (RequestReceived → Middleware → Controller → ResponseReady)

✅ Confirmed as designed. packages/core/kernel/src/Event/ directory exists. public/index.php and HttpBootstrapper wire listeners for these. The architect's distinction between framework/runtime events vs. domain events vs. integration events is a recommendation, not yet a code-level separation.

#Failure paths

💬 Sound recommendation, partially implemented. public/index.php lines ~158–180 wrap Kernel::handle() in try/catch and emit a 500 PSR-7 response. The "every failure must become a controlled HTTP response" contract is mostly there for the entry-point layer. What's missing: a formal contract that no exception escapes the worker — the current try/catch is in public/index.php, not in Kernel::handle() itself, so a bug in the handler's finally block could still escape.

#State contamination across requests

💬 The most important recommendation in the whole review. This is the single highest-leverage thing the architect flagged. Long-running FrankenPHP workers + accidental singleton state = subtle cross-request data leakage. The infrastructure exists (pulse() + WeakMap), but no architecture test enforces the invariant. This should become a P0 architectural fitness function.

#Area 2 net verdict

Confirmed with all 8 hardening requirements valid. The runtime lifecycle is sound as designed. The architect's recommendations (ApplicationFactory, RULE-DI-001 + automated test, middleware classification, route compile-at-boot, thin controllers, events-for-observability-not-orchestration, contamination tests, failure-contract spec) are all reasonable next steps. None are urgent blockers for current walking skeleton, all become urgent as soon as auth/cache/db arrive.

#"8 implemented Core packages"

⚠️ Outdated — actual is 11. See Area 1.

#"31 Hub blueprints"

✅ Confirmed. Architecture/Hub/ has 31 blueprints (HUB-01..HUB-31 per INDEX.md). Only HUB-30 has a package implementation (packages/hub/config/). The architect's "Hub early/scaffolded" verdict is correct — actually even more lopsided than the 1/31 ratio suggests, since the one Hub package is itself only at depth 1–2.

#"45 Spoke blueprints"

❌ Slightly wrong. Per INDEX.md: Spoke = 27 Internal (ISPOKE-01..27) + 18 External (ESPOKE-01..18) + 1 Bridge (BRIDGE-01) = 46 Spoke blueprints, not 45. The architect likely rounded down. Minor, but the README's "105 component blueprints" is also wrong — actual canonical count is 102 (20 Core + 31 Hub + 46 Spoke + 5 Deploy).

#"19 ADRs"

❌ Wrong — actual is 20. Architecture/ADRs/ contains ADR-001..ADR-020 (with ADR-011 marked "Proposed" not "Accepted"). The README also claims 19; both are off by one. Worth a doc fix.

#"Hub = aggregates, not database models"

💬 Sound recommendation. The README's terse "Aggregates" label for Hub is genuinely underspecified. The architect's proposed Hub definition (entities + value objects + aggregates + domain services + domain events + repository interfaces) matches DGLab's own INDEX.md intent and standard DDD practice. Worth promoting to a formal governance doc.

#"Repository ports should be in domain layer, implementations outward"

💬 Sound and aligns with the existing Wheel. ADR-004 (Tier enforcement DAG) already mandates dependency inwardness; the architect's recommendation is the DDD specialization of that. Currently no Hub code has repository ports (because no Hub is implemented at depth ≥ 2), so this is forward-looking guidance, not a correction.

#"Don't prematurely design tables until CORE-19/Hub land"

💬 Strongly agree. The README explicitly defers persistence architecture to CORE-19 (DBAL) + CORE-15 (Cache) + CORE-14 (Filesystem) + CORE-16 (Encryption). ⚠️ But CORE-16 has now landed (the architect's review predates the crypto merge). So three persistence packages remain: CORE-19, CORE-15, CORE-14. The architect's caution against premature schema design stands.

#"105 blueprints and 19 ADRs while implementation concentrated in Core"

✅ Confirmed pattern, with corrected numbers (102 blueprints, 20 ADRs). The "architecture-by-blueprint" risk is real. INDEX.md is honestly self-aware about this — it explicitly states "this index is correct and the other document is stale" and tracks an "implementation depth" field separately from blueprint existence. But the architect's call for automated architecture tests (ring-boundary import checks in CI) is the missing piece. The repo has a .github/workflows/ directory; I'd recommend adding a PHPStan-based rule that flags use SovereignStack\Core\… from inside SovereignStack\Hub\… (which already wouldn't happen, but make it enforceable).

#"Six rings should become six dependency contracts"

💬 Strongest single recommendation in the review. Turning "dependencies point inward" from a documentation principle into a CI-enforced contract is the highest-leverage architectural move available. Currently ADR-004 asserts the DAG; nothing verifies it automatically. This would close the gap between "architecture on paper" and "architecture in code."

#Area 3 net verdict

Confirmed with corrections. The component/data analysis is largely accurate. Three numbers need fixing: 8→11 Core packages, 45→46 Spoke blueprints, 19→20 ADRs (and 105→102 total blueprints). The forward-looking recommendations (Hub-as-domain-boundary, repository ports inward, automated ring-boundary tests, no premature schema) all align with the repo's own stated direction.

The architect's review is architecturally sound and directionally accurate. Three categories of correction:

A. Stale numbers (fix in the architect's final SPEC):

• 8 Core packages → 11 (CORE-16 Encryption merged; CORE-18 Kernel and CORE-19 DBAL also have implementations)
• 19 ADRs → 20 (ADR-020 exists)
• 45 Spoke blueprints → 46 (INDEX says 27 + 18 + 1 = 46)
• 105 total blueprints → 102 (per INDEX canonical count)
• "CORE-16 next persistence package" → already implemented (PR #260)

B. Working-tree vs merged-commit divergence (investigate):

• PRs #253 (resource ceilings), #256 (KernelLifecycleRecord), #257 (chaos tests) exist in git log --all but their content is not in the working tree at HEAD a4a3402. The architect's "Kernel imposes boot/request/termination ceilings" and "records lifecycle events" claims match the intent of those PRs but not the current HEAD state. Either the work needs to be re-merged, or HEAD needs to be advanced to a ref that contains them.

C. README contradictions (the architect's biggest finding, and it's worse than flagged):

• The README simultaneously says (i) all 8 Milestone-0 blueprints shipped + post-MUWV, (ii) 5 of 8 + pre-MUWV, (iii) HUB-01/BRIDGE-01/ISPOKE-09/ESPOKE-01 are "Not started", (iv) public/index.php is a "503 placeholder" while shipping a 274-line working implementation. The architect's call for "a single machine-verifiable architecture status source" is the most important documentation fix available.

Top 3 recommendations I'd prioritize from the architect's list, ordered by leverage:

1. Automated ring-boundary architecture tests in CI — turns "dependencies point inward" from documentation into enforceable contract. Highest leverage, lowest effort.
2. Singleton state-contamination fitness function — RULE-DI-001 as an actual test that scans worker-scoped services for request-derived state fields. This is the failure mode that will bite hardest under FrankenPHP workers + multi-tenant auth.
3. Single machine-verifiable status source — replace the contradictory README tables with a YAML/JSON status file that CI checks against actual packages/ directory state. Closes the drift the architect flagged.

When you send Area 4 (Infrastructure & Deployment — Anvil), I'll verify that against the live Anvil trio config (anvil/lib/, Caddyfile, Tengine conf, FrankenPHP worker directive).

Verifying Areas 4 + 5 against the live repo. Same protocol — every specific factual claim cross-checked against actual code/config. I have enough data. Writing the verification now.

Verification Report — Areas 4 & 5

Same protocol — every specific factual claim cross-checked against the actual repo. Verdict legend: ✅ Confirmed · ⚠️ Outdated/Partial · ❌ Wrong · 💬 Sound Opinion · ✅❌ Partially Right (claim has both true and false elements).

#Caddy → Tengine → FrankenPHP topology

✅ Confirmed. All three tiers exist with real configs:

• anvil/edge/Caddyfile (Caddy 2.11.4, TLS edge)
• anvil/lb/tengine.conf (Tengine 3.2.0, internal LB)
• anvil/app/Caddyfile.blue + Caddyfile.green (FrankenPHP worker config — blue/green template)
• anvil/systemd/[email protected] (template unit, %i = blue|green)
• anvil/systemd/anvil-tengine.service + anvil-caddy.service

Boot order is enforced by systemd dependencies: anvil-secrets → anvil-frankenphp@blue → anvil-tengine → anvil-caddy.

#"What architectural responsibility does each proxy uniquely provide?"

✅❌ Partially right. The architect's challenge is valid in principle (every layer should justify itself), but the premise that "if Tengine merely forwards HTTP, it adds a network hop for no benefit" is factually wrong about this repo. Tengine has six documented, non-trivial responsibilities in tengine.conf:

The architect's "default to Caddy → FrankenPHP, only enable Tengine when justified" recommendation is sound as a general principle, but for this specific repo, Tengine's role is already justified and documented. The challenge should be retracted or restated as "Tengine's six responsibilities should be made into INFRA-008 documented requirements" rather than "Tengine might be removable."

#Caddy's role

✅ Mostly confirmed, with one error. The architect said Caddy handles "coarse rate limiting." Wrong. The Caddyfile comment line 6 explicitly says: "rate limiting lives at the Tengine tier where limit_req is built in" — Caddy has no rate limiting by design (plugin-free binary, auditable CVE floor). Caddy's actual roles: TLS termination, ACME cert management, on-demand TLS for tenant vhosts, security headers (HSTS/X-Content-Type-Options/X-Frame-Options/Referrer-Policy), HTTP/3 + HTTP/2, JSON access logs to journald, reverse-proxy to Tengine with health-gated fail-fast (/_anvil/ping).

#Worker recycling

✅ Already implemented. The architect recommended MAX_REQUESTS_PER_WORKER etc. Actual config:

• anvil/app/Caddyfile.blue line: max_requests 500 (production)
• anvil/dev/Caddyfile.dev: max_requests 1000 (dev)
• anvil/app/Caddyfile.blue: php_ini "memory_limit" "256M" (memory ceiling)
• max_consecutive_failures referenced in ReImplementation_Instruction.md (FrankenPHP built-in)
• systemd Restart=on-failure, RestartSec=2s (restart policy)

So 3 of 4 thresholds the architect proposed are already enforced; MAX_WORKER_LIFETIME (time-based, not request-count-based) is not yet set.

#Health checks

✅❌ Partially right. The architect proposed three tiers: /health/live, /health/ready, dependency health. The repo currently has:

• GET /health (single endpoint, in public/index.php + HealthController) — HUB-15 contract per verify.sh
• /_anvil/ping (Tengine→Caddy internal health)
• Tengine check_status rise>=2 (verifies upstream)
• Caddy health_uri /_anvil/ping, health_interval 10s, health_timeout 2s, health_status 200

So liveness and readiness are conflated into a single /health — the architect's three-tier split is a valid gap. The current /health doesn't distinguish "worker alive" from "ready to receive traffic" from "dependencies healthy." The recommendation to split is sound.

#Graceful shutdown

✅ Implemented via systemd. The architect's SIGTERM sequence maps directly onto existing config:

• KillSignal=SIGTERM (matches "STOP ACCEPTING")
• TimeoutStopSec=30s (matches "graceful_shutdown_timeout = configurable")
• Restart=on-failure, RestartSec=2s
• FrankenPHP worker doc: "Let in-flight Fibers finish during deploys" (matches "WAIT FOR ACTIVE REQUESTS")

The "FLUSH TELEMETRY" step is not yet explicit — no telemetry flush hook in the Kernel terminate path. Minor gap.

#Deployment strategy (immutable images, blue/green)

✅ Fully implemented. [email protected] is a systemd template unit (%i = blue|green). anvil/lib/deploy.sh orchestrates green-startup → smoke-test → traffic-shift → blue-drain. This is canonical blue/green. The architect's "immutable application images" recommendation aligns with the existing pattern (deploy.sh + __ANVIL_CURRENT_SYMLINK__ symlink swap).

#Observability

✅ Largely implemented. FrankenPHP admin API exposes /frankenphp/threads and /metrics (Prometheus format). anvil/lib/frankenphp.sh parses frankenphp_total_threads and frankenphp_busy_threads. Tengine logs upstream timing. Caddy emits JSON access logs to stdout/journald. The architect's recommended metrics map onto existing ones:

So the metrics exist in some form, but they're scattered across three systems (FrankenPHP /metrics, Tengine access log, systemd journal). The architect's call for standardized worker-specific metrics is reasonable — what's missing is unified correlation, not raw data.

#Security boundaries

✅ Architecturally sound and implemented. The "infrastructure protects infrastructure; application code protects application semantics" rule is exactly what's deployed:

• Caddy: TLS, HSTS, X-Frame-Options, Referrer-Policy, cert management
• Tengine: rate limiting, request size limits (client_max_body_size 25m), real-IP trust
• FrankenPHP: NoNewPrivileges=true, ProtectSystem=strict, ProtectHome=true, PrivateTmp=true, RestrictAddressFamilies, SystemCallArchitectures=native (systemd hardening)
• App: ADR-008 Argon2id, ADR-003 ES256 JWT, ADR-013 datastore choice

#INFRA-001 through INFRA-008 requirements

Status against existing repo:

6 of 8 already met, 2 partial. The architect's INFRA requirements are largely restating what the repo already does.

#Area 4 net verdict

Confirmed with one important correction: The Tengine "challenge" is overstated. Tengine has six concrete documented responsibilities (slow-client shielding, rate-limiting, real-IP restoration, upstream-timing logs, DYUPS blue/green routing, on-demand TLS gate). The recommendation should be reframed as "Tengine's six responsibilities should be promoted from comments to INFRA-008 documented requirements" — not "consider removing Tengine."

Everything else (worker recycling, blue/green deploy, graceful shutdown, security boundaries, INFRA requirements) is largely already implemented. The genuine gaps the architect identifies are: (1) three-tier health split (liveness/readiness/dependency), (2) explicit telemetry flush on shutdown, (3) unified metric correlation across Caddy/Tengine/FrankenPHP/systemd.

#Implementation maturity matrix

✅❌ Mostly correct, two outdated cells.

#Gap #1 — Architecture enforcement

✅ Genuine gap, partially filled. The repo HAS an architecture-lint.yml workflow + Architecture/Verification/lint/run.php. But its scope is explicitly limited to 3 checks:

1. Reference existence (every CORE-/HUB-/ISPOKE-... token in a blueprint is a valid ID)
2. Misattribution phrases (two historically-wrong phrasings forbidden)
3. Structural completeness (every expected blueprint file exists)

The workflow's own comment says: "Do not assume broader coverage (Pulse consistency, naming drift, Soft-Freeze, blueprint-fidelity) is enforced here yet; those are cooldown-expansion targets."

It does NOT enforce ring-boundary import rules — the architect's specific recommendation (Hub importing App\Http\Controller\OrderController should fail CI) is not implemented. The recommendation is valid.

#Gap #2 — ApplicationFactory (composition root)

✅ Genuine gap. No ApplicationFactory class exists anywhere in the repo. public/index.php (274 lines) does direct construction of: Container, ConfigRepository, ErrorHandler + PlainTextRenderer, EventDispatcher + ListenerProvider, Logger, Vanguard + ContractRegistry + WafInspector + DefaultDtoTransformer, ResponseFactory, Kernel + 5 factory closures, anonymous bootstrapper, 2 Route instances, 2 controller bindings. The architect's recommendation to extract this into ApplicationFactory is valid and would close a real coupling concern.

#Gap #3 — Configuration lifecycle (immutable)

❌ Already implemented. The architect's recommendation:

"Configuration should be immutable after boot. Bad: $config->set('database.host', $host). Good: $config->database()->host() with immutable configuration objects."

The repo already does this:

• packages/core/config/src/ConfigBuilder.php line 31: private bool $frozen = false; line 64: $this->frozen = true; — builder freezes after build()
• packages/core/config/src/ConfigRepository.php line 13: "worker's lifetime. The backing array is marked readonly at construction" line 31: private readonly array $data,
• ConfigBuilderInterface line 16: "After build() is called, the builder is frozen — further mutations throw"

This gap is already closed in code. The architect should be told.

#Gap #4 — Persistence architecture (ports and adapters)

💬 Forward-looking, not yet applicable. No Hub-level repository ports exist (because Hub is 1 of 31 implemented). CORE-19 DBAL is at depth 1 with infrastructure primitives (Connection, Driver, QueryBuilder) but no domain-side port interfaces. The recommendation is sound when Hub domain components arrive.

#Gap #5 — Transaction ownership by application services

💬 Forward-looking, not yet applicable. No application services exist yet. The recommendation is sound.

#Gap #6 — Domain events vs runtime events separation

✅ Genuine gap. Single PSR-14 EventDispatcher exists in packages/core/event-dispatcher/. No package-level separation between:

• Runtime events (RequestReceived, ResponseReady, KernelBooted) — currently in packages/core/kernel/src/Event/
• Domain events (UserRegistered, OrderCreated) — none exist yet (no Hub)
• Integration events (UserRegistered.v1) — none exist yet (no Bridges)

The architect's recommendation to keep these semantically separate at the package level is sound. Currently they all share one dispatcher.

#Gap #7 — Asynchronous work / outbox

✅ Genuine gap. No outbox pattern visible. No queue infrastructure. Forward-looking — valid when integration events arrive.

#Gap #8 — Error taxonomy

✅ Genuine gap, partially filled. Many exception classes exist per-package:

packages/core/kernel/src/KernelException.php
packages/core/container/src/NotFoundException.php
packages/core/container/src/CircularDependencyException.php
packages/core/event-dispatcher/src/Exception/{EventDispatchException,ListenerRegistrationException}.php
packages/core/config/src/Exception/{MissingConfigurationException,InvalidEnvFileException,InvalidConfigFileException,UndefinedInterpolationException}.php
packages/core/router/src/Exception/{RouteNotFoundException,MissingRouteParameterException,InvalidRoutePatternException,DuplicateRouteNameException}.php
packages/core/crypto/src/CryptoException.php
packages/core/dbal/src/DatabaseException.php
packages/spoke/internal/codex/src/DocumentNotFoundException.php
packages/hub/config/src/{UnknownFlagException,InvalidOverrideKeyException}.php

But there's no unified taxonomy — no DomainException, ApplicationException, InfrastructureException, AuthenticationException, AuthorizationException, ValidationException, HttpException base classes. The architect's recommendation to formalize this taxonomy before application services proliferate is valid and well-timed.

#Gap #9 — Observability contract (trace_id)

❌ Genuine gap, confirmed. I grepped packages/ for trace_id, correlation_id, x-request-id — zero hits in application code. Tengine logs $sent_http_x_request_id (it propagates the header) but no application code reads or sets it. No correlation ID is generated, propagated through the request lifecycle, or attached to logs.

This is a real gap. The architect's recommendation to standardize {trace_id, request_id, worker_id, method, route, status, duration_ms} as the request log schema is sound and would close a real observability hole.

#Gap #10 — Testing strategy (4 layers)

✅❌ Partially exists.

• ✅ Unit tests: packages/core/*/tests/Unit/ (multiple packages)
• ✅ Integration tests: packages/core/kernel/tests/Integration/ (HelloWorld round-trip)
• ⚠️ Architecture tests: Architecture/Verification/lint/run.php exists but only 3 basic checks (see Gap #1)
• ❌ Component tests: no explicit component-test layer distinguished from integration

The architect's recommendation to formalize 4 distinct layers is reasonable. The persistent-worker state-contamination tests and Fiber concurrency tests the architect proposes specifically do NOT exist — these are the highest-value additions.

#Gap #11 — Documentation governance (machine-generated status)

✅ Genuine gap, confirmed. The README contradictions flagged in Area 1 (line 95 says "all 8 Milestone 0 blueprints shipped" while lines 211–214 say "Not started") are direct evidence. No CI-generated ARCHITECTURE_STATUS.md exists. The repo relies on manual maintenance of README, INDEX.md, FROZEN-CONTRACTS.md, worklog, ADRs — which is exactly what produced the drift.

The architect's recommendation to have CI generate ARCHITECTURE_STATUS.md from actual packages/ directory state is the highest-leverage documentation fix available.

#Area 5 net verdict

Confirmed with two corrections:

1. Persistence/Encryption cell is outdated. CORE-16 Encryption is now at depth 2 (8 source files, full nuclear-grade crypto: AES-256-GCM + Argon2id + HKDF-SHA256 + sodium_memzero + SensitiveParameterValue + versioned envelope). CORE-19 DBAL has basic infrastructure. The "not mature" verdict applied 2 weeks ago; now it's "Encryption mature, Cache/Filesystem pending, DBAL basic."

2. Gap #3 (Configuration immutability) is already closed. ConfigBuilder freezes after build(), ConfigRepository has readonly array $data. This isn't a gap — it's done.

The other 9 gaps are genuine. Ordered by leverage:

1. Gap #11 (machine-generated status) — closes the README drift, cheapest fix
2. Gap #1 (ring-boundary CI tests) — turns Wheel from documentation into contract
3. Gap #9 (trace_id propagation) — single biggest observability hole
4. Gap #2 (ApplicationFactory) — composition-root cleanup before Hub arrives
5. Gap #8 (error taxonomy) — clean evolution before too many exception classes proliferate
6. Gap #10 (4-layer testing + contamination tests) — defensive against the persistent-worker bug class
7. Gap #6 (event category separation) — clean evolution before too many events accumulate
8. Gap #7 (outbox) — when async arrives
9. Gaps #4/#5 (ports/adapters, transaction ownership) — when Hub arrives

Area 4: The deployment architecture is more mature than the architect credits. Tengine is not a redundant layer — it has six documented responsibilities, all of which Caddy explicitly defers to it. Worker recycling (max_requests 500), blue/green deployment (systemd template unit), graceful shutdown (SIGTERM + TimeoutStopSec=30s), and security hardening (systemd ProtectSystem=strict etc.) are all already implemented. The genuine gaps are: (1) three-tier health split, (2) explicit telemetry flush, (3) unified metric correlation, (4) INFRA-002 fitness function (the same one flagged in Area 2).

Area 5: The gap analysis is largely accurate but two cells are outdated:

• "Persistence/Encryption not mature" → Encryption is now mature, DBAL is basic
• "Configuration immutability is a gap" → Already implemented (ConfigBuilder frozen + readonly array)

The architect's single best recommendation is Gap #11 (machine-generated ARCHITECTURE_STATUS.md) — this directly closes the README contradiction drift flagged in Area 1. The second best is Gap #1 (ring-boundary CI tests) — this turns the Wheel from a documentation principle into an enforceable contract.

Before the architect writes SPEC-001-DGLab-Sovereign-Stack-Architecture (Area 6), tell them:

1. Update the maturity matrix: Encryption = depth 2 (not "not mature"), DBAL = depth 1 (basic). Core package count = 11 (not 8). ADRs = 20 (not 19). Blueprints = 102 (not 105).
2. Retract or reframe the Tengine challenge. Tengine has six documented responsibilities; the challenge as written ("if Tengine merely forwards HTTP") is factually wrong about this repo. Reframe as "promote Tengine's six responsibilities from comments to INFRA-008 documented requirements."
3. Mark Gap #3 (config immutability) as already closed in the SPEC's gap analysis.
4. Distinguish existing DGLab behavior from target-state recommendations explicitly. The architect's own Area 6 commitment to do this is correct — but it matters most for: (a) INFRA requirements (6 of 8 already met), (b) blue/green deploy (already done), (c) worker recycling (already done), (d) config immutability (already done). Without this distinction, contractors will rebuild existing infrastructure.

When you send Area 6 (final SPEC), I'll verify its MoSCoW requirements against actual repo capabilities before you commit to it.

chatgpt response

Yes. This external review materially changes the earlier SPEC in several places. The key point is that Z.ai's verification is not merely agreeing with the architecture review—it identifies where the review was stale versus the current repository HEAD.

#What I would change in our architecture baseline

#The most important correction

I would not carry the previous SPEC forward unchanged.

The new baseline should explicitly distinguish:

Already implemented

• Wheel dependency direction
• Fiber/pulse request isolation mechanism
• frozen router/middleware
• Kernel lifecycle
• immutable configuration
• encryption
• basic DBAL
• Tengine responsibilities
• worker recycling
• graceful shutdown
• blue/green deployment
• infrastructure security hardening
• basic architecture linting

Architecture hardening to implement

• executable ring-boundary dependency tests
• singleton/request-state contamination tests
• ApplicationFactory
• request/trace correlation
• unified error taxonomy
• runtime/domain/integration event separation
• stronger health semantics
• unified observability
• machine-generated architecture status
• outbox when asynchronous integration is introduced

Future architecture

• mature Hub/domain model
• repository ports/adapters
• application transaction ownership
• cache/filesystem
• integration adapters
• asynchronous messaging

#One especially important finding

The README/state inconsistency should become an explicit architecture-governance problem, rather than just a documentation cleanup.

The repository apparently has several authoritative-looking artifacts—README, INDEX, ADRs, blueprints, worklog, implementation—and they can disagree.

I'd therefore change the architecture principle to:

Architecture status must be derived from executable repository state wherever technically possible; manually maintained documents may describe intent, but cannot be authoritative about implementation status.

That is more fundamental than fixing individual README lines.

#Tengine also needs correcting

I agree with Z.ai that our previous framing was too aggressive.

The right architecture question isn't:

"Can we remove Tengine?"

It's:

"Are Tengine's six responsibilities explicit, tested, observable, and independently justified?"

Given the reported implementation—rate limiting, buffering/slow-client protection, real-IP handling, upstream timing, DYUPS routing, and the TLS authorization gate—Tengine is currently an intentional architectural component rather than redundant proxying.

The repository is actually in a fairly interesting state:

The infrastructure/runtime architecture is substantially ahead of the application/domain architecture.

So the next phase shouldn't be "build the architecture."

It should be:

Turn the existing architecture into enforceable contracts, then build the missing application/domain layers without weakening those contracts.

That gives us a much cleaner SPEC.

#Proposed next step

Before rewriting the final SPEC, I suggest we now do one focused verification pass on the actual repository dependency graph and package boundaries.

I want to establish, from the code rather than the documentation:

1. Exactly which namespaces/packages currently depend on which other packages.
2. Whether the six-ring rule is actually violated anywhere today, including indirect Composer dependencies.

If you approve, I'll take that as the next area and present only the dependency-boundary findings for confirmation.

you asked

Proceed https://github.com/DGCodeIdeas/DGLab is public

chatgpt response

I checked the public main branch directly, including the root Composer manifest, dependency inventory, architecture linter, and repository structure. (GitHub)

#1. The six-ring model is real

The repository explicitly defines:

Outer Rim → Outer Spokes → Inner Rim → Inner Spokes → Hub → Core

and states that inner rings must not import outer rings. (GitHub) The root Composer manifest also reflects a separation between:

• SovereignStack\Core\...
• SovereignStack\Hub\...
• SovereignStack\Bridge\...
• SovereignStack\Internal\...
• SovereignStack\External\...
• App\...

with local packages discovered through Composer path repositories. (GitHub) Finding: ✅ Architectural boundary exists.

#2. But Composer does NOT currently enforce the six-ring boundary

This is the important distinction.

The architecture linter is currently concerned with blueprint governance, not PHP dependency direction.

Its three checks are:

1. component-reference existence
2. blueprint identity/misattribution
3. blueprint structural completeness

There is no namespace/import analysis in the linter. (GitHub) So this hypothetical violation:

namespace SovereignStack\Hub\Order;

use App\Controller\OrderController;

would not be rejected by architecture-lint merely because it violates the Wheel.

Likewise, a Core class importing a Hub class would not be caught by the current architecture linter.

Finding: ⚠️ The architecture is documented, but not yet mechanically enforced at the PHP dependency level.

This validates Z.ai's strongest recommendation.

#3. The root package currently has an architectural ambiguity

The root composer.json directly requires every implemented internal package, including:

• Core
• Hub
• Bridge
• Internal Spoke
• External Spoke

For example:

core-config
core-container
core-error-handler
...
hub-config
bridge-vanguard
spoke-codex
spoke-canvas
core-dbal
core-crypto

(GitHub) This is not itself a violation.

The root application is the composition boundary, so it is expected to assemble the graph.

But it means Composer's root dependency graph alone cannot express:

"Hub may depend on Core, but Core may never depend on Hub."

That rule must exist at the source/import layer, not merely the package-installation layer.

#4. There is also documentation drift inside dependency metadata

The root Composer manifest says PHP ^8.4, while DEPENDENCIES.md still describes FrankenPHP as "PHP 8.3" and lists encryption/database extensions as future dependencies even though the current Composer manifest already contains core-crypto and core-dbal. (GitHub) This reinforces the earlier finding:

DGLab has a source-of-truth problem, not merely a README problem.

Multiple architectural artifacts can become stale independently.

Confirmed Boundary Model

Based on the actual repository, I would formalize the dependency graph as:

                     ┌───────────────┐
                     │   App / UI    │
                     └───────┬───────┘
                             │
                     ┌───────▼───────┐
                     │    Spokes     │
                     │ Internal /    │
                     │ External      │
                     └───────┬───────┘
                             │
                     ┌───────▼───────┐
                     │     Hub       │
                     │ Domain +      │
                     │ Ports         │
                     └───────┬───────┘
                             │
                     ┌───────▼───────┐
                     │     Core      │
                     │ Runtime +     │
                     │ Contracts     │
                     └───────────────┘

Allowed:        ↓
Forbidden:      ↑

But I would add one crucial architectural rule:

The root application/composition layer may depend on all implemented rings; individual rings may depend only on explicitly permitted inner-ring contracts.

That prevents contractors from interpreting "dependencies point inward" too literally and accidentally creating awkward restrictions on the composition root.

The Architecture Fitness Function I Recommend

This should become an actual CI test rather than another document rule:

And explicitly forbid:

Core       → Hub
Core       → Spoke
Core       → Bridge
Core       → App

Hub        → App
Hub        → Spoke
Hub        → Bridge
Hub        → vendor SDK

Domain     → HTTP implementation
Domain     → database driver
Domain     → framework/controller
Domain     → external API client

The key improvement is that this becomes executable architecture.

The Wheel itself is not the problem.

The repo already has a coherent dependency philosophy. The architectural weakness is that the strongest rule—

"nothing in an inner ring is imported by an outer ring"

—is currently much stronger in documentation than in automated enforcement. (GitHub) So I would now lock this into the SPEC as:

REQ-ARCH-001 — Ring dependency direction MUST be enforced by CI against actual PHP namespaces/imports, not merely documented in architecture blueprints.

And separately:

REQ-ARCH-002 — The root application/composition boundary MAY assemble all implemented rings.

This is the boundary model I recommend carrying into the final SPEC.

you asked

Proceed

chatgpt response

The dependency direction is now clear enough that the next question is where the assembled application actually belongs.

#Current situation

The repository's runtime composition is concentrated in public/index.php. The file constructs and wires the container, configuration, logging, error handling, event dispatcher, Vanguard, kernel, bootstrappers, routes, middleware and controller bindings.

That is a valid composition root, but it currently combines several responsibilities:

public/index.php
 ├── infrastructure construction
 ├── dependency registration
 ├── application registration
 ├── route registration
 ├── middleware registration
 ├── controller registration
 └── kernel startup

The important distinction is:

The composition root may know about every ring. Individual rings should not know about the composition root.

So I would not move composition into Core. That would invert the architecture.

#Proposed target

Introduce an application-level composition boundary:

public/index.php
        │
        ▼
ApplicationFactory
        │
        ├── createContainer()
        ├── registerCore()
        ├── registerHub()
        ├── registerSpokes()
        ├── registerBridges()
        ├── registerInfrastructure()
        ├── registerRoutes()
        ├── registerMiddleware()
        └── createKernel()
                 │
                 ▼
              Kernel
                 │
                 ▼
        request execution

public/index.php then becomes approximately:

<?php

require dirname(__DIR__) . '/vendor/autoload.php';

$app = ApplicationFactory::create();

$app->run();

The exact API can differ; the architectural constraint matters more than the naming.

#Why this matters now

This is not primarily a code-cleanliness refactor.

It creates a hard boundary between:

Composition knowledge

"Which implementation satisfies UserRepository?"
"Which middleware is enabled?"
"Which routes exist?"
"Which infrastructure adapter is active?"

and:

Runtime/domain knowledge

"I need a UserRepository."
"I need to dispatch an event."
"I need the current request."

That separation becomes particularly valuable once Hub and the external spokes grow.

#Important constraint

ApplicationFactory should not become a new god object.

I would eventually split registration into explicit providers/modules:

ApplicationFactory
   │
   ├── CoreProvider
   ├── DomainProvider
   ├── InfrastructureProvider
   ├── IntegrationProvider
   └── HttpProvider

But I would not introduce that abstraction prematurely. First extract the existing composition faithfully; then split providers when there is enough application complexity to justify them.

REQ-APP-001 — Composition Boundary

Application composition MUST occur outside Core and Hub. The composition root MAY depend on all enabled application rings and infrastructure implementations, while runtime and domain packages MUST NOT depend on the composition root.

REQ-APP-002 — Thin Entry Point

public/index.php SHOULD contain only process/bootstrap concerns and MUST NOT contain business registration logic.

REQ-APP-003 — No Service Locator

Application/domain code MUST receive dependencies through explicit constructor or method contracts and MUST NOT retrieve arbitrary services from the global container.

#Area 7 conclusion

The recommended direction is therefore:

Keep the Wheel. Keep Core independent. Keep the root composition omniscient. Move that omniscience out of public/index.php into an explicit application composition layer.

This gives us the missing boundary between architecture and assembly before Hub becomes substantially implemented.

Next area: I recommend we examine the Hub/domain boundary and persistence model, because that is where the architecture needs to become concrete enough for contractors to implement business capabilities.

you asked

Proceed

chatgpt response

The repository is not yet far enough into Hub implementation to justify a concrete business database schema. That is actually useful: we can define the boundary now without prematurely locking the data model.

#Current verified state

The Hub currently has only the configuration package implemented. The large majority of Hub blueprints remain specifications rather than executable domain code.

Meanwhile, Core now contains a basic DBAL implementation, including database connection, query-building, transactions and tenant context.

So the architecture currently looks like:

                 APPLICATION
                     │
                     ▼
              Application Service
                     │
             ┌───────┴────────┐
             ▼                ▼
       Domain Aggregate    Domain Event
             │
             ▼
       Repository Port
             │
             │ implementation
             ▼
      Infrastructure Adapter
             │
             ▼
           Core DBAL
             │
             ▼
          PostgreSQL

The critical boundary is that DBAL belongs to infrastructure/runtime; it does not become the domain's programming model.

#Proposed Hub structure

For each bounded business capability, I recommend:

packages/hub/<capability>/

src/
├── Domain/
│   ├── Entity/
│   ├── ValueObject/
│   ├── Aggregate/
│   ├── Event/
│   ├── Exception/
│   └── Repository/
│
├── Application/
│   ├── Command/
│   ├── Query/
│   └── Service/
│
└── ...

But there is an important architectural nuance:

Repository interfaces should belong to the domain boundary, while implementations must remain outside it.

For example:

interface UserRepository
{
    public function get(UserId $id): ?User;

    public function save(User $user): void;
}

Then:

Hub\Domain\Repository\UserRepository
                    ▲
                    │ implements
                    │
Infrastructure\Persistence\PostgresUserRepository
                    │
                    ▼
             Core\DBAL\Connection

The Hub therefore has no knowledge of:

• PostgreSQL
• SQL
• PDO
• DBAL implementation details
• HTTP
• vendor SDKs
• infrastructure credentials

This should be explicit before application services arrive.

I recommend:

Application Service
       │
       ├── begin transaction
       │
       ├── load aggregate
       ├── execute domain operation
       ├── persist aggregate
       ├── persist outbox events
       │
       └── commit

Not:

Repository
   └── silently begins/commits transactions

That gives one application use-case one coherent transaction boundary.

It also makes the eventual outbox implementation straightforward:

             SAME TRANSACTION
┌─────────────────────────────────────┐
│                                     │
│  Aggregate state       Outbox row   │
│       │                    │        │
│       └─────────┬──────────┘        │
│                 │                   │
│              COMMIT                 │
└─────────────────────────────────────┘
                       │
                       ▼
                 Outbox Publisher
                       │
                       ▼
                    Broker

One detail deserves special attention: the current DBAL already contains a TenantContext.

That means tenant isolation should not be reinvented independently inside every repository.

The target contract should be:

Tenant context is established at the application/request boundary and is consumed by infrastructure persistence policies; domain objects should not obtain tenant identity from global/static state.

For a multi-tenant aggregate, tenant identity should either be an explicit domain concept or an infrastructure-enforced invariant, depending on the business semantics.

What we should not permit is:

// Domain
$db->where('tenant_id', TenantContext::current());

That would leak persistence infrastructure into the domain.

I would not put tables into the final architecture SPEC yet.

Instead, the SPEC should define the invariant:

Every persisted aggregate MUST have an explicit persistence mapping owned by an infrastructure adapter, and database schema design MUST follow the domain model rather than precede it.

This is especially important because DGLab's Hub is still mostly unimplemented.

The DBAL's existence changes the earlier conclusion from "persistence is future" to:

Persistence infrastructure exists; domain persistence contracts do not yet.

That is a much more accurate description of the current repository.

REQ-DOM-001 — Domain isolation

Hub domain code MUST NOT depend on HTTP, controllers, DBAL implementations, SQL drivers, framework infrastructure, or vendor integration SDKs.

REQ-DOM-002 — Repository ports

Repository interfaces MUST be defined at the domain boundary when persistence is required.

REQ-DOM-003 — Persistence adapters

Database-specific repository implementations MUST reside outside the domain and depend inward on domain contracts.

REQ-DOM-004 — Transaction ownership

Application services MUST define transaction boundaries for business use cases. Repositories MUST NOT silently establish unrelated transaction boundaries.

REQ-DOM-005 — Tenant isolation

Tenant context MUST NOT be implemented through mutable global/static domain state.

REQ-DOM-006 — Outbox consistency

When asynchronous integration events are introduced, aggregate state and its corresponding outbox records MUST be committed atomically.

#Area 8 conclusion

The key architectural decision is:

Core DBAL is a capability, not the domain persistence model.

That lets DGLab proceed with DBAL/PostgreSQL infrastructure now without prematurely coupling the eventual Hub to a database.

The next area should therefore be events and asynchronous integration, because that determines how Hub domain events cross the Wheel into Bridges/External Spokes—and whether the outbox boundary should be part of the initial implementation contract.

you asked

Proceed

chatgpt response

This is where the Wheel needs a second, semantic boundary: not every event is the same kind of event.

#Current repository state

DGLab already has a PSR-14 event dispatcher in Core and runtime events such as request/response lifecycle events.

What does not yet exist at meaningful Hub depth is a separate domain-event and integration-event model.

So I recommend keeping the existing dispatcher mechanism while separating the meaning of events.

#Three event categories

                    EVENT SYSTEM
                         │
          ┌──────────────┼──────────────┐
          │              │              │
          ▼              ▼              ▼
      RUNTIME          DOMAIN       INTEGRATION
       EVENTS          EVENTS          EVENTS
          │              │              │
          ▼              ▼              ▼
        Core            Hub          Bridges/
                                    External
                                      Spokes

1. Runtime events — Core

Examples:

RequestReceived
KernelBooted
ResponseReady
KernelTerminating

Their purpose is framework/runtime lifecycle.

They should never become a hidden mechanism for executing business workflows.

2. Domain events — Hub

Examples might eventually be:

UserRegistered
OrderPlaced
SubscriptionCancelled

These describe something meaningful that happened inside the domain.

A domain aggregate may produce them:

$order->place();

$events = $order->releaseEvents();

The aggregate should not know who consumes those events.

3. Integration events — Bridges / External Spokes

These represent communication across a system boundary:

OrderPlaced.v1
CustomerRegistered.v1
InvoiceIssued.v1

An integration event should generally be a stable external contract, rather than exposing the internal aggregate directly.

That gives us:

Hub Aggregate
     │
     │ Domain Event
     ▼
Application Service
     │
     │ transaction
     ▼
Outbox
     │
     ▼
Publisher
     │
     │ Integration Event
     ▼
Message Broker
     │
     ├───────────────┐
     ▼               ▼
External Spoke    Bridge
     │               │
     ▼               ▼
 Vendor/API       External system

Without an outbox, this is dangerous:

DB transaction
      │
      ├── COMMIT
      │
      └── publish message
               │
               └── FAILURE

The database says the order exists, but the external system never learns about it.

The outbox instead makes:

BEGIN
  │
  ├── UPDATE orders
  │
  ├── INSERT outbox_events
  │
  └── COMMIT
           │
           ▼
      Publisher
           │
           ▼
        Broker

The publisher can retry independently.

When this capability is implemented, I recommend an initial table approximately like:

outbox_events

id                  UUID / UUIDv7
aggregate_type      VARCHAR(100)
aggregate_id        VARCHAR(100)
event_type          VARCHAR(200)
event_version       SMALLINT
payload             JSONB
occurred_at         TIMESTAMPTZ
available_at        TIMESTAMPTZ
published_at        TIMESTAMPTZ NULL
attempt_count       INTEGER
last_error          TEXT NULL

With indexes around:

(published_at, available_at)
(aggregate_type, aggregate_id)

The exact schema should wait until the first actual integration contract is known, but the delivery semantics can be specified now.

The first implementation should explicitly promise:

At-least-once delivery, not exactly-once.

Therefore consumers MUST tolerate duplicates.

A consumer can use an idempotency key such as:

event_id

and maintain:

processed_messages

event_id
consumer
processed_at

with a uniqueness constraint on:

(event_id, consumer)

This is considerably easier to make reliable than attempting distributed exactly-once semantics.

I would add:

REQ-EVT-001 — Runtime events

Core runtime events MUST remain concerned with runtime lifecycle and MUST NOT orchestrate business workflows.

REQ-EVT-002 — Domain events

Domain events MUST originate from domain state transitions and MUST NOT depend on infrastructure or external transport.

REQ-EVT-003 — Integration events

External messages MUST use explicit integration contracts and MUST NOT expose domain aggregate objects.

REQ-EVT-004 — Transactional publication

A business transaction that produces an asynchronously delivered integration event MUST persist the corresponding outbox record atomically with the business state.

REQ-EVT-005 — At-least-once

Integration delivery MUST assume at-least-once semantics; consumers MUST be idempotent.

REQ-EVT-006 — No event-driven spaghetti

Events MUST NOT replace explicit application-service orchestration when a business operation requires a known sequence of commands.

That last rule is important.

For example:

PlaceOrder()
 ├── validate
 ├── reserve inventory
 ├── calculate payment
 └── persist

should remain an explicit use case.

Events are appropriate when another component needs to react:

OrderPlaced
   ├── Notification
   ├── Analytics
   └── External fulfilment

rather than turning the entire business process into invisible listener chains.

#Area 9 conclusion

The architecture should therefore retain one technical event-dispatch mechanism if useful, but establish three semantic event boundaries:

Core runtime events → Hub domain events → external integration events

and use an outbox when crossing the transactional boundary into asynchronous infrastructure.

This gives contractors a very clear rule: events describe facts; application services orchestrate use cases; the outbox provides reliable external delivery.

The next area should be security, error handling, and request observability, because those three concerns intersect directly with the persistent-worker model and need explicit contracts before the application layer grows.

you asked

Proceed.

But analyze and verify this first from https://github.com/DGCodeIdeas/DGLab:

From Z.ai:

Verifying Areas 7 + 8 + 9 against the live repo. Same protocol. I have the data. Writing the verification.

Verification Report — Areas 7, 8, 9 + Thesis Update

Same protocol — every specific factual claim cross-checked against the actual repo. Verdict legend: ✅ Confirmed · ⚠️ Outdated/Partial · ❌ Wrong · 💬 Sound Opinion · ✅❌ Partially Right.

✅ All 16 rows confirmed accurate. No corrections needed. The architect absorbed the previous verification cleanly. The three-bucket framework (Already implemented / Hardening / Future) is the right mental model.

The single most important thesis-level correction — "Architecture status must be derived from executable repository state wherever technically possible; manually maintained documents may describe intent, but cannot be authoritative about implementation status" — is exactly right and matches the repo's existing architecture-lint.yml pattern (which already derives reference validity from code, not docs). Promoting this from a recommendation to a governance principle is the highest-leverage single move available.

#"public/index.php combines 7 responsibilities"

✅ Confirmed. 21 direct new/register/->pipe(/registerContract/registerRoute calls across 274 lines. The 7 responsibilities the architect lists map directly:

1. Infrastructure construction → new Container(), new Logger(), new ErrorHandler(…), new EventDispatcher(…)
2. Dependency registration → 3 $container->instance(…) calls
3. Application registration → controller bindings ($container->bind(HelloController::class))
4. Route registration → 2 $router->addRoute(new Route(…)) calls
5. Middleware registration → $pipeline->pipe($this->vanguard)
6. Controller registration → inside the anonymous bootstrapper
7. Kernel startup → $kernel->boot()

#REQ-APP-001 (Composition Boundary: composition outside Core/Hub)

✅ Already met as a practice. Sampled: packages/core/*/src/ contains zero references to ApplicationFactory, public/index.php, or any composition-root concept. Core packages don't know how they're wired. The constraint the architect proposes is already enforced by convention — though not by an automated test.

#REQ-APP-002 (Thin Entry Point)

✅ Genuine gap, confirmed. No ApplicationFactory exists anywhere in packages/ or app/. Searched: zero hits for ApplicationFactory, AppBootstrap, CompositionRoot. The recommendation is valid.

#REQ-APP-003 (No Service Locator)

✅ Already met — surprisingly clean. I grepped packages/ and app/ for $container->get(, $container->make(, Container::getInstance, and app( (Laravel-style helper) — zero hits in production code. The codebase does not use the service-locator anti-pattern anywhere. The architect's requirement is already observed; what's missing is formalizing it as an executable architecture test (so a future contractor can't introduce it).

#Architectural rule

💬 Sound and well-timed. The constraint "ApplicationFactory should not become a new god object; split providers when there's enough complexity" is exactly right. Extract-then-split is the correct order. Don't prematurely abstract.

#Area 7 net verdict

Confirmed. Two of three requirements (APP-001, APP-003) are already met in practice; only APP-002 (the actual ApplicationFactory extraction) is a real implementation gap. The architect should know: this is a "write the missing class + add a CI rule that forbids service-locator usage" job, not a "fundamentally change the architecture" job. Low effort, high leverage.

#"Hub has only the configuration package implemented"

✅ Confirmed. packages/hub/ contains exactly one subdirectory: config/. The 30 other Hub blueprints (HUB-01..HUB-30 minus HUB-30) are spec-only.

#"Core now contains a basic DBAL implementation"

✅ Confirmed, with structure detail. packages/core/dbal/src/ contains:

Connection.php            ConnectionInterface.php
DatabaseException.php     Driver/  (MysqlDriver.php, SqliteDriver.php)
DriverInterface.php       QueryBuilder.php
QueryBuilderInterface.php TenantContext.php
Transaction.php           TypeMapper.php

The architect's proposed structure (Connection/, Transaction/, Query/, Migration/, Exception/ as subdirectories) is close but not exact — actual is flat files at src/ level + a Driver/ subdirectory. No Migration/ namespace yet. Minor.

#TenantContext — the architect's specific concern

✅❌ Important nuance. The architect's anti-pattern example:

// Domain
$db->where('tenant_id', TenantContext::current());

is not what the code does. Actual implementation:

• TenantContext is an immutable value object (constructor-injected ?string $tenantId, no ::current() static accessor — I checked, it doesn't exist).
• QueryBuilder accepts ?TenantContext $tenant = null as a constructor parameter (line 44), then auto-injects WHERE tenant_id = :tenant_id (line 128) when present.
• The class docblock explicitly says: "Constructed by HUB-04 (Identity) after authentication."

So the architect's recommended pattern — tenant context is established at the application/request boundary and consumed by infrastructure persistence policies; domain objects should not obtain tenant identity from global/static state — is already what the code does. REQ-DOM-005 is met in principle by the existing TenantContext design.

The architect should be told: "Your concern is valid in general, but this specific codebase has already proactively avoided the anti-pattern. The TenantContext is constructor-injected into QueryBuilder, not statically accessed."

#Repository ports

✅ Pattern already exists in Hub/config. Two repository interfaces defined at the domain boundary:

• packages/hub/config/src/FeatureFlagRepositoryInterface.php
• packages/hub/config/src/ConfigOverrideRepositoryInterface.php

Both have in-memory implementations (InMemoryFeatureFlagRepository, InMemoryConfigOverrideRepository) — exactly the "interface in domain, implementation elsewhere" pattern the architect's REQ-DOM-002 + REQ-DOM-003 specify.

So the architect's recommended pattern is already proven in Hub/config. It just hasn't been applied to persistence yet, because no Hub persistence domain exists. The pattern is established; the gap is "apply it to a real aggregate."

#Transaction ownership

✅ Infrastructure exists, not yet used by application services. Transaction.php is described as "Disposable: one Transaction per logical unit of work" — exactly the architect's recommended unit-of-work pattern. Connection::beginTransaction(), commit(), getTransactionNestingLevel() are all there. What's missing: an actual application service that uses Transaction to wrap a load-invoke-persist-publish sequence. That's a Hub-implementation gap, not a Core gap.

#Outbox pattern

❌ Confirmed absent. Zero hits for "outbox" or "Outbox" in packages/ or app/. The architect's REQ-DOM-006 is forward-looking and valid.

#Aggregate event recording (releaseEvents() / recordEvent() pattern)

❌ Confirmed absent. Zero hits for releaseEvents, recordEvent, pullEvents, getEvents. No Hub aggregates exist yet to produce domain events. Forward-looking.

#Database schema decision

💬 Strongly agree. "Every persisted aggregate MUST have an explicit persistence mapping owned by an infrastructure adapter, and database schema design MUST follow the domain model rather than precede it." This is the right call given (a) DBAL exists, (b) no Hub aggregates exist, (c) no concrete business requirements have been pinned. Premature schema = guaranteed rework.

#Area 8 net verdict

Confirmed with two corrections:

1. TenantContext already follows the architect's recommended pattern. It's a constructor-injected immutable value object, not a static. The anti-pattern the architect warns against (TenantContext::current()) doesn't exist in the codebase. REQ-DOM-005 is met by design, not just intent.

2. The repository-port pattern already exists in Hub/config (FeatureFlagRepositoryInterface + InMemoryFeatureFlagRepository). REQ-DOM-002 + REQ-DOM-003 are proven patterns in this codebase, not just recommendations — they just haven't been applied to persistence yet.

The other recommendations (outbox, transaction ownership by application services, aggregate event recording) are forward-looking and valid.

#"PSR-14 event dispatcher in Core + runtime events"

✅ Confirmed. packages/core/event-dispatcher/src/ has:

• EventDispatcher.php + EventDispatcherInterface.php (PSR-14)
• Event.php — abstract base implementing StoppableEventInterface, with an "immutable stamp audit trail" (list of [key, value, microtime] triples, append-only)

This stamp mechanism is not mentioned by the architect and is potentially relevant to Area 5 Gap #9 (trace_id propagation) — the infrastructure for stamping events with microtime-keyed context already exists.

#Runtime events actually defined

✅ Confirmed with naming detail. Four runtime events exist in packages/core/kernel/src/Event/:

Close enough. The architect's intent is met.

#"Domain events do not yet exist at meaningful Hub depth"

✅ Confirmed. Zero Hub aggregates → zero domain events. The architect's recommendation to keep the dispatcher mechanism but separate event meaning is sound.

#"Integration events do not yet exist"

✅ Confirmed. No versioned external contracts anywhere in packages/ or app/.

#Outbox pattern

❌ Confirmed absent. Zero hits. The architect's REQ-EVT-004 is forward-looking.

#At-least-once / idempotency infrastructure

❌ Confirmed absent. No processed_messages table, no consumer idempotency key infrastructure. Forward-looking.

#Aggregate event recording ($order->releaseEvents())

❌ Confirmed absent. No releaseEvents / recordEvent pattern in code. The architect's recommendation for aggregate-internal event recording is forward-looking and would be the right pattern when Hub aggregates arrive.

#REQ-EVT-001 through REQ-EVT-006

💬 All sound. Specific notes:

• REQ-EVT-001 (runtime events don't orchestrate business) — already the design intent; current runtime events (BootEvent, RequestReceivedEvent, ResponseReadyEvent, TerminateEvent) are pure lifecycle signals.
• REQ-EVT-002 (domain events from state transitions) — pattern not yet implemented; valid.
• REQ-EVT-003 (integration contracts ≠ aggregate objects) — valid; would prevent leaky abstractions later.
• REQ-EVT-004 (atomic outbox commit) — valid for future async.
• REQ-EVT-005 (at-least-once + idempotent consumers) — valid; standard reliable-messaging practice.
• REQ-EVT-006 (no event-driven spaghetti) — the most important single rule in Area 9. This is the rule that prevents the PSR-14 dispatcher from becoming an invisible business-orchestration bus.

#Area 9 net verdict

Confirmed. Three semantic event categories (runtime/domain/integration) is the right model. Outbox + at-least-once + idempotent consumers is the right async pattern when it arrives. One unmentioned finding worth surfacing: the existing Event base class already has an "immutable stamp audit trail" mechanism — this could be the foundation for trace_id propagation (Area 5 Gap #9) without needing to invent new infrastructure. The architect should know this exists before specifying trace propagation from scratch.

The architect's analysis is consistently sound, and absorbs the earlier verification cleanly. Three notable points:

1. Area 7 is mostly already met. REQ-APP-001 (composition outside Core/Hub) and REQ-APP-003 (no service locator) are already observed in practice. Only REQ-APP-002 (the ApplicationFactory extraction) is a real implementation gap. The architect should know this is a "write one class + add one CI rule" job, not a fundamental refactor.

2. Area 8 has two surprises for the architect. (a) TenantContext is already constructor-injected into QueryBuilder, not statically accessed — the anti-pattern the architect warns against doesn't exist. (b) The repository-port pattern is already proven in Hub/config (FeatureFlagRepositoryInterface + InMemoryFeatureFlagRepository) — just not yet applied to persistence. Both should be reflected in the SPEC as "existing patterns to extend," not "new patterns to introduce."

3. Area 9 has one unmentioned asset. The Event base class already has an "immutable stamp audit trail" (list of [key, value, microtime] triples). This is potentially the foundation for trace_id propagation — closing Area 5 Gap #9 without inventing new infrastructure. Worth surfacing before the SPEC specifies trace propagation from scratch.

Before SPEC-001-DGLab-Sovereign-Stack-Architecture is written, transmit these three corrections:

1. REQ-APP-001 and REQ-APP-003 are already met in practice. The SPEC should describe them as "existing conventions to formalize as CI rules," not as new architectural changes. This affects contractor scope: the job is "add a CI rule that forbids service-locator usage in packages/ and app/," not "rebuild the composition layer."

2. REQ-DOM-005 (tenant isolation) is already met by design. TenantContext is an immutable value object constructor-injected into QueryBuilder. The SPEC should describe this as "extend the existing pattern to new aggregates," not "introduce the pattern." Same for REQ-DOM-002/003 — the repository-port pattern is proven in Hub/config.

3. The Event base class's stamp mechanism should be evaluated as the foundation for trace_id propagation. Don't specify trace propagation from scratch; check whether the existing stamping infrastructure can carry trace context first.

When you send Area 10+ (security/error/observability, per the architect's stated "next area"), I'll verify against the actual ErrorHandler, Logger, ADR-008 (Argon2id), ADR-003 (ES256 JWT), and the Tengine access-log format (which already logs x_request_id).

chatgpt response

I re-checked the live repository first. The Z.ai report is substantially correct, but there is an important freshness issue: the live GitHub main README now contains newer doctrine/kernel claims while also retaining contradictory historical status text. For example, it currently claims the post-MUWV state and full Pulse verification, but later still says public/index.php is a 503 placeholder and MUWV is not authorized. (GitHub) The Event stamp finding is also confirmed: Event::stamp() records append-only [key, value, microtime] entries. (GitHub) So I would carry Areas 7–9 forward exactly as corrected by Z.ai, with one addition: architecture-status drift itself should be treated as a governance/control problem, not merely documentation debt.

The live repository gives us a stronger starting point than the earlier architecture review suggested.

#1. Error handling — largely implemented

ErrorHandler is explicitly designed for the persistent-worker model:

• worker-scoped registration;
• global exception/error handlers;
• shutdown/fatal-error handling;
• display_errors=Off;
• recursion protection;
• logger/rendering failures are swallowed so error handling does not recursively fail;
• TypeError/Error are elevated to CRITICAL, other uncaught throwables to ERROR;
• HTTP fallback emits a generic 500 response. (GitHub) So the gap is not "build an error handler."

The remaining architectural gap is to define a stable application error taxonomy and response contract that sits above this mechanism.

The README's current doctrine also explicitly describes a five-class error taxonomy:

Transient / Permanent-External / Permanent-Local / Corrupt / Panic

and says this doctrine is binding for Core. (GitHub) Recommendation: make that taxonomy an executable contract across Core → Hub → Spokes, rather than inventing another exception hierarchy independently in each layer.

#2. Security — infrastructure already provides meaningful controls

The repository's current Anvil design already places important security controls at the edge, while application authorization remains an application concern.

The architecture should therefore not duplicate controls unnecessarily.

Target responsibility split:

Internet
   │
   ▼
Caddy
 ├── TLS / ACME
 ├── security headers
 ├── HTTP/2 + HTTP/3
 └── edge access logging
   │
   ▼
Tengine
 ├── request/connection limiting
 ├── buffering / slow-client protection
 ├── real-IP restoration
 ├── upstream timing
 └── blue/green routing
   │
   ▼
FrankenPHP
 ├── authentication
 ├── authorization
 ├── input validation
 ├── domain invariants
 └── application security policy

This means the architecture requirement should be security responsibility boundaries, rather than "add more security middleware."

#3. Request correlation — this is the main observability gap

The existing Event stamp mechanism is useful, but I would not make the event object itself the source of truth for request correlation.

Instead:

HTTP request
    │
    ▼
RequestContext
 ├── request_id
 ├── trace_id
 ├── tenant_id (when authenticated)
 └── start_time
    │
    ├──────────────► Logger context
    │
    ├──────────────► Runtime events
    │
    ├──────────────► Error responses
    │
    └──────────────► Downstream integration headers

Then Event::stamp() can record correlation metadata as an audit trail, while RequestContext remains the authoritative request-scoped state.

This is particularly important because DGLab uses persistent FrankenPHP workers and Fiber-scoped request state; correlation data must never leak from one request/Fiber into another.

#4. Proposed requirements

MUST

• REQ-SEC-001 — Security Boundary: edge, transport, application, and domain security responsibilities MUST be explicitly separated.
• REQ-ERR-001 — Error Taxonomy: application failures MUST map to the existing five-class taxonomy rather than arbitrary exception categories.
• REQ-ERR-002 — Worker-Safe Error Handling: no request error or fatal path MAY leave persistent worker state contaminated.
• REQ-OBS-001 — Request Identity: every application request MUST have a request ID and trace ID.
• REQ-OBS-002 — Fiber Isolation: correlation context MUST be Fiber/request scoped and cleared after request completion.
• REQ-OBS-003 — Error Correlation: error responses MUST expose a safe correlation identifier without exposing stack traces or internal paths.
• REQ-OBS-004 — Structured Logs: request ID, trace ID, route, status, duration, and error classification SHOULD be consistently available to structured logging.
• REQ-OBS-005 — Event Correlation: runtime events SHOULD receive correlation metadata through the existing event-stamp mechanism.

SHOULD

• propagate W3C traceparent when distributed tracing is introduced;
• return the request/correlation ID in HTTP responses;
• distinguish liveness, readiness, and dependency health;
• add persistent-worker contamination tests covering logs, errors, tenant context, events, and DI scopes.

#Area 10 verdict

Security infrastructure is ahead of the application layer; error handling is substantially implemented; observability is the meaningful remaining gap.

The architectural move I recommend is therefore not another large subsystem. It is to establish one request-scoped correlation contract and make the existing ErrorHandler, Logger, Kernel events, Fiber scope, and edge logs conform to it.

Please confirm Area 10, and I'll proceed to the next area: testing, architecture fitness functions, and production verification.

you asked

Proceed. But analyze and verify this first from https://github.com/DGCodeIdeas/DGLab: From Z.ai:

Verifying Area 10 against the live repo. I have the data. Writing the verification.

Verification Report — Area 10

Same protocol — every specific factual claim cross-checked against the actual repo. Verdict legend: ✅ Confirmed · ⚠️ Outdated/Partial · ❌ Wrong · 💬 Sound Opinion.

#"ErrorHandler is explicitly designed for the persistent-worker model"

✅ Every specific claim confirmed. Cross-checked packages/core/error-handler/src/ErrorHandler.php line-by-line:

Also has PlainTextRenderer.php and JsonRenderer.php (Renderer directory). The architect's claim that "the gap is not 'build an error handler'" is correct — it's done.

#"Doctrine's five-class taxonomy is binding for Core"

✅ Confirmed verbatim. Architecture/CrossCutting/NUCLEAR-GRADE-DOCTRINE.md:

• Line 3: > **Status:** Canonical, binding.
• Line 138: ## §2. Error taxonomy — five and only five kinds
• Lines 145–149 define exactly the five classes the architect named:

• Line 152: "every log line MUST name the class. Catching a Corrupt as if it were Transient [is forbidden]"

So the architect's recommendation — "make that taxonomy an executable contract across Core → Hub → Spokes, rather than inventing another exception hierarchy independently in each layer" — is exactly the right move. The doctrine is binding, but I find no automated CI rule that verifies error classes are actually used in log lines or that exception hierarchies map to the five classes. REQ-ERR-001 is currently doctrine, not yet executable contract. The recommendation is valid.

#"Anvil security controls at the edge"

✅ Confirmed (re-verified from Area 4 work). Same conclusion as before: Caddy has TLS/ACME/security headers/HTTP2+3/edge logs; Tengine has rate-limiting/buffering/real-IP/upstream-timing/blue-green routing; FrankenPHP worker hardening via systemd (NoNewPrivileges, ProtectSystem=strict, ProtectHome, PrivateTmp, RestrictAddressFamilies, SystemCallArchitectures=native). Plus ADR-008 (Argon2id) and ADR-003 (ES256 JWT) for application-layer crypto/auth.

The architect's recommendation — "security responsibility boundaries, rather than 'add more security middleware'" — is the right framing. REQ-SEC-001 is sound.

#ADR-008 (Argon2id) and ADR-003 (ES256 JWT) — verified in depth

✅ Both ADRs are Accepted and detailed. ADR-008 specifies Argon2id with parameters memory_cost=65536 KiB, time_cost=4, threads=2 (RFC 9106 §4 second-tier). ADR-003 specifies ES256 (ECDSA P-256 + SHA-256), JWKS endpoint, kid header rotation, none algorithm rejected unconditionally. Both have full alternatives-considered tables (bcrypt/PBKDF2/scrypt/Argon2i for ADR-008; HS256/RS256/EdDSA/PS256/none for ADR-003). The doctrine + ADR pair is exactly what a contractor needs.

#"Event stamp mechanism"

✅ Confirmed. packages/core/event-dispatcher/src/Event.php has the stamp mechanism the architect describes — append-only list<array{string, mixed, float}> (key/value/microtime triples).

#The architect's RequestContext distinction

💬 Strongly agree, with one nuance. The architect's argument — "I would not make the event object itself the source of truth for request correlation. Instead: RequestContext → request_id, trace_id, tenant_id, start_time. Event::stamp() can record correlation metadata as an audit trail, while RequestContext remains the authoritative request-scoped state." — is exactly right.

The nuance: the existing TenantContext value object in packages/core/dbal/src/TenantContext.php is already the seed of this pattern — it's an immutable constructor-injected value object carrying tenant identity. RequestContext would extend the same pattern to carry request_id + trace_id + start_time + tenant_id. So the architect isn't proposing a brand-new abstraction; they're proposing to extend the existing TenantContext pattern upward to cover full request-scoped correlation.

I verified: no RequestContext class exists anywhere in packages/ or app/. Zero hits for RequestContext, RequestCorrelation, CorrelationContext. REQ-OBS-001 and REQ-OBS-002 are genuine gaps. The infrastructure for Fiber-isolated storage already exists (WeakMap in Container), so the implementation path is: a RequestContext value object + a WeakMap<Fiber, RequestContext> accessor — same pattern as pulseInstances.

#REQ-SEC-001 / REQ-ERR-001 / REQ-ERR-002 / REQ-OBS-001..005

Status against repo:

Summary: 2 of 8 already met, 4 partial (mechanism exists, contract doesn't), 2 genuine gaps (RequestContext + trace_id propagation).

#SHOULD items

• W3C traceparent propagation: 💬 Forward-looking, sound. No traceparent handling in code yet.
• Return request/correlation ID in HTTP responses: 💬 Sound. Standard practice; easy once REQ-OBS-001 is met.
• Liveness/readiness/dependency health split: 💬 Same gap flagged in Area 4. /health currently conflates concerns.
• Persistent-worker contamination tests (logs, errors, tenant context, events, DI scopes): 💬 Highest-leverage single test addition. None of these exist yet. This is the test layer that catches the bug class the persistent-worker model uniquely enables.

#Area 10 net verdict

Confirmed. The architect's framing — "security infrastructure is ahead of the application layer; error handling is substantially implemented; observability is the meaningful remaining gap" — exactly matches the repo. The single architectural move the architect recommends (one request-scoped correlation contract that ties together ErrorHandler, Logger, Kernel events, Fiber scope, and edge logs) is the correct minimal-architecture addition. It does not require a new subsystem — it requires one value object (RequestContext) + one WeakMap accessor + a doctrine rule that error classes appear in log lines + a CI check.

The architect should know: this is a "extend the existing TenantContext pattern + add a CI rule" job, not a "design a new observability subsystem" job. Low effort, high leverage, closes the largest remaining gap.

The architect has now absorbed all prior corrections cleanly. The live verification confirms:

Strong starting points (more mature than initial review suggested):

• ErrorHandler (persistent-worker-safe, all 8 design properties present)
• Doctrine 5-class error taxonomy (binding, just not yet CI-enforced)
• TenantContext pattern (constructor-injected immutable value object — exactly the pattern the architect's anti-pattern warning guards against)
• Event stamp mechanism (append-only audit trail — perfect foundation for trace metadata)
• ADR-008 Argon2id (full alternatives-considered)
• ADR-003 ES256 JWT (full alternatives-considered)
• Anvil security boundary split (3-tier documented responsibilities)

Genuine gaps the architect correctly identifies:

• RequestContext value object (extend TenantContext pattern)
• Trace_id propagation (no code reads x-request-id today)
• CI rule enforcing error-class-in-log-line (doctrine is binding but not automated)
• Liveness/readiness/dependency health split
• Persistent-worker contamination tests (logs/errors/tenant/events/DI scopes)
• Ring-boundary import CI rule (still the highest-leverage architecture-test addition)

Things the architect previously flagged as gaps that are already met:

• Config immutability (ConfigBuilder frozen + readonly array)
• Worker recycling (max_requests 500)
• Blue/green deployment (systemd template unit)
• Graceful shutdown (SIGTERM + TimeoutStopSec=30s)
• Worker-safe error handling (recursion protection + swallow-on-fail)
• Tenant isolation via value object (no static accessor)

Three corrections to transmit:

1. REQ-ERR-001 should be split into two requirements: (a) "application failures MUST map to the existing five-class taxonomy" (doctrine already states this) and (b) "a CI rule MUST verify that log lines name the error class and that exception hierarchies declare their class." The first is met; the second is the real gap. Contractors need to know the job is "add the CI rule," not "introduce the taxonomy."

2. REQ-OBS-001 (RequestContext) should explicitly extend the existing TenantContext pattern. The architect's recommendation is sound, but the SPEC should reference packages/core/dbal/src/TenantContext.php as the existing pattern to extend — not propose RequestContext as a new abstraction. Same shape: immutable value object, constructor-injected, no static accessor, Fiber-isolated storage via WeakMap<Fiber, RequestContext> (same pattern as pulseInstances).

3. REQ-OBS-005 (Event correlation via stamps) should explicitly use the existing Event::stamp() mechanism. The infrastructure is already there (append-only [key, value, microtime] triples). The SPEC should say "stamp events with request_id and trace_id from RequestContext," not "build an event correlation mechanism."

When you send Area 11+ (testing, architecture fitness functions, production verification), I'll verify against packages/core/*/tests/, Architecture/Verification/lint/, and the actual .github/workflows/ CI matrix.

chatgpt response

I verified Area 11 against the live repository before proceeding. One important correction from the earlier Z.ai baseline: the current GitHub main README is internally contradictory about MUWV/production status—it simultaneously says the stack is post-MUWV with a verified real HTTP path and later says the four non-Core Milestone-0 components are “Not started” and public/index.php is still a 503 placeholder. So README status cannot be treated as authoritative implementation evidence. (GitHub) The repository does, however, clearly contain a dedicated tests/ tree, architecture verification tooling, PHPUnit/PHPStan tooling, and GitHub Actions. (GitHub)

Area 11 — Testing, Architecture Fitness & Production Verification

The central architectural issue here is not lack of tests. It is that the most important architectural guarantees need to become executable fitness functions.

#1. Existing testing foundation is real

The repository already uses:

• PHPUnit 10.5
• PHPStan 2.x at maximum level
• package-level tests
• integration testing
• a dedicated tests/ tree
• architecture verification tooling. (GitHub) The README also explicitly identifies KernelHelloWorldIntegrationTest::testHelloWorldRoundTrip as proving the architectural request round-trip. (GitHub) So the recommendation is not “introduce testing.”

It is:

Test the architectural invariants that are uniquely important to a persistent-worker, six-ring framework.

This remains the highest-leverage architectural test.

The current architecture documentation says:

nothing in an outer ring is imported by an inner ring. (GitHub) That statement should be checked against the actual PHP dependency graph, not merely documented.

The fitness test should inspect PHP namespaces/imports and fail if, for example:

Core → Hub                    forbidden
Core → Spoke                  forbidden
Hub → Spoke                   forbidden
Hub → Bridge                  forbidden
Domain → HTTP implementation  forbidden
Domain → SQL/DB driver        forbidden
Domain → external SDK         forbidden

while permitting the intended inward dependencies.

This should run on every PR.

REQ-ARCH-001 therefore becomes a blocking CI fitness function.

This is the most important runtime-specific test category.

A conventional PHP request model can hide state leakage because the process frequently dies after the request.

DGLab deliberately uses FrankenPHP workers and Fiber-based request scoping. The README explicitly identifies the Fiber-based cooperative runtime as ADR-017. (GitHub) Therefore tests should deliberately perform:

Request A
  ├── tenant = A
  ├── request_id = A
  ├── DI pulse state = A
  ├── events = A
  └── error/log context = A

Request B
  ├── tenant = B
  ├── request_id = B
  ├── DI pulse state = B
  ├── events = B
  └── error/log context = B

and assert:

state(A) ∩ state(B) = ∅

This should cover at least:

• Fiber-local DI instances
• TenantContext
• future RequestContext
• event stamps
• logger context
• router/middleware state
• exception/error state
• request-scoped services
• static/global mutable state

The Kernel should be tested as a state machine rather than merely as a collection of methods.

Expected invariant:

Unbooted
   │ boot()
   ▼
Booting
   │
   ▼
Booted
   │ handle()
   ▼
Handling
   │
   ▼
Booted
   │ terminate()
   ▼
Terminating
   │
   ▼
Terminated

Tests should deliberately attempt invalid transitions:

boot() after Terminated       → reject
handle() before Booted        → reject
handle() during Booting       → reject
terminate() twice             → reject/idempotent by contract
concurrent handle()           → contract-defined behavior

The important point is that the lifecycle contract should be asserted, not inferred from implementation.

DGLab already uses freezing semantics in important runtime components.

The fitness suite should therefore verify that mutation after activation is impossible or explicitly rejected for:

• Router
• Middleware pipeline
• configuration
• other future compiled runtime structures.

For example:

construct
   ↓
configure
   ↓
freeze
   ↓
serve
   ↓
mutation attempt → deterministic failure

This is particularly important in a persistent worker because accidental post-boot mutation persists across requests.

This is the major governance lesson from the current README.

The repository currently contains mutually inconsistent status statements—for example, the README says both that all eight Milestone-0 blueprints shipped and that four remain “Not started.” (GitHub) Therefore:

#New requirement — REQ-GOV-001

Implementation status MUST be generated from executable repository state wherever technically possible.

For example:

packages/
Architecture/INDEX.md
       │
       ▼
architecture-status.php
       │
       ├── package exists?
       ├── source exists?
       ├── tests exist?
       ├── blueprint exists?
       ├── CI verification exists?
       └── implementation depth?
              │
              ▼
      ARCHITECTURE_STATUS.md

Human documentation can describe intent.

Generated status should describe reality.

That distinction will prevent exactly the kind of contradictory status currently visible in the README.

Unit and architecture tests aren't enough.

The production verification ladder should be:

                 ┌──────────────────┐
                 │ Static Analysis  │
                 └────────┬─────────┘
                          ▼
                 ┌──────────────────┐
                 │ Unit Tests       │
                 └────────┬─────────┘
                          ▼
                 ┌──────────────────┐
                 │ Integration      │
                 └────────┬─────────┘
                          ▼
                 ┌──────────────────┐
                 │ Architecture    │
                 │ Fitness Tests    │
                 └────────┬─────────┘
                          ▼
                 ┌──────────────────┐
                 │ Worker/Fiber     │
                 │ Contamination    │
                 └────────┬─────────┘
                          ▼
                 ┌──────────────────┐
                 │ Real HTTP        │
                 │ Caddy→Tengine→   │
                 │ FrankenPHP       │
                 └────────┬─────────┘
                          ▼
                 ┌──────────────────┐
                 │ Deployment       │
                 │ / rollback test  │
                 └──────────────────┘

The production gate should therefore validate the complete path, not simply that PHPUnit passes.

#MUST

• REQ-TEST-001: Every Core package MUST have unit tests for its public contract.
• REQ-TEST-002: Ring dependency direction MUST be checked against actual PHP imports in CI.
• REQ-TEST-003: Persistent-worker tests MUST prove request/Fiber state isolation.
• REQ-TEST-004: Kernel lifecycle transitions MUST have positive and negative tests.
• REQ-TEST-005: Frozen runtime components MUST reject post-freeze mutation.
• REQ-TEST-006: Architecture tests MUST run as blocking CI gates.
• REQ-GOV-001: Implementation status MUST be derivable from executable repository state wherever technically possible.
• REQ-PROD-001: A release candidate MUST pass a real HTTP-path verification through the deployed stack.

#SHOULD

• chaos-test worker failures and restart/recycle behavior;
• test blue/green rollback;
• test graceful SIGTERM handling with in-flight requests;
• test correlation-ID isolation across concurrent Fibers;
• periodically run long-lived worker soak tests.

#COULD

• generate architecture diagrams/status from the same machine-readable model;
• expose architecture-fitness results as CI artifacts;
• maintain a small "contract test" package shared across all Core implementations.

#WON'T

• use code coverage percentage as the primary architecture-quality metric;
• treat passing unit tests as proof of ring compliance;
• treat manually maintained README status as authoritative implementation state.

#Area 11 verdict

The testing foundation exists. The missing piece is turning architectural intent into blocking, executable fitness functions.

The contractor-facing priority should therefore be:

ring imports → worker/Fiber isolation → lifecycle → freeze invariants → generated status → full-stack HTTP verification.

This also gives us the backbone for the final SPEC: the architecture becomes something the repository can prove, rather than something contractors merely have to read and remember.

Please confirm Area 11, and I'll proceed to the final area: deployment, operational SLOs, acceptance criteria, and the final contractor-ready implementation boundary.

you asked

Proceed. But analyze and verify this first from https://github.com/DGCodeIdeas/DGLab: From Z.ai:

Verifying Area 11 against the live repo. I have the data. Writing the verification.

Verification Report — Area 11

Same protocol — every specific factual claim cross-checked against the actual repo. Verdict legend: ✅ Confirmed · ⚠️ Outdated/Partial · ❌ Wrong · 💬 Sound Opinion.

#"PHPUnit 10.5"

❌ Wrong. Actual is ^11.0 (PHPUnit 11). Per composer.json (root) and packages/core/kernel/composer.json require-dev: "phpunit/phpunit": "^11.0". The architect is one major version behind. Worth correcting in the SPEC.

#"PHPStan 2.x at maximum level"

✅ Confirmed exactly. composer.json has "phpstan/phpstan": "^2.2". All per-package phpstan.neon files set level: max. Several packages additionally include vendor/phpstan/phpstan/conf/bleedingEdge.neon — the strictest available PHPStan configuration. Plus reportUnmatchedIgnoredErrors: true enforces that @phpstan-ignore annotations must actually match an error (prevents stale ignores).

#"Package-level tests"

✅ Confirmed. 15 packages have their own tests/ directory:

packages/core/{kernel, error-handler, container, event-dispatcher, config, logger, middleware, router, crypto, dbal, http-message}/tests/
packages/bridge/vanguard/tests/
packages/spoke/internal/codex/tests/
packages/spoke/external/canvas/tests/
packages/hub/config/tests/

#"Integration testing"

✅ Confirmed, with one naming correction. The architect (and the README) reference KernelHelloWorldIntegrationTest::testHelloWorldRoundTrip. Actual file is packages/core/kernel/tests/Integration/HelloWorldTest.php (class name: HelloWorldTest, not KernelHelloWorldIntegrationTest). The method name testHelloWorldRoundTrip is correct. The integration test file has 6 test methods covering:

• testHelloWorldRoundTrip — full Pulse round-trip
• testMultipleRequestsInSequence — sequential request handling
• testUnmatchedRouteReturns404 — router 404
• testCannotHandleAfterTerminate — kernel lifecycle invariant
• testBootEventIsDispatched — runtime event verification
• testMiddlewareIsExecuted — pipeline execution

So the README's "proving the architectural request round-trip" claim is met — just under a different class name than the README states.

#"Dedicated tests/ tree"

✅ Confirmed. Per-package tests/ directories at every level (Unit, Integration, Immutability, Security, Performance, Contract, Fixtures as applicable per package).

#"Architecture verification tooling"

✅ Confirmed (already verified in Area 5). Architecture/Verification/lint/run.php + .github/workflows/architecture-lint.yml. But the tool only performs 3 checks (reference existence, misattribution phrases, structural completeness). The workflow's own self-comment says: "Do not assume broader coverage (Pulse consistency, naming drift, Soft-Freeze, blueprint-fidelity) is enforced here yet; those are cooldown-expansion targets."

#"KernelHelloWorldIntegrationTest::testHelloWorldRoundTrip proves the architectural request round-trip"

✅ Confirmed (with naming correction above). Real round-trip test exists.

#ADR-017 (Fiber-based cooperative runtime)

✅ Confirmed. Referenced directly in Container.php line 70 ("Under ADR-017's cooperative scheduler (Fibers)"). The WeakMap<Fiber, ...> design and per-Fiber cycle-detection are explicitly ADR-017-driven.

#REQ-TEST-001 (every Core package has unit tests for public contract)

✅ Largely met. All 11 Core packages have tests/ directories with Unit test files. Sampling shows real test coverage (not just .gitkeep placeholders). For example, packages/core/kernel/tests/Unit/KernelStateMachineTest.php has 16 test methods, packages/core/middleware/tests/Immutability/PipelineImmutabilityTest.php has multiple, packages/core/router/tests/Unit/RouterTest.php has testMatchSetsFrozenFlag, etc. Whether every public contract is covered is a deeper audit, but the structural foundation is real.

#REQ-TEST-002 (ring dependency direction checked against actual PHP imports in CI)

❌ Genuine gap. This is the single highest-leverage addition the architect proposes. The current architecture-lint.yml workflow runs run.php which checks only 3 things: reference validity, misattribution phrases, structural completeness. It does NOT inspect PHP use statements for ring-boundary violations. No contractor adding use App\Http\Controller\OrderController inside a Hub aggregate would be blocked by CI today.

The recommendation is valid and unmet. The implementation path is: a PHP script that walks packages/{core,hub,spoke,bridge}/src/, parses use statements, and fails if any forbidden ring-direction import is found. Approximate effort: 200-line PHP script + 1 workflow addition. Low effort, high leverage.

#REQ-TEST-003 (persistent-worker state isolation tests)

❌ Genuine gap. I searched packages/ for "contamination", "state leak", "fiber isolation", "cross request" — zero hits in test files. The Container has comments noting "no state leak (Security Property #3)" at line 7 of the cycle-detection logic, but there's no test that proves this property under concurrent Fibers. The architect's recommended test (state(A) ∩ state(B) = ∅ across two requests with different tenant/request_id/DI pulse/events/error/log context) does not exist.

This is the second-highest-leverage test addition. The infrastructure to test it exists (pulse() + WeakMap<Fiber, ...>), but no test exercises it with two Fibers running concurrently with different state.

#REQ-TEST-004 (Kernel lifecycle positive + negative tests)

✅ Substantially met — 16 test methods exist. packages/core/kernel/tests/Unit/KernelStateMachineTest.php covers exactly the architect's proposed invariants:

REQ-TEST-004 is already substantially met. The architect should be told. The one missing piece is concurrent handle() contract — but that's a Fiber-scheduler test, which is a different concern (it's REQ-TEST-003 territory).

#REQ-TEST-005 (frozen runtime components reject post-freeze mutation)

✅ Substantially met — for the three components the architect specifically names. I verified freeze tests exist for:

So REQ-TEST-005 is already substantially met. The architect should be told.

#REQ-TEST-006 (architecture tests as blocking CI gates)

⚠️ Partial. architecture-lint.yml IS a blocking CI gate (it runs on PRs, fails the build on violations). But its current scope is only 3 checks. So the mechanism exists; the coverage is the gap. REQ-TEST-006 is half-met.

#REQ-GOV-001 (implementation status derived from executable repository state)

❌ Genuine gap, confirmed. No ARCHITECTURE_STATUS.md is generated by CI. README is manually maintained and contradictory (post-MUWV vs 503 placeholder, 5 of 8 vs 8 of 8, "Not started" vs "Complete"). The architect's recommendation is exactly the right fix. Implementation path: a small PHP script that walks packages/ + Architecture/INDEX.md + blueprint metadata and emits ARCHITECTURE_STATUS.md. The architect's architecture-status.php sketch is reasonable.

#REQ-PROD-001 (release candidate passes real HTTP-path verification through deployed stack)

⚠️ Partial. Two layers exist:

• Kernel-level round-trip: HelloWorldTest::testHelloWorldRoundTrip exercises the full Pulse trace (ServerRequest → Vanguard → Kernel → middleware → router → controller → Response). But this is PHPUnit, not a real HTTP request through the deployed stack.
• Deploy-time HTTP check: anvil/provisioning/cloud-init.yaml has a first-boot health gate that polls https://localhost/health for 60s. anvil/lib/deploy-smoke.sh checks /health returns 2xx within 5s.

So there IS a real-HTTP-path check at deploy time, but it's a smoke test (/health 2xx), not a comprehensive release-candidate gate. The architect's REQ-PROD-001 recommendation — release candidate must pass a real HTTP-path verification through the deployed stack — is partially met (smoke test exists) but a comprehensive gate doesn't exist.

All five SHOULD items are genuine gaps. The SIGTERM test is the highest-value of these — it would catch the bug class that persistent-worker model uniquely enables.

💬 All sound. None exist. Low priority relative to the gaps above.

💬 All three are exactly right:

• WON'T use code coverage percentage as primary architecture-quality metric — correct; coverage doesn't prove invariants.
• WON'T treat passing unit tests as proof of ring compliance — correct; this is precisely the gap REQ-TEST-002 closes.
• WON'T treat manually maintained README status as authoritative implementation state — correct; this is precisely the gap REQ-GOV-001 closes.

The WON'T list is a sharp summary of the architectural discipline the SPEC should enforce.

Confirmed with corrections. The architect's verdict — "the testing foundation exists; the missing piece is turning architectural intent into blocking, executable fitness functions" — is exactly right.

Three corrections the architect should absorb before the final SPEC:

1. PHPUnit version is 11.0, not 10.5. Minor but the SPEC should reflect reality.

2. REQ-TEST-004 (Kernel lifecycle tests) is already substantially met. 16 test methods cover exactly the positive + negative transition matrix the architect proposes. The SPEC should describe REQ-TEST-004 as "existing tests to extend with concurrent handle() contract," not "tests to write from scratch."

3. REQ-TEST-005 (freeze tests) is already substantially met for the three components the architect names (Router, Middleware pipeline, Configuration). Each has explicit freeze/reject-mutation tests. The SPEC should describe REQ-TEST-005 as "extend existing freeze-test pattern to future runtime structures (route compiler, service provider registry, etc.)," not "introduce freeze tests."

Three genuine gaps the architect correctly identifies:

1. REQ-TEST-002 (ring-boundary CI rule) — highest leverage. ~200-line PHP script + 1 workflow addition. Closes the gap between "Wheel architecture as documentation" and "Wheel architecture as contract."

2. REQ-TEST-003 (worker/Fiber contamination tests) — second highest leverage. The infrastructure exists (pulse() + WeakMap<Fiber, ...>), but no test exercises two concurrent Fibers with different state.

3. REQ-GOV-001 (machine-generated ARCHITECTURE_STATUS.md) — closes the README contradiction drift flagged in Areas 1, 5, and 11. Highest leverage per unit of effort.

The architect's testing foundation analysis is accurate, with three small corrections (PHPUnit version, REQ-TEST-004 substantially met, REQ-TEST-005 substantially met). The architect's priority list — "ring imports → worker/Fiber isolation → lifecycle → freeze invariants → generated status → full-stack HTTP verification" — should be reordered to:

1. Ring-boundary CI rule (REQ-TEST-002) — unmet, highest leverage
2. Worker/Fiber contamination tests (REQ-TEST-003) — unmet, second-highest leverage
3. Machine-generated architecture status (REQ-GOV-001) — unmet, closes README drift
4. Full-stack HTTP verification gate (REQ-PROD-001) — partial (smoke test exists, comprehensive gate doesn't)
5. Lifecycle tests (REQ-TEST-004) — already substantially met; extend with concurrent handle() contract
6. Freeze tests (REQ-TEST-005) — already substantially met; extend pattern to future runtime structures

Items 5 and 6 are largely done. Items 1–4 are the genuine work. The architect's recommendation that "the architecture becomes something the repository can prove, rather than something contractors merely have to read and remember" is the right north star.

Three corrections to transmit:

1. PHPUnit version is 11.0, not 10.5. PHPStan version (2.x at max + bleedingEdge) is correct.

2. REQ-TEST-004 and REQ-TEST-005 are substantially already met. The SPEC should distinguish "extend existing tests" (these two) from "introduce new fitness functions" (REQ-TEST-002 ring boundaries, REQ-TEST-003 contamination, REQ-GOV-001 status generation, REQ-PROD-001 full-stack HTTP). Contractors need to know which work is "build new" vs. "extend existing" — otherwise they'll rebuild tests that already exist.

3. The priority order should be revised to reflect what's actually missing. The architect's order (ring imports → worker/Fiber → lifecycle → freeze → status → HTTP verification) implies all six are unmet. Actually only the first two and last two are unmet; lifecycle and freeze are done. Reordered priority: ring boundaries → contamination → status generation → HTTP verification gate → (extend lifecycle with concurrent handle) → (extend freeze pattern to future structures).

When you send the final area (deployment, operational SLOs, acceptance criteria, contractor-ready implementation boundary), I'll verify against anvil/lib/deploy.sh, anvil/lib/verify.sh, anvil/lib/deploy-smoke.sh, the systemd units, and the SLO/acceptance language in the doctrine + ADRs.

chatgpt response

I verified the Area 11 corrections first. The Z.ai report is consistent with the repository evidence available to me, including the PHPUnit 11 correction and the distinction between existing lifecycle/freeze tests versus genuinely missing fitness tests. The repository's own architecture-lint workflow is indeed narrower than the architectural doctrine it is intended to protect. (GitHub)

The final area should not introduce another architectural subsystem. DGLab already has a substantial deployment architecture. The goal is to turn that deployment machinery into explicit, measurable release contracts.

#1. Deployment architecture is already substantially implemented

The existing Anvil deployment model should be treated as the baseline:

                         Internet
                            │
                            ▼
                    ┌───────────────┐
                    │    Caddy      │
                    │ TLS / ACME    │
                    │ HTTP/2 / HTTP3│
                    └───────┬───────┘
                            │
                            ▼
                    ┌───────────────┐
                    │   Tengine     │
                    │ rate limiting │
                    │ buffering     │
                    │ blue/green    │
                    └───────┬───────┘
                            │
                  ┌─────────┴─────────┐
                  ▼                   ▼
           ┌────────────┐      ┌────────────┐
           │ FrankenPHP │      │ FrankenPHP │
           │   BLUE     │      │   GREEN    │
           └────────────┘      └────────────┘

The important architectural conclusion from the earlier verification remains:

Tengine should not be removed merely because Caddy exists.

Its responsibilities are distinct enough to justify keeping it: request limiting, buffering, real-IP handling, timing observability and blue/green routing.

#2. Deployment verification needs to move beyond /health

The repository already has deployment-time health/smoke verification. The gap is that this proves primarily:

"Can the deployed stack answer?"

rather than:

"Does the deployed stack implement the architecture we released?"

The release gate should eventually validate:

Caddy
  ↓
Tengine
  ↓
active FrankenPHP worker
  ↓
Kernel
  ↓
Middleware
  ↓
Router
  ↓
Controller/Application
  ↓
Response

and verify:

• expected HTTP status;
• response contract;
• request/trace ID propagation;
• correct active color;
• health/readiness;
• no unexpected error;
• worker remains healthy after repeated requests.

Blue/green infrastructure already exists, so the SPEC should define its acceptance invariants, not ask contractors to redesign deployment.

BLUE active
     │
     │ deploy GREEN
     ▼
GREEN provisioned
     │
     ├── health check
     ├── smoke test
     ├── architecture verification
     └── HTTP verification
     │
     ▼
switch traffic
     │
     ▼
GREEN active
     │
     ├── monitor
     │
     └── rollback if release gate fails

Required property:

Traffic MUST NOT be switched to a candidate merely because its process started successfully.

The candidate must pass its release checks first.

The existing worker model already has bounded recycling. The remaining concern is proving that recycling is safe.

A production test should demonstrate:

requests
   │
   ▼
worker reaches recycle threshold
   │
   ▼
graceful worker replacement
   │
   ├── no failed requests beyond allowed drain behavior
   ├── no state leakage
   ├── no lost critical logs
   └── service remains available

This should be tested separately from ordinary unit tests.

I would not hard-code latency numbers into the architecture document until there is representative workload data.

Instead, define the measurement contract first:

Once baseline production traffic exists, numerical SLO targets can be selected from observed behavior rather than guessed.

This is the most important part for making the final SPEC directly implementable.

A contractor should be able to demonstrate:

#Architecture

• forbidden ring imports fail CI;
• Core/Hub/domain boundaries remain intact;
• service locator usage remains forbidden;
• architecture status is generated from repository state.

#Runtime

• two concurrent Fibers cannot observe one another's request state;
• Kernel lifecycle invariants pass;
• frozen components cannot be mutated;
• worker recycling does not leak state.

#Application

• public/index.php remains a thin entry point;
• ApplicationFactory owns composition;
• domain code does not depend on HTTP/SQL/vendor SDKs;
• repository ports remain inward-facing.

#Events

• runtime/domain/integration events remain semantically distinct;
• domain events originate from domain state changes;
• asynchronous integration eventually uses an outbox;
• consumers are idempotent.

#Observability

• every request gets request_id and trace_id;
• Fiber isolation is proven;
• error classification is logged;
• safe correlation information reaches error responses;
• runtime events receive correlation stamps.

#Deployment

• candidate environment passes full-stack HTTP verification;
• traffic switches only after verification;
• rollback restores the previous color;
• SIGTERM and worker recycling are exercised;
• health/readiness semantics are explicit.

#MUST

• REQ-DEP-001 — Candidate Verification: deployment MUST verify the complete Caddy → Tengine → FrankenPHP → application path before traffic activation.
• REQ-DEP-002 — Blue/Green Safety: traffic MUST NOT switch to an unverified candidate.
• REQ-DEP-003 — Rollback: the previous known-good deployment MUST remain recoverable without rebuilding it.
• REQ-DEP-004 — Worker Recycling: worker recycling MUST preserve request isolation and service availability within the defined drain contract.
• REQ-OPS-001 — Health Semantics: liveness, readiness, and dependency health MUST have distinct semantics.
• REQ-OPS-002 — Structured Metrics: deployment and runtime MUST expose measurable availability, latency, error-rate, restart, and recycling metrics.
• REQ-ACC-001 — Contractor Acceptance: every MUST requirement in the SPEC MUST have an automated or reproducible acceptance test.

#SHOULD

• automated blue/green rollback testing;
• graceful-shutdown tests with in-flight requests;
• long-lived worker soak testing;
• deployment smoke tests using representative application routes rather than /health alone;
• deployment artifacts containing commit/build identity.

#COULD

• automated canary traffic before full color switch;
• OpenTelemetry-compatible tracing;
• generated operational dashboards;
• automated architecture-status publication as a release artifact.

#WON'T

• redesign the existing Anvil topology merely for stylistic simplification;
• introduce microservices solely to satisfy architectural layering;
• define arbitrary latency SLO numbers before production baseline data exists;
• consider /health → 200 alone sufficient evidence of a successful release.

Final architectural conclusion

Across Areas 1–12, the repository shows a consistent pattern:

The runtime/infrastructure architecture is substantially ahead of the application/domain layer.

The major work is therefore not rebuilding the framework. It is making the architecture enforceable while extending the Hub/application layer.

The highest-value contractor work is now:

1. Ring-boundary CI
        ↓
2. Fiber/request contamination tests
        ↓
3. Generated architecture status
        ↓
4. RequestContext + trace propagation
        ↓
5. Error-taxonomy CI enforcement
        ↓
6. ApplicationFactory
        ↓
7. Full-stack release verification
        ↓
8. Hub domain + repository ports
        ↓
9. Transaction + domain-event infrastructure
        ↓
10. Outbox when asynchronous integration is actually required

And importantly, several things should not be rebuilt:

• configuration immutability;
• TenantContext;
• repository-port pattern in Hub/config;
• ErrorHandler;
• Kernel lifecycle tests;
• existing freeze tests;
• worker recycling;
• blue/green deployment;
• graceful shutdown;
• Anvil's Caddy/Tengine/FrankenPHP topology.

Those are existing foundations to extend and verify.

This completes the architecture discovery phase. The next step is to consolidate Areas 1–12 into the contractor-ready SPEC-001-DGLab-Sovereign-Stack-Architecture, explicitly separating Current State, Required Hardening, and Future Implementation so contractors don't redo functionality that already exists.

you asked

Proceed. But analyze and verify this first from https://github.com/DGCodeIdeas/DGLab: From Z.ai:

Verifying Area 12. Before doing the substantive check, one critical observation:

Citation issue at the bottom of your message. The footnote [1] in this Area 12 message points to:

https://github.com/kafkade/anvil?utm_source=chatgpt.com
"GitHub - kafkade/anvil: A declarative cross-platform configuration management tool for workstations"

This is not the DGLab repo. It's a different, unrelated project (a YAML-based dev-environment configurator for workstations). The previous 11 areas all cited https://github.com/DGCodeIdeas/DGLab. This one citation is wrong. It doesn't invalidate the architect's substantive analysis (the claims about DGLab are consistent with the prior verifications), but it's a citation-hygiene issue worth flagging — if the SPEC inherits this link, contractors will be confused.

Now the substantive verification.

Verification Report — Area 12 (Final)

Same protocol. Verdict legend: ✅ Confirmed · ⚠️ Outdated/Partial · ❌ Wrong · 💬 Sound Opinion.

#"Deployment architecture is already substantially implemented"

✅ Confirmed (re-verified from Area 4). All three tiers exist with real configs:

• anvil/edge/Caddyfile (Caddy 2.11.4)
• anvil/lb/tengine.conf (Tengine 3.2.0)
• anvil/app/Caddyfile.blue + Caddyfile.green (FrankenPHP worker config)
• anvil/systemd/[email protected] (blue/green template unit)

#"Tengine's responsibilities are distinct"

✅ Confirmed (re-verified from Area 4). Six documented, non-overlapping responsibilities in tengine.conf:

1. Slow-client shielding (proxy_buffering on, 32×16k buffers, 64k busy_buffers)
2. Rate limiting (per_ip 20r/s, per_host 100r/s, conn_per_ip)
3. Real client IP restoration (real_ip module)
4. Upstream timing observability (log_format anvil with request_time, upstream_connect_time, upstream_response_time)
5. Dynamic blue/green routing (DYUPS, no reload)
6. On-Demand TLS gate (/_anvil/tls-allowed endpoint)

Caddyfile comment line 6 explicitly defers rate-limiting to Tengine: "rate limiting lives at the Tengine tier where limit_req is built in."

#"Repository already has deployment-time health/smoke verification"

✅ Confirmed. Three layers of deploy-time HTTP verification exist:

• anvil/provisioning/cloud-init.yaml: first-boot health gate polls https://localhost/health for 60s, refuses to mark provisioned if /health fails
• anvil/lib/deploy-smoke.sh: checks /health returns 2xx within 5s
• anvil/lib/verify.sh: verify/health checks /health with Tengine check_status rise>=2

So the architect's claim that "this proves primarily 'can the deployed stack answer?' rather than 'does the deployed stack implement the architecture we released?'" is exactly right. Smoke test exists; architecture verification at deploy time does not.

#"Blue/green infrastructure already exists"

✅ Confirmed. [email protected] is a systemd template unit (%i = blue|green). Boot order is enforced: anvil-secrets → anvil-frankenphp@blue → anvil-tengine → anvil-caddy. lib/deploy.sh orchestrates green-startup → smoke-test → traffic-shift → blue-drain.

#"Existing worker model already has bounded recycling"

✅ Confirmed. anvil/app/Caddyfile.blue has max_requests 500 (production), anvil/dev/Caddyfile.dev has max_requests 1000 (dev). systemd Restart=on-failure, RestartSec=2s, TimeoutStopSec=30s, KillSignal=SIGTERM.

#"Traffic MUST NOT be switched to a candidate merely because its process started successfully"

💬 Sound requirement, currently partially met. deploy.sh does run smoke tests before traffic switch, but I don't see explicit architecture-verification gates in the deploy flow. The architect's REQ-DEP-002 recommendation is the right contract.

#REQ-DEP-001 through REQ-OPS-002

Status against repo:

1 of 7 fully met, 4 partial, 2 unmet.

#SLO metrics table

💬 Sound — and correctly avoids the trap of hard-coding arbitrary latency numbers. The architect's 10 metrics (availability, P50/P95/P99 latency, 5xx rate, worker recycling, restart rate, health recovery, deployment rollback, state contamination) are exactly the right set for a persistent-worker architecture. The architect's explicit refusal to invent latency targets before baseline data exists is the right discipline — directly addresses a common SPEC failure mode.

#Contractor acceptance boundary (the 6 categories)

All six categories (Architecture / Runtime / Application / Events / Observability / Deployment) map cleanly to the gaps identified across Areas 1–11:

The acceptance boundary correctly captures the genuine work.

#The 10-item contractor priority list

✅ Accurate and correctly ordered. Cross-checking against all 12 areas of verification:

1. Ring-boundary CI — unmet, highest leverage (closes the gap between Wheel-as-documentation and Wheel-as-contract)
2. Fiber/request contamination tests — unmet, second-highest leverage (the persistent-worker bug class)
3. Generated architecture status — unmet, closes the README drift (Areas 1, 5, 11)
4. RequestContext + trace propagation — unmet, closes the largest observability gap (Area 10)
5. Error-taxonomy CI enforcement — doctrine exists, CI rule doesn't (Area 10)
6. ApplicationFactory — unmet (Area 7)
7. Full-stack release verification — partial, needs comprehensive gate (Areas 11, 12)
8. Hub domain + repository ports — pattern exists in Hub/config, needs extending (Area 8)
9. Transaction + domain-event infrastructure — infrastructure (Transaction.php) exists, no application usage yet (Areas 8, 9)
10. Outbox when async is actually required — unmet, but correctly deferred to "when needed" (Area 9)

This list is correct and DAG-honest. Each item depends on prior items in the order given.

#"Things that should not be rebuilt"

✅ All 10 items verified as already implemented across Areas 1–11. Each one was cross-checked in a prior verification:

The "should not be rebuilt" list is exactly the right defensive list — it prevents contractors from redoing existing work.

#WON'T items

💬 All four are correct:

• WON'T redesign the existing Anvil topology — correct, Tengine's six responsibilities are documented (Area 4)
• WON'T introduce microservices solely for layering — correct, the monorepo + ring-boundary CI is the right tool
• WON'T define arbitrary latency SLOs before baseline data — correct, the measurement-contract-first discipline
• WON'T consider /health → 200 alone sufficient — correct, this is precisely the gap REQ-DEP-001 closes

Confirmed. The architect's final-area framing is exactly right: "the deployment architecture is already substantially implemented; the goal is to turn that machinery into explicit, measurable release contracts."

Three minor items:

1. The footnote [1] citation is wrong — points to kafkade/anvil, not DGCodeIdeas/DGLab. Fix before SPEC publication.

2. REQ-DEP-001 and REQ-DEP-002 are partially met by existing deploy.sh + deploy-smoke.sh + cloud-init.yaml. The SPEC should describe them as "extend existing smoke-test pipeline to comprehensive architecture verification gate," not "introduce deployment verification from scratch."

3. REQ-DEP-004 (worker recycling preserves isolation) — infrastructure exists, no test exists. This is a sub-case of REQ-TEST-003 (Fiber contamination tests), and the two can be tested together: spawn a worker, run request A with state X, recycle (hit max_requests), run request B with state Y, assert state(A) ∩ state(B) = ∅. One test closes both requirements.

Over the 12 areas, the verification has produced a consistent picture:

#Architectural thesis (correctly identified by the architect across multiple areas)

The runtime/infrastructure architecture is substantially ahead of the application/domain layer. Verified in:

• 11 Core packages implemented vs 1 Hub, 1 Bridge, 1 Spoke/Int, 1 Spoke/Ext
• Anvil trio fully operational vs Hub at depth 1–2
• Worker recycling, blue/green, graceful shutdown all implemented vs no Hub application services

#What's already implemented (verified across all areas)

• Six-ring Wheel architecture (dependency inwardness documented)
• Container with singleton/pulse/transient + WeakMap<Fiber, ...> (ADR-017)
• Frozen router/middleware pipeline
• Kernel 6-state lifecycle
• Immutable configuration (ConfigBuilder frozen + readonly array)
• Encryption at depth 2 (AES-256-GCM + Argon2id + HKDF-SHA256 + sodium_memzero + SensitiveParameterValue)
• Basic DBAL (Connection, Transaction, QueryBuilder, TenantContext, TypeMapper)
• TenantContext as constructor-injected immutable value object (no static accessor — the anti-pattern the architect worried about doesn't exist)
• Repository-port pattern proven in Hub/config
• 5-class error taxonomy (Transient/Permanent-External/Permanent-Local/Corrupt/Panic) — doctrine-binding
• ErrorHandler with all 8 persistent-worker-safe properties
• Event stamp mechanism (append-only audit trail — foundation for trace metadata)
• Per-package tests/ tree (15 packages)
• PHPUnit 11 + PHPStan 2.x at level: max + bleedingEdge.neon
• Kernel state machine: 16 test methods (positive + negative transitions)
• Freeze tests for Router, Middleware pipeline, Configuration
• Architecture-lint CI workflow (3 checks: reference validity, misattribution, structure)
• Anvil trio: Caddy + Tengine + FrankenPHP with documented responsibilities
• Worker recycling (max_requests 500)
• Blue/green deployment (systemd template unit + deploy.sh)
• Graceful shutdown (SIGTERM + TimeoutStopSec=30s)
• Deploy-time smoke tests (cloud-init.yaml, deploy-smoke.sh, verify.sh)
• ADR-003 (ES256 JWT) + ADR-008 (Argon2id) — both Accepted with full alternatives-considered

#Genuine gaps (verified across all areas)

1. Ring-boundary CI rule — architecture-lint runs 3 checks but doesn't inspect PHP use statements for ring violations
2. Worker/Fiber contamination tests — zero contamination/isolation tests in packages/
3. Machine-generated ARCHITECTURE_STATUS.md — README manually maintained and contradictory (MUWV vs pre-MUWV, 5-of-8 vs 8-of-8, "Not started" vs "Complete", "503 placeholder" vs working entrypoint)
4. RequestContext value object — no class exists; trace_id propagation is zero in application code (Tengine logs x_request_id but app doesn't read it)
5. Error-class-in-log-line CI rule — doctrine is binding, but no automated check enforces it
6. ApplicationFactory — composition stays in public/index.php (274 lines, 21 direct new/register/pipe calls)
7. Three-tier health split — single /health endpoint conflates liveness/readiness/dependency
8. SIGTERM-with-in-flight-requests test — graceful shutdown configured but not tested
9. Full-stack HTTP verification gate — smoke test exists, comprehensive architectural gate doesn't
10. Service-locator CI rule — anti-pattern not used anywhere, but not formally enforced

#Forward-looking items (correctly deferred by architect)

• Outbox pattern (when async integration arrives)
• Hub domain model (when CORE-15/14/19 + Hub blueprints land)
• Repository ports for persistence (extend the Hub/config pattern)
• Transaction ownership by application services (when application services exist)
• Domain event recording (releaseEvents() pattern on aggregates)
• Three semantic event categories (runtime/domain/integration) — when Hub aggregates exist
• W3C traceparent propagation (when distributed tracing is needed)

#Number corrections the architect absorbed across the 12 areas

• Core packages: 8 → 11
• ADRs: 19 → 20
• Total blueprints: 105 → 102 (per INDEX canonical)
• Spoke blueprints: 45 → 46 (27 Internal + 18 External + 1 Bridge)
• PHPUnit version: 10.5 → 11.0
• CORE-16 Encryption: "not mature" → depth 2 implemented
• CORE-19 DBAL: "future" → basic implementation exists
• Config immutability: "gap" → already implemented

#Single most important governance principle (correctly identified by the architect)

"Architecture status must be derived from executable repository state wherever technically possible; manually maintained documents may describe intent, but cannot be authoritative about implementation status."

This is the right north star. The existing architecture-lint.yml workflow already follows this principle for 3 narrow checks (reference validity, misattribution, structure). Extending it to cover (a) ring-boundary imports, (b) error-class in log lines, (c) status generation from packages/ directory — closes the README drift problem at its root.

Transmit four items:

1. Fix the [1] citation in Area 12 — currently points to kafkade/anvil (wrong repo). All SPEC citations must point to DGCodeIdeas/DGLab.

2. The 10-item contractor priority list is correct and DAG-honest. Keep it as the SPEC's implementation-order backbone. Each item genuinely depends on prior items in the order given.

3. The "should not be rebuilt" list is correct. Keep it as a defensive list at the front of the SPEC to prevent contractors from redoing existing work. Every one of the 10 items was verified as already implemented.

4. Distinguish "extend existing" from "introduce new" explicitly in the SPEC. Several requirements the architect proposes are partially met — REQ-TEST-004 (Kernel lifecycle tests, 16 methods exist), REQ-TEST-005 (freeze tests, 3 components covered), REQ-DEP-001 (smoke test exists), REQ-DEP-002 (smoke-before-switch exists), REQ-DEP-003 (blue/green rollback implicit), REQ-DEP-004 (worker recycling infrastructure exists), REQ-OPS-002 (metrics scattered across 3 systems). Without this distinction, contractors will rebuild existing functionality. The architect's stated Area 6 commitment to "distinguish existing DGLab behavior from recommended target-state changes" is exactly the right framing — but it matters most for these partially-met items.

When you receive the consolidated SPEC-001-DGLab-Sovereign-Stack-Architecture (the architect's stated next deliverable), I'll do a final verification pass against the actual repo before you commit it to contractors.

chatgpt response

The Area 12 verification is accepted. I also corrected the citation issue: the final specification below references the actual DGLab repository rather than the unrelated kafkade/anvil project.

The final SPEC deliberately distinguishes implemented, extend, and new work so contractors do not rebuild existing infrastructure. The current repository evidence supports the central thesis: DGLab has a comparatively mature runtime/deployment foundation, while the Hub/application/domain layer and executable architecture enforcement are the main areas requiring further work.

**Document Title: **

SPEC-001-DGLab-Sovereign-Stack-Architecture

DGLab — Sovereign Stack is a PHP 8.4 monorepo/framework built around a six-ring Wheel Architecture:

Outer Rim
   ↓
Outer Spokes
   ↓
Inner Rim
   ↓
Inner Spokes
   ↓
Hub
   ↓
Core

Dependencies are intended to point inward. The repository currently contains 11 implemented Core packages, a partially implemented Hub, Bridge/Spoke packages, and a substantial Anvil deployment/runtime layer.

The runtime architecture is significantly more mature than the application/domain layer. Existing infrastructure includes:

• persistent FrankenPHP workers;
• Fiber-scoped dependency lifetimes;
• immutable/frozen runtime structures;
• a six-state Kernel lifecycle;
• immutable configuration;
• cryptographic primitives;
• basic DBAL;
• PSR-14 event dispatching;
• persistent-worker-safe error handling;
• Caddy → Tengine → FrankenPHP deployment;
• blue/green deployment;
• worker recycling;
• graceful shutdown;
• deployment smoke tests;
• package-level PHPUnit tests;
• PHPStan maximum-level static analysis;
• architecture-lint CI.

The principal architectural risk is therefore not missing infrastructure. It is that several important architectural rules currently exist primarily as documentation, convention, or doctrine rather than executable repository contracts.

Examples include:

• ring dependency direction is documented but not enforced against PHP imports;
• worker/Fiber isolation is implemented but lacks dedicated contamination tests;
• error taxonomy is binding doctrine but lacks complete CI enforcement;
• request correlation has no RequestContext;
• composition remains concentrated in public/index.php;
• implementation status is manually documented and has contradictory statements;
• deployment smoke tests verify /health, but do not constitute a comprehensive release architecture gate;
• Hub domain/application/persistence depth remains largely future work.

The purpose of this specification is therefore to preserve the existing architecture, make its important invariants executable, and provide a contractor-ready path for extending the Hub/application layer without weakening the Core/runtime design.

#Current-state evidence rule

Implementation status MUST be established from executable repository state wherever technically possible.

Documentation MAY describe architectural intent, but manually maintained documentation MUST NOT be treated as authoritative evidence that a component is implemented.

The canonical repository is:

urlDGCodeIdeas/DGLab on GitHubhttps://github.com/DGCodeIdeas/DGLab

T

REQ-ARCH-001 — Six-ring dependency enforcement

The six-ring dependency direction MUST be enforced against actual PHP source imports in CI.

Allowed direction:

Core
  ↑
Hub
  ↑
Inner Spokes
  ↑
Outer Spokes / Bridges
  ↑
Application / Composition Root

An inner ring MUST NOT import an outer ring.

At minimum, CI MUST reject:

Core → Hub
Core → Spoke
Core → Bridge
Core → Application

Hub → Spoke
Hub → Bridge
Hub → Application

Domain → HTTP implementation
Domain → SQL/database driver
Domain → external SDK
Domain → controller

The root composition/application boundary MAY assemble all enabled packages.

Status: Extend existing architecture-lint CI.

REQ-ARCH-002 — No service locator

Production code in packages/ and app/ MUST NOT introduce service-locator access such as:

$container->get(...)
$container->make(...)
Container::getInstance()
global app(...)

The current repository already follows this convention.

Status: Existing behavior; add executable CI enforcement.

REQ-RUNTIME-001 — Fiber/request isolation

Request-scoped state MUST be isolated between concurrent Fibers and sequential persistent-worker requests.

No request may observe another request's:

• DI pulse instances;
• tenant context;
• request context;
• event state;
• logging context;
• error state;
• mutable request data.

Status: Infrastructure exists; dedicated contamination tests are required.

REQ-RUNTIME-002 — Explicit DI lifetimes

DI objects MUST explicitly belong to one of:

Worker / Singleton
Pulse / Fiber / Request
Transient

Request-scoped objects MUST NOT be stored in worker-global mutable state.

Status: Existing container model; enforce through tests and code review.

REQ-RUNTIME-003 — Kernel lifecycle contract

The Kernel lifecycle MUST preserve:

Unbooted
   ↓
Booting
   ↓
Booted
   ↓
Handling
   ↓
Booted
   ↓
Terminating
   ↓
Terminated

Invalid transitions MUST fail deterministically.

Status: Existing tests substantially satisfy this requirement; extend for concurrent handling semantics.

REQ-RUNTIME-004 — Frozen runtime structures

Runtime structures that are frozen after activation MUST reject mutation after freezing.

The existing pattern covers:

• Router;
• Middleware pipeline;
• Configuration.

Future compiled runtime structures MUST use the same invariant.

Status: Existing tests; extend pattern for future structures.

REQ-APP-001 — Composition boundary

Application composition MUST remain outside Core and Hub.

The composition root MAY depend on all enabled application packages and infrastructure adapters.

Core and Hub MUST NOT know how they are assembled.

Status: Already satisfied in practice; formalize with CI.

REQ-APP-002 — Thin HTTP entry point

public/index.php MUST contain only process/bootstrap concerns.

Application construction, registration, route composition, middleware composition, and infrastructure wiring MUST move behind an ApplicationFactory or equivalent composition API.

Target:

public/index.php
       │
       ▼
ApplicationFactory
       │
       ├── Core
       ├── Hub
       ├── Spokes
       ├── Bridges
       ├── Infrastructure
       ├── Middleware
       └── Routes
       │
       ▼
Kernel

The factory MUST remain an assembly component rather than a business-logic container.

Status: New implementation.

REQ-DOM-001 — Domain isolation

Hub domain code MUST NOT depend on:

• HTTP implementations;
• controllers;
• SQL;
• DB drivers;
• vendor SDKs;
• transport protocols;
• framework-specific infrastructure.

Domain code owns business invariants.

Status: Architectural boundary to preserve as Hub expands.

REQ-DOM-002 — Repository ports

Persistence repository interfaces MUST be defined inward, at the domain/application boundary.

Implementations MUST live in infrastructure/adapters.

The existing Hub/config repository pattern is the reference implementation:

FeatureFlagRepositoryInterface
        ↑
InMemoryFeatureFlagRepository

The same pattern SHOULD be extended to real persisted aggregates.

Status: Existing pattern; extend.

REQ-DOM-003 — Persistence adapters

Database persistence MUST be implemented outside domain objects.

Core DBAL provides technical database capability; it MUST NOT become the domain programming model.

Status: DBAL exists; persistence adapters are future Hub work.

REQ-DOM-004 — Transaction ownership

Application services MUST own transaction boundaries.

A typical command transaction is:

begin
  ↓
load aggregate
  ↓
invoke domain behavior
  ↓
persist aggregate
  ↓
record integration/outbox state
  ↓
commit

Repositories MUST NOT silently create independent transaction boundaries.

Status: Core transaction primitive exists; application usage is future work.

REQ-DOM-005 — Tenant isolation

Tenant identity MUST be represented through immutable constructor-injected context.

Domain code MUST NOT obtain tenant identity through static/global access.

The existing TenantContext value object is the reference pattern.

Status: Already satisfied by existing design; extend to new persistence/application components.

REQ-EVT-001 — Runtime event isolation

Runtime events MUST remain runtime lifecycle signals.

They MUST NOT become an implicit business workflow orchestration mechanism.

Examples include:

BootEvent
RequestReceivedEvent
ResponseReadyEvent
TerminateEvent

Status: Existing design.

REQ-EVT-002 — Domain events

Domain events MUST originate from domain state transitions.

They MUST NOT depend on HTTP, databases, brokers, or external SDKs.

Status: Future Hub implementation.

REQ-EVT-003 — Integration events

Integration events MUST be explicit versioned contracts.

External consumers MUST NOT receive aggregate/entity objects directly.

Example:

OrderPlaced.v1

rather than:

OrderAggregate

Status: Future implementation.

REQ-EVT-004 — Atomic outbox

When asynchronous integration is introduced, business state and the corresponding outbox record MUST be committed atomically.

Minimum outbox model:

CREATE TABLE outbox (
    id              UUID PRIMARY KEY,
    aggregate_type  VARCHAR(100) NOT NULL,
    aggregate_id    VARCHAR(100) NOT NULL,
    event_type      VARCHAR(200) NOT NULL,
    event_version   SMALLINT NOT NULL,
    payload         JSONB NOT NULL,
    occurred_at     TIMESTAMPTZ NOT NULL,
    available_at    TIMESTAMPTZ NOT NULL,
    published_at    TIMESTAMPTZ NULL,
    attempt_count   INTEGER NOT NULL DEFAULT 0,
    last_error      TEXT NULL
);

CREATE INDEX idx_outbox_publish
    ON outbox (published_at, available_at);

CREATE INDEX idx_outbox_aggregate
    ON outbox (aggregate_type, aggregate_id);

The outbox MUST NOT be implemented merely because the framework has events; it becomes mandatory when reliable asynchronous integration is required.

Status: Future implementation.

REQ-EVT-005 — At-least-once delivery

Asynchronous integration MUST assume at-least-once delivery.

Consumers MUST be idempotent using an event identifier.

A consumer may maintain:

CREATE TABLE processed_messages (
    event_id      UUID NOT NULL,
    consumer      VARCHAR(200) NOT NULL,
    processed_at  TIMESTAMPTZ NOT NULL,
    PRIMARY KEY (event_id, consumer)
);

Status: Future implementation.

REQ-ERR-001 — Five-class error taxonomy

Application failures MUST map to the existing canonical taxonomy:

Transient
Permanent-External
Permanent-Local
Corrupt
Panic

The taxonomy MUST NOT be replaced by independent per-package interpretations.

Status: Existing binding doctrine.

REQ-ERR-002 — Error-class enforcement

Every application error log MUST identify its canonical error class.

CI SHOULD verify that declared exception/error mappings conform to the five-class taxonomy.

Status: New executable enforcement.

REQ-ERR-003 — Worker-safe error handling

No uncaught error path may intentionally contaminate persistent worker state.

Error handling MUST remain safe if logging or rendering itself fails.

Status: Existing ErrorHandler implementation; add contamination/fitness tests.

REQ-OBS-001 — RequestContext

Introduce an immutable RequestContext following the existing TenantContext value-object pattern.

Minimum fields:

request_id
trace_id
tenant_id nullable
started_at

No static/global accessor is permitted.

Status: New implementation.

REQ-OBS-002 — Fiber isolation of RequestContext

RequestContext MUST be associated with the active Fiber/request.

The existing WeakMap<Fiber, ...> approach SHOULD be reused rather than introducing another global state mechanism.

Status: New implementation using existing infrastructure.

REQ-OBS-003 — Correlated error responses

Safe correlation information MUST be available to clients when an application error occurs.

Responses MUST NOT expose:

• stack traces;
• source paths;
• internal SQL;
• secrets;
• internal exception details.

Status: Partial; generic error handling exists, correlation ID does not.

REQ-OBS-004 — Structured request observability

Application logs SHOULD consistently expose:

request_id
trace_id
route
HTTP method
status
duration
error class

The application-side fields MUST align with edge-layer observability.

REQ-OBS-005 — Event correlation

Runtime events SHOULD receive:

request_id
trace_id

using the existing immutable Event::stamp() mechanism.

The stamp mechanism is an audit trail, not the authoritative source of request context.

Status: Existing event mechanism; correlation integration is new.

REQ-GOV-001 — Generated architecture status

Implementation status MUST be generated from repository state wherever technically possible.

The generator SHOULD inspect:

packages/
Architecture/
blueprints/
tests/
CI configuration

and produce:

ARCHITECTURE_STATUS.md

Human-authored documents MAY describe intent, roadmap, or rationale but MUST NOT override generated implementation status.

Status: New implementation.

REQ-TEST-001 — Package contract tests

Every implemented Core package MUST have meaningful tests covering its public contract.

Status: Substantially satisfied.

REQ-TEST-002 — Ring-boundary fitness test

CI MUST parse actual PHP source imports and fail on forbidden ring dependencies.

This MUST be a blocking pull-request check.

Status: New implementation.

REQ-TEST-003 — Persistent-worker contamination tests

Tests MUST execute multiple requests/Fibers with deliberately different state and prove that:

state(request A) ∩ state(request B) = ∅

At minimum test:

• DI pulse state;
• tenant context;
• RequestContext;
• event stamps;
• logging context;
• error context.

Status: New implementation.

REQ-TEST-004 — Existing lifecycle test extension

Existing Kernel state-machine tests MUST remain passing.

Additional concurrent handle() behavior MUST be explicitly defined and tested.

Status: Existing tests; extend.

REQ-TEST-005 — Existing freeze-test extension

Existing Router, Middleware, and Configuration freeze tests MUST remain passing.

New immutable runtime structures MUST receive equivalent tests.

Status: Existing tests; extend.

REQ-TEST-006 — Architecture checks are blocking CI

Architecture fitness checks MUST run as blocking CI gates.

The existing architecture-lint workflow MUST be extended rather than replaced.

Status: Partial; extend coverage.

REQ-PROD-001 — Full-stack release verification

A release candidate MUST pass verification through:

Caddy
 → Tengine
 → active FrankenPHP worker
 → Kernel
 → Middleware
 → Router
 → application endpoint
 → HTTP response

/health → 200 alone MUST NOT constitute release acceptance.

Status: Partial; existing smoke test must be extended.

REQ-DEP-001 — Candidate verification before activation

Blue/green candidates MUST pass release verification before traffic is switched.

Status: Partial; existing smoke-before-switch behavior should be extended.

REQ-DEP-002 — Safe traffic switching

Traffic MUST NOT switch merely because the candidate process started.

The candidate MUST pass health and application verification first.

Status: Partial; extend existing deploy pipeline.

REQ-DEP-003 — Rollback

The previous known-good deployment MUST remain selectable without rebuilding it.

Existing blue/green deployment SHOULD remain the rollback mechanism.

Status: Existing capability; formalize and test.

REQ-DEP-004 — Worker recycling safety

Worker recycling MUST preserve request isolation and service availability according to the defined drain contract.

Status: Recycling exists; test it together with contamination testing.

REQ-OPS-001 — Health semantics

Health endpoints MUST distinguish:

Liveness
Readiness
Dependency health

A dependency failure MUST NOT necessarily imply process liveness failure.

Status: New implementation.

REQ-OPS-002 — Operational metrics

The deployment/runtime system MUST expose measurable:

• availability;
• P50 latency;
• P95 latency;
• P99 latency;
• 5xx rate;
• worker restart rate;
• worker recycling rate;
• health recovery time;
• deployment rollback time.

Numerical SLO thresholds MUST be established from representative production baselines rather than invented prematurely.

Status: Partial; existing metrics/logs need a unified contract.

REQ-ACC-001 — Requirement-to-test traceability

Every MUST requirement MUST have at least one:

• automated test;
• architecture fitness test;
• deployment test;
• or reproducible operational acceptance procedure.

A release MUST NOT be accepted solely on manual inspection.

Status: New governance mechanism.

#SHOULD

• W3C traceparent propagation when distributed tracing becomes necessary.
• Automated blue/green rollback testing.
• SIGTERM tests with in-flight requests.
• Long-lived worker soak tests.
• Application-route deployment smoke tests.
• Release/build identity in deployment artifacts.
• Generated architecture diagrams.
• Generated operational dashboards.
• Architecture verification results as CI artifacts.

#COULD

• Canary traffic before full blue/green activation.
• OpenTelemetry-compatible tracing.
• Automated architecture-status publication.
• A shared architecture-contract test library.

#WON'T

• Redesign Anvil merely for stylistic simplification.
• Remove Tengine solely because Caddy already exists.
• Introduce microservices merely to satisfy layering.
• Define arbitrary latency targets before representative baseline measurements.
• Use code-coverage percentage as the primary architecture-quality metric.
• Treat passing unit tests as proof of ring compliance.
• Treat /health → 200 as sufficient release verification.
• Treat manually maintained README status as authoritative implementation status.
• Introduce an outbox before asynchronous integration actually requires it.
• Allow runtime events to become an implicit business orchestration bus.

#1. Target architecture

@startuml
skinparam componentStyle rectangle

package "Application / Composition Root" {
  [ApplicationFactory]
  [Routes]
  [Application Services]
}

package "Outer Spokes" {
  [External Adapters]
}

package "Inner Spokes" {
  [Infrastructure Adapters]
}

package "Hub" {
  [Domain]
  [Application]
  [Repository Ports]
  [Domain Events]
}

package "Core" {
  [Kernel]
  [Container]
  [Router]
  [Middleware]
  [DBAL]
  [Event Dispatcher]
  [Error Handler]
  [Logger]
  [HTTP Message]
  [Crypto]
}

[ApplicationFactory] --> [Application Services]
[ApplicationFactory] --> [External Adapters]
[ApplicationFactory] --> [Infrastructure Adapters]
[ApplicationFactory] --> [Core]

[Application Services] --> [Domain]
[Application Services] --> [Repository Ports]

[Infrastructure Adapters] --> [Repository Ports]
[Infrastructure Adapters] --> [DBAL]

[External Adapters] --> [Core]
[Infrastructure Adapters] --> [Core]

[Domain] --> [Core]
@enduml

The composition root is intentionally the exception to the inward dependency rule: it assembles the system.

Core MUST NOT depend on application code.

#2. Composition boundary

Current:

public/index.php
 ├── constructs Core services
 ├── registers dependencies
 ├── registers controllers
 ├── registers middleware
 ├── registers routes
 ├── constructs Kernel
 └── boots Kernel

Target:

@startuml
actor HTTP

HTTP --> "public/index.php"
"public/index.php" --> ApplicationFactory

ApplicationFactory --> Core
ApplicationFactory --> Hub
ApplicationFactory --> "Inner Spokes"
ApplicationFactory --> "Outer Spokes"
ApplicationFactory --> Bridges
ApplicationFactory --> Kernel

Kernel --> Middleware
Kernel --> Router
Kernel --> ApplicationServices
@enduml

public/index.php should eventually be limited to process entry and invocation of the composition boundary.

#3. Request lifecycle

@startuml
participant Caddy
participant Tengine
participant FrankenPHP
participant Kernel
participant Middleware
participant Router
participant Application
participant Logger

Caddy -> Tengine: HTTP request
Tengine -> FrankenPHP: proxied request

FrankenPHP -> Kernel: RequestReceived
Kernel -> Kernel: create RequestContext
Kernel -> Middleware: handle(request)
Middleware -> Router: match(request)
Router -> Application: invoke handler
Application --> Router: response
Router --> Middleware: response
Middleware --> Kernel: response

Kernel -> Logger: correlated structured log
Kernel --> FrankenPHP: response
FrankenPHP --> Tengine: HTTP response
Tengine --> Caddy: HTTP response
Caddy --> Caddy: access log
@enduml

RequestContext is the authoritative request correlation state.

Event::stamp() records correlation metadata on runtime events but does not replace RequestContext.

#4. RequestContext

final readonly class RequestContext
{
    public function __construct(
        public string $requestId,
        public string $traceId,
        public ?string $tenantId,
        public float $startedAt,
    ) {}
}

The exact implementation MAY use stronger identifier types later.

The important invariants are:

1. immutable;
2. constructor-injected;
3. no static current() accessor;
4. Fiber/request isolated;
5. disposed when the request completes.

#5. Dependency fitness algorithm

The architecture verifier SHOULD operate directly on PHP source.

Pseudo-algorithm:

for each PHP source file:
    determine owning ring from path
    parse namespace and use statements

    for each imported symbol:
        resolve imported namespace

        determine target ring

        if target ring is outward:
            report violation

        if forbidden technical dependency:
            report violation

fail CI if violations > 0

The implementation SHOULD use an AST parser where practical rather than regular expressions so aliases, grouped imports, fully-qualified references, and comments cannot create false positives.

#6. Worker/Fiber contamination test

Test structure:

@startuml
participant Test
participant FiberA
participant FiberB
participant Container

Test -> FiberA: request(A)
FiberA -> Container: pulse()
Container --> FiberA: state A

Test -> FiberB: request(B)
FiberB -> Container: pulse()
Container --> FiberB: state B

FiberA -> FiberA: read state
FiberB -> FiberB: read state

Test -> Test: assert A != B
Test -> Test: assert no cross-Fiber state
@enduml

The test MUST deliberately use distinct values so that leakage cannot be hidden.

Example:

tenant A = tenant-alpha
tenant B = tenant-beta

request A = req-alpha
request B = req-beta

service state A = A
service state B = B

#7. Hub persistence architecture

Target:

@startuml
package "Hub Domain" {
  [Aggregate]
  [Value Object]
  [Domain Event]
  [Repository Interface]
}

package "Hub Application" {
  [Command Handler]
  [Query Handler]
  [Application Service]
}

package "Infrastructure" {
  [Repository Implementation]
  [Outbox]
  [Transaction Adapter]
}

package "Core" {
  [DBAL]
}

[Command Handler] --> [Application Service]
[Application Service] --> [Aggregate]
[Application Service] --> [Repository Interface]

[Repository Implementation] ..|> [Repository Interface]
[Repository Implementation] --> [DBAL]
[Application Service] --> [Transaction Adapter]
[Application Service] --> [Outbox]

@enduml

Transaction ownership belongs to the application service.

#8. Transaction and outbox algorithm

BEGIN TRANSACTION

load aggregate

aggregate.execute(command)

collect domain events

persist aggregate

for each integration event:
    insert outbox record

COMMIT

publisher later:
    select unpublished events
    publish
    mark published

consumer:
    check event_id + consumer
    if already processed:
        acknowledge/no-op
    else:
        process
        record processed_messages

No external message broker call should be required for the atomic business-state transaction.

#9. Error handling

The existing ErrorHandler remains the worker-level safety mechanism.

The architectural contract becomes:

Throwable
   │
   ▼
classification
   │
   ├── Transient
   ├── Permanent-External
   ├── Permanent-Local
   ├── Corrupt
   └── Panic
   │
   ▼
structured logging
   │
   ├── request_id
   ├── trace_id
   └── error_class
   │
   ▼
safe HTTP response

Panic and Corrupt paths MUST receive stronger isolation/operator treatment than ordinary application failures.

#10. Deployment verification

Existing deployment smoke checks should be extended rather than replaced.

Target:

build artifact
    ↓
static analysis
    ↓
unit tests
    ↓
architecture fitness
    ↓
worker/Fiber tests
    ↓
candidate deployment
    ↓
/health
    ↓
readiness
    ↓
real application HTTP request
    ↓
correlation verification
    ↓
error-path verification
    ↓
traffic switch
    ↓
post-switch verification

Blue/green rollback remains the recovery mechanism.

#11. Status generation

Create a machine-readable architecture status generator.

Conceptually:

@startuml
[Repository] --> [Status Generator]

[Status Generator] --> [Package Scanner]
[Status Generator] --> [Blueprint Scanner]
[Status Generator] --> [Test Scanner]
[Status Generator] --> [CI Scanner]

[Package Scanner] --> [ARCHITECTURE_STATUS.md]
[Blueprint Scanner] --> [ARCHITECTURE_STATUS.md]
[Test Scanner] --> [ARCHITECTURE_STATUS.md]
[CI Scanner] --> [ARCHITECTURE_STATUS.md]
@enduml

The generated document should distinguish:

IMPLEMENTED
PARTIAL
SPECIFIED
PLANNED
MISSING

and should never claim implementation solely because a blueprint or README section exists.

Implementation MUST follow dependency order.

#Phase 1 — Architecture fitness foundation

1. Add PHP source import/ring analyzer.
2. Encode the six-ring allowed dependency matrix.
3. Add forbidden service-locator detection.
4. Add CI workflow gate.
5. Keep the existing architecture-lint checks.
6. Add regression fixtures containing deliberately forbidden imports.

Do not refactor application code until the fitness test can detect violations.

#Phase 2 — Worker/Fiber safety

1. Create contamination fixtures.
2. Run multiple Fibers with distinct tenant/request/service state.
3. Assert isolation.
4. Test sequential requests in the same worker.
5. Test worker recycling behavior.
6. Add SIGTERM/in-flight-request test where the deployment environment permits it.
7. Add long-lived soak test infrastructure.

#Phase 3 — Architecture status generation

Implement:

Architecture/Verification/status.php

or an equivalent command.

It should inspect:

packages/
Architecture/
tests/
.github/workflows/

and emit:

ARCHITECTURE_STATUS.md

CI MUST fail if generated status differs from the committed/generated artifact where the project chooses to commit it.

#Phase 4 — Request correlation

1. Implement immutable RequestContext.
2. Extend the existing TenantContext design principles.
3. Store RequestContext using Fiber-local state.
4. Generate/accept request ID.
5. Generate/propagate trace ID.
6. Attach correlation metadata to logger context.
7. Stamp runtime events using Event::stamp().
8. Return safe correlation ID on errors.
9. Ensure cleanup after request completion.
10. Add concurrent isolation tests.

#Phase 5 — Error taxonomy enforcement

1. Define canonical error-class representation.
2. Map existing error paths to the taxonomy.
3. Include class in structured logs.
4. Add CI checks for required classification.
5. Add tests for each class.
6. Verify retry/breaker/HTTP semantics against the existing doctrine.

Do not create a second competing error taxonomy.

#Phase 6 — ApplicationFactory

Extract composition from public/index.php.

Suggested structure:

app/
  Application/
    ApplicationFactory.php
    Providers/
      CoreProvider.php
      HubProvider.php
      SpokeProvider.php
      BridgeProvider.php
      InfrastructureProvider.php

Do not create all providers immediately if the resulting abstraction is artificial.

Initial implementation may contain one factory and split only when complexity warrants it.

#Phase 7 — Health and release verification

Split health semantics:

/live
/ready
/health/dependencies

Exact URI names may be adjusted to existing operational conventions.

Add release checks for:

• active color;
• application route;
• response contract;
• request ID;
• trace ID;
• expected status;
• worker health;
• dependency readiness.

Extend deploy.sh rather than replacing the existing blue/green mechanism.

#Phase 8 — Hub domain foundation

Only after the preceding architectural protections are in place:

1. Define first real aggregate.
2. Define value objects.
3. Define repository port.
4. Define application service.
5. Define persistence adapter.
6. Define transaction boundary.
7. Add aggregate tests.
8. Add repository contract tests.
9. Add integration tests.

The concrete database schema MUST follow the selected domain model.

Do not invent generic business tables before a concrete Hub aggregate exists.

#Phase 9 — Domain events

Implement:

Aggregate
  ↓
record domain event
  ↓
Application Service
  ↓
transaction
  ↓
persistence + outbox

Do not make PSR-14 runtime events the business-event store.

#Phase 10 — Asynchronous integration

Only when an actual asynchronous integration requirement exists:

1. introduce outbox table;
2. implement publisher;
3. implement retry scheduling;
4. implement consumer idempotency;
5. implement dead-letter/operator handling;
6. test duplicate delivery;
7. test publisher failure;
8. test consumer failure;
9. test transaction rollback.

#Existing functionality that contractors MUST NOT rebuild

The following are existing foundations:

• configuration immutability;
• TenantContext;
• Hub/config repository-port pattern;
• persistent-worker-safe ErrorHandler;
• Kernel lifecycle implementation/tests;
• Router freeze behavior;
• Middleware freeze behavior;
• configuration freeze behavior;
• worker recycling;
• graceful shutdown;
• blue/green deployment;
• Caddy/Tengine/FrankenPHP topology;
• basic DBAL;
• encryption primitives;
• existing architecture-lint workflow.

The contractor's task is to extend, verify, and enforce these foundations.

#M1 — Architecture enforcement

Deliverables

• ring-boundary analyzer;
• service-locator rule;
• blocking CI integration;
• regression fixtures.

Acceptance

All forbidden dependency fixtures fail CI.

#M2 — Worker safety

Deliverables

• concurrent Fiber contamination suite;
• sequential persistent-worker tests;
• worker-recycling isolation test.

Acceptance

No cross-request state leakage.

#M3 — Architecture status

Deliverables

• status generator;
• generated ARCHITECTURE_STATUS.md;
• CI consistency check.

Acceptance

Implementation status is reproducible from repository state.

#M4 — Request observability

Deliverables

• RequestContext;
• Fiber-local storage;
• request/trace IDs;
• logger integration;
• event stamps;
• correlated error responses.

Acceptance

Two concurrent requests retain independent correlation state.

#M5 — Error contract

Deliverables

• error-class mapping;
• structured error logging;
• CI enforcement;
• taxonomy tests.

Acceptance

Every tested application failure maps to exactly one canonical class.

#M6 — Application composition

Deliverables

• ApplicationFactory;
• reduced public/index.php;
• composition tests.

Acceptance

Entry point contains no business/application registration logic.

#M7 — Operational readiness

Deliverables

• liveness/readiness/dependency health;
• comprehensive release smoke test;
• blue/green candidate gate;
• rollback test.

Acceptance

Unhealthy candidates cannot receive traffic.

#M8 — Hub domain foundation

Deliverables

• first real aggregate;
• repository port;
• persistence adapter;
• application service;
• transaction boundary.

Acceptance

Domain tests pass without HTTP/database-driver dependencies.

#M9 — Domain events

Deliverables

• aggregate event recording;
• domain event contracts;
• integration-event boundary.

Acceptance

Domain state transitions produce deterministic domain events without infrastructure coupling.

#M10 — Async integration, if required

Deliverables

• outbox;
• publisher;
• idempotent consumer;
• retry/dead-letter handling.

Acceptance

Business state and outbox commit atomically; duplicate delivery does not duplicate business effects.

Evaluation MUST focus on architectural invariants rather than raw code volume or coverage percentage.

#Architecture

Target:

Forbidden ring imports = 0
Service locator violations = 0
Undeclared architecture violations = 0

#Worker safety

Target:

Cross-request state leaks = 0
Cross-Fiber state leaks = 0
Unexpected worker contamination = 0

#Runtime

Measure:

worker restart rate
worker recycle rate
graceful shutdown success
request failure during recycling

#Observability

Every sampled production request SHOULD be traceable through:

request_id
trace_id
edge log
application log
runtime events
error response where applicable

#Error handling

Measure:

uncategorized errors = 0
error logs without error class = 0
unsafe error responses = 0

#Deployment

Measure:

candidate verification success rate
deployment rollback time
failed candidate traffic switches
health recovery time

A deployment MUST NOT be considered successful merely because /health returns HTTP 200.

#Performance

Record:

P50
P95
P99
5xx rate
request throughput
worker memory behavior
worker recycling behavior

Numerical SLO targets SHOULD be selected after representative baseline measurements.

The architecture specification deliberately does not invent latency targets.

#Contractor acceptance matrix

#Final architectural principle

DGLab should evolve according to the following rule:

Do not add architecture merely because the framework can support it. Add architecture when a concrete requirement needs it, and make every important architectural invariant executable.

The existing runtime should therefore be preserved.

The next major engineering effort is not a rewrite of Core or Anvil. It is the controlled transition from:

documented architecture

to:

executable architecture

and then from:

runtime foundation

to:

well-isolated Hub/domain/application functionality

That gives contractors a concrete implementation boundary while protecting the architecture already established in DGLab.

Please contact me at sammuti.com :)

This is the consolidated contractor-ready baseline. The most important implementation order is ring enforcement → worker/Fiber isolation → generated status → request correlation → error enforcement → ApplicationFactory → release verification → Hub/domain work.

you asked

Too large to copy-paste, Split into parts.

chatgpt response

Yes. I’ll split the final SPEC into 4 copy-pasteable parts, while keeping the sections in the required order.

Part 1: Background + Requirements
Part 2: Method — Architecture + Runtime
Part 3: Method — Events + Security + Deployment
Part 4: Implementation + Milestones + Gathering Results

I’ll keep each part self-contained enough to paste sequentially into one Markdown file, without repeating content.

you asked

Proceed

chatgpt response

Below is Part 1 of 4. It contains the document header, Background, and Requirements only.

**Document Title: **

SPEC-001-DGLab-Sovereign-Stack-Architecture

urlDGLab repositoryhttps://github.com/DGCodeIdeas/DGLab is a PHP 8.4 monorepok with explicit architectural boundaries.

The repository uses a six-ring "Wheel Architecture":

Outer Rim
   ↓
Outer Spokes
   ↓
Inner Rim
   ↓
Inner Spokes
   ↓
Hub
   ↓
Core

Dependencies are intended to point inward. ADR-004 formalizes this as a tier-enforcement DAG.

The current implementation shows that the runtime and infrastructure foundations are substantially more mature than the application/domain layer. The Core contains the principal runtime primitives, the Hub currently has configuration-oriented functionality, and the Spokes provide a larger collection of internal/external integration blueprints.

The existing implementation already provides several architectural foundations that must be preserved rather than rebuilt:

• PHP 8.4 runtime.
• Persistent FrankenPHP worker model.
• Fiber-isolated pulse/request instances.
• Immutable configuration after build.
• Immutable TenantContext.
• Repository-port pattern in existing Hub configuration code.
• Kernel lifecycle state machine.
• Router and middleware freezing after first use.
• Persistent-worker-safe global error handling.
• PSR-14 event dispatching.
• AES-256-GCM encryption and Argon2id key derivation.
• PostgreSQL-oriented DBAL abstractions.
• Caddy → Tengine → FrankenPHP deployment topology.
• Blue/green deployment.
• Graceful worker shutdown and recycling.
• PHPUnit/PHPStan-based testing.
• Blocking architecture-lint CI.

The principal architectural gap is therefore not a lack of infrastructure. It is that several architectural intentions are not yet executable constraints, while the Hub/domain/application layer has not yet been developed deeply enough to demonstrate the complete architecture.

The project also has documentation/status drift. In particular, README status statements conflict with executable repository state, while dependency documentation is not always synchronized with Composer and the actual package structure.

The next phase should therefore follow this principle:

Turn the existing architecture into enforceable contracts first, then build the Hub/domain layer without weakening those contracts.

The design must be contractor-implementable. A contractor should be able to determine:

1. which existing components must remain untouched;
2. which components must be extended;
3. which components must be introduced;
4. which architecture rules must be enforced automatically;
5. how deployment acceptance is determined; and
6. how production results are measured.

#Verification basis

The baseline in this specification incorporates the supplied file-level verification of the repository at HEAD a4a3402. Direct web search did not independently surface the repository files reliably, so this specification does not claim that the individual implementation details below were independently re-verified through web indexing.

Requirements use MoSCoW prioritization.

#MUST

M01 — Enforce ring dependency direction

The build/CI system MUST inspect actual PHP namespaces/imports and enforce the six-ring dependency DAG.

At minimum:

Core
  → Core / approved PSR / PHP extensions

Hub
  → Hub + Core

Inner Spokes
  → Inner Spokes + Hub + Core

External Spokes
  → External Spokes + Hub + Core

Bridge
  → Bridge + Hub + Core

Application
  → enabled application packages

Infrastructure
  → approved Core/Hub contracts

The following dependency directions MUST fail CI:

Core → Hub
Core → Spoke
Core → Bridge
Core → Application

Hub Domain → DBAL
Hub Domain → HTTP implementation
Hub Domain → controller
Hub Domain → SQL
Hub Domain → external SDK

Hub → Application
Hub → Spoke
Hub → Bridge

M02 — Establish an explicit composition root

Application composition MUST occur outside Core and Hub.

public/index.php MUST become a thin entry point delegating composition to an ApplicationFactory or equivalent application-level composition boundary.

The root composition layer may depend on all enabled rings.

Core MUST NOT become aware of application-specific implementations.

M03 — Prohibit Service Locator usage

Production application code MUST NOT resolve dependencies dynamically through a Service Locator.

Forbidden patterns include:

$container->get(...);
$container->make(...);
Container::getInstance();
app(...);

Dependency injection MUST be constructor/factory based.

CI MUST detect prohibited patterns rather than relying solely on code review.

M04 — Preserve persistent-worker isolation

The application MUST remain safe under persistent FrankenPHP workers.

Each request/pulse MUST receive isolated request-scoped state.

Tests MUST demonstrate that:

• request A cannot observe request B's state;
• Fiber A cannot observe Fiber B's state;
• tenant context cannot leak;
• request/trace correlation cannot leak;
• exceptions do not leave mutable state behind.

M05 — Preserve lifecycle and freezing invariants

Existing lifecycle and immutability guarantees MUST remain enforced.

The following MUST continue to have tests:

• Kernel lifecycle transitions.
• Router freeze-after-first-match.
• Middleware pipeline freeze-after-first-handle.
• Config freeze-after-build.
• Immutable TenantContext.

New mutable runtime structures MUST follow the same explicit lifecycle/freeze model where appropriate.

M06 — Introduce authoritative RequestContext

A request-scoped immutable RequestContext MUST be introduced.

It SHOULD contain at minimum:

request_id
trace_id
tenant_id
started_at

Optional metadata such as route name MAY be populated after routing.

The context MUST be Fiber/request isolated and MUST NOT use static global state.

It MUST integrate with the existing TenantContext design rather than replacing it with a global context accessor.

M07 — Enforce safe and classified error handling

The existing five-class error taxonomy MUST become executable architecture:

Transient
Permanent-External
Permanent-Local
Corrupt
Panic

Every operational error MUST map to one of these classes.

The existing doctrine MUST remain the canonical definition of the classes.

CI MUST verify that:

• exception/error handling identifies the appropriate class;
• log entries contain the class;
• Corrupt failures cannot silently become Transient;
• Panic failures trigger the required isolation/shutdown behavior;
• HTTP responses do not expose stack traces, internal filesystem paths, SQL, credentials, or other sensitive implementation details.

M08 — Separate runtime, domain, and integration events

Events MUST be semantically classified.

Runtime Events
    Core lifecycle/runtime concerns

Domain Events
    Hub business state transitions

Integration Events
    External/Bridge contracts

Runtime events MUST NOT become a substitute for business-domain orchestration.

Integration events MUST use explicit, versioned contracts.

M09 — Establish domain/persistence boundaries

The Hub domain MUST follow:

Entity
ValueObject
Aggregate
DomainEvent
DomainException
Repository interfaces

Persistence implementations MUST live outside the domain.

Repositories MUST be ports/interfaces owned by the appropriate domain/application boundary, with infrastructure adapters implementing them.

The application service MUST own the transaction boundary.

M10 — Separate health semantics

The current single /health concept MUST evolve into distinct health checks:

/health/live
/health/ready
/health/dependencies

/_anvil/ping remains infrastructure-specific.

Liveness MUST NOT depend on external services.

Readiness MAY verify required dependencies.

Detailed dependency information MUST be protected from uncontrolled public exposure.

M11 — Introduce a complete release verification gate

Traffic MUST NOT be switched to a new blue/green candidate merely because the FrankenPHP process started successfully.

Before traffic switching, the candidate MUST pass a full-stack verification path:

Caddy
  ↓
Tengine
  ↓
FrankenPHP
  ↓
Application

The gate MUST verify at least:

• liveness/readiness;
• representative application route;
• request/trace propagation;
• safe error responses;
• architecture fitness checks;
• application smoke tests;
• candidate health after startup;
• expected worker/runtime behavior.

Rollback MUST be possible by selecting the previous immutable deployment artifact.

M12 — Generate authoritative architecture status

Implementation status MUST be derived from executable repository state wherever technically possible.

A generated artifact such as:

ARCHITECTURE_STATUS.md

SHOULD be produced from:

• package directories;
• blueprint metadata;
• executable verification;
• tests;
• Composer configuration;
• architecture manifests.

Manually maintained README status MUST describe intent but MUST NOT be the authoritative source for implementation status.

M13 — Establish requirement-to-acceptance traceability

Every MUST requirement MUST have an executable acceptance criterion.

The project MUST maintain a traceability structure equivalent to:

Requirement
    ↓
Implementation
    ↓
Test / Fitness Check
    ↓
Deployment Verification

A requirement is not considered complete merely because code exists.

M14 — Verify graceful worker lifecycle behavior

The persistent worker MUST be tested for:

• SIGTERM;
• in-flight requests;
• worker recycling;
• startup after failure;
• shutdown completion;
• absence of request-state contamination after recycling.

Existing worker limits MUST be retained unless measured evidence requires adjustment.

#SHOULD

S01 — Support W3C trace context

The request context SHOULD support W3C traceparent propagation.

Incoming trace information SHOULD be validated and propagated downstream.

S02 — Introduce an outbox for asynchronous integration

When domain state changes must produce asynchronous integration events, an outbox SHOULD be used.

The design SHOULD provide at-least-once publication semantics with idempotent consumers.

S03 — Add operational chaos tests

The system SHOULD test:

• worker termination;
• dependency failure;
• health-check failure;
• blue/green candidate failure;
• rollback;
• SIGTERM during active traffic.

S04 — Automate rollback verification

CI/CD SHOULD periodically demonstrate that a known-good artifact can be restored without reconstructing the deployment manually.

S05 — Add persistent-worker soak testing

The system SHOULD run extended multi-request workloads to detect:

• memory growth;
• stale state;
• Fiber contamination;
• resource leaks;
• degradation over worker lifetime.

S06 — Consolidate observability

Logs, metrics and request correlation SHOULD converge on common:

request_id
trace_id
tenant_id

where appropriate and safe.

#COULD

C01 — Route compilation

The router COULD eventually support a compiled/frozen representation for production startup efficiency.

C02 — Expand freeze-contract coverage

Additional mutable infrastructure structures COULD adopt the existing freeze-after-first-use testing pattern.

C03 — Architecture status visualization

Generated architecture status COULD later feed a human-readable dashboard.

#WON'T

The following are explicitly outside this specification:

• Rebuilding the existing Core primitives.
• Redesigning the Anvil Caddy/Tengine/FrankenPHP topology.
• Introducing microservices merely to enforce architectural layering.
• Introducing arbitrary latency SLOs before production baselines exist.
• Treating /health returning HTTP 200 as sufficient release verification.
• Treating percentage code coverage as the primary architecture-quality metric.
• Using unit tests alone as proof of ring compliance.
• Treating the manually maintained README as authoritative implementation status.
• Using runtime events as business-domain orchestration.
• Coupling the Hub domain directly to vendor SDKs or infrastructure implementations.

Part 1 ends here. Part 2 will start directly with ## Method and cover the target architecture, composition root, dependency enforcement, persistent-worker/Fiber model, RequestContext, and runtime lifecycle.

you asked

Proceed

chatgpt response

**Document Title: **

SPEC-001-DGLab-Sovereign-Stack-Architecture

#1. Target Architecture

The existing six-ring Wheel Architecture remains the architectural foundation. This specification does not replace the Wheel; it makes its boundaries executable.

@startuml
skinparam componentStyle rectangle

component "Application\nComposition Root" as APP

package "Outer Rim" {
  component "External Infrastructure" as EXTINF
}

package "Outer Spokes" {
  component "External Spokes" as EXT
}

package "Inner Rim" {
  component "Infrastructure Adapters" as INFRA
}

package "Inner Spokes" {
  component "Internal Spokes" as INT
}

package "Hub" {
  component "Hub Application" as HUBAPP
  component "Hub Domain" as HUBDOM
}

package "Core" {
  component "Config" as CONFIG
  component "Container" as CONTAINER
  component "Crypto" as CRYPTO
  component "DBAL" as DBAL
  component "Error Handler" as ERROR
  component "Event Dispatcher" as EVENT
  component "HTTP Message" as HTTP
  component "Kernel" as KERNEL
  component "Logger" as LOGGER
  component "Middleware" as MIDDLE
  component "Router" as ROUTER
}

APP --> EXTINF
APP --> EXT
APP --> INT
APP --> INFRA
APP --> HUBAPP
APP --> HUBDOM
APP --> KERNEL

EXT --> HUBAPP
EXT --> HUBDOM
EXT --> CONFIG
EXT --> HTTP

INT --> HUBAPP
INT --> HUBDOM
INT --> CONFIG

INFRA --> HUBDOM
INFRA --> DBAL
INFRA --> CONFIG

HUBAPP --> HUBDOM
HUBAPP --> DBAL
HUBAPP --> EVENT

HUBDOM --> EVENT

KERNEL --> MIDDLE
KERNEL --> ROUTER
KERNEL --> EVENT
KERNEL --> ERROR
KERNEL --> HTTP

CONFIG --> CONTAINER
@enduml

The important rule is that dependencies point inward, while the application composition root is allowed to assemble the complete graph.

The diagram describes logical ownership. Actual namespace/package names MUST be mapped to this model through an architecture manifest used by CI.

#2. Current State vs Required Change

The implementation should be extended rather than reconstructed.

This distinction is mandatory for contractor implementation: existing functionality must not be recreated merely because it appears in the target architecture.

#3. Composition Root

public/index.php currently performs too much application composition.

The target structure is:

public/index.php
       |
       v
ApplicationFactory
       |
       +--> Container
       +--> Config
       +--> Logger
       +--> ErrorHandler
       +--> EventDispatcher
       +--> HTTP
       +--> Router
       +--> Middleware
       +--> Hub services
       +--> Infrastructure adapters
       |
       v
Kernel

@startuml
actor "Web Server" as SERVER

component "public/index.php" as INDEX
component "ApplicationFactory" as FACTORY
component "DI Container" as DI
component "Infrastructure" as INFRA
component "Hub Application" as HUB
component "Kernel" as KERNEL

SERVER --> INDEX
INDEX --> FACTORY
FACTORY --> DI
FACTORY --> INFRA
FACTORY --> HUB
FACTORY --> KERNEL
KERNEL --> DI
@enduml

public/index.php SHOULD ultimately be limited to:

1. loading the application factory;
2. creating the application;
3. invoking the kernel/runtime;
4. allowing the established error/shutdown infrastructure to operate.

The ApplicationFactory belongs at the application/infrastructure composition boundary, not inside Core.

#4. Dependency Injection Rules

The container remains an implementation mechanism rather than an application-facing global registry.

Dependencies SHOULD be expressed as:

final class SomeService
{
    public function __construct(
        private readonly RepositoryInterface $repository,
        private readonly LoggerInterface $logger,
    ) {}
}

Factories MAY receive the container when composition genuinely requires dynamic assembly, but runtime business/application objects MUST NOT use the container as a Service Locator.

CI SHOULD scan production PHP files for forbidden patterns.

The initial forbidden-pattern set is:

Container::getInstance(
->get(
->make(
app(
resolve(

The implementation MUST avoid false positives by analysing PHP AST/imports where practical rather than relying solely on textual grep.

#5. Ring-Boundary Fitness Test

The architecture-lint workflow MUST be extended from documentation checks into executable dependency analysis.

The algorithm is:

1. Discover all production PHP files.
2. Determine owning package/ring.
3. Parse namespace and use/import declarations.
4. Resolve imported classes/interfaces.
5. Determine the imported package/ring.
6. Compare source ring against allowed dependency set.
7. Fail CI on forbidden dependency.
8. Emit source → target → rule in the failure.

Example failure:

ARCH-BOUNDARY-001

Forbidden dependency:
packages/core/kernel/src/Kernel.php
    → DGLab\Hub\Application\ReleaseService

Rule:
Core MUST NOT depend on Hub.

Allowed targets:
Core, approved PSR interfaces, PHP extensions.

This test is an architecture fitness test, not a unit test.

The same mechanism SHOULD be extended to enforce:

• domain purity;
• prohibited infrastructure imports;
• prohibited vendor SDK imports;
• application composition boundaries.

#6. Architecture Manifest

A machine-readable manifest SHOULD define the ownership and dependency rules.

Conceptually:

rings:
  core:
    paths:
      - packages/core/*
    allowed:
      - core
      - psr
      - php-extension

  hub:
    paths:
      - packages/hub/*
    allowed:
      - hub
      - core

  inner-spokes:
    paths:
      - packages/spokes/internal/*
    allowed:
      - inner-spokes
      - hub
      - core

  external-spokes:
    paths:
      - packages/spokes/external/*
    allowed:
      - external-spokes
      - hub
      - core

  bridge:
    paths:
      - packages/spokes/bridge/*
    allowed:
      - bridge
      - hub
      - core

The exact package paths MUST be generated from the repository rather than blindly assuming these example paths.

This manifest becomes the input to the architecture-lint tool and the generated architecture-status document.

#7. Persistent Worker Runtime

The persistent FrankenPHP worker changes the correctness model.

A PHP process can serve many requests:

Worker
 ├── Request A
 ├── Request B
 ├── Request C
 └── Request D

Therefore, state that would normally disappear at process termination can survive between requests.

The existing container already distinguishes worker/singleton, pulse/Fiber/request, and transient lifetimes.

That model MUST be retained.

@startuml
participant "FrankenPHP Worker" as W
participant "Container" as C
participant "Fiber A" as A
participant "Fiber B" as B
participant "RequestContext A" as RCA
participant "RequestContext B" as RCB

W -> C: Resolve worker-scoped services

W -> A: Handle Request A
A -> C: pulse()
C -> RCA: Create request context
A -> C: Resolve pulse-scoped service
A --> W: Response A

W -> B: Handle Request B
B -> C: pulse()
C -> RCB: Create independent request context
B -> C: Resolve pulse-scoped service
B --> W: Response B

note over RCA,RCB
No mutable request state
may cross Fiber boundaries.
end note
@enduml

#8. RequestContext

RequestContext SHOULD follow the immutable-value-object approach already established by TenantContext.

Proposed representation:

final readonly class RequestContext
{
    public function __construct(
        public string $requestId,
        public string $traceId,
        public ?string $tenantId,
        public \DateTimeImmutable $startedAt,
    ) {}
}

The actual implementation MAY use stronger identifier/value-object types.

Requirements:

• immutable;
• no static accessor;
• created at request boundary;
• stored in Fiber-isolated request scope;
• destroyed/replaced with the next request;
• available to logging/error/event infrastructure.

If a tenant is established later in request processing, the context SHOULD be replaced with a new immutable instance rather than mutated.

#9. Request and Trace Correlation

The request lifecycle becomes:

@startuml
actor Client

participant Caddy
participant Tengine
participant FrankenPHP
participant "RequestContext" as RC
participant Middleware
participant Controller
participant Kernel
participant Logger

Client -> Caddy: HTTP request
Caddy -> Tengine: Proxy
Tengine -> FrankenPHP: Proxy

FrankenPHP -> RC: Create request_id / trace_id
RC -> Kernel: Context
Kernel -> Middleware: Handle request
Middleware -> Controller: Dispatch
Controller --> Middleware: Response
Middleware --> Kernel: Response

Kernel -> Logger: request_id + trace_id
Kernel --> FrankenPHP: Response
FrankenPHP --> Tengine: Response
Tengine --> Caddy: Response
Caddy --> Client: HTTP response
@enduml

The application SHOULD:

• accept a valid incoming trace context when enabled;
• generate a request ID when absent;
• generate a trace ID when absent;
• propagate correlation through application logs;
• attach correlation to safe error responses;
• avoid exposing sensitive tenant information.

The application MUST NOT trust arbitrary incoming IDs as proof of identity.

#10. Event Audit Context

The existing immutable event stamp mechanism can be used to associate runtime events with the request context.

For example:

RequestReceivedEvent
    |
    +-- request_id
    +-- trace_id
    +-- tenant_id (when appropriate)
    +-- timestamp

The stamp is an audit record, not mutable event state.

This preserves the existing append-only event audit design while providing operational correlation.

#11. Kernel Lifecycle

The existing Kernel lifecycle remains authoritative:

Unbooted
    ↓
Booting
    ↓
Booted
    ↓
Handling
    ↓
Booted
    ↓
Terminating
    ↓
Terminated

@startuml
[*] --> Unbooted

Unbooted --> Booting
Booting --> Booted

Booted --> Handling
Handling --> Booted

Booted --> Terminating
Terminating --> Terminated

Booting --> Terminating : fatal startup failure
Handling --> Terminating : fatal worker/runtime failure

Terminated --> [*]
@enduml

Existing lifecycle unit tests SHOULD remain unchanged unless the implementation requires additional cases.

The principal addition is concurrent/persistent-worker testing.

#12. Concurrency and Isolation Test Strategy

A new integration/fitness suite MUST repeatedly execute requests in different Fibers.

Conceptual test:

Fiber A:
    tenant = tenant-A
    request_id = A
    set request-local state
    yield

Fiber B:
    tenant = tenant-B
    request_id = B
    set request-local state
    yield

Resume Fiber A:
    assert tenant == tenant-A
    assert request_id == A

Resume Fiber B:
    assert tenant == tenant-B
    assert request_id == B

The test MUST also verify cleanup after exceptions:

Request A
   ↓
throw exception
   ↓
cleanup
   ↓
Request B
   ↓
assert no state from A

A test failure indicates a runtime architecture defect, not merely a failed business test.

#13. State Ownership Rules

Every runtime value MUST have an explicit lifetime.