Coretsia Framework

Coretsia [kɔˈrɛtsjɑ] / [ko-RET-si-ya] — from the Ukrainian word “серцевина” (core, foundation)

A deterministic PHP 8.4+ application framework with explicit preset policy and runtime module selection, reproducible artifacts, explicit runtime lifecycles, and machine-enforced package boundaries and framework architecture rules.

Start minimal. Add capabilities as the application grows. Keep the same foundation.

[!WARNING] Coretsia is pre-release and is not production-ready.

The current repository is suitable for architecture review, framework development, and experimental evaluation. Stable Micro, Express, Hybrid, and Enterprise application releases are not available yet.

What is Coretsia?

Coretsia is a modular PHP framework designed for applications that may begin as small APIs, command-line tools, or conventional web applications and later grow into systems with background workers, queues, scheduled workloads, broader integrations, and stricter operational requirements.

The framework is built around a single architectural premise:

Application capabilities should be composed explicitly and deterministically, rather than emerging from incidental registration order, filesystem discovery, or undocumented bootstrap behavior.

Coretsia therefore treats module composition, generated artifacts, package boundaries, runtime lifecycles, and architecture verification as parts of the framework itself.

Core model

Coretsia’s framework composition model is based on explicit inputs:

explicit application target set
+ per-target mode preset / module overrides
        ↓
per-target ModuleSelection
        ↓
release installation catalog
        ↓
ProjectPackagePlan + managed Coretsia root requirements
        ↓
Composer lock/vendor graph
        ↓
fresh installed metadata verification
        ↓
per-target deterministic ModulePlan
        ↓
ordered provider planning and runtime artifacts
        ↓
runtime

Runtime module discovery uses Composer installed metadata only. It does not scan package directories or source trees to infer application composition. Physical mode-dependent package requirements are planned separately from an explicit application target set through the Kernel installation catalog and are applied only by explicit dependency synchronization.

Progressive capability modes

Coretsia defines four canonical framework modes:

`micro`

A minimal runtime profile for:

focused APIs;
small services;
lightweight CLI workloads;
applications that need a small active framework surface.

`express`

A conventional application profile for:

HTTP and web application workflows;
routing and validation;
persistence;
filesystem and other common application IO concerns.

`hybrid`

A mixed synchronous and asynchronous profile for:

background processing;
queues;
events;
scheduled workloads;
more complex business workflows.

`enterprise`

An extended platform profile for:

stronger operational requirements;
governance and observability;
broader infrastructure integrations;
larger and longer-lived systems.

Modes are capability profiles. They do not prescribe MVC, DDD, Clean Architecture, Vertical Slice Architecture, or another application architecture style.

An application may use a simple architecture in a broader mode or a highly structured architecture in micro. The application architecture remains an owner decision.

Modes, targets, and runtime drivers

Coretsia keeps three concerns separate:

a mode preset selects the active framework capability profile;
an application target identifies an application entrypoint or execution surface, such as web, api, console, or worker;
a runtime driver selects the execution mechanism, such as classic PHP, FrankenPHP, Swoole, or RoadRunner.

These concepts are related but are not interchangeable. The selected application target determines which validated moduleOverrides apply to the preset policy. Effective module selection is represented by ModuleSelection; the application target does not change dependency-graph traversal or introduce filesystem-based module discovery.

How Coretsia differs

Coretsia does not attempt to differentiate itself merely by providing a container, modules, middleware, queues, workers, or runtime adapters. Modern PHP frameworks already provide mature versions of those capabilities.

Its intended difference is the way those capabilities are composed and governed.

Deterministic module composition

A namespace-owned ModePreset and one explicit application target’s validated ResolvedModuleOverrides produce an immutable target-local ModuleSelection. For dependency synchronization, the Kernel resolves each selected target against the release installation catalog, retains per-target closures, and forms one immutable ProjectPackagePlan for the shared Composer graph. After Composer, a fresh process resolves each target independently against the installed ModuleManifest to produce its deterministic ModulePlan.

The plan records:

the selected application target;
enabled runtime modules;
explicitly excluded runtime modules;
deterministic dependency-first topological order;
resolved entries for exactly the enabled runtime modules.

The immutable ModulePlan is the payload of the existing module-manifest@1 artifact. Runtime boot hydrates it from the validated artifact without reloading preset policy or rediscovering installed modules.

Reproducible generated artifacts

Generated framework artifacts use a common versioned envelope and deterministic serialization rules.

Artifacts:

have explicit schema identities;
contain deterministic fingerprints;
do not contain timestamps or absolute paths;
must be rerun-no-diff;
are validated by schema and header semantics.

The production determinism contract — including canonical ordering, fingerprint and generation identity, artifact byte reproducibility, runtime verification, Worker semantic determinism, and cross-platform guarantees — is defined in Coretsia Determinism Contract.

Shared runtime lifecycle

Coretsia uses a format-neutral Unit-of-Work model for runtime operations such as:

HTTP requests;
CLI invocations;
worker jobs;
queue messages;
scheduler ticks.

Framework-managed Unit-of-Work-local state is reset after each operation so that participating services do not retain state from previous operations.

Explicit runtime compatibility

Runtime drivers are selected explicitly and checked against a canonical compatibility matrix.

The Kernel must not infer active runtimes from:

