refactor: address review feedback on recent push

- Strip leaked internal `@architect:T*` task-ownership markers from the
  Redis adapter; they were planning artifacts and add no value to readers.
- Document::fromRow: collapse two `array_key_exists('$permissions', ...)`
  branches into one — the second `is_array` check was redundant given the
  first arm throws on non-array.
- SQL::generateOrderBy: rename `$callerSuppliedOrder` to its positive
  counterpart `$shouldAutoOrderByRelevance` so the gate predicate reads
  without double-negation.
- Redis::orderDocuments: docblock said "preserve usort transitivity" but
  the random branch never calls usort — explain the actual reason
  (non-deterministic comparators are undefined for usort).
- Structure::$mergedAttributes: weaken the "Stable for the lifetime of
  this validator" comment — `readonly` blocks property reassignment but
  not inner Document mutation, so callers that mutate the held
  collection between `isValid()` calls would see a stale memo.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: claude

src/Database/Adapter/Redis.php

@@ -1310,8 +1310,6 @@ private function loadMetadataDocument(string $collection): ?Document
         return $this->decode($payload);
     }
 
-    // === @architect:T20 owns: schema + collection + attribute ops ===
-
     public function create(string $name): bool
     {
         $name = $this->filter($name);
@@ -1975,14 +1973,6 @@ private function measureKey(string $key): int
         }
     }
 
-    // === @architect:T20 end ===
-
-
-
-
-
-    // === @architect:T30 owns: document CRUD + bulk + increase ===
-
     public function getDocument(Document $collection, string $id, array $queries = [], bool $forUpdate = false): Document
     {
         $col = $this->filter($collection->getId());
@@ -2629,14 +2619,6 @@ public function increaseDocumentAttribute(
         });
     }
 
-    // === @architect:T30 end ===
-
-
-
-
-
-    // === @architect:T40 owns: indexes + queries + counts ===
-
     public function createIndex(string $collection, string $id, string $type, array $attributes, array $lengths, array $orders, array $indexAttributeTypes = [], array $collation = [], int $ttl = 1): bool
     {
         $collection = $this->filter($collection);
@@ -3356,8 +3338,9 @@ private function matchesDocumentObject(mixed $value, Query $query): bool
     }
 
     /**
-     * Stable ordering across Documents. Random short-circuits via shuffle to
-     * preserve usort transitivity; absent attributes fall back to $sequence.
+     * Stable ordering across Documents. Random short-circuits to shuffle()
+     * because a non-deterministic comparator passed to usort is undefined;
+     * absent attributes fall back to $sequence.
      *
      * @param  array<int, Document>  $documents
      * @param  array<int, string>  $orderAttributes
@@ -3807,14 +3790,6 @@ private function projectDocument(Document $document, array $selections): Documen
         return new Document($projected);
     }
 
-    // === @architect:T40 end ===
-
-
-
-
-
-    // === @architect:T50 owns: permissions + relationships ===
-
     public function createRelationship(string $collection, string $relatedCollection, string $type, bool $twoWay = false, string $id = '', string $twoWayKey = ''): bool
     {
         // Redis stores documents as flexible JSON blobs, so the relationship
@@ -3948,14 +3923,6 @@ public function deleteRelationship(string $collection, string $relatedCollection
         return true;
     }
 
-    // === @architect:T50 end ===
-
-
-
-
-
-    // === @architect:T56 owns: transactions + journal ===
-
     public function startTransaction(): bool
     {
         $this->journalStack[] = [];
@@ -3988,8 +3955,6 @@ public function rollbackTransaction(): bool
         return true;
     }
 
-    // === @architect:T56 end ===
-
     /**
      * Resolve any Operator-typed attributes against the existing document
      * before persisting. Mirrors Memory::applyOperators — non-operator

src/Database/Adapter/SQL.php

@@ -1440,12 +1440,12 @@ public function find(Document $collection, array $queries = [], ?int $limit = 25
         // relevance. Anything else (multiple entries, or a leading attribute
         // other than $sequence) means the caller has an explicit order and
         // relevance ordering would silently override it.
-        $callerSuppliedOrder = ! (
+        $shouldAutoOrderByRelevance = (
             count($orderAttributes) === 0
             || (count($orderAttributes) === 1 && $orderAttributes[0] === '$sequence')
         );
 
-        if (! empty($searchQueries) && ! $callerSuppliedOrder) {
+        if (! empty($searchQueries) && $shouldAutoOrderByRelevance) {
             $builder->select(['*']);
             foreach ($searchQueries as $searchQuery) {
                 $relevanceRaw = $this->getSearchRelevanceRaw($searchQuery, $alias);

src/Database/Document.php

@@ -99,11 +99,10 @@ public static function fromRow(array $row): self
             throw new StructureException('$id must be of type string');
         }
 
-        if (array_key_exists('$permissions', $row) && ! is_array($row['$permissions'])) {
-            throw new StructureException('$permissions must be of type array');
-        }
-
-        if (array_key_exists('$permissions', $row) && is_array($row['$permissions'])) {
+        if (array_key_exists('$permissions', $row)) {
+            if (! \is_array($row['$permissions'])) {
+                throw new StructureException('$permissions must be of type array');
+            }
             $row['$permissions'] = \array_values(\array_unique($row['$permissions']));
         }
 

src/Database/Validator/Structure.php

@@ -114,9 +114,11 @@ class Structure extends Validator
     /**
      * Lazily-built merged attribute list (internal + collection).
      *
-     * Stable for the lifetime of this validator: $attributes is constant and
-     * $collection is readonly, so the merge result never changes after the
-     * first call.
+     * Cached for the lifetime of this validator. `$collection` is `readonly`
+     * (the property cannot be reassigned), but its inner Document state is
+     * not deep-frozen — callers that mutate `$collection->setAttribute(
+     * 'attributes', ...)` between `isValid()` calls would see a stale memo.
+     * Construct a fresh validator if the underlying schema may change.
      *
      * @var array<array<string, mixed>>|null
      */