Per-chain semantic-variable validation cache (#81)

src/Becoming.php

@@ -26,6 +26,7 @@ final class Becoming implements BecomingInterface
 {
     private Being $being;
     private LoggerInterface $logger;
+    private BecomingArgumentsInterface $becomingArguments;
 
     public function __construct(
         InjectorInterface $injector,
@@ -37,6 +38,7 @@ public function __construct(
         $becomingArguments ??= new BecomingArguments($injector, new SemanticValidator($semanticNamespace));
         $logger ??= new Logger(new SemanticLogger(), $becomingArguments);
         $this->logger = $logger;
+        $this->becomingArguments = $becomingArguments;
         $this->being = new Being($logger, $becomingArguments, new BecomingType());
     }
 
@@ -57,6 +59,10 @@ public function __invoke(object $input): object
         $current = $input;
         $isFirst = true;
 
+        // Activate the semantic validator's per-chain cache; the finally below
+        // guarantees it is discarded whether the chain succeeds or throws.
+        $this->becomingArguments->beginChain();
+
         try {
             // Being reveals its becoming, then becomes it
             while ($nextForm = $this->being->willBe($current)) {
@@ -90,6 +96,8 @@ public function __invoke(object $input): object
             }
 
             throw $e;
+        } finally {
+            $this->becomingArguments->endChain();
         }
 
         // Success close is outside the try so a logging failure here is not

src/BecomingArguments.php

@@ -82,6 +82,18 @@ public function be(object $current, string $becoming): array
         return $args;
     }
 
+    #[Override]
+    public function beginChain(): void
+    {
+        $this->semanticValidator->beginChain();
+    }
+
+    #[Override]
+    public function endChain(): void
+    {
+        $this->semanticValidator->endChain();
+    }
+
     /**
      * Resolves #[Inject] parameters from DI container
      *

src/BecomingArgumentsInterface.php

@@ -25,4 +25,14 @@ interface BecomingArgumentsInterface
      * @phpstan-return array<string, mixed>
      */
     public function be(object $current, string $becoming): array;
+
+    /**
+     * Begin a metamorphosis chain (activates the semantic validator's per-chain cache).
+     */
+    public function beginChain(): void;
+
+    /**
+     * End a metamorphosis chain (discards the per-chain cache; must run even on failure).
+     */
+    public function endChain(): void;
 }

src/SemanticVariable/NullValidator.php

@@ -73,4 +73,22 @@ public function validateObject(object $object): Errors
     {
         return new NullErrors();
     }
+
+    /**
+     * No-op: the null validator has no cache to activate.
+     */
+    #[Override]
+    public function beginChain(): void
+    {
+        // No-op
+    }
+
+    /**
+     * No-op: the null validator has no cache to discard.
+     */
+    #[Override]
+    public function endChain(): void
+    {
+        // No-op
+    }
 }

src/SemanticVariable/SemanticValidator.php

@@ -14,14 +14,24 @@
 use ReflectionMethod;
 use ReflectionParameter;
 
+use function array_filter;
 use function array_key_exists;
+use function array_values;
 use function class_exists;
+use function count;
 use function get_object_vars;
+use function gettype;
+use function implode;
 use function in_array;
 use function is_array;
+use function is_object;
+use function reset;
+use function sort;
+use function spl_object_id;
 use function str_replace;
 use function trigger_error;
 use function ucwords;
+use function var_export;
 
 use const E_USER_NOTICE;
 
@@ -43,6 +53,19 @@ final class SemanticValidator implements SemanticValidatorInterface
     private readonly array $classMap;
     private readonly SemanticValidationMethodResolver $validationMethodResolver;
 
+    /** @var array<string, true> Full class names already confirmed missing — avoids re-checking class_exists() and re-emitting the notice on every call. */
+    private array $missingSemanticClasses = [];
+
+    /**
+     * Per-chain value-validation cache. null = inactive (outside a chain): every
+     * call re-validates and nothing accumulates. An array (set by beginChain())
+     * remembers successfully validated (name, attributes, value) triples for the
+     * lifetime of one Becoming::__invoke() chain.
+     *
+     * @var array<string, true>|null
+     */
+    private array|null $chainCache = null;
+
     /** @param array<string, class-string>|SemanticValidationMethodResolver|null $classMapOrValidationMethodResolver */
     public function __construct(
         #[Named('semantic_namespace')]
@@ -255,6 +278,12 @@ public function validateWithAttributes(string $variableName, array $parameterAtt
             return new NullErrors();
         }
 
+        $cacheKey = $this->chainCacheKey($variableName, $parameterAttributes, $args, $validationMethods);
+        if ($cacheKey !== null && isset($this->chainCache[$cacheKey])) {
+            // Same value carried unchanged through this chain — already validated.
+            return new NullErrors();
+        }
+
         $exceptions = [];
 
         foreach ($validationMethods as $method) {
@@ -266,9 +295,85 @@ public function validateWithAttributes(string $variableName, array $parameterAtt
             }
         }
 
+        if ($cacheKey !== null && empty($exceptions)) {
+            $this->chainCache[$cacheKey] = true;
+        }
+
         return empty($exceptions) ? new NullErrors() : new Errors($exceptions);
     }
 
