feat(error-layer): introduce deterministic error serialization kernel

- Introduced ErrorContext immutable VO
- Introduced NormalizedError immutable VO with defensive meta snapshot
- Introduced ErrorResponseModel immutable response abstraction
- Introduced ThrowableToErrorInterface (deterministic mapping contract)
- Implemented DefaultThrowableToError with strict fallback lock
- Introduced FormatterInterface (pure deterministic formatting contract)
- Implemented JsonErrorFormatter (stable JSON envelope)
- Implemented ProblemDetailsFormatter (RFC7807 compliant)
- Introduced ErrorSerializer readonly orchestrator
- Added determinism stress tests (JSON + RFC)
- Added immutability validation tests
- Added fallback safety tests (no external message leakage)
- Extended API_FREEZE_POLICY with Determinism Boundary section

Compliance:
- Preserves 1.x API freeze guarantees
- Maintains strict determinism (no randomness, no timestamps)
- No public signature modifications
- No JSON envelope breaking changes
- Fully backward compatible

Phase: Error Layer – Determinism Lock Complete

Author: megyptm

docs/API_FREEZE_POLICY.md

@@ -175,6 +175,43 @@ Breaking determinism = breaking change.
 
 ---
 
+## 7.1 Determinism Boundary & Extension Responsibility
+
+The library guarantees deterministic behavior for all **shipped components**, including:
+
+* DefaultThrowableToError
+* JsonErrorFormatter
+* ProblemDetailsFormatter
+* ErrorSerializer
+* All Value Objects
+
+Determinism means:
+
+* Same Throwable + Same Context → identical output
+* No randomness
+* No timestamps
+* No environment-based branching
+* No stack trace exposure
+
+However, the following are **outside the deterministic guarantee of the library**:
+
+* Custom implementations of `ThrowableToErrorInterface`
+* Custom implementations of `FormatterInterface`
+* Application-provided `meta` data
+
+The library guarantees deterministic **transformation of input**.
+It does not guarantee deterministic **input provided by the application**.
+
+Custom extensions must preserve:
+
+* Safety
+* Determinism
+* JSON contract stability
+
+Failure to do so constitutes misuse of the extension surface, not a defect in the kernel.
+
+---
+
 # 8️⃣ Extension Rules
 
 All extension mechanisms must:

src/Application/Error/DefaultThrowableToError.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Maatify\Exceptions\Application\Error;
+
+use Maatify\Exceptions\Exception\MaatifyException;
+use Throwable;
+
+final class DefaultThrowableToError implements ThrowableToErrorInterface
+{
+    public function map(Throwable $t): NormalizedError
+    {
+        if ($t instanceof MaatifyException) {
+            return new NormalizedError(
+                $t->getErrorCode()->getValue(),
+                $t->getMessage(),
+                $t->getHttpStatus(),
+                $t->getCategory()->getValue(),
+                $t->isRetryable(),
+                $t->isSafe(),
+                $t->getMeta()
+            );
+        }
+
+        // Fallback for external exceptions
+        return new NormalizedError(
+            'INTERNAL_ERROR',
+            'An unexpected error occurred.',
+            500,
+            'internal',
+            false,
+            true,
+            []
+        );
+    }
+}

src/Application/Error/ErrorContext.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Maatify\Exceptions\Application\Error;
+
+/**
+ * Immutable Value Object representing the error context.
+ *
+ * @psalm-immutable
+ */
+final readonly class ErrorContext
+{
+
+    public function __construct(
+        private ?string $traceId = null,
+        private ?string $instance = null,
+        private bool $debug = false
+    ) {
+    }
+
+    public function getTraceId(): ?string
+    {
+        return $this->traceId;
+    }
+
+    public function getInstance(): ?string
+    {
+        return $this->instance;
+    }
+
+    public function isDebug(): bool
+    {
+        return $this->debug;
+    }
+}

src/Application/Error/ErrorResponseModel.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Maatify\Exceptions\Application\Error;
+
+/**
+ * Immutable Value Object representing the final error response.
+ *
+ * @psalm-immutable
+ */
+final class ErrorResponseModel
+{
+    /** @var array<string, string> */
+    private array $headers;
+    /** @var array<mixed> */
+    private array $body;
+
+    /**
+     * @param int $status
+     * @param array<string, string> $headers
+     * @param string $contentType
+     * @param array<mixed> $body
+     */
+    public function __construct(
+        private readonly int $status,
+        array $headers,
+        private readonly string $contentType,
+        array $body
+    ) {
+        $this->headers = [...$headers];
+        $this->body = [...$body];
+    }
+
+    public function getStatus(): int
+    {
+        return $this->status;
+    }
+
+    /**
+     * @return array<string, string>
+     */
+    public function getHeaders(): array
+    {
+        return [...$this->headers];
+    }
+
+    public function getContentType(): string
+    {
+        return $this->contentType;
+    }
+
+    /**
+     * @return array<mixed>
+     */
+    public function getBody(): array
+    {
+        return [...$this->body];
+    }
+}

