Coretsia Application

This is a Coretsia application created from the coretsia/skeleton project template.

The project starts with Composer-managed runtime dependencies, application configuration, app targets, environment configuration, and mutable runtime state under var/.

Adapt it as the application evolves.

Application root

The project directory is the application root.

Installed Coretsia packages operate within this application context.

Dependencies

The application baseline requires:

PHP ^8.4
coretsia/framework

coretsia/framework is the only project-owned Coretsia baseline root requirement. It is a Composer metapackage that requires Kernel and CLI. CLI requires Redaction, so baseline Composer installation also installs Redaction transitively:

coretsia/skeleton
    -> coretsia/framework
        -> coretsia/core-kernel
        -> coretsia/platform-cli
            -> coretsia/core-kernel
            -> coretsia/platform-redaction

Composer also installs the remaining transitive dependencies, including Coretsia Contracts and Foundation. No separate CLI or Redaction root requirement is needed in the Skeleton project.

The default Kernel preset is micro (kernel.boot.default_preset). It selects core.foundation and core.kernel as required runtime modules and platform.cli as a selectable module. The CLI module requires core.kernel and platform.redaction; Redaction is therefore part of the effective default Console ModulePlan through the Kernel dependency graph, not an additional preset root.

Composer installation establishes the physical package graph; it does not enable runtime modules. The Kernel independently resolves a target-local ModulePlan from the effective preset and module overrides. The normal CLI host requires an enabled platform.cli in its Console plan and fails closed when it is excluded.

Additional mode-required Coretsia packages are materialized only through explicit application dependency synchronization. DependencySync may manage only the Coretsia root requirements recorded in its ownership marker; application-owned roots remain unchanged.

The project composer.json defines the application's runtime and application-specific dependencies.

Composer records the resolved dependency graph in composer.lock and installs dependencies under vendor/.

Command-line interface

After baseline Composer installation, run the canonical CLI from the Skeleton project root:

php coretsia list
php coretsia help
php coretsia doctor
php coretsia config:validate --target=web

The project-root coretsia file is a thin wrapper that delegates to the Composer-installed vendor/bin/coretsia binary. Running php vendor/bin/coretsia <command> from the same project root invokes the same packaged CLI implementation directly. No additional CLI package installation, shell alias, or CLI configuration step is required after the baseline Composer installation.

The Skeleton project-root wrapper is distinct from the monorepo-root coretsia wrapper. The Skeleton wrapper delegates only through its installed Composer binary and retains consumer project-root resolution; the monorepo wrapper uses a fixed repository-relative path to packages/platform/cli/bin/coretsia. Neither wrapper implements an additional CLI runtime.

If vendor/bin/coretsia is missing or unreadable, the Skeleton wrapper writes exactly CORETSIA_CLI_BOOTSTRAP_FAILED: autoload-unavailable followed by one LF to stderr and exits with code 1, without exposing paths, PHP warnings, or exception traces.

Normal CLI commands bootstrap the Kernel-owned Console operations host using the resolved Console ModulePlan. Built-in Kernel operations such as config:validate require an explicit --target=web|api|console|worker; the requested operation target does not change the CLI host's Console target. The doctor command is the ultra-early diagnostic path and does not require Kernel host boot or generated artifacts.

Application dependency synchronization

Dependency synchronization is an explicit consumer operation. It is never triggered by composer create-project, preset selection, CLI invocation, or application/runtime boot.

Canonical workflow:

baseline Composer install
    -> explicit application targets
    -> per-target preset and module policy
    -> plan/review
    -> explicit apply
    -> composer.lock/vendor validation
    -> fresh per-target ModulePlan verification

The shipped integration entrypoint is:

bin/dependency-sync.php

Examples:

php bin/dependency-sync.php plan --target=web
php bin/dependency-sync.php review --target=web --target=worker
php bin/dependency-sync.php apply --target=web --target=worker

A fixed installation preset can be supplied only for a selected target:

php bin/dependency-sync.php review \
  --target=web \
  --target=worker \
  --preset=worker=enterprise

Apply-only effect authorization flags are:

--allow-composer-scripts
--allow-composer-plugins
--allow-broad-update
--allow-repair

DependencySync records the Coretsia root requirements it owns under extra.coretsia.dependencySync using managedRequire and lastAppliedRequire. An untracked root remains project-owned and is never silently claimed.

Every explicit non-Coretsia root in require or require-dev is protected for a synchronization. Its root constraint, locked identity, and installed identity must remain unchanged. If the requested Coretsia solve requires changing that package, the synchronization fails visibly instead of widening the update scope.