+    /**
+     * Activate a fresh per-chain cache. See {@see SemanticValidatorInterface::beginChain()}.
+     */
+    #[Override]
+    public function beginChain(): void
+    {
+        $this->chainCache = [];
+    }
+
+    /**
+     * Discard the per-chain cache. See {@see SemanticValidatorInterface::endChain()}.
+     */
+    #[Override]
+    public function endChain(): void
+    {
+        $this->chainCache = null;
+    }
+
+    /**
+     * Cache key for a single-value validation, or null when caching must be bypassed.
+     *
+     * Bypassed when: no active chain; not a single-value call; the value is an
+     * array (normalizing it costs more than re-validating); or any resolved
+     * #[Validate] method takes an #[Inject] parameter (it may consult mutable
+     * injected state and legitimately return a different answer for the same
+     * value, so its result must never be cached).
+     *
+     * The key combines the variable name, the SORTED attribute set (so a later
+     * #[Teen] int $age never reuses an earlier plain int $age result — they
+     * select different #[Validate] methods), and a value key. Scalars/null are
+     * type-tagged to avoid 1/"1"/true collisions; objects use spl_object_id(),
+     * which is a safe stand-in for value identity ONLY because Be Framework's
+     * public-readonly convention means an object's identity implies its state
+     * is unchanged since construction.
+     *
+     * @param ParameterAttributes $parameterAttributes
+     * @param ValidationArguments $args
+     * @param ReflectionMethods   $validationMethods
+     * @phpstan-param array<array-key, mixed>      $parameterAttributes
+     * @phpstan-param array<array-key, mixed>      $args
+     * @phpstan-param array<int, ReflectionMethod> $validationMethods
+     */
+    private function chainCacheKey(string $variableName, array $parameterAttributes, array $args, array $validationMethods): string|null
+    {
+        if ($this->chainCache === null || count($args) !== 1) {
+            return null;
+        }
+
+        /** @var mixed $value */
+        $value = reset($args);
+        if (is_array($value)) {
+            return null;
+        }
+
+        foreach ($validationMethods as $method) {
+            foreach ($method->getParameters() as $parameter) {
+                if ($this->validationMethodResolver->hasInjectAttribute($parameter)) {
+                    return null;
+                }
+            }
+        }
+
+        $valueKey = is_object($value)
+            ? 'obj:' . spl_object_id($value)
+            : gettype($value) . ':' . var_export($value, true);
+
+        $attributes = array_values(array_filter($parameterAttributes, 'is_string'));
+        sort($attributes);
+
+        return $variableName . '|' . implode(',', $attributes) . '|' . $valueKey;
+    }
+
     /**
      * Resolve semantic class from variable name
      */
@@ -277,7 +382,12 @@ private function resolveSemanticClass(string $variableName): object|null
         $className = $this->convertToClassName($variableName);
         $fullClassName = $this->classMap[$className] ?? "{$this->semanticNamespace}\\$className";
 
+        if (isset($this->missingSemanticClasses[$fullClassName])) {
+            return null;
+        }
+
         if (! class_exists($fullClassName)) {
+            $this->missingSemanticClasses[$fullClassName] = true;
             trigger_error("Semantic variable '{$className}' not registered in ontology namespace {$this->semanticNamespace}", E_USER_NOTICE);
 
             return null;

src/SemanticVariable/SemanticValidatorInterface.php

@@ -39,4 +39,22 @@ public function validateArgs(ReflectionMethod $method, array $args): Errors;
      * @return Errors Validation errors (empty if validation passes)
      */
     public function validateArg(ReflectionParameter $parameter, mixed $value): Errors;
+
+    /**
+     * Begin a metamorphosis chain: activate the per-chain value-validation cache.
+     *
+     * Between beginChain() and endChain(), a successfully validated
+     * (parameterName, attributes, value) triple is remembered so an unchanged
+     * value carried through several hops of one chain is validated once. Outside
+     * this window the cache is inactive and every call re-validates.
+     */
+    public function beginChain(): void;
+
+    /**
+     * End a metamorphosis chain: discard the per-chain cache.
+     *
+     * Must be called (even on failure) so cache entries never outlive their
+     * chain — the unbounded-growth failure mode documented for SemanticLogger.
+     */
+    public function endChain(): void;
 }