src/Application/Error/ErrorSerializer.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Maatify\Exceptions\Application\Error;
+
+use Maatify\Exceptions\Application\Format\FormatterInterface;
+use Throwable;
+
+final readonly class ErrorSerializer
+{
+    public function __construct(
+        private ThrowableToErrorInterface $mapper,
+        private FormatterInterface $formatter
+    ) {
+    }
+
+    public function serialize(Throwable $t, ?ErrorContext $context = null): ErrorResponseModel
+    {
+        $context = $context ?? new ErrorContext();
+        $normalized = $this->mapper->map($t);
+
+        return $this->formatter->format($normalized, $context);
+    }
+}

src/Application/Error/NormalizedError.php

@@ -0,0 +1,73 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Maatify\Exceptions\Application\Error;
+
+/**
+ * Immutable Value Object representing a normalized error.
+ *
+ * @psalm-immutable
+ */
+final class NormalizedError
+{
+
+    /**
+     * @param string $code
+     * @param string $message
+     * @param int $status
+     * @param string $category
+     * @param bool $retryable
+     * @param bool $safe
+     * @param array<mixed> $meta
+     */
+    public function __construct(
+        private readonly string $code,
+        private readonly string $message,
+        private readonly int $status,
+        private readonly string $category,
+        private readonly bool $retryable,
+        private readonly bool $safe,
+        private array $meta
+    ) {
+        $this->meta = [...$meta];
+    }
+
+    public function getCode(): string
+    {
+        return $this->code;
+    }
+
+    public function getMessage(): string
+    {
+        return $this->message;
+    }
+
+    public function getStatus(): int
+    {
+        return $this->status;
+    }
+
+    public function getCategory(): string
+    {
+        return $this->category;
+    }
+
+    public function isRetryable(): bool
+    {
+        return $this->retryable;
+    }
+
+    public function isSafe(): bool
+    {
+        return $this->safe;
+    }
+
+    /**
+     * @return array<mixed>
+     */
+    public function getMeta(): array
+    {
+        return $this->meta;
+    }
+}

src/Application/Error/ThrowableToErrorInterface.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Maatify\Exceptions\Application\Error;
+
+use Throwable;
+
+interface ThrowableToErrorInterface
+{
+    /**
+     * Maps any Throwable to a NormalizedError VO.
+     * Must be deterministic.
+     */
+    public function map(Throwable $t): NormalizedError;
+}

src/Application/Format/FormatterInterface.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Maatify\Exceptions\Application\Format;
+
+use Maatify\Exceptions\Application\Error\ErrorContext;
+use Maatify\Exceptions\Application\Error\ErrorResponseModel;
+use Maatify\Exceptions\Application\Error\NormalizedError;
+
+interface FormatterInterface
+{
+    /**
+     * Formats a normalized error into a response model.
+     * Must be deterministic.
+     */
+    public function format(NormalizedError $error, ErrorContext $context): ErrorResponseModel;
+}

src/Application/Format/JsonErrorFormatter.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Maatify\Exceptions\Application\Format;
+
+use Maatify\Exceptions\Application\Error\ErrorContext;
+use Maatify\Exceptions\Application\Error\ErrorResponseModel;
+use Maatify\Exceptions\Application\Error\NormalizedError;
+
+final class JsonErrorFormatter implements FormatterInterface
+{
+    public function format(NormalizedError $error, ErrorContext $context): ErrorResponseModel
+    {
+        $body = [
+            'error' => [
+                'code' => $error->getCode(),
+                'message' => $error->getMessage(),
+                'status' => $error->getStatus(),
+                'category' => $error->getCategory(),
+                'retryable' => $error->isRetryable(),
+                'safe' => $error->isSafe(),
+                'meta' => $error->getMeta(),
+            ],
+        ];
+
+        if ($context->getTraceId() !== null) {
+            $body['trace_id'] = $context->getTraceId();
+        }
+
+        return new ErrorResponseModel(
+            $error->getStatus(),
+            [],
+            'application/json; charset=utf-8',
+            $body
+        );
+    }
+}