README

coretsia/core-contracts

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

Scope: public interfaces, ports, enums, small value objects, 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;
• 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\ResetInterface
• Coretsia\Contracts\Runtime\Hook\BeforeUowHookInterface
• Coretsia\Contracts\Runtime\Hook\AfterUowHookInterface

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

Runtime discovery and execution are owned by runtime implementation packages.

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.

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.

References

• Coretsia monorepo
• Contracts package source
• Packaging strategy
• Roadmap
• Modules and manifests SSoT
• Config and env SSoT
• UoW and Reset Contracts SSoT
• Observability and Errors SSoT
• Routing and HttpApp Contracts SSoT
• Validation Contracts SSoT
• Filesystem Contracts SSoT
• Database Contracts SSoT
• Rate Limit Contracts SSoT
• Mail Contracts SSoT
• Secrets Contracts SSoT