Coretsia Framework (Monorepo)

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

A modular, deterministic-by-default PHP framework monorepo with strict compile-time boundaries and SSoT-driven development

Status

Coretsia Framework is in active development and remains pre-release.

Roadmap status:

• Prelude: implemented
• Phase 0 — Spikes and prototypes: implemented
• Phase 1 — Core: implemented
• Phase 2 — Mode Infrastructure & CLI: active development
• Phase 3 — RELEASE: micro: planned
• Phase 4 — RELEASE: express: planned
• Phase 5 — RELEASE: hybrid: planned
• Phase 6+ — RELEASE: enterprise (extensions): planned
• Stable production release: not available yet

Current public implementation baseline:

• deterministic tooling, gates, and CI verification rails
• managed Composer workspace/repository synchronization
• publishing rails and public split-package publishing baseline
• canonical CLI ports and prod-safe CLI base
• Phase 0 devtools command pack
• Phase 1 core/* baseline:
  • contracts baseline
  • foundation baseline
  • kernel baseline
• deterministic module planning, config kernel, artifact generation, fingerprinting, cache verification, and container compilation
• Kernel runtime baseline with format-neutral UnitOfWork shapes and lifecycle policy
• runtime driver selection and compatibility guard
• DTO policy, package compliance rails, and package publish safety rails
• Composer audit and secret leakage security gates
• architecture, quality, test, and spike verification rails

Authoritative planning and invariants:

• Roadmap (canonical)
• Single Source of Truth (invariants/shapes/policies)
• Security policy

Coretsia also tracks architecture generator idempotence evidence in CI. See Architecture Generator Idempotence Evidence.

Repository layout (canonical)

• framework/ — framework meta-package + all framework packages
  • packages: framework/packages/<layer>/<slug>/
  • layers: core|platform|integrations|enterprise|devtools|presets
• skeleton/ — local workspace app sandbox
  • fixtures, entrypoints, E2E tests, runtime caches (skeleton/var/**)
• docs/ — documentation
  • docs/roadmap/** — task-first roadmap (phases/epics)
  • docs/ssot/** — Single Source of Truth (invariants, shapes, policies)
  • docs/architecture/**, docs/ops/** — non-SSoT guides (must link to SSoT for truth)
• framework/tools/ — tooling, gates, CI rails, spikes (Phase 0 / Prelude)

Canonical rules (selected highlights)

Monorepo packaging law (MUST)

• Package path: framework/packages/<layer>/<slug>/
• Package id: <layer>/<slug>
• Composer name: coretsia/<layer>-<slug>
• Monorepo-wide release-train versioning via git tags vMAJOR.MINOR.PATCH (no per-package versions)
• Canonical packaging strategy (single-choice)

Release-train versioning (MUST)

Coretsia packages are split for distribution, dependency boundaries, and Packagist publishing, but they are versioned as one framework release train.

All split packages receive the same version as the monorepo tag.

Independent package versions are intentionally not supported.

SemVer applies at the Coretsia framework release-train level, not as independent SemVer streams for every package.

A patch that changes one package may still produce a monorepo-wide patch release. Unchanged packages may receive the same new tag so consumers can keep all coretsia/* packages aligned.

This avoids maintaining a compatibility matrix across framework packages, generated artifacts, runtime contracts, platform adapters, docs, and tooling.

Canonical entrypoints (MUST)

Run commands from the repo root. Canonical scripts:

composer setup
composer test
composer ci

Managed Composer repositories (MUST NOT edit manually)

repositories blocks in root/framework/skeleton composer.json files are managed only through the canonical repo-root commands:

composer sync:check
composer sync:repos

Manual edits are forbidden by policy and enforced by pre-commit/CI drift checks.

See:

• Command catalog
• Git hooks + managed repositories policy

Lock determinism (MUST)

• lock files are committed for root/framework/skeleton
• CI uses composer install and fails on lock drift
• drift check for managed repositories runs before installs

SSoT config shape invariant (cemented)

• config/<name>.php returns a subtree (no wrapper repeating the root key).
  • Example: config/foundation.php returns ['container' => ...], not ['foundation' => ...].
• Runtime reads from global config under that root key (e.g. foundation.container.*).

Runtime discovery (MUST)

• Runtime module discovery uses Composer metadata only.
• Runtime discovery MUST NOT do filesystem scanning.
• Tooling package indexes MUST NOT be used as runtime input.

Spikes boundary (MUST)

• The only spikes root is framework/tools/spikes/**.
• Spikes must not import runtime packages (core/*, platform/*, integrations/*) nor path-import framework/packages/**/src/**.
• Single exception: coretsia/devtools-internal-toolkit (tooling-only) used only via Composer autoload.

Requirements

• PHP: >= 8.4
• Composer: 2.x

Quick start (monorepo dev)

Run everything from the repository root. Canonical entrypoints:

composer setup
composer test
composer ci

• composer setup enables .githooks/ (sets core.hooksPath) and ensures managed Composer repositories policy.
• composer test runs the baseline test suite.
• composer ci runs the CI-style pipeline locally.

Documentation index

Guides

• Quickstart (clean clone → working baseline)
• Command catalog (canonical)
• Developer onboarding checklist
• Git hooks + managed repositories policy
• Dependency graph (conceptual; truth is in SSoT)
• Releasing (GitHub Release + Packagist)
• Packagist split publishing

References

• Packaging strategy (canonical)
• Repository structure
• Roadmap
• Canonical condensed rules (normative)
• SSoT index
• Branding spec
• Architecture generator idempotence evidence

Community RFCs

Website Design RFC

Coretsia is collecting open-source ideas for the official website design direction.

The discussion is focused on translating the canonical Coretsia branding specification into a practical website concept, including the homepage, documentation section, news/blog section, and community pages.

Design discussion and direction are tracked in:

• Website design RFC

Accepted website and visual implementation decisions are recorded in:

• Coretsia website decision records

Website implementation work happens through scoped issues and pull requests in:

• Coretsia website repository

Website proposals must align with:

• Branding specification

License

Licensed under the Apache License, Version 2.0. See LICENSE.
See NOTICE for attribution and third-party notices (if applicable).