Relocate cache logging into decorators (storage and dependency)

Move all semantic-log emission for cache writes out of the business classes
and into transparent decorators, so ResourceStorage and CacheDependency carry
no logging concern.

- LoggableResourceStorage wraps ResourceStorage: every save event, the
  invalidate outcome (manual_invalidate scope when top-level), and the
  fail-closed CDN re-throw live here. ResourceStorage no longer takes a logger.
- LoggableCacheDependency wraps CacheDependency: emits the depends-on edge.
  The child tags are read before delegating, since depends() unsets the child's
  surrogate-key header while wiring the dependency.
- CacheTags centralizes the tag derivation shared by the storage (which saves
  with the tags) and the decorators (which log the same tags), with no
  duplication.
- invalidateTags() returns an InvalidateResult value object carrying the
  per-target (resource pool / ETag pool / CDN) outcome, which the side-effecting
  pool operations compute and a bare bool could not express. The decorator turns
  it into the InvalidateContext and re-throws the CDN error after logging.
- Wire both via the Ray.Di decorator idiom: the undecorated implementation is
  bound under 'origin', the interface to the decorator.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SJnuk1B1yXK6bxXuU9DGCo

Author: koriym

src/CacheDependency.php

@@ -4,43 +4,29 @@
 
 namespace BEAR\QueryRepository;
 
-use BEAR\QueryRepository\Log\Context\DependsOnContext;
-use BEAR\QueryRepository\Log\NullSemanticLogger;
 use BEAR\Resource\ResourceObject;
-use Koriym\SemanticLogger\SemanticLoggerInterface;
 use Override;
 
-use function explode;
 use function sprintf;
 
 final readonly class CacheDependency implements CacheDependencyInterface
 {
     public function __construct(
-        private UriTagInterface $uriTag,
-        private SemanticLoggerInterface $logger = new NullSemanticLogger(),
+        private CacheTags $cacheTags,
     ) {
     }
 
     #[Override]
     public function depends(ResourceObject $from, ResourceObject $to): void
     {
-        $childTags = ($this->uriTag)($to->uri);
-        if (isset($to->headers[Header::SURROGATE_KEY])) {
-            $childTags .= sprintf(' %s', $to->headers[Header::SURROGATE_KEY]);
-            unset($to->headers[Header::SURROGATE_KEY]);
-        }
+        $childTags = $this->cacheTags->childTags($to);
+        unset($to->headers[Header::SURROGATE_KEY]);
 
         // Accumulate across every embedded child: a resource that embeds more than one
         // child must depend on all of them, not only the last. Overwriting here used to
         // silently drop earlier children's dependencies (stale-cache bug).
         $from->headers[Header::SURROGATE_KEY] = isset($from->headers[Header::SURROGATE_KEY])
             ? sprintf('%s %s', $from->headers[Header::SURROGATE_KEY], $childTags)
             : $childTags;
-
-        $this->logger->event(new DependsOnContext(
-            (string) $from->uri,
-            (string) $to->uri,
-            explode(' ', $childTags),
-        ));
     }
 }

src/CacheTags.php