Composer effects are not transactionally atomic across composer.json, composer.lock, and vendor/. When an effectful process has started and a later Composer or verification failure occurs, the adapter reports RECOVERY_REQUIRED with a recovery receipt. Recovery material is stored under:

var/dependency-sync/recovery/<recoveryReceiptId>/

Effectful synchronization uses:

var/locks/dependency-sync.lock

A stable repeated synchronization starts from a fresh PHP process and is a no-op when manifest, lock, vendor state, and all selected target plans already match.

Canonical multi-target example with explicitly selected web and worker targets, the default micro preset for web, and a target-qualified enterprise preset for worker:

explicit targets: web, worker
web    -> micro      -> core.foundation, core.kernel, platform.cli, platform.redaction
worker -> enterprise -> core.foundation, core.kernel, platform.cli, platform.redaction, platform.worker

project-wide physical module union:
core.foundation, core.kernel, platform.cli, platform.redaction, platform.worker

Both target-local closures include platform.redaction through the platform.cli runtime dependency. The project-wide union determines physical Composer installation intent, not global runtime enablement: platform.worker remains disabled in ModulePlan(web) even though it is installed for worker. Only explicitly selected targets participate in dependency planning, and adding mode-required packages still requires an explicit DependencySync apply.

See docs/ssot/application-dependency-sync.md in the Coretsia monorepo for the normative ownership, execution, verification, and recovery contract.

Project structure

The initial project structure is:

./
├── bin/
│   └── dependency-sync.php
├── composer.json
├── coretsia
├── .env.example
├── .gitignore
├── README.md
│
├── config/
│   └── app.php
│
├── apps/
│   └── web/
│       ├── config/
│       └── public/
│
└── var/
    ├── cache-data/
    ├── cache/
    ├── etl/
    ├── locks/
    ├── logs/
    ├── maintenance/
    ├── quarantine/
    ├── sessions/
    └── tmp/

App targets

Each app target lives under:

apps/<appTarget>/

The initial project includes a web app target:

apps/web/
├── config/
└── public/

apps/web/config/ contains configuration specific to the web app target.

apps/web/public/ is the public directory for the web app target.

Add additional app-target directories under apps/ as the application requires. Directory presence does not select a target for DependencySync; installation target membership is explicit caller input.

Configuration

Application configuration contains project-specific overrides.

Default values are provided by the installed Coretsia packages.

Only add overrides that the application actually needs. Coretsia combines package defaults with the application's configuration during bootstrap.

Bootstrap configuration

The application provides:

config/app.php

This file contains application settings required during early bootstrap.

The initial file returns an empty array:

return [];

An empty initial config means the application uses the defaults provided by installed Coretsia packages until project-specific bootstrap settings are added.

Application-wide configuration

Application-wide configuration belongs under:

config/

Environment-specific application-wide configuration can live under:

config/environments/<appEnv>/

Only create configuration files for overrides the application actually needs.

App-target configuration

App-target-specific configuration belongs under:

apps/<appTarget>/config/

Environment-specific app-target configuration can live under:

apps/<appTarget>/config/environments/<appEnv>/

The initial apps/web/config/ directory is empty until the application requires an app-target-specific override.

Runtime directories

var/ contains mutable application runtime state such as caches, logs, locks, sessions, temporary data, and generated runtime artifacts.

Mutable contents under var/ are ignored by Git, while tracked .gitkeep files preserve the initial directory structure.

Environment configuration

The application includes:

.env.example

The initial file contains no KEY=VALUE entries because no environment key is currently required by every Coretsia application.

Create a local .env file when environment-specific overrides are required.

The local .env file is ignored by Git.

Coretsia loads environment configuration during application bootstrap.

Version control

The project .gitignore excludes local environment files, generated dependencies under vendor/, and mutable runtime contents under var/.

Keep .env.example, tracked .gitkeep files, and composer.lock under version control.

Extending the application

The initial project is intentionally small. Add these areas when the application needs them:

modules/
resources/
tests/
config/modes/

Application modules are part of the project codebase and are separate from installed Coretsia packages.

Observability

Logging, metrics, tracing, and other observability capabilities are provided by installed Coretsia packages and configured through the application's configuration files.

Security

Keep secrets, credentials, and other sensitive application data out of source control.

Use .env.example only for documentation-safe examples, never for production credentials or private environment values.

Keep committed configuration under config/ and apps/*/config/ free of secrets and private environment values.

For documentation and guides, see coretsia.dev.