tests/BecomingTest.php

@@ -18,7 +18,9 @@
 use Be\Framework\SemanticVariable\Errors;
 use Be\Framework\SemanticVariable\SemanticValidator;
 use InvalidArgumentException;
+use Koriym\SemanticLogger\Exception\NoLogSessionException;
 use Koriym\SemanticLogger\SemanticLogger;
+use MyVendor\MyApp\SemanticVariables\Counted;
 use PHPUnit\Framework\TestCase;
 use Ray\Di\AbstractModule;
 use Ray\Di\Di\Inject;
@@ -291,6 +293,27 @@ public function testChainCloseLogRecordsRuntimeOrigin(): void
         $this->assertSame(BecomingCloseContext::ORIGIN_RUNTIME, $context['origin']);
     }
 
+    public function testFlushReturnsAccumulatedSessionAndResetsState(): void
+    {
+        // BeModule binds SemanticLoggerInterface as a singleton so one instance
+        // can accumulate several chains before the caller reads it out (see
+        // docs/semantic-log-architecture.md#log-lifecycle-flush-ownership).
+        // flush() must return everything accumulated so far AND reset the
+        // logger's internal state so a later read finds no session.
+        $semanticLogger = new SemanticLogger();
+        $becoming = $this->becomingWithLogger($semanticLogger);
+
+        $becoming(new BecomingTestInput('first'));
+        $becoming(new BecomingTestInput('second'));
+
+        $session = $semanticLogger->flush()->toArray();
+        assert(is_array($session['open']));
+        $this->assertCount(2, $session['open'], 'flush() must return both accumulated chains');
+
+        $this->expectException(NoLogSessionException::class);
+        $semanticLogger->toArray();
+    }
+
     private function becomingWithLogger(SemanticLogger $semanticLogger): Becoming
     {
         $injector = new Injector(new BecomingTestModule());
@@ -349,6 +372,50 @@ public function testInfrastructureExceptionPropagatesImmediately(): void
         $input = new BecomingTestInfrastructureErrorInput('test');
         ($this->becoming)($input);
     }
+
+    public function testUnchangedValueValidatedOncePerChainThenReValidatedNextChain(): void
+    {
+        // Issue #81: a value carried unchanged through a chain's hops is
+        // validated once, but each new Becoming::__invoke() starts fresh.
+        Counted::$count = 0;
+
+        $result = ($this->becoming)(new BecomingTestCacheStart(5));
+        $this->assertSame(5, $result->counted);
+        $this->assertSame(1, Counted::$count, 'Unchanged value validated once within one chain');
+
+        ($this->becoming)(new BecomingTestCacheStart(5));
+        $this->assertSame(2, Counted::$count, 'A new chain re-validates (cache is per-chain)');
+    }
+}
+
+// Cache-per-chain fixtures (issue #81): `counted` carried unchanged through hops.
+#[Be(BecomingTestCacheMid::class)]
+final class BecomingTestCacheStart
+{
+    public function __construct(
+        #[Input]
+        public readonly int $counted,
+    ) {
+    }
+}
+
+#[Be(BecomingTestCacheEnd::class)]
+final class BecomingTestCacheMid
+{
+    public function __construct(
+        #[Input]
+        public readonly int $counted,
+    ) {
+    }
+}
+
+final class BecomingTestCacheEnd
+{
+    public function __construct(
+        #[Input]
+        public readonly int $counted,
+    ) {
+    }
 }
 
 // Test fixtures for coverage testing

tests/FakeApp/SemanticVariables/Counted.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MyVendor\MyApp\SemanticVariables;
+
+use Be\Framework\Attribute\Validate;
+
+/**
+ * Pure semantic variable (no #[Inject]) used to observe per-chain caching:
+ * $count reveals how many times validation actually ran.
+ */
+final class Counted
+{
+    public static int $count = 0;
+
+    #[Validate]
+    public function validateCounted(int $counted): void
+    {
+        self::$count++;
+    }
+}