@@ -0,0 +1,78 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BEAR\QueryRepository;
+
+use BEAR\Resource\AbstractUri;
+use BEAR\Resource\ResourceObject;
+
+use function array_merge;
+use function array_unique;
+use function array_values;
+use function explode;
+use function sprintf;
+
+/**
+ * Pure cache-tag computation shared by ResourceStorage (which saves with the tags)
+ * and LoggableResourceStorage (which logs the same tags)
+ *
+ * Extracted so the decorator can report exactly the tags that were stored without
+ * duplicating the derivation logic. Every method is a pure function of its inputs.
+ */
+final class CacheTags
+{
+    public function __construct(private readonly UriTagInterface $uriTag)
+    {
+    }
+
+    /**
+     * Tags for storing a resource: its ETag, its URI tag, and any surrogate keys
+     *
+     * @return list<string>
+     */
+    public function ofResource(ResourceObject $ro): array
+    {
+        $tags = [$ro->headers[Header::ETAG], ($this->uriTag)($ro->uri)];
+        if (isset($ro->headers[Header::SURROGATE_KEY])) {
+            $tags = array_merge($tags, explode(' ', $ro->headers[Header::SURROGATE_KEY]));
+        }
+
+        /** @var list<string> $uniqueTags */
+        $uniqueTags = array_values(array_unique($tags));
+
+        return $uniqueTags;
+    }
+
+    /**
+     * The surrogate-key string a parent inherits when it depends on a child
+     *
+     * The child's URI tag, plus the child's own surrogate keys when present. Pure read:
+     * it does not mutate the child (the dependency wiring is CacheDependency's concern).
+     */
+    public function childTags(ResourceObject $to): string
+    {
+        $childTags = ($this->uriTag)($to->uri);
+        if (isset($to->headers[Header::SURROGATE_KEY])) {
+            $childTags .= sprintf(' %s', $to->headers[Header::SURROGATE_KEY]);
+        }
+
+        return $childTags;
+    }
+
+    /**
+     * Tags for storing an ETag entry: the surrogate keys plus the URI tag
+     *
+     * @return list<string>
+     */
+    public function ofEtag(AbstractUri $uri, string $surrogateKeys): array
+    {
+        $tags = $surrogateKeys !== '' ? explode(' ', $surrogateKeys) : [];
+        $tags[] = ($this->uriTag)($uri);
+
+        /** @var list<string> $uniqueTags */
+        $uniqueTags = array_values(array_unique($tags));
+
+        return $uniqueTags;
+    }
+}

src/InvalidateResult.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BEAR\QueryRepository;
+
+use Throwable;
+
+/**
+ * Outcome of a tag invalidation across the resource pool, the ETag pool, and the CDN
+ *
+ * ResourceStorage returns this instead of a bare bool so the logging decorator can
+ * report the per-target outcome (roPool / etagPool / cdn) that is computed by the
+ * side-effecting pool operations and is not derivable from the inputs alone. The
+ * CDN purge error is carried (not thrown) so the decorator can log the failure
+ * before re-throwing it (fail-closed).
+ */
+final class InvalidateResult
+{
+    /** @param list<string> $tags */
+    public function __construct(
+        public readonly array $tags,
+        public readonly bool $roInvalidated,
+        public readonly bool $etagInvalidated,
+        public readonly Throwable|null $cdnError = null,
+    ) {
+    }
+
+    /**
+     * Whether both local pools were invalidated (the legacy bool return value)
+     */
+    public function isInvalidated(): bool
+    {
+        return $this->roInvalidated && $this->etagInvalidated;
+    }
+}

src/LoggableCacheDependency.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BEAR\QueryRepository;
+
+use BEAR\QueryRepository\Log\Context\DependsOnContext;
+use BEAR\Resource\ResourceObject;
+use Koriym\SemanticLogger\SemanticLoggerInterface;
+use Override;
+use Ray\Di\Di\Named;
+
+use function explode;
+
+/**
+ * Logging decorator for CacheDependency
+ *
+ * Emits the depends-on edge as a semantic-log event, keeping CacheDependency itself
+ * free of logging. The child tags are read with {@see CacheTags} before delegating,
+ * because depends() unsets the child's surrogate-key header as part of wiring the
+ * dependency, which would otherwise destroy the inputs needed to report the edge.
+ */
+final readonly class LoggableCacheDependency implements CacheDependencyInterface
+{
+    public function __construct(
+        #[Named('origin')]
+        private CacheDependencyInterface $cacheDependency,
+        private SemanticLoggerInterface $logger,
+        private CacheTags $cacheTags,
+    ) {
+    }
+
+    #[Override]
+    public function depends(ResourceObject $from, ResourceObject $to): void
+    {
+        $childTags = $this->cacheTags->childTags($to);
+        $this->cacheDependency->depends($from, $to);
+        $this->logger->event(new DependsOnContext(
+            (string) $from->uri,
+            (string) $to->uri,
+            explode(' ', $childTags),
+        ));
+    }
+}

