Download the PHP package coretsia/core-kernel without Composer

On this page you can find all versions of the php package coretsia/core-kernel. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Example code of coretsia/core-kernel

Informations about the package core-kernel

coretsia/core-kernel

core/kernel is the Kernel runtime package for the Coretsia Framework monorepo.

Scope: Kernel module metadata, Kernel service provider/factory wiring, Bootstrap Phase A minimal boot-input resolution, deterministic app target selection, dotenv/system env source precedence, immutable env repository snapshot construction, deterministic ModulePlan resolution, mode preset loading, module graph policy, canonical runtime driver selection and matrix guarding, ConfigKernel Phase B orchestration, config directives, deterministic config merge, semantic config validation, safe config explain traces, Kernel-owned artifact production for module-manifest.php, config.php, and container.php, deterministic artifact fingerprint input construction and calculation, Kernel-owned cache verification for generated artifacts, public artifact-only production runtime boot facade, Kernel-owned KernelRuntime implementation, hook invocation, Kernel-owned format-neutral UnitOfWork context/result shapes, UnitOfWork type and outcome vocabularies, UoW-specific json-like shape policy through a Foundation-backed internal wrapper, normalized hook payload production, canonical UnitOfWork lifecycle policy, and safe lifecycle summary observability.

Out of scope: public bootstrap orchestration facade ownership, public bootstrap aggregate result ownership, config CLI command UX, module debug CLI UX, reusable baseline json-like runtime value model ownership, generic redaction engine, HTTP response construction, HTTP status-code selection, PSR-7/PSR-15 integration, runtime adapter implementation, worker pool implementation, CLI command execution, CLI output rendering, platform-owned artifact production such as routes@1, platform adapters, integrations, observability exporters/backends, reset discovery implementation, and tooling-only behavior.

Package identity

Monorepo versioning is repo-wide only via git tags vMAJOR.MINOR.PATCH.

Per-package independent versions MUST NOT be used.

Dependency policy

This package is runtime-safe and format-neutral.

core/kernel MUST NOT depend on transport implementation packages.

Kernel UnitOfWork shapes MUST remain format-neutral and MUST NOT expose transport objects.

Kernel UoW shape normalization consumes the Foundation-owned baseline json-like normalizer:

through the Kernel-owned internal wrapper:

Kernel MUST NOT duplicate the baseline recursive json-like walker.

Runtime responsibilities

This package provides the Kernel baseline runtime layer:

Foundation owns reusable runtime mechanisms such as ids, clocks, stopwatch, context storage, deterministic tags, and reset orchestration.

Foundation also owns the reusable baseline json-like runtime value model.

Kernel owns only the UoW-specific layer on top of that model: root map policy, unsafe metadata key policy, attributes limits, exported error map policy, and UoW exception mapping.

Platform packages own transport adapters.

Bootstrap Phase A

Bootstrap Phase A is the minimal deterministic Kernel boot-input phase.

It resolves only:

Phase A is not a full config merge phase.

Full config file discovery, merge, directives, validation, explain output, and environment overlays are owned by ConfigKernel Phase B.

Phase A MAY read only one bootstrap-only skeleton config file:

This file is not a config root and MUST NOT participate in ConfigKernel Phase B merge.

Phase A MUST NOT read:

Application target selection is explicit and entrypoint-owned.

Canonical app targets are:

The selected app root is derived deterministically as:

Phase A MUST NOT scan skeleton/apps/* to infer the selected app.

BootstrapConfig is a resolved immutable value object only. It MUST NOT resolve defaults, read skeleton/config/app.php, parse dotenv files, read system env, or build an env repository.

BootstrapConfigResolver is internal and owns only Phase A config resolution:

Artifact cache directory resolution uses:

BootstrapConfig::artifactsCacheDir() is the only resolved artifact location source used by ArtifactPathResolver, ArtifactCompiler, and CacheVerifier.

ConfigKernel Phase B and compiled config@1 do not re-resolve artifact location.

EnvRepositoryBuilder is internal and owns only immutable env repository snapshot construction.

BootstrapEnvSourcePolicy controls dotenv/system env source precedence:

It is intentionally separate from Coretsia\Contracts\Env\EnvPolicy, which remains a missing-value policy only.

Kernel does not introduce public Bootstrapper or public BootstrapResult in this package. Entrypoint and platform owners compose the explicit Phase A services through DI until a future owner epic requires a stable public orchestration facade.

ConfigKernel Phase B

ConfigKernel Phase B is the deterministic full config pipeline.

The canonical orchestration entrypoint is:

ConfigKernel Phase B consumes:

ConfigKernel Phase B MUST NOT read:

ConfigKernel is an orchestration service only. It coordinates loaders, directives, merge, validation, and explain generation. It does not implement loader, merger, validator, or explainer semantics itself.

The active Phase B order is:

Package defaults are loaded only from enabled ModulePlan modules.

Skeleton/app config uses:

roots.php is the aggregate root-map file for a config layer.

<root>.php is the split root-subtree file for one config root.

At the same layer, root-specific <root>.php files override aggregate roots.php entries.

Config directives are processed per file before merge:

Directive application happens during merge, when the previous/base value is known.

Environment overlays are generated only from the immutable EnvRepositoryInterface snapshot and only for known ruleset-backed or explicitly mapped config paths.

Example projection:

User-owned/custom roots are accepted when they obey global config safety rules. If no ruleset exists for a custom root, it is merged, explained, fingerprinted, and marked as:

Config explain is a baseline Kernel facility. It is caller-requested, not feature-disabled by config.

ConfigKernel emits safe observability:

Config explain, logs, metrics, and spans MUST NOT expose raw config values, raw env values, secrets, tokens, DSNs, cookies, headers, raw SQL, payloads, stack traces, previous throwable messages, or absolute local paths.

Related documents:

Kernel artifacts, fingerprint, and cache verification

core/kernel owns Kernel-side artifact production, fingerprint behavior, and cache verification for Kernel-owned artifacts.

The Kernel-owned artifact basenames are:

Artifact path resolution consumes:

The default path shape is:

A custom valid Bootstrap Phase A override may instead produce:

ArtifactCompiler and CacheVerifier consume the same resolved BootstrapConfig, so they write and verify the same artifact location.

The corresponding canonical artifact identities are:

The canonical global artifact envelope, header fields, deterministic serialization law, and artifact registry are owned by:

Kernel-side artifact production and fingerprint behavior are owned by:

Kernel cache verification semantics are owned by:

Compiled container payload shape and artifact-only runtime boot semantics are owned by:

routes@1 is not Kernel-owned. Route artifact production belongs to platform/routing.

ArtifactCompiler owns Kernel artifact production orchestration. It builds deterministic fingerprint input, calculates the current fingerprint, compiles descriptor-based container input through ContainerCompiler, builds Kernel-owned artifact envelopes, builds the compiled container@1 envelope through CompiledContainerBuilder, resolves artifact paths, and writes Kernel-owned artifacts through ArtifactWriter.

CacheVerifier owns Kernel cache verification. It rebuilds expected Kernel artifacts in memory, rebuilds expected compiled container@1 through ContainerCompiler and CompiledContainerBuilder, reads existing artifacts through PhpArtifactReader, validates existing artifact envelopes through ArtifactSchemaValidator, compares stored fingerprint to the current fingerprint, compares deterministic LF-normalized bytes, and returns safe clean/dirty/invalid summary data.

Cache verification semantics are:

Cache verification MUST NOT use mtimes, ctimes, permissions, owners, inode ids, directory ordering, or filesystem traversal order as cache semantics.

The resolved artifact cache directory is always added to the effective fingerprint traversal exclusions.

It is not serialized into Bootstrap fingerprint identity or configured fingerprint policy solely because it is the selected output directory.

Therefore:

Changing the package fallback:

is not a location-only change. It also changes package and compiled config input and may therefore change the fingerprint through normal config provenance.

The configured baseline:

contains only explicit operational/source exclusion policy such as:

The mandatory generated-output exclusion covers only the current resolved artifact cache directory.

After relocating artifacts, stale files under the previous directory should be removed. When that directory must remain and may appear under a fingerprinted skeleton-local directory candidate, it must be retained explicitly in:

Compiled container artifact

container.php is the Kernel-owned container@1 compiled container artifact.

The container@1 compiled payload uses this canonical payload shape:

Container compilation is descriptor-based and closure-free. ContainerCompiler consumes explicit deterministic descriptor input and produces a deterministic DefinitionGraph. It MUST NOT discover runtime providers, discover modules, read source config, read generated artifacts, write artifacts, instantiate runtime services, or use provider fallback.

Production runtime container construction is artifact-only. CompiledContainerFactory builds the runtime Foundation container from:

Production runtime boot MUST NOT read source config files, run ConfigKernel, discover modules, compile a new container graph, write or repair artifacts, or silently fall back to provider-based container construction.

ArtifactRuntimeBooter is the public artifact-only production runtime boot facade.

It is the supported public Kernel boundary for runtime consumers that need to build a PSR container from already generated Kernel-owned artifacts.

Callers provide already resolved artifact filesystem paths:

ArtifactRuntimeBooter reads and validates config@1, extracts the validated config payload, and delegates runtime container construction to Kernel-owned compiled-container internals.

ArtifactRuntimeBooter currently performs artifact-only container boot from config.php and container.php.

It does not currently run an absolute pre-container-build runtime entrypoint guard because ModulePlan is not available as a dedicated artifact in this boot path yet.

The future module-plan.php artifact and pre-container entrypoint guard path are tracked only as a cleanup candidate and are not accepted runtime policy until promoted into a numbered epic, ADR, or SSoT update.

External packages MUST use:

External packages MUST NOT import or depend directly on Kernel artifact/container implementation classes such as:

Those classes remain Kernel implementation details.

Kernel artifact/fingerprint/container-compile/cache services are registered by KernelServiceProvider as factories only.

Artifact/fingerprint/container-compile/cache registration happens after ConfigKernel Phase B service registrations and before Kernel runtime service registrations.

Provider registration MUST NOT:

KernelServiceFactory artifact/fingerprint/container-compile/cache methods are construction/wiring methods only.

Factory methods MUST NOT write files, read generated artifacts, calculate fingerprints, run cache verification, resolve bootstrap/config/module plans, retain the container, retain mutable config snapshots, depend on ResetOrchestrator, or keep mutable runtime state.

Artifact/fingerprint/container-compile/cache services receive observability dependencies through public ports/interfaces only:

core/kernel artifact/fingerprint/container-compile/cache services MUST NOT instantiate Noop observability implementations and MUST NOT know whether observability dependencies are real adapters or Noop/no-op adapters.

Real-vs-Noop/default binding is owned by the application/foundation composition layer.

Artifact/fingerprint/container-compile/cache observability failures MUST NOT change deterministic artifact writing, fingerprint calculation, container compilation, or cache verification behavior.

ConfigKernel and ModulePlanResolver stopwatch failures are observability-isolated duration measurement failures.

They MUST NOT change config compilation, config explain, ModulePlan resolution, or ModulePlan failure precedence.

ConfigKernel and ModulePlanResolver primary failures remain fail-fast and MUST be surfaced according to their owner exception policies.

When duration cannot be measured, the duration value MAY collapse to 0 or the timing signal MAY be omitted according to owner policy.

KernelRuntime stopwatch failures MUST NOT change UnitOfWork lifecycle behavior, hook invocation policy, reset policy, or lifecycle failure precedence.

When monotonic timing is unavailable, KernelRuntime MAY use 0 only as an internal unavailable timer sentinel for private lifecycle timing state.

The internal timer sentinel MUST NOT be exported in:

The internal timer sentinel MUST NOT be passed to Stopwatch::stop().

When duration cannot be measured, UnitOfWorkResult.durationMs MUST be 0.

Compiled-container compile, factory, and public artifact-runtime boot failures use deterministic Kernel-owned exceptions and safe fixed messages.

Compile-time failures use:

Internal compiled-container artifact failures use:

Public artifact-only runtime boot facade failures use:

ArtifactRuntimeBooter MUST NOT expose artifact paths, absolute paths, raw config values, raw artifact payloads, env values, secrets, tokens, headers, command lines, PHP warning text, filesystem details, previous throwable messages, or stack traces.

ModulePlan resolution

ModulePlan resolution is Kernel-owned runtime policy.

The canonical orchestration entrypoint is:

ModulePlan resolution uses these single-choice inputs:

BootstrapConfig::preset() selects the mode preset.

BootstrapConfig::appTarget() is output metadata for ModulePlan::app() and app-root derivation only. It MUST NOT create a parallel module-selection source.

Mode preset lookup order is:

The first existing preset file wins.

Skeleton mode preset overrides replace framework defaults. They are not merged.

Kernel-owned loaded mode preset construction is not weaker than preset schema validation.

Coretsia\Kernel\Module\ModePreset is internal, but direct construction still rejects values that would be rejected by ModePresetSchemaValidator, including unsafe preset names, path-like descriptions, unsafe feature bundle / metadata strings or keys, excessive JSON-like depth/key/string limits, and overlapping required / optional / disabled module sets.

Module discovery is metadata-only. Runtime module discovery uses Composer installed metadata and Coretsia module metadata under:

Runtime discovery MUST NOT scan:

Module dependency and conflict edges are read only from:

Composer package-level require and conflict are not Coretsia runtime module graph edges unless explicitly represented in extra.coretsia.requires or extra.coretsia.conflicts.

ModulePlan output is deterministic and artifact-ready.

ModulePlan is an immutable artifact-ready value object and rejects contradictory module set state.

The following intersections MUST be empty:

A module id MUST NOT be exported as enabled, disabled, and/or optional-missing at the same time.

ModulePlan resolution itself does not write artifacts. Kernel artifact production may materialize the ModulePlan-derived module-manifest.php artifact through ArtifactCompiler and ModuleManifestBuilder.

ModulePlan resolution emits safe observability:

Allowed outcome values are:

success is emitted only after full successful ModulePlan resolution.

Known ModuleResolutionException failures emit their mapped deterministic outcome.

Unexpected non-ModuleResolutionException throwables emit unexpected_failure and are rethrown unchanged.

Diagnostics MUST NOT expose filesystem paths, raw Composer metadata, raw preset payloads, secrets, PII, stack traces, exception messages, or previous throwable messages.

Related documents:

ModulePlan diagnostics

ModulePlan resolution failures use deterministic Kernel-owned exceptions.

Canonical error codes include:

Optional missing modules are non-fatal warnings:

Diagnostics expose only stable reason tokens and safe deterministic context.

Diagnostics MUST NOT expose paths, raw Composer metadata, raw preset payloads, secrets, PII, stack traces, or previous throwable messages.

Runtime driver and entrypoint guard

core/kernel owns the canonical runtime-driver vocabulary, Kernel-owned runtime-driver selection, runtime-driver composition, and runtime entrypoint compatibility guard.

The public Kernel API is:

RuntimeDriverGuard is a Kernel-internal implementation detail behind RuntimeEntrypointGuard.

Runtime adapters and owner packages that have a resolved ConfigRepositoryInterface, caller-provided ModulePlan, and explicit RuntimeDriverContributions MUST use the public RuntimeEntrypointGuard boundary.

Callers that need the resolved active driver set use:

Assertion-only entrypoints use:

Both methods use the same canonical matrix and module-compatibility policy. Callers MUST NOT invoke both methods for one entrypoint attempt.

Kernel production boot paths MUST use this boundary whenever those three required inputs are available.

The current ArtifactRuntimeBooter path does not yet have a dedicated ModulePlan artifact and therefore does not currently perform this pre-container entrypoint check. That limitation is documented in the artifact-only runtime boot section and MUST NOT be treated as an implicit fallback policy for runtime adapters.

Callers MUST NOT call RuntimeDriverGuard directly.

Canonical HTTP driver ids are:

The canonical background driver id is:

Kernel-owned runtime-driver input is:

Allowed Kernel-selected HTTP runtime driver values are:

http.worker is intentionally not accepted by kernel.runtime.http_driver.

kernel.runtime.http_driver selects exactly one Kernel-owned HTTP runtime driver.

Owner packages that need to participate in runtime-driver selection MUST map their owner-owned runtime inputs to explicit:

RuntimeDriverContributions contains already-selected runtime drivers only.

It MUST NOT read config, inspect ModulePlan, resolve packages, inspect container services, inspect generated artifacts, or know which package produced the contribution.

For owner packages that do not contribute runtime drivers, callers MUST pass an explicit empty contribution object:

This is an explicit "no owner contributions" signal, not an implicit fallback.

Worker-owned runtime input is:

worker.task_type is owned by platform/worker.

core/kernel MUST NOT read worker.task_type.

core/kernel MUST NOT define worker.* defaults.

core/kernel MUST NOT validate the worker config subtree.

core/kernel MUST NOT inspect ModulePlan membership for platform.worker to infer, synthesize, enable, disable, or conditionally select Worker runtime-driver contributions.

The Worker package maps its owner-owned task type to runtime-driver contributions:

That mapping is owned by platform/worker, not by core/kernel.

The public entrypoint methods are:

resolveEntrypointDrivers(...) is the canonical query-and-validation boundary.

assertEntrypointAllowed(...) is its assertion-only wrapper.

It receives:

The guard MUST be invoked after config and ModulePlan are resolved and before runtime execution starts.

The internal matrix implementation returns RuntimeDrivers only for a valid single-HTTP-driver selection after Kernel config and explicit owner contributions have been composed.

The composition rules are:

Kernel HTTP driver owner contribution result
http.classic none http.classic
http.classic bg.worker_queue http.classic + bg.worker_queue
http.classic http.worker http.worker
http.frankenphp bg.worker_queue http.frankenphp + bg.worker_queue
http.swoole bg.worker_queue http.swoole + bg.worker_queue
http.roadrunner bg.worker_queue http.roadrunner + bg.worker_queue
http.frankenphp http.worker conflict
http.swoole http.worker conflict
http.roadrunner http.worker conflict

The internal module compatibility rule requires platform.http for:

It does not require platform.http for:

Runtime adapters MUST NOT partially duplicate this policy.

They MUST NOT decide independently that platform.http is required only for worker.task_type=http.

The compatibility check is based on the complete composed runtime-driver matrix, not on raw owner package config.

Runtime-driver failures are deterministic and safe:

Diagnostics expose only canonical driver ids, canonical module ids, deterministic error codes, and fixed reason tokens.

Diagnostics MUST NOT expose raw config values, config dumps, env values, adapter internals, filesystem paths, stack traces, previous throwable messages, or payload dumps.

The canonical source for runtime-driver ids, config keys, compatibility matrix, and decision rules is:

The architecture overview is:

KernelRuntime SPI

The external runtime SPI is owned by core/contracts:

The concrete implementation is owned by core/kernel:

Coretsia\Kernel\Runtime\KernelRuntime is the core/kernel implementation bound to the contracts port by DI.

Platform, worker, scheduler, queue, and custom runtime adapters MUST depend on:

Adapters MUST NOT typehint, construct, or directly depend on:

The high-level lifecycle API is:

runUnitOfWork() returns the external body return value.

It MUST NOT return the exported UnitOfWork result array.

Low-level adapters that need exported context/result payloads MAY use:

beginUnitOfWork() returns an opaque lifecycle handle.

Low-level adapters MAY read the normalized exported context array through:

Low-level adapters MUST execute their external body only after successful beginUnitOfWork().

If beginUnitOfWork() throws, no open lifecycle handle has been handed to the adapter.

For a failed beginUnitOfWork() attempt, the adapter MUST NOT call afterUnitOfWork().

This includes failures raised while invoking before-uow hooks.

Low-level adapters that need the exported result array MUST pass the exact returned handle to afterUnitOfWork().

Low-level lifecycle methods are a sharp-edge adapter API.

Adapters SHOULD prefer runUnitOfWork() whenever the external runtime body can be delegated to KernelRuntime.

If beginUnitOfWork() returns successfully, the adapter owns completion responsibility and MUST attempt exactly one matching afterUnitOfWork() call with the exact returned handle.

Low-level adapters MUST structure external body execution with a finally-equivalent completion path so that afterUnitOfWork() is attempted on both success and failure paths.

A low-level adapter MUST NOT start another UnitOfWork on the same runtime boundary before the previous successful beginUnitOfWork() has been completed with afterUnitOfWork().

KernelRuntime lifecycle

The canonical high-level lifecycle is:

This linear sequence describes executions whose before-uow hooks complete successfully.

If a before-uow hook throws after base ContextStore keys have been written, the UnitOfWork has crossed the reset-responsibility boundary but has not entered after-phase handling.

In that case KernelRuntime MUST:

The conceptual shorthand is:

KernelRuntime writes these base context keys before the external runtime body is executed:

Reset responsibility starts only after the base ContextStore keys have been written successfully.

If UnitOfWork context creation or base context key writing fails before that boundary, KernelRuntime MUST surface the primary failure without invoking reset orchestration.

A before-uow hook failure happens after the reset-responsibility boundary and therefore MUST NOT skip reset.

However, a before-uow hook failure happens before after-phase eligibility. It MUST NOT cause after-uow hooks to run.

Before hooks receive the normalized exported UnitOfWork context array.

After hooks receive the normalized exported UnitOfWork context array and normalized exported UnitOfWork result array.

No UnitOfWorkContext, UnitOfWorkResult, ErrorDescriptor, Throwable, transport object, service object, closure, or resource may cross the hook/export boundary.

Hook discovery

Kernel lifecycle hooks are discovered through Kernel-owned reserved tags.

The canonical code-level identifiers for these framework-reserved DI tags are:

Their values are:

Runtime package source MUST use ReservedTags::* for framework-reserved DI tag identifiers.

Hook services are resolved by HookInvoker from Foundation TagRegistry entries.

HookInvoker preserves the exact order returned by TagRegistry::all().

It MUST NOT re-sort hooks.

It MUST NOT dedupe hooks.

It MUST NOT apply custom priority rules.

Hook invocation is sequential and fail-fast.

The first hook service resolution failure, interface mismatch, or exception thrown by a valid hook stops the remaining hooks in the same phase.

HookInvoker wraps only service-resolution failures and interface mismatches in safe KernelRuntimeException diagnostics.

Exceptions thrown by valid hook implementations propagate unchanged to KernelRuntime.

HookInvoker does not execute reset orchestration and does not aggregate hook failures.

Once the reset-responsibility boundary has been crossed, KernelRuntime ensures that ResetOrchestrator::resetAll() is invoked exactly once even when a before or after hook fails.

Hook service ids are resolved through PSR-11 container lookup.

A before hook must implement:

An after hook must implement:

Configuration

The package owns the kernel configuration root.

Defaults live in:

The defaults file MUST return the subtree only and MUST NOT repeat the root key.

Valid shape:

Invalid shape:

Package fallback values are declared under kernel.*.

Bootstrap Phase A resolves its values before artifact path lookup.

Runtime and ConfigKernel Phase B consumers read the merged global configuration under kernel.*, but artifact path consumers use the already resolved BootstrapConfig::artifactsCacheDir().

Canonical Kernel config keys:

key default
kernel.boot.default_env "local"
kernel.boot.default_preset "micro"
kernel.boot.default_debug false
kernel.boot.default_artifacts_cache_dir "var/cache"
kernel.runtime.http_driver "http.classic"
kernel.env.source_policy.default_local "strict_dotenv"
kernel.env.source_policy.default_production "allow_system"
kernel.env.dotenv.files [".env", ".env.local", ".env.<env>", ".env.<env>.local"]
kernel.modules.discovery.source "composer"
kernel.modules.discovery.allowed_sources ["composer"]
kernel.modes.schema_version 1
kernel.modes.defaults_path "resources/modes"
kernel.modes.overrides_path "config/modes"
kernel.config.forbidden_top_level_roots ["coretsia", "_internal"]
kernel.fingerprint.skeleton_ignore_prefixes ["var/maintenance"]
kernel.uow.attributes.max_depth 10
kernel.uow.attributes.max_keys 200

kernel.boot.default_artifacts_cache_dir is the package fallback for the Bootstrap Phase A artifact cache directory.

The default is:

Applications may override it in bootstrap-only:

using:

Entrypoints may provide the highest-precedence explicit value through:

The resolved value is exposed through:

Kernel artifact paths use:

The directory must be a portable, bounded, skeletonRoot-relative dedicated generated-output root.

Absolute paths, traversal, source/config roots, public roots, dependency roots, repository roots, Windows-invalid components, and unsafe path segments are rejected.

ConfigKernel Phase B merged config and compiled config@1 are not artifact location resolution sources.

The runtime-driver entrypoint guard reads only Kernel-owned runtime config keys from the config repository.

The Kernel-owned runtime-driver config key is:

The guard receives owner-selected runtime drivers through explicit:

core/kernel does not read worker.task_type.

worker.task_type is owned, defaulted, normalized, and validated by platform/worker.

When Worker participates in runtime-driver selection, platform/worker must convert worker.task_type into RuntimeDriverContributions before calling the Kernel runtime entrypoint guard.

kernel.modules.discovery.source is shape-validated by config rules, but supported-source membership is enforced by ModulePlanResolver against kernel.modules.discovery.allowed_sources.

kernel.modes.defaults_path is package-relative.

kernel.modes.overrides_path is skeleton-root-relative.

Both mode paths MUST be relative safe paths.

kernel.config.forbidden_top_level_roots configures the global forbidden top-level config roots used when wiring ConfigNamespaceGuard.

The default forbidden roots are:

kernel and foundation MUST NOT be listed as forbidden top-level roots because applications must be able to configure those roots.

This package does not introduce generic json-like configuration.

The following config keys MUST NOT be introduced by Kernel:

Baseline json-like runtime value policy is owned by Foundation and is not configurable by Kernel.

Both values MUST be integers greater than zero.

This package does not introduce outcome mapping configuration.

Outcome mapping is canonical policy, not runtime configuration.

Config files

Package default config files use root-specific files:

Package default config files MUST return the subtree for <root>.

Package defaults MUST NOT use:

config/roots.php

Skeleton/app config files may use both aggregate and split styles:

skeleton/config/roots.php
skeleton/config/<root>.php
skeleton/config/environments/<appEnv>/roots.php
skeleton/config/environments/<appEnv>/<root>.php
skeleton/apps/<appTarget>/config/roots.php
skeleton/apps/<appTarget>/config/<root>.php
skeleton/apps/<appTarget>/config/environments/<appEnv>/roots.php
skeleton/apps/<appTarget>/config/environments/<appEnv>/<root>.php

roots.php returns a global root map.

<root>.php returns only the subtree for <root>.

Root-specific files override aggregate roots.php files at the same layer.

Config rules are declarative data files:

config/rules.php

Rules files MUST return plain arrays and MUST NOT contain closures, objects, resources, or executable validation callbacks.

Config directives

Config directives are normalized per file before merge and applied during merge.

Supported directives are:

@append
@prepend
@remove
@merge
@replace

Directive namespace is reserved.

Any unsupported @* key fails as a reserved namespace violation.

If a map level contains a directive key, that level must contain exactly one directive key and no normal config keys.

Directive examples are documented in:

docs/ssot/config-directives.md

The canonical merge order is documented in:

docs/ssot/config-merge-order.md
docs/ssot/config-precedence-matrix.md

Config explain

Config explain is a safe Kernel baseline facility.

It may expose:

normalized relative source ids
config dot paths
directive names
source type
source precedence/order
validated/unvalidated root status
safe hash/length metadata when produced upstream

It MUST NOT expose:

raw config values
raw env values
secrets
tokens
DSNs
cookies
headers
raw SQL
payloads
stack traces
previous throwable messages
absolute local paths

User-owned roots without loaded rulesets are marked as:

user_owned
unvalidated

UnitOfWork types

The canonical UnitOfWork type values are:

http
cli
queue
scheduler

The implementation is:

Coretsia\Kernel\Runtime\UnitOfWorkType

The class is intentionally enum-like instead of a native PHP enum because exported UnitOfWork shapes carry plain strings and no object instance may cross Kernel hook/export boundaries.

The tokens are stable lowercase ASCII values and MUST be compared byte-for-byte.

Outcomes

The canonical UnitOfWork outcome values are:

success
handled_error
fatal_error

The implementation is:

Coretsia\Kernel\Runtime\Outcome

The class is intentionally enum-like instead of a native PHP enum because exported UnitOfWork shapes carry plain strings and no object instance may cross Kernel hook/export boundaries.

The tokens are stable lowercase ASCII values and MUST be compared byte-for-byte.

HTTP and CLI outcome mapping is governed by:

docs/ssot/uow-outcome-policy.md

UnitOfWorkContext

Coretsia\Kernel\Runtime\UnitOfWorkContext is the canonical Kernel runtime shape for the beginning of a UnitOfWork.

Canonical internal fields:

uowId
type
startedAtToken
correlationId
attributes

startedAtToken is Kernel-internal lifecycle timing state.

It MUST NOT be exported in:

UnitOfWorkContext::toArray()
UnitOfWorkHandle::context()
before-uow hook payloads
after-uow hook context payloads
UnitOfWorkResult::toArray()
logs
metrics
traces
diagnostics
generated artifacts
persistence payloads

KernelRuntime maintains two separate lifecycle channels:

UnitOfWorkContext::toArray()
  -> normalized exported context
  -> UnitOfWorkHandle::context()

UnitOfWorkContext::startedAtToken()
  -> private WeakMap<UnitOfWorkHandle, int>
  -> duration calculation during afterUnitOfWork()

The WeakMap is keyed by the exact handle object identity.

afterUnitOfWork() retrieves the private timing token from that map. It does not read timing state from UnitOfWorkHandle::context().

The exported context shape is:

attributes
correlationId
type
uowId

attributes MUST be a json-like map.

The baseline json-like runtime value model is owned by:

docs/ssot/json-like-runtime-values.md

The baseline normalizer is:

Coretsia\Foundation\Serialization\JsonLikeNormalizer

Kernel owns the UoW-specific attributes root map policy.

A non-empty root list MUST NOT be used as attributes.

attributes are normalized by the Kernel-owned internal wrapper:

Coretsia\Kernel\Runtime\Internal\JsonLikeShapeNormalizer::normalizeContextAttributes()

The wrapper delegates baseline recursive normalization to Foundation and preserves Kernel-owned policy:

attributes root map policy
unsafe metadata key policy
attributes max_depth
attributes max_keys
UoW context exception mapping

Validation failures MUST use:

Coretsia\Kernel\Runtime\Exception\UnitOfWorkContextInvalidException
CORETSIA_UOW_CONTEXT_INVALID

UnitOfWorkResult

Coretsia\Kernel\Runtime\UnitOfWorkResult is the canonical Kernel runtime shape for the completion of a UnitOfWork.

Canonical fields:

uowId
type
correlationId
durationMs
outcome
error
extensions

error is optional.

The exported result shape with no error is:

correlationId
durationMs
extensions
outcome
type
uowId

The exported result shape with error is:

correlationId
durationMs
error
extensions
outcome
type
uowId

durationMs is the only exported timing field.

It MUST be:

int
>= 0

durationMs MUST be measured by Kernel runtime from private lifecycle timing state using the canonical monotonic timing source:

Coretsia\Foundation\Time\Stopwatch

UnitOfWorkResult MUST NOT export Stopwatch tokens.

The following fields are not valid UnitOfWorkResult fields:

startedAt
startedAtToken
finishedAt

Consumers MUST NOT calculate duration from exported start or finish timing fields. Such exported fields MUST NOT exist.

extensions MUST be a json-like map.

The baseline json-like runtime value model is owned by:

docs/ssot/json-like-runtime-values.md

The baseline normalizer is:

Coretsia\Foundation\Serialization\JsonLikeNormalizer

Kernel owns the UoW-specific extensions root map policy.

A non-empty root list MUST NOT be used as extensions.

extensions are normalized by the Kernel-owned internal wrapper:

Coretsia\Kernel\Runtime\Internal\JsonLikeShapeNormalizer::normalizeResultExtensions()

The wrapper delegates baseline recursive normalization to Foundation and preserves Kernel-owned policy:

extensions root map policy
unsafe metadata key policy
UoW result exception mapping

Validation failures MUST use:

Coretsia\Kernel\Runtime\Exception\UnitOfWorkResultInvalidException
CORETSIA_UOW_RESULT_INVALID

ErrorDescriptor boundary

UnitOfWorkResult.error MAY be represented internally as:

Coretsia\Contracts\Observability\Errors\ErrorDescriptor

Before crossing any Kernel hook/export boundary, the error MUST be normalized to a json-like exported error map.

The exported error map is normalized by:

Coretsia\Kernel\Runtime\Internal\JsonLikeShapeNormalizer::normalizeExportedErrorMap()

The wrapper delegates baseline recursive normalization to:

Coretsia\Foundation\Serialization\JsonLikeNormalizer

Kernel owns the exported error map policy, including the non-empty root map requirement and UoW result exception mapping.

No ErrorDescriptor object instance MAY cross the hook/export boundary.

No Throwable object MAY cross the hook/export boundary.

Invalid exported error maps MUST fail with:

CORETSIA_UOW_RESULT_INVALID

Json-like shape normalization

Kernel centralizes UoW-specific json-like shape policy in:

Coretsia\Kernel\Runtime\Internal\JsonLikeShapeNormalizer

This class is internal and is not public API.

It is not a DI service.

It is not a transport extension point.

It MUST NOT be exposed through:

framework/packages/core/kernel/PUBLIC_API.md

It provides:

normalizeContextAttributes(array $attributes, int $maxDepth, int $maxKeys): array
normalizeResultExtensions(array $extensions): array
normalizeExportedErrorMap(array $error): array

Baseline json-like value validation and recursive deterministic normalization are owned by Foundation:

Coretsia\Foundation\Serialization\JsonLikeNormalizer

Baseline failures are represented by:

Coretsia\Foundation\Serialization\Exception\JsonLikeNormalizationException

JsonLikeShapeNormalizer MUST delegate baseline recursive normalization to Foundation.

JsonLikeShapeNormalizer owns only UoW-specific policy:

JsonLikeShapeNormalizer MUST NOT duplicate the baseline recursive json-like walker.

Foundation owns:

Hook and export boundary

Kernel hooks and low-level adapters receive exported array shapes, not shape objects.

Before hooks receive context data as:

UnitOfWorkContext -> normalized array $context

After hooks receive context/result data as:

UnitOfWorkContext -> normalized array $context
UnitOfWorkResult -> normalized array $result

The contracts hook signatures are:

BeforeUowHookInterface::beforeUow(array $context): void
AfterUowHookInterface::afterUow(array $context, array $result): void

Nested attributes, extensions, and exported error maps MUST be baseline-normalized through JsonLikeShapeNormalizer, which delegates recursive normalization to Foundation.

No object instance MAY cross the hook/export boundary.

Forbidden boundary values include:

Reset lifecycle boundary

Foundation owns reset discovery and reset orchestration mechanics.

The canonical Foundation reset executor is:

Coretsia\Foundation\Runtime\Reset\ResetOrchestrator

Kernel runtime code consumes reset only through:

ResetOrchestrator::resetAll()

core/kernel MUST NOT enumerate reset-tagged services directly.

core/kernel MUST NOT call ResetInterface::reset() directly on discovered services.

core/kernel MUST NOT define KERNEL_RESET constants.

The reset discovery tag is owned by core/foundation.

The canonical lifecycle position is:

after-uow hooks → ResetOrchestrator.resetAll()

For every UnitOfWork lifecycle that reaches reset responsibility, KernelRuntime MUST call ResetOrchestrator::resetAll() exactly once.

If an earlier primary failure exists and reset also fails, the earlier primary failure remains surfaced.

The earlier primary throwable is surfaced unchanged.

A later reset failure does not replace, wrap, or mutate it.

If body execution fails and after-phase handling also fails, the body failure remains primary.

If body execution succeeds and after-phase handling fails, the after-phase failure becomes primary.

KernelRuntime does not aggregate secondary lifecycle or reset failures into the surfaced throwable.

If no earlier primary failure exists and reset fails, KernelRuntime surfaces a safe KernelRuntimeException with reason:

kernel-runtime-reset-failed

No PSR-7/15 runtime boundary

Kernel runtime APIs are format-neutral.

core/kernel MUST NOT expose or require:

Psr\Http\Message\*
Psr\Http\Server\*

Kernel runtime code MUST NOT depend on platform HTTP request/response objects, PSR-7 request/response objects, PSR-15 middleware/handler objects, CLI command objects, queue vendor messages, scheduler vendor contexts, or integration package objects.

PSR logger and PSR container usage are allowed implementation dependencies:

Psr\Container\ContainerInterface
Psr\Log\LoggerInterface

The PSR-7/15 ban is specific to transport APIs, not every Psr\* namespace.

Observability

KernelRuntime emits safe lifecycle summary observability through injected ports.

The concrete exporters/backends remain out of scope for core/kernel.

KernelRuntime receives these observability dependencies through DI:

Psr\Log\LoggerInterface
Coretsia\Contracts\Observability\Tracing\TracerPortInterface
Coretsia\Contracts\Observability\Metrics\MeterPortInterface

The canonical span name is:

kernel.uow

The canonical metrics are:

kernel.uow_total
kernel.uow_duration_ms

The lifecycle summary log message is:

kernel.uow

Allowed labels/attributes for span and metrics are:

operation
outcome

operation is the normalized UnitOfWork type.

For an HTTP UnitOfWork:

operation = http

outcome is the normalized UnitOfWork outcome token.

The lifecycle summary log context contains only:

duration_ms
operation
outcome

Lifecycle summary observability MUST NOT include:

Observability port failures MUST NOT replace primary KernelRuntime lifecycle failures.

Errors

This package defines Kernel UnitOfWork validation exceptions:

Baseline json-like failures from:

Coretsia\Foundation\Serialization\Exception\JsonLikeNormalizationException

are mapped locally by:

Coretsia\Kernel\Runtime\Internal\JsonLikeShapeNormalizer

to UoW-specific validation exceptions and reason tokens.

Exception messages MUST be deterministic and safe.

Exception messages MAY include only:

safe path-to-value
stable reason code
safe type name

Exception messages MUST NOT include:

Higher-level error reporting, rendering, and transport mapping are owned by higher layers.

Security / Redaction

core/kernel MUST NOT leak sensitive runtime data through UnitOfWork shapes.

Forbidden in UnitOfWorkContext.attributes and UnitOfWorkResult.extensions:

Allowed safe metadata includes:

safe ids
stable enums
counts
lengths
hashes
bounded safe status/category tokens

Runtime owners MUST prefer omission over unsafe emission.

The Kernel internal json-like shape wrapper includes deterministic unsafe-key guards for known unsafe metadata keys.

This guard is Kernel-owned UoW-specific policy.

It is not a PII detector.

It is a deterministic denylist for obvious policy-key names.

Foundation JsonLikeNormalizer does not own the unsafe metadata key denylist.

Public API

Package-local public API evidence is maintained in:

framework/packages/core/kernel/PUBLIC_API.md

That file is the source used by the Kernel public API gate.

Bootstrap Phase A public API symbols are:

Coretsia\Kernel\Boot\AppTarget
Coretsia\Kernel\Boot\BootstrapConfig
Coretsia\Kernel\Boot\BootstrapEnvSourcePolicy
Coretsia\Kernel\Boot\BootstrapInput
Coretsia\Kernel\Boot\Exception\BootstrapException

Artifact-only production runtime boot public API symbols are:

Coretsia\Kernel\Boot\ArtifactRuntimeBooter
Coretsia\Kernel\Boot\Exception\ArtifactRuntimeBootException

ArtifactRuntimeBooter is not a Bootstrap Phase A resolver and does not own bootstrap input resolution. It is a production runtime artifact boot facade for already generated Kernel-owned artifacts.

Runtime driver and entrypoint public API symbols are:

Coretsia\Kernel\Runtime\Driver\HttpDriver
Coretsia\Kernel\Runtime\Driver\BackgroundDriver
Coretsia\Kernel\Runtime\Driver\RuntimeDriverContributions
Coretsia\Kernel\Runtime\Driver\RuntimeDrivers
Coretsia\Kernel\Runtime\Entrypoint\RuntimeEntrypointGuard
Coretsia\Kernel\Runtime\Exception\RuntimeDriverConflictException
Coretsia\Kernel\Runtime\Exception\RuntimeDriverInvalidConfigException

Coretsia\Kernel\Runtime\Driver\RuntimeDriverGuard is internal implementation detail and MUST NOT be listed as Kernel public API.

Bootstrap Phase A implementation helpers are internal and MUST NOT be listed as public API:

Coretsia\Kernel\Boot\BootstrapConfigResolver
Coretsia\Kernel\Boot\BootstrapOverridesLoader
Coretsia\Kernel\Boot\DotenvLoader
Coretsia\Kernel\Boot\EnvRepositoryBuilder
Coretsia\Kernel\Boot\ArrayEnvRepository

Coretsia\Kernel\Runtime\Internal\JsonLikeShapeNormalizer is internal implementation detail.

It MUST NOT be listed as Kernel public API.

Kernel public API consumers MUST use UnitOfWorkContext and UnitOfWorkResult, not the internal normalizer.

Runtime adapters MUST use the contracts-level runtime port:

Coretsia\Contracts\Runtime\KernelRuntimeInterface

Runtime adapters MUST NOT typehint or construct the concrete implementation directly:

Coretsia\Kernel\Runtime\KernelRuntime

The concrete implementation is resolved through DI binding in core/kernel.

References

All versions of core-kernel with dependencies

PHP Build Version
Package Version
Requires php Version ^8.4
ext-ctype Version *
composer-runtime-api Version ^2.2
coretsia/core-contracts Version ^0.6.0
coretsia/core-foundation Version ^0.6.0
psr/container Version ^2.0
psr/log Version ^3.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package coretsia/core-kernel contains the following files

Loading the files please wait ...