Introduce foundation architectural support

.github/codecov.yaml

@@ -16,6 +16,12 @@ component_management:
         - "src/Exception/**"
       coverage:
         target: 80%
+    - component_id: module_meta
+      name: meta
+      paths:
+        - "src/Meta/**"
+      coverage:
+        target: 80%
     - component_id: module_type
       name: type
       paths:

src/Boundary/Algorithm/Sorting/DistributionSortAlgorithm.php

@@ -0,0 +1,55 @@
+<?php declare(strict_types = 1);
+
+/**
+ * This file is part of the FireHub Project ecosystem
+ *
+ * @author Danijel Galić <danijel.galic@outlook.com>
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=7.4
+ * @package Core
+ */
+
+namespace FireHub\Core\Boundary\Algorithm\Sorting;
+
+/**
+ *  ### Defines a distribution sorting algorithm
+ *
+ * Defines the contract for non-comparison sorting algorithms that distribute elements according to numeric keys
+ * extracted from their values.
+ *
+ * Unlike comparison-based sorting algorithms, distribution sorting algorithms do not determine ordering by repeatedly
+ * comparing pairs of elements. Instead, they use the structure or distribution of extracted numeric keys to place
+ * elements into their resulting order.
+ * @since 1.0.0
+ *
+ * @template TElement
+ * @template TKey of int|float
+ */
+interface DistributionSortAlgorithm {
+
+    /**
+     * ### Sorts elements
+     *
+     * Sorts elements addressed by sequential positions according to integer keys extracted from their values.
+     * @since 1.0.0
+     *
+     * @param non-negative-int $size <p>
+     * Number of elements to sort.
+     * </p>
+     * @param callable(non-negative-int):TElement $element <p>
+     * Callback used to retrieve an element by its sequential position.
+     * </p>
+     * @param callable(non-negative-int, TElement):void $set <p>
+     * Callback used to replace an element at its sequential position.
+     * </p>
+     * @param callable(TElement):TKey $key <p>
+     * Callback used to extract the integer distribution key from an element.
+     * </p>
+     *
+     * @return void
+     */
+    public function sort (int $size, callable $element, callable $set, callable $key):void;
+
+}

src/Boundary/Algorithm/Sorting/SortAlgorithm.php

@@ -0,0 +1,61 @@
+<?php declare(strict_types = 1);
+
+/**
+ * This file is part of the FireHub Project ecosystem
+ *
+ * @author Danijel Galić <danijel.galic@outlook.com>
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=7.4
+ * @package Core
+ */
+
+namespace FireHub\Core\Boundary\Algorithm\Sorting;
+
+/**
+ * ### Sorting algorithm
+ *
+ * Defines a strategy for ordering elements within an indexed range.
+ *
+ * Elements are addressed internally by sequential positions, independently of the keys or indexes used by their
+ * underlying representation. This allows the algorithm to operate on sequential values, key-value entries, and other
+ * ordered representations without depending on their storage semantics.
+ *
+ * Sorting is performed in place through the supplied access and swap operations.
+ * @since 1.0.0
+ *
+ * @template TElement
+ */
+interface SortAlgorithm {
+
+    /**
+     * ### Sorts elements
+     *
+     * Rearranges the specified number of elements according to the supplied comparison callback.
+     *
+     * The callback must return a value less than zero when the first element should precede the second, zero when both
+     * elements compare equally, or a value greater than zero when the first element should follow the second.
+     * @since 1.0.0
+     *
+     * @param non-negative-int $size <p>
+     * Number of elements to sort.
+     * </p>
+     * @param callable(non-negative-int):TElement $element <p>
+     * Callback used to retrieve an element by its internal position.
+     * </p>
+     * @param callable(non-negative-int, TElement):void $set <p>
+     * Callback used to replace an element at its sequential position.
+     * </p>
+     * @param callable(non-negative-int, non-negative-int):void $swap <p>
+     * Callback used to exchange two elements by their internal positions.
+     * </p>
+     * @param callable(TElement, TElement):int $comparator <p>
+     * Callback used to compare two elements.
+     * </p>
+     *
+     * @return void
+     */
+    public function sort (int $size, callable $element, callable $set, callable $swap, callable $comparator):void;
+
+}

src/Boundary/Capability/Access/BackAccess.php

@@ -0,0 +1,41 @@
+<?php declare(strict_types = 1);
+
+/**
+ * This file is part of the FireHub Project ecosystem
+ *
+ * @author Danijel Galić <danijel.galic@outlook.com>
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=7.4
+ * @package Core
+ */
+
+namespace FireHub\Core\Boundary\Capability\Access;
+
+use FireHub\Core\Type\Maybe;
+
+/**
+ * ### Defines access to the back boundary value
+ *
+ * Back access provides read-only access to the last value of an ordered sequence.
+ *
+ * The capability defines the fundamental operation for retrieving the value at the back boundary without
+ * prescribing how values are stored, organized, or represented internally.
+ * @since 1.0.0
+ *
+ * @template TValue
+ */
+interface BackAccess {
+
+    /**
+     * ### Returns the last value
+     *
+     * Returns the value at the end of the sequence when it exists.
+     * @since 1.0.0
+     *
+     * @return \FireHub\Core\Type\Maybe<TValue|mixed> The last value, or an empty Maybe if no value exists.
+     */
+    public function last ():Maybe;
+
+}