src/LoggableResourceStorage.php

@@ -0,0 +1,158 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BEAR\QueryRepository;
+
+use BEAR\QueryRepository\Log\Context\InvalidateContext;
+use BEAR\QueryRepository\Log\Context\ManualInvalidateContext;
+use BEAR\QueryRepository\Log\Context\SaveDonutContext;
+use BEAR\QueryRepository\Log\Context\SaveDonutViewContext;
+use BEAR\QueryRepository\Log\Context\SaveEtagContext;
+use BEAR\QueryRepository\Log\Context\SaveValueContext;
+use BEAR\QueryRepository\Log\Context\SaveViewContext;
+use BEAR\QueryRepository\Log\SafeSemanticLogger;
+use BEAR\Resource\AbstractUri;
+use BEAR\Resource\ResourceObject;
+use Koriym\SemanticLogger\SemanticLoggerInterface;
+use Override;
+use Ray\Di\Di\Named;
+
+use function hrtime;
+use function round;
+
+/**
+ * Logging decorator for ResourceStorage
+ *
+ * Keeps the storage itself free of any logging concern: every cache write emits its
+ * semantic-log event here, around a transparent delegation to the wrapped storage.
+ * The tags reported for a save are recomputed with the same {@see CacheTags} the
+ * storage uses, so the log records exactly what was stored.
+ *
+ * Reads (get / getDonut / hasEtag) are pass-through: a request's hit/miss is logged
+ * at the interceptor / donut-repository layer where the request-level outcome lives,
+ * not at the low-level pool read.
+ */
+final class LoggableResourceStorage implements ResourceStorageInterface
+{
+    public function __construct(
+        #[Named('origin')]
+        private readonly ResourceStorageInterface $storage,
+        private readonly SemanticLoggerInterface $logger,
+        private readonly CacheTags $cacheTags,
+        private readonly UriTagInterface $uriTag,
+    ) {
+    }
+
+    #[Override]
+    public function hasEtag(string $etag): bool
+    {
+        return $this->storage->hasEtag($etag);
+    }
+
+    #[Override]
+    public function saveEtag(AbstractUri $uri, string $etag, string $surrogateKeys, int|null $ttl): void
+    {
+        $this->storage->saveEtag($uri, $etag, $surrogateKeys, $ttl);
+        $this->logger->event(new SaveEtagContext((string) $uri, $etag, $this->cacheTags->ofEtag($uri, $surrogateKeys)));
+    }
+
+    #[Override]
+    public function deleteEtag(AbstractUri $uri)
+    {
+        return $this->invalidateTags([($this->uriTag)($uri)])->isInvalidated();
+    }
+
+    #[Override]
+    public function get(AbstractUri $uri): ResourceState|null
+    {
+        return $this->storage->get($uri);
+    }
+
+    #[Override]
+    public function getDonut(AbstractUri $uri): ResourceDonut|null
+    {
+        return $this->storage->getDonut($uri);
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * A top-level invalidation is a direct (non-AOP) call with no enclosing scope, so the
+     * event would be dropped at flush. Root it in a manual_invalidate scope whose close
+     * carries the outcome. Nested invalidations (inside a GET or a command) stay events.
+     *
+     * The CDN purge is fail-closed: a purge failure is logged (cdn=failed) and then
+     * re-thrown so a write does not silently leave stale CDN content.
+     */
+    #[Override]
+    public function invalidateTags(array $tags): InvalidateResult
+    {
+        $start = hrtime(true);
+        $result = $this->storage->invalidateTags($tags);
+        $context = new InvalidateContext(
+            $result->tags,
+            roPoolInvalidated: $result->roInvalidated,
+            etagPoolInvalidated: $result->etagInvalidated,
+            cdnPurged: $result->cdnError === null,
+            durationMs: round((hrtime(true) - $start) / 1_000_000, 3),
+        );
+
+        if ($this->logger instanceof SafeSemanticLogger && $this->logger->isTopLevel()) {
+            $openId = $this->logger->open(new ManualInvalidateContext($tags));
+            $this->logger->close($context, $openId);
+        } else {
+            $this->logger->event($context);
+        }
+
+        if ($result->cdnError !== null) {
+            throw $result->cdnError;
+        }
+
+        return $result;
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @return bool
+     */
+    #[Override]
+    public function saveValue(ResourceObject $ro, int $ttl)
+    {
+        $saved = $this->storage->saveValue($ro, $ttl);
+        $this->logger->event(new SaveValueContext((string) $ro->uri, $this->cacheTags->ofResource($ro), $ttl));
+
+        return $saved;
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @return bool
+     */
+    #[Override]
+    public function saveView(ResourceObject $ro, int $ttl)
+    {
+        $saved = $this->storage->saveView($ro, $ttl);
+        $this->logger->event(new SaveViewContext((string) $ro->uri, $ttl));
+
+        return $saved;
+    }
+
+    #[Override]
+    public function saveDonut(AbstractUri $uri, ResourceDonut $donut, int|null $sMaxAge, array $headerKeys): void
+    {
+        $this->storage->saveDonut($uri, $donut, $sMaxAge, $headerKeys);
+        $this->logger->event(new SaveDonutContext((string) $uri, $sMaxAge));
+    }
+
+    #[Override]
+    public function saveDonutView(ResourceObject $ro, int|null $ttl): bool
+    {
+        $saved = $this->storage->saveDonutView($ro, $ttl);
+        $this->logger->event(new SaveDonutViewContext((string) $ro->uri, $this->cacheTags->ofResource($ro), $ttl));
+
+        return $saved;
+    }
+}

src/QueryRepositoryModule.php

@@ -61,14 +61,22 @@ protected function configure(): void
         $this->bind(TagAwareAdapterInterface::class)->annotatedWith(EtagPool::class)->toInstance(null);
         // core
         $this->bind(QueryRepositoryInterface::class)->to(QueryRepository::class)->in(Scope::SINGLETON);
-        $this->bind(CacheDependencyInterface::class)->to(CacheDependency::class);
+        // CacheDependency is likewise wrapped by a logging decorator; the undecorated
+        // dependency resolver is bound under 'origin'.
+        $this->bind(CacheDependencyInterface::class)->annotatedWith('origin')->to(CacheDependency::class);
+        $this->bind(CacheDependencyInterface::class)->to(LoggableCacheDependency::class);
         $this->bind(EtagSetterInterface::class)->to(EtagSetter::class);
         $this->bind(NamedParameterInterface::class)->to(NamedParameter::class);
-        $this->bind(ResourceStorageInterface::class)->to(ResourceStorage::class)->in(Scope::SINGLETON);
+        // The storage is wrapped by a logging decorator: cache writes are emitted as
+        // semantic-log events in LoggableResourceStorage, keeping ResourceStorage itself
+        // free of any logging concern. The undecorated storage is bound under 'origin'.
+        $this->bind(ResourceStorageInterface::class)->annotatedWith('origin')->to(ResourceStorage::class)->in(Scope::SINGLETON);
+        $this->bind(ResourceStorageInterface::class)->to(LoggableResourceStorage::class)->in(Scope::SINGLETON);
         $this->bind(MatchQueryInterface::class)->to(MatchQuery::class);
         $this->bind(RefreshAnnotatedCommand::class);
         $this->bind(RefreshSameCommand::class);
         $this->bind(ResourceStorageSaver::class);
+        $this->bind(CacheTags::class);
         // Server context for thread safety (Swoole, RoadRunner, etc.)
         $this->bind(ServerContextInterface::class)->to(GlobalServerContext::class)->in(Scope::SINGLETON);
         // #[Cacheable]