README

coretsia/core-contracts

core/contracts is the boundary-only contracts package for the Coretsia Framework monorepo.

Scope: public interfaces, ports, enums, small value objects, public context key identifiers, and contract-level shapes that define cross-package boundaries.

Out of scope: runtime implementations, DI wiring, filesystem scanning, platform adapters, integrations, generated artifacts, and tooling-only behavior.

Package identity

Monorepo source path: framework/packages/core/contracts
Split repository: coretsia/core-contracts
Package id: core/contracts
Composer name: coretsia/core-contracts
Namespace: Coretsia\Contracts\* (PSR-4: src/)
Kind: library

Versioning is monorepo-wide.

The monorepo tag vMAJOR.MINOR.PATCH is the single version source of truth, and the split repository receives the same tag for the corresponding package subtree.

Per-package independent versions MUST NOT be used.

Dependency policy

This package is boundary-only and MUST stay lightweight.

Depends on: PHP only
Forbidden:
- platform/*
- integrations/*
- devtools/*

Contracts MUST NOT introduce concrete runtime dependencies or vendor-specific implementation types that would leak implementation details across package boundaries.

Contracts MUST remain:

stable;
minimal;
format-neutral;
deterministic where they expose exported shapes;
safe to depend on from runtime packages.

Contract areas

This package contains contracts for cross-package capabilities such as:

CLI command/input/output boundaries;
module identity, descriptors, manifests, and mode preset access;
config, env, source tracking, and validation result shapes;
runtime reset and unit-of-work hooks;
read-only runtime context access and public context key identifiers;
observability, health, profiling, and error descriptor boundaries;
routing and HTTP application ports;
validation ports;
filesystem ports;
database and migrations ports;
rate limit ports;
mail ports;
secrets ports.

Implementations live outside core/contracts.

CLI ports

CLI contracts prevent package-local cross-package interfaces and keep CLI behavior implementation-owned.

`Cli\Input\InputInterface`

Exposes raw input tokens only.
MUST NOT freeze parsing semantics.
Flags, options, argv rules, and command-line policy are owned by CLI implementations.

`Cli\Output\OutputInterface`

Output adapters MUST enforce:

deterministic output behavior;
redaction safety;
no secrets or PII leakage.

The interface intentionally does not define styling, verbosity, formatting, or terminal capability policy.

`Cli\Command\CommandInterface`

Provides a stable command identifier via name(): string.
Executes via run(InputInterface $input, OutputInterface $output): int.
Returns a standard process exit code.

Runtime contracts

Runtime contracts are format-neutral and transport-neutral.

Examples include:

Coretsia\Contracts\Runtime\KernelRuntimeInterface
Coretsia\Contracts\Runtime\UnitOfWorkHandle
Coretsia\Contracts\Runtime\ResetInterface
Coretsia\Contracts\Runtime\Hook\BeforeUowHookInterface
Coretsia\Contracts\Runtime\Hook\AfterUowHookInterface

UnitOfWorkHandle is a contracts-owned opaque low-level lifecycle handle.

It is not a Kernel context/result schema object.

It may expose only the normalized safe context array through UnitOfWorkHandle::context().

A runtime implementation may associate private lifecycle state with the exact handle object identity.

Such state is not part of the contracts-owned handle context shape and MUST NOT be exposed through UnitOfWorkHandle::context().

It MUST NOT expose Stopwatch tokens, wall-clock timestamps, transport objects, service instances, mutable runtime state, or Kernel-owned runtime internals.

The contracts package does not own DI tags, reset discovery, hook discovery, lifecycle execution, lifecycle timing state, config defaults, config rules, or provider wiring.

Runtime discovery and execution are owned by runtime implementation packages.

Context contracts

Context contracts define the public vocabulary and read-only access boundary for runtime context data.

The canonical public context key registry is:

Coretsia\Contracts\Context\ContextKeys

ContextKeys defines stable key identifiers only.

Importing ContextKeys does not grant write ownership over context values.

The read-only context access port is:

Coretsia\Contracts\Context\ContextAccessorInterface

Runtime readers SHOULD depend on ContextAccessorInterface when they need access to current context values.

Runtime readers MAY import ContextKeys to avoid raw string key drift.

The contracts package does not own context storage, mutable context writes, write validation, reset behavior, lifecycle writes, context propagation, logging, tracing, or export policy.

Those responsibilities are owned by runtime implementation packages.

Known implementation owners include:

core/foundation for ContextStore, ContextBag, ContextStorePolicy, and accessor binding;
core/kernel for base UnitOfWork context writes;
platform packages for transport/runtime-specific context enrichment.

Config and env contracts

Config and env contracts define stable ports and safe shapes for:

merged config access;
env-derived values;
config source tracking;
config validation results;
config validation violations;
declarative ruleset boundaries.

The contracts package does not implement config loading, config merging, env loading, ruleset discovery, validation execution, or generated config artifacts.

Package config/rules.php files are implementation-owned by their package owners and MUST remain declarative data.

Observability and errors contracts

Observability and error contracts define boundaries and safe shapes only.

They MUST NOT require concrete logger, tracer, metrics, HTTP, database, queue, or vendor-specific clients.

Diagnostic shapes MUST NOT expose:

raw payloads;
secrets;
credentials;
tokens;
cookies;
authorization headers;
private customer data;
absolute local paths;
host-specific bytes.

Notes for implementers

Implementations belong in owner packages such as:

core/foundation
core/kernel
platform/cli
platform/http
future platform or integration packages

Implementation packages MAY depend on core/contracts.

core/contracts MUST NOT depend back on implementation packages.

Importing contract-level vocabulary classes such as Coretsia\Contracts\Context\ContextKeys does not imply ownership of the corresponding runtime behavior.

Implementation packages MUST enforce their own write, lifecycle, propagation, and safety rules at their owner boundaries.

Observability

This package does not emit telemetry directly.

It defines observability-related contract boundaries and safe shapes only.

Errors

This package does not define runtime error mapping behavior directly.

Error mapping, exception normalization, and transport-specific error responses are owned by higher layers.

Security / Redaction

This package does not process sensitive runtime payloads directly.

Contracts that expose diagnostic or exported shapes MUST be safe by construction and MUST NOT require storing raw secrets, raw env values, raw request data, raw response data, credentials, tokens, cookies, authorization headers, private customer data, or absolute local paths.

Context contracts expose key identifiers and read-only access only.

They MUST NOT require exposing secrets, credentials, tokens, cookies, authorization headers, raw request payloads, raw response payloads, raw SQL, private customer data, transport objects, runtime objects, or mutable context storage.

coretsia / core-contracts

Maintainers

Package info

Statistics

Security