src/Boundary/Capability/Access/BoundaryAccess.php

@@ -0,0 +1,30 @@
+<?php declare(strict_types = 1);
+
+/**
+ * This file is part of the FireHub Project ecosystem
+ *
+ * @author Danijel Galić <danijel.galic@outlook.com>
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=7.0
+ * @package Core
+ */
+
+namespace FireHub\Core\Boundary\Capability\Access;
+
+/**
+ * ### Defines access to boundary values
+ *
+ * Boundary access provides read-only access to the first and last values of an ordered sequence.
+ *
+ * The capability defines the fundamental operations for retrieving values at the boundaries without prescribing
+ * how values are stored, organized, or represented internally.
+ * @since 1.0.0
+ *
+ * @template TValue
+ *
+ * @extends \FireHub\Core\Boundary\Capability\Access\FrontAccess<TValue>
+ * @extends \FireHub\Core\Boundary\Capability\Access\BackAccess<TValue>
+ */
+interface BoundaryAccess extends FrontAccess, BackAccess {}

src/Boundary/Capability/Access/FrontAccess.php

@@ -0,0 +1,41 @@
+<?php declare(strict_types = 1);
+
+/**
+ * This file is part of the FireHub Project ecosystem
+ *
+ * @author Danijel Galić <danijel.galic@outlook.com>
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=7.4
+ * @package Core
+ */
+
+namespace FireHub\Core\Boundary\Capability\Access;
+
+use FireHub\Core\Type\Maybe;
+
+/**
+ * ### Defines access to the front boundary value
+ *
+ * Front access provides read-only access to the first value of an ordered sequence.
+ *
+ * The capability defines the fundamental operation for retrieving the value at the front boundary without
+ * prescribing how values are stored, organized, or represented internally.
+ * @since 1.0.0
+ *
+ * @template TValue
+ */
+interface FrontAccess {
+
+    /**
+     * ### Returns the first value
+     *
+     * Returns the value at the beginning of the sequence when it exists.
+     * @since 1.0.0
+     *
+     * @return \FireHub\Core\Type\Maybe<TValue|mixed> The first value, or an empty Maybe if no value exists.
+     */
+    public function first ():Maybe;
+
+}

src/Boundary/Capability/Access/IndexAccess.php

@@ -0,0 +1,60 @@
+<?php declare(strict_types = 1);
+
+/**
+ * This file is part of the FireHub Project ecosystem
+ *
+ * @author Danijel Galić <danijel.galic@outlook.com>
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=7.4
+ * @package Core
+ */
+
+namespace FireHub\Core\Boundary\Capability\Access;
+
+use FireHub\Core\Type\Maybe;
+
+/**
+ * ### Defines indexed access to values
+ *
+ * Indexed access provides read-only access to values identified by an integer index.
+ *
+ * The capability defines the fundamental operations for determining whether an index exists and retrieving the
+ * value associated with it, without prescribing how values are stored, organized, or represented internally.
+ * @since 1.0.0
+ *
+ * @template TValue
+ */
+interface IndexAccess {
+
+    /**
+     * ### Determines whether an index exists
+     *
+     * Determines whether a value is available at the specified index.
+     * @since 1.0.0
+     *
+     * @param int $index <p>
+     * The index to check.
+     * </p>
+     *
+     * @return bool True if the index exists, false otherwise.
+     */
+    public function has (int $index):bool;
+
+    /**
+     * ### Returns the value at the specified index
+     *
+     * Returns the value currently stored at the specified index.
+     * @since 1.0.0
+     *
+     * @param int $index <p>
+     * The zero-based index of the value to retrieve.
+     * </p>
+     *
+     * @return \FireHub\Core\Type\Maybe<TValue|mixed> The value at the specified index, or an empty Maybe if the index
+     * does not exist.
+     */
+    public function get (int $index):Maybe;
+
+}

src/Boundary/Capability/Access/KeyAccess.php

@@ -0,0 +1,56 @@
+<?php declare(strict_types = 1);
+
+/**
+ * This file is part of the FireHub Project ecosystem
+ *
+ * @author Danijel Galić <danijel.galic@outlook.com>
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=7.4
+ * @package Core
+ */
+
+namespace FireHub\Core\Boundary\Capability\Access;
+
+use FireHub\Core\Type\Maybe;
+
+/**
+ * ### Defines key-based access to values
+ *
+ * Key access provides read-only access to values identified by their keys.
+ *
+ * The capability defines the fundamental operations for determining whether a key exists and retrieving the value
+ * associated with it, without prescribing how values are stored, organized, or represented internally.
+ * @since 1.0.0
+ *
+ * @template TKey
+ * @template TValue
+ */
+interface KeyAccess {
+
+    /**
+     * ### Determines whether a key exists
+     * @since 1.0.0
+     *
+     * @param TKey $key <p>
+     * The key to check.
+     * </p>
+     *
+     * @return bool True if a value exists for the specified key, false otherwise.
+     */
+    public function has (mixed $key):bool;
+
+    /**
+     * ### Returns the value associated with the specified key
+     * @since 1.0.0
+     *
+     * @param TKey $key <p>
+     * The key whose value should be returned.
+     * </p>
+     *
+     * @return \FireHub\Core\Type\Maybe<TValue|mixed> The associated value, or an empty Maybe if the key does not exist.
+     */
+    public function get (mixed $key):Maybe;
+
+}