loaded extensions;
process names;
open ports;
filesystem contents;
container services;
reflection.

Runtime conflicts fail deterministically before the runtime entrypoint executes.

Machine-enforced architecture

Coretsia architecture rules are backed by repository tooling and CI rather than documentation alone.

Enforcement covers package and dependency boundaries, DTO and public API policy, runtime/tooling separation, deterministic generated outputs, security checks, and publishing safety.

Current status

Development status by capability track:

Bootstrap & prototypes — implemented. Repository bootstrap, packaging foundations, development tooling, CI/architecture verification, deterministic tooling primitives, prototypes, and initial CLI foundations are in place.
Core — implemented. Contracts, Foundation, Kernel, the baseline persistent Worker runtime, and the supporting composition and runtime infrastructure are implemented.
Micro release track — active development. Current work focuses on mode infrastructure, production CLI integration, target-aware application entrypoints, and the remaining runtime infrastructure required for the first complete micro application release.
Express release — planned.
Hybrid release — planned.
Enterprise extensions — planned.

Implemented today

Core runtime and composition baseline

contracts, foundation, and Kernel package baseline;
deterministic mode-preset and module-plan contracts;
Composer-metadata module discovery;
explicit multi-target application dependency planning and managed Composer root synchronization;
package-distributed installation catalog and fresh installed per-target verification;
module dependency and conflict resolution;
deterministic topological ordering;
immutable module-resolution snapshots;
configuration Kernel and merge policy;
deterministic artifact generation and fingerprinting;
cache verification;
compiled container artifact baseline;
format-neutral Unit-of-Work shapes and lifecycle;
runtime context and reset orchestration;
runtime-driver selection and compatibility guard.

Tooling and architecture governance

deterministic tooling and CI verification;
package identity and structure checks;
DTO policy and consistency checks;
architecture and dependency-boundary checks;
managed Composer workspace synchronization;
lock-drift checks;
Composer audit;
secret leakage checks;
split-package publishing checks;
release and publishing safety checks;
architecture generator idempotence verification.

Current stability limitations

Coretsia does not yet provide:

long-term backward compatibility guarantees;
stable upgrade paths;
a mature third-party package ecosystem.

Product-level integration and release hardening remain in progress.

Design priorities

Coretsia prioritizes:

a small initial application surface that can grow by adding capabilities without replacing the application foundation;
deterministic module and artifact composition;
consistent lifecycle behavior across classic and long-running runtimes;
enforceable architecture boundaries without unnecessary application-level ceremony.

Who should evaluate Coretsia?

Coretsia may currently be relevant to:

framework and platform engineers;
maintainers of long-lived PHP systems;
teams interested in reproducible framework artifacts;
developers working with modular monoliths;
engineers evaluating long-running PHP lifecycle safety;
contributors interested in architecture tooling and enforceable package boundaries.

Coretsia should not currently be selected for a production application that requires a stable framework, broad ecosystem support, or proven long-term upgrade compatibility.

Repository layout

packages/
  framework/
  applications/
    skeleton/
  core/
  platform/
  integrations/
  devtools/

tools/
var/
docs/

packages/framework/ — public coretsia/framework distribution;
packages/applications/skeleton/ — public coretsia/skeleton application template, including the consumer bin/dependency-sync.php integration entrypoint;
packages/{core,platform,integrations,devtools}/** — publishable split Composer packages;
tools/** — repository tooling, generators, and CI support, including installation-catalog generation/checking;
var/** — mutable/generated repository workspace state;
docs/ssot/** — canonical invariants, schemas, ownership, and policies;
docs/architecture/** — architecture guidance that refers to SSoT for normative truth;
docs/ops/** — operational and repository-maintenance documentation.

Canonical package layers are:

core
platform
integrations
devtools

Package and release model

Coretsia packages are developed in this monorepo and published as split Composer packages.

Canonical package identity is defined by package metadata.

Layered package source:

path: packages/<layer>/<slug>/
package id: <layer>/<slug>
Composer name: composer.json `name`

Special distributions:

packages/framework/              → coretsia/framework
packages/applications/skeleton/ → coretsia/skeleton

All Coretsia packages use one monorepo-wide release train:

vMAJOR.MINOR.PATCH

Independent per-package version streams are intentionally not supported.

This keeps Coretsia packages, runtime contracts, generated artifact schemas, documentation, and tooling aligned under one compatibility line.

See:

Evaluate the monorepo

Requirements:

PHP 8.4 or later;
Composer 2.x.

Run commands from the repository root:

composer setup
composer ci

composer setup configures the repository development environment and managed Composer repositories;
composer ci runs the full verification pipeline, including default tests, the dedicated slow test rail, and architecture checks.

This is the framework-development workflow. Consumer package synchronization uses the skeleton bin/dependency-sync.php entrypoint after the baseline application dependencies are installed.

Canonical documentation

Start here

Architecture and operations

Contributing and discussions

Coretsia is currently seeking technical review of:

architecture boundaries;
consistency between SSoT, implementation, tests, and tooling;
deterministic behavior;
package ownership;
runtime lifecycle;
unclear documentation;
unnecessary complexity.

The project is not currently seeking production adoption claims or comparisons positioning Coretsia as a replacement for established frameworks.

Architecture and design discussions are tracked through:

License

Licensed under the Apache License, Version 2.0.

See: