Foundation Support #13

Affected Version

v0.0.0

Pre-check

• I understand this is a final or near-final architectural decision, not an open discussion
• I have reviewed existing architecture decisions, RFCs, and related issues

Context

The introduction of the FireHub Foundation layer requires Core to provide a stable set of architectural contracts that enable high-level developer APIs without creating direct dependencies from Core to implementation layers.

The Foundation layer represents the high-level API layer of the FireHub ecosystem. It provides expressive, object-oriented abstractions for common programming concepts such as strings, dates, mathematics, paths, identifiers, and other application-level building blocks.

To maintain proper dependency direction, Core must define the minimal contracts that represent these concepts while leaving implementation details and developer-facing APIs to Foundation.

This architectural decision establishes the relationship between Core, Runtime, and Foundation:
Core → Defines architectural contracts
Runtime → Provides low-level execution logic
Foundation → Provides high-level developer APIs
Application → Consumes high-level abstractions

Architectural Decision

Core SHALL provide minimal contracts for high-level abstractions that are considered fundamental concepts within the FireHub ecosystem.

The Foundation layer SHALL implement these contracts and provide the complete developer-facing API.

Core contracts:

• Define the existence and expected behavior of fundamental abstractions.
• Remain minimal and implementation-independent.
• Must not contain convenience APIs or framework-specific logic.
• Must not depend on Foundation or Runtime implementations.

Foundation implementations:

• Provide rich object-oriented APIs.
• Provide fluent interfaces where appropriate.
• Encapsulate common programming operations.
• Implement Core contracts.
• Utilize Runtime functionality for low-level execution.

The dependency direction SHALL remain:

Core
↑
│ defines contracts
│
Foundation
↑
│ implements abstractions
│
Runtime
↑
│ executes primitives
│
PHP Engine

Rationale

FireHub separates architectural truth, execution, and developer experience into independent layers.

Without Core contracts, framework components would need to depend directly on Foundation implementations or primitive PHP types, causing architectural coupling and limiting future evolution.

By introducing minimal contracts in Core:

• Core remains the single source of architectural truth.
• Foundation can evolve its API without affecting Core architecture.
• Runtime remains focused on execution and performance.
• Applications receive expressive and consistent APIs.
• Future implementations remain replaceable.

This follows the FireHub architectural principle:
Core defines.
Runtime executes.
Foundation exposes.
Application consumes.

System Boundaries

Included

• Definition of contracts for fundamental high-level concepts.
• Architectural rules between Core, Runtime, and Foundation.
• Support for future Foundation implementations.
• Standardized abstraction patterns for developer-facing APIs.

Examples of possible Core contracts:
String abstraction
Date/time abstraction
Identifier abstraction
Value-based application objects
Common framework-level abstractions

Excluded

The following responsibilities do NOT belong in Core:

• Fluent APIs.
• Convenience methods.
• Formatting helpers.
• Transformation logic.
• User-facing developer utilities.
• Implementation algorithms.
• Runtime execution details.
• Performance optimizations.

These responsibilities belong to Foundation or Runtime depending on their purpose.

Rejected Alternatives

No contracts in Core

Rejected because Core components would be unable to depend on high-level abstractions without referencing Foundation directly.

This would violate dependency direction rules.

Complete high-level APIs inside Core

Rejected because Core should remain stable and minimal.

Adding complete APIs into Core would:

• Increase architectural coupling.
• Slow down Core evolution.
• Mix contracts with implementations.
• Reduce flexibility for future Foundation development.

Foundation depending only on Runtime

Rejected because Foundation concepts would have no shared architectural contracts.

Core must define the concepts that represent the system's fundamental abstractions.

Impact Analysis

Core

• Introduces contracts for fundamental high-level abstractions.
• Remains implementation-free.
• Becomes the authoritative definition layer for Foundation concepts.

Runtime

• No change in responsibility.
• Continues providing low-level execution primitives.
• Does not depend on Foundation.

Foundation

• Becomes the implementation layer for Core high-level contracts.
• Provides developer-oriented APIs.
• Establishes reusable patterns for future high-level components.

Adapters

• No immediate impact.
• Can consume Foundation APIs where appropriate.

Capabilities

• Can depend on Core contracts.
• May optionally use Foundation implementations when required.

Backwards Compatibility

No breaking changes are expected.

This introduces new contracts and architectural capabilities without modifying existing runtime behavior.

Implementation Guidelines

• Core contracts MUST be minimal.
• Core contracts MUST not expose convenience APIs.
• Foundation classes SHOULD be immutable where applicable.
• Foundation MUST depend on Core contracts.
• Foundation MAY depend on Runtime execution utilities.
• Runtime MUST remain independent from Foundation.
• New high-level APIs should follow the same contract/implementation separation.

Follow-up Work

• Define Core contracts required by Foundation.
• Implement Foundation high-level APIs.
• Establish Foundation development conventions.
• Add contract tests.
• Document dependency rules.
• Review future abstractions before introducing new Core contracts.

Additional Context

This decision establishes the foundation for all future FireHub high-level APIs.

Future Foundation components such as:

• Str
• Char
• DateTime
• Uuid
• Uri
• Path
• Math