@adcp/sdk 9.2.0 → 9.3.0

package/dist/lib/registry/sync.js

@@ -2,77 +2,168 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RegistrySync = void 0;
 const node_events_1 = require("node:events");
+const feed_stream_1 = require("./feed-stream");
 const cursor_store_1 = require("./cursor-store");
 // ====== RegistrySync ======
 /**
  * In-memory replica of the AdCP registry.
  *
- * Bootstraps from the agent search endpoint, then polls the event feed
- * to maintain up-to-date indexes for zero-latency lookups.
+ * Bootstraps from the agent search endpoint, then tails the change feed —
+ * Server-Sent Events by default (`transport: 'auto'`), falling back to polling
+ * `/api/registry/feed` when streaming is unavailable — to keep its indexes
+ * current for zero-latency lookups.
+ *
+ * **Staleness:** lookups (`getAgent`, `isAuthorized`, the authorization getters)
+ * return the last synced state. After a transient failure the engine keeps
+ * reconnecting/polling, but a fatal error (e.g. `401`) leaves `state === 'error'`
+ * while the indexes still hold their last values. For decisions where staleness
+ * is unsafe (e.g. authorization enforcement), gate on `state` and
+ * `getLagSeconds()` / `getFreshness()` rather than trusting a lookup blindly.
+ * Index size is bounded only by registry trust — a replica mirrors the whole
+ * registry, so an untrusted/compromised feed could grow memory without limit.
  *
  * @example
  * ```ts
  * const client = new RegistryClient({ apiKey: 'sk_...' });
- * const sync = new RegistrySync({ client });
- * await sync.start();
+ * const sync = new RegistrySync({ client }); // transport: 'auto' (SSE, polling fallback)
  *
  * // Zero-latency lookups
+ * sync.on('event', ({ event }) => console.log('registry change:', event.event_type));
+ *
+ * // Lag monitoring for the SSE feed
+ * sync.on('transport', ({ transport }) => console.log('feed transport:', transport));
+ * sync.on('freshness', ({ freshness }) => {
+ *   if ((freshness.lag_seconds ?? 0) > 300) console.warn('registry feed lag > 5m');
+ * });
+ *
+ * await sync.start();
  * const agent = sync.getAgent('https://ads.example.com');
  * const authorized = sync.isAuthorized('https://ads.example.com', 'publisher.com');
  * const ctv = sync.findAgents({ channels: ['ctv'], markets: ['US'] });
- *
- * sync.on('event', ({ event }) => console.log('registry change:', event.event_type));
  * sync.stop();
  * ```
  */
 class RegistrySync extends node_events_1.EventEmitter {
     client;
+    transportMode;
     pollIntervalMs;
+    types;
+    feedPageLimit;
+    streamPollIntervalSeconds;
+    streamIdleTimeoutMs;
+    streamReconnectMinMs;
+    streamReconnectMaxMs;
+    maxStreamFailures;
     indexAgents;
     indexAuthorizations;
+    indexBrandHierarchies;
     errorHandler;
     cursorStore;
     _state = 'idle';
     cursor = null;
     pollTimer = null;
+    // Streaming state
+    activeTransport = null;
+    streamController = null;
+    streamIdleTimer = null;
+    lastFreshness = null;
+    /**
+     * Incremented by stop()/reset() and each start(). Async work (bootstrap,
+     * rebootstrap, the stream loop) captures its generation and bails the moment
+     * it no longer matches — so a stop() that lands mid-bootstrap is honored and
+     * a stale loop can never resume after the caller stopped or restarted.
+     */
+    generation = 0;
     // Indexes
     agents = new Map();
     authByDomain = new Map();
     authByAgent = new Map();
+    brandAncestorsByDomain = new Map();
+    brandHierarchyByDomain = new Map();
+    brandHierarchyKeysByEntity = new Map();
+    brandHierarchyEntityByKey = new Map();
     constructor(config) {
         super();
         this.client = config.client;
+        this.transportMode = config.transport ?? 'auto';
         this.pollIntervalMs = config.pollIntervalMs ?? 30_000;
+        this.types = config.types;
+        this.feedPageLimit = config.feedPageLimit ?? 1000;
+        // Fail closed on out-of-range values rather than letting the registry reject
+        // them with a 400 that the reconnect/poll loop would hot-retry forever.
+        if (!Number.isInteger(this.feedPageLimit) || this.feedPageLimit < 1 || this.feedPageLimit > 10_000) {
+            throw new Error('feedPageLimit must be an integer between 1 and 10000');
+        }
+        this.streamPollIntervalSeconds = config.streamPollIntervalSeconds ?? 15;
+        if (!Number.isInteger(this.streamPollIntervalSeconds) ||
+            this.streamPollIntervalSeconds < 5 ||
+            this.streamPollIntervalSeconds > 60) {
+            throw new Error('streamPollIntervalSeconds must be an integer between 5 and 60');
+        }
+        this.streamIdleTimeoutMs = config.streamIdleTimeoutMs ?? 90_000;
+        this.streamReconnectMinMs = config.streamReconnectMinMs ?? 1_000;
+        this.streamReconnectMaxMs = config.streamReconnectMaxMs ?? 30_000;
+        this.maxStreamFailures = config.maxStreamFailures ?? 3;
         this.indexAgents = config.indexes?.agents !== false;
         this.indexAuthorizations = config.indexes?.authorizations !== false;
+        this.indexBrandHierarchies = config.indexes?.brandHierarchies !== false;
         this.cursorStore = config.cursorStore ?? new cursor_store_1.InMemoryCursorStore();
         this.errorHandler = config.onError;
     }
     // ====== Lifecycle ======
-    /** Bootstrap from the registry and begin polling the event feed. */
+    /** Bootstrap from the registry and begin tailing the event feed. */
     async start() {
         if (this._state === 'syncing' || this._state === 'bootstrapping')
             return;
-        await this.bootstrap();
-        this.schedulePoll();
+        const gen = ++this.generation;
+        await this.bootstrap(gen);
+        // A stop()/reset() (or another start()) during bootstrap bumps the
+        // generation; beginSync re-validates both generation and state before
+        // starting the sync loop.
+        this.beginSync(gen);
     }
-    /** Stop polling. In-memory state is preserved. */
+    /** Stop tailing the feed. In-memory state is preserved. */
     stop() {
+        // Invalidate any in-flight bootstrap/rebootstrap/stream loop, even while
+        // state is still 'bootstrapping'.
+        this.generation++;
         if (this.pollTimer) {
             clearTimeout(this.pollTimer);
             this.pollTimer = null;
         }
-        if (this._state === 'syncing') {
+        this.abortStream();
+        this.activeTransport = null;
+        if (this._state === 'syncing' || this._state === 'bootstrapping') {
             this.setState('idle');
         }
     }
-    /** Stop, clear all state. Call start() again to re-bootstrap. */
+    /**
+     * Stop, clear all in-memory state, and drop the persisted cursor. Call start()
+     * again to re-bootstrap from scratch. Because this clears the stored cursor,
+     * it is the correct way to switch the `types` subscription: `reset()` then
+     * `start()` begins a fresh subscription rather than resuming a cursor minted
+     * under the previous filter.
+     */
     async reset() {
         this.stop();
         this.clearIndexes();
         this.cursor = null;
+        this.lastFreshness = null;
+        await this.cursorStore.clearCursor();
         this.setState('idle');
     }
+    /** Begin tailing the feed using the configured transport. Bootstrap leaves state at 'syncing'. */
+    beginSync(gen) {
+        if (gen !== this.generation || this._state !== 'syncing')
+            return;
+        if (this.transportMode === 'poll') {
+            this.setTransport('poll');
+            this.schedulePoll(gen);
+            return;
+        }
+        this.setTransport('stream');
+        void this.runStream(gen);
+    }
     // ====== Agent Lookups ======
     /** Get an agent by URL. */
     getAgent(url) {
@@ -125,11 +216,30 @@ class RegistrySync extends node_events_1.EventEmitter {
      * Check if an agent has any authorization for a publisher domain.
      * Does not evaluate property_id scoping, time bounds, or effective dates.
      * For scoped checks, use getAuthorizationsForDomain() and inspect entries directly.
+     *
+     * Returns the last synced state — see the class-level staleness note. For
+     * enforcement, confirm `state === 'syncing'` and an acceptable `getLagSeconds()`
+     * before trusting an allow decision, so a stalled feed can't serve a stale
+     * authorization after a missed revocation.
      */
     isAuthorized(agentUrl, domain) {
         const entries = this.authByDomain.get(domain);
         return entries != null && entries.some(e => e.agent_url === agentUrl);
     }
+    // ====== Brand Hierarchy Lookups ======
+    /**
+     * Get the ordered corporate ancestor domain chain for a brand domain.
+     *
+     * The returned array includes the resolved brand itself as the first entry and
+     * the house domain as the last entry when known.
+     */
+    getAncestors(domain) {
+        return [...(this.brandAncestorsByDomain.get(this.normalizeDomainKey(domain)) ?? [])];
+    }
+    /** Get the ordered resolved brand chain for a brand domain, when the feed supplied it. */
+    getBrandHierarchy(domain) {
+        return (this.brandHierarchyByDomain.get(this.normalizeDomainKey(domain)) ?? []).map(brand => ({ ...brand }));
+    }
     // ====== State ======
     get state() {
         return this._state;
@@ -141,10 +251,30 @@ class RegistrySync extends node_events_1.EventEmitter {
         let authCount = 0;
         for (const entries of this.authByDomain.values())
             authCount += entries.length;
-        return { agents: this.agents.size, authorizations: authCount };
+        return {
+            agents: this.agents.size,
+            authorizations: authCount,
+            brandHierarchies: this.brandHierarchyKeysByEntity.size,
+        };
+    }
+    /** The active feed transport once syncing, or null when idle. */
+    getTransport() {
+        return this.activeTransport;
+    }
+    /**
+     * Latest feed freshness metadata, or null if the registry has not reported it
+     * yet (e.g. before the first feed page/heartbeat lands). For push updates,
+     * prefer the `freshness` event over polling this right after `start()`.
+     */
+    getFreshness() {
+        return this.lastFreshness;
+    }
+    /** Latest feed lag in seconds, or null when unavailable. Convenience over getFreshness(). */
+    getLagSeconds() {
+        return this.lastFreshness?.lag_seconds ?? null;
     }
     // ====== Private: Bootstrap ======
-    async bootstrap() {
+    async bootstrap(gen) {
         this.setState('bootstrapping');
         try {
             // Restore cursor from store if available
@@ -167,7 +297,10 @@ class RegistrySync extends node_events_1.EventEmitter {
                 } while (cursor);
             }
             // Get initial feed cursor and apply any events
-            await this.drainFeed();
+            await this.drainFeed(gen);
+            // A stop()/reset() landed mid-bootstrap: do not flip to 'syncing' or emit.
+            if (gen !== this.generation)
+                return;
             this.setState('syncing');
             this.emit('bootstrap', {
                 agentCount: this.agents.size,
@@ -175,44 +308,61 @@ class RegistrySync extends node_events_1.EventEmitter {
             });
         }
         catch (err) {
-            this.setState('error');
             const error = err instanceof Error ? err : new Error(String(err));
+            // If we were stopped mid-bootstrap, swallow the abort rather than parking
+            // the engine in 'error'.
+            if (gen !== this.generation)
+                return;
+            this.setState('error');
             this.errorHandler?.(error);
             this.emit('error', { error });
             throw error;
         }
     }
+    /** Clear all state, drop the persisted cursor, and bootstrap again from scratch. */
+    async rebootstrap(gen) {
+        this.clearIndexes();
+        this.cursor = null;
+        await this.cursorStore.clearCursor();
+        await this.bootstrap(gen);
+    }
     // ====== Private: Polling ======
-    schedulePoll() {
-        this.pollTimer = setTimeout(() => this.pollLoop(), this.pollIntervalMs);
+    schedulePoll(gen) {
+        this.pollTimer = setTimeout(() => this.pollLoop(gen), this.pollIntervalMs);
     }
-    async pollLoop() {
+    async pollLoop(gen) {
+        if (gen !== this.generation)
+            return;
         try {
-            await this.poll();
+            await this.poll(gen);
         }
         catch (err) {
             const error = err instanceof Error ? err : new Error(String(err));
             this.emit('error', { error });
             this.errorHandler?.(error);
         }
-        // Schedule next poll even after errors (will retry), unless stopped
-        if (this._state === 'syncing') {
-            this.schedulePoll();
+        // Schedule next poll even after errors (will retry), unless stopped/superseded.
+        if (gen === this.generation && this._state === 'syncing') {
+            this.schedulePoll(gen);
         }
     }
-    async poll() {
+    async poll(gen) {
         let totalEventsApplied = 0;
         let hasMore = true;
         while (hasMore) {
-            const feed = await this.client.getFeed({
-                cursor: this.cursor ?? undefined,
-                limit: 1000,
-            });
+            const feed = await this.client.getFeed(this.feedQuery());
             if (feed.cursor_expired) {
-                // Clear state and re-bootstrap inline; the existing poll loop continues
-                this.clearIndexes();
-                this.cursor = null;
-                await this.bootstrap();
+                // Cursor aged out of retention: drop state and re-bootstrap, then resume.
+                try {
+                    await this.rebootstrap(gen);
+                }
+                catch {
+                    // bootstrap() already emitted 'error' and parked state in 'error'.
+                    // Restore 'syncing' so pollLoop reschedules and retries (mirrors the
+                    // stream path, which also keeps trying after a failed rebootstrap).
+                    if (gen === this.generation && this._state === 'error')
+                        this.setState('syncing');
+                }
                 return;
             }
             for (const event of feed.events) {
@@ -220,14 +370,13 @@ class RegistrySync extends node_events_1.EventEmitter {
                 this.emit('event', { event });
                 totalEventsApplied++;
             }
+            this.observeFreshness(feed.freshness);
             if (feed.cursor) {
                 this.cursor = feed.cursor;
             }
-            hasMore = feed.has_more && this.cursor != null;
-        }
-        if (this.cursor) {
-            await this.cursorStore.setCursor(this.cursor);
+            hasMore = feed.has_more && feed.cursor != null;
         }
+        await this.persistCursor();
         if (totalEventsApplied > 0) {
             this.emit('sync', { cursor: this.cursor, eventsApplied: totalEventsApplied });
         }
@@ -235,23 +384,314 @@ class RegistrySync extends node_events_1.EventEmitter {
     /**
      * Drain all available feed pages. Used during bootstrap (does not emit 'event' per event).
      */
-    async drainFeed() {
+    async drainFeed(gen) {
         let hasMore = true;
+        let recoveredFromExpiry = false;
         while (hasMore) {
-            const feed = await this.client.getFeed({
-                cursor: this.cursor ?? undefined,
-                limit: 1000,
-            });
+            const feed = await this.client.getFeed(this.feedQuery());
+            if (feed.cursor_expired) {
+                // Stored cursor aged out of retention: drop it and retry once from the
+                // start of the window. A second expiry (now cursor-less) means a
+                // misbehaving server — stop draining rather than hot-looping.
+                this.cursor = null;
+                await this.cursorStore.clearCursor();
+                if (recoveredFromExpiry)
+                    break;
+                recoveredFromExpiry = true;
+                continue;
+            }
             for (const event of feed.events) {
                 this.applyEvent(event);
             }
-            this.cursor = feed.cursor;
-            hasMore = feed.has_more && this.cursor != null;
+            this.observeFreshness(feed.freshness);
+            if (feed.cursor)
+                this.cursor = feed.cursor;
+            hasMore = feed.has_more && feed.cursor != null;
+        }
+        // A stop()/reset() during the drain bumps the generation — don't persist a
+        // cursor a later start() would read back.
+        if (gen === this.generation)
+            await this.persistCursor();
+    }
+    // ====== Private: Streaming ======
+    async runStream(gen) {
+        // `consecutiveFailures` drives 'auto' polling fallback. It counts connections
+        // that ended in a transport/parse failure — a heartbeat does NOT reset it
+        // (else heartbeat → malformed-frame → reconnect could loop forever and never
+        // fall back, despite the parse-failure fallback contract). It resets only on
+        // real feed progress or a clean close that delivered something.
+        // `consecutiveRebootstraps` bounds a tight cursor_expired loop.
+        let consecutiveFailures = 0;
+        let consecutiveRebootstraps = 0;
+        while (gen === this.generation && this.transportMode !== 'poll') {
+            const controller = new AbortController();
+            this.streamController = controller;
+            let feedApplied = false;
+            let receivedAny = false;
+            let disposition;
+            try {
+                disposition = await this.streamConnection(gen, controller.signal, isFeed => {
+                    receivedAny = true;
+                    if (isFeed)
+                        feedApplied = true;
+                });
+            }
+            catch (err) {
+                // Aborted by stop()/reset() (which bumps the generation): exit quietly.
+                if (controller.signal.aborted && gen !== this.generation) {
+                    return;
+                }
+                const error = err instanceof Error ? err : new Error(String(err));
+                disposition = this.classifyStreamError(error);
+                if (disposition === 'reconnect' || disposition === 'fatal') {
+                    this.emit('error', { error });
+                    this.errorHandler?.(error);
+                }
+            }
+            finally {
+                this.clearStreamIdleTimer();
+            }
+            if (gen !== this.generation)
+                return;
+            // Applying a feed page proves the stream works end to end.
+            if (feedApplied) {
+                consecutiveFailures = 0;
+                consecutiveRebootstraps = 0;
+            }
+            if (disposition === 'stopped')
+                return;
+            if (disposition === 'fatal') {
+                // Permanent error (e.g. 400/401): retrying cannot help. Park in 'error'.
+                this.setState('error');
+                this.activeTransport = null;
+                return;
+            }
+            if (disposition === 'rebootstrap') {
+                let ok = false;
+                try {
+                    await this.rebootstrap(gen);
+                    ok = true;
+                }
+                catch {
+                    // bootstrap() already emitted 'error' and parked state in 'error'.
+                }
+                if (gen !== this.generation)
+                    return;
+                if (!ok) {
+                    consecutiveFailures++;
+                    if (this.shouldFallBack(consecutiveFailures)) {
+                        this.fallBackToPolling(gen);
+                        return;
+                    }
+                    // Recover: bootstrap left us in 'error'. In 'stream' mode the contract
+                    // is to keep reconnecting, so restore 'syncing' and back off.
+                    this.setState('syncing');
+                    await this.delay(this.reconnectBackoffMs(consecutiveFailures), controller.signal);
+                    if (gen !== this.generation)
+                        return;
+                    continue;
+                }
+                // Successful re-bootstrap. Back off proportionally to repeated expiries
+                // so a server stuck emitting cursor_expired can't drive a tight loop.
+                consecutiveRebootstraps++;
+                await this.delay(this.reconnectBackoffMs(consecutiveRebootstraps), controller.signal);
+                if (gen !== this.generation)
+                    return;
+                continue;
+            }
+            if (disposition === 'fallback') {
+                this.fallBackToPolling(gen);
+                return;
+            }
+            if (disposition === 'closed' && receivedAny) {
+                // Clean close after real activity (feed or heartbeat): the transport
+                // works; reconnect promptly without counting it as a failure.
+                consecutiveFailures = 0;
+                await this.delay(this.reconnectBackoffMs(0), controller.signal);
+                if (gen !== this.generation)
+                    return;
+                continue;
+            }
+            // 'reconnect' (transport/parse failure or server feed_stream_error), or a
+            // clean close that delivered nothing — count toward fallback so 'auto'
+            // degrades to polling rather than looping on a stream that never delivers.
+            consecutiveFailures++;
+            if (this.shouldFallBack(consecutiveFailures)) {
+                this.fallBackToPolling(gen);
+                return;
+            }
+            await this.delay(this.reconnectBackoffMs(consecutiveFailures), controller.signal);
+            if (gen !== this.generation)
+                return;
         }
+    }
+    /**
+     * Consume one SSE connection. Invokes `onMessage(isFeed)` for each feed page
+     * (true) or heartbeat (false) received. Returns the disposition for the
+     * reconnect loop: `closed` on a clean server EOF, `reconnect` on a server
+     * `feed_stream_error`, `rebootstrap` on `cursor_expired`, `stopped` if the
+     * engine was stopped mid-stream.
+     */
+    async streamConnection(gen, signal, onMessage) {
+        this.armStreamIdleTimer();
+        const query = {
+            cursor: this.cursor ?? undefined,
+            types: this.types,
+            limit: this.feedPageLimit,
+            pollIntervalSeconds: this.streamPollIntervalSeconds,
+        };
+        for await (const msg of this.client.streamFeed(query, { signal })) {
+            if (gen !== this.generation)
+                return 'stopped';
+            this.armStreamIdleTimer();
+            if (msg.type === 'feed') {
+                onMessage(true);
+                await this.applyStreamPage(msg.page);
+            }
+            else if (msg.type === 'heartbeat') {
+                onMessage(false);
+                // Heartbeats keep the connection alive and expose freshness; they do NOT
+                // advance the cursor and do NOT count as feed progress for fallback.
+                this.observeFreshness(msg.heartbeat.freshness);
+            }
+            else {
+                // 'error' — the server closes the stream after this frame.
+                if (msg.error.error === 'cursor_expired') {
+                    return 'rebootstrap';
+                }
+                // Registry-supplied strings are untrusted: escape before logging/emitting.
+                const code = (0, feed_stream_1.sanitizeStreamText)(msg.error.error);
+                const detail = msg.error.message ? ` (${(0, feed_stream_1.sanitizeStreamText)(msg.error.message)})` : '';
+                const error = new Error(`registry feed stream error: ${code}${detail}`);
+                this.emit('error', { error });
+                this.errorHandler?.(error);
+                return 'reconnect';
+            }
+        }
+        // Stream closed cleanly by the server — reconnect from the last cursor.
+        return 'closed';
+    }
+    /** Apply one SSE feed page: events, freshness, then advance + persist the cursor. */
+    async applyStreamPage(page) {
+        let applied = 0;
+        for (const event of page.events) {
+            this.applyEvent(event);
+            this.emit('event', { event });
+            applied++;
+        }
+        this.observeFreshness(page.freshness);
+        // Advance the cursor only after the full page is applied, so a mid-page
+        // disconnect resumes from the last fully-applied page.
+        if (page.cursor) {
+            this.cursor = page.cursor;
+            try {
+                await this.persistCursor();
+            }
+            catch (err) {
+                // Persisting is best-effort; replay after restart is idempotent.
+                const error = err instanceof Error ? err : new Error(String(err));
+                this.emit('error', { error });
+                this.errorHandler?.(error);
+            }
+        }
+        if (applied > 0) {
+            this.emit('sync', { cursor: this.cursor, eventsApplied: applied });
+        }
+    }
+    classifyStreamError(error) {
+        if (error instanceof feed_stream_1.FeedStreamCursorExpiredError)
+            return 'rebootstrap';
+        if (error instanceof feed_stream_1.FeedStreamUnsupportedError) {
+            // Endpoint absent (older registry) or a proxy returned non-stream content.
+            return this.transportMode === 'auto' ? 'fallback' : 'reconnect';
+        }
+        if (error instanceof feed_stream_1.FeedStreamHttpError && (error.status === 400 || error.status === 401)) {
+            // Permanent client-side error: a malformed request or bad credentials.
+            // Retrying (or polling, which hits the same status) cannot recover.
+            return 'fatal';
+        }
+        // Other HTTP errors, parse failures, idle timeouts, network/abort errors.
+        return 'reconnect';
+    }
+    shouldFallBack(consecutiveFailures) {
+        return this.transportMode === 'auto' && consecutiveFailures >= this.maxStreamFailures;
+    }
+    fallBackToPolling(gen) {
+        if (gen !== this.generation || this._state !== 'syncing')
+            return;
+        this.abortStream();
+        this.setTransport('poll');
+        this.schedulePoll(gen);
+    }
+    armStreamIdleTimer() {
+        this.clearStreamIdleTimer();
+        const controller = this.streamController;
+        if (!controller)
+            return;
+        this.streamIdleTimer = setTimeout(() => {
+            controller.abort(new Error('registry feed stream idle timeout'));
+        }, this.streamIdleTimeoutMs);
+        this.streamIdleTimer.unref?.();
+    }
+    clearStreamIdleTimer() {
+        if (this.streamIdleTimer) {
+            clearTimeout(this.streamIdleTimer);
+            this.streamIdleTimer = null;
+        }
+    }
+    abortStream() {
+        this.clearStreamIdleTimer();
+        if (this.streamController) {
+            this.streamController.abort();
+            this.streamController = null;
+        }
+    }
+    reconnectBackoffMs(attempt) {
+        const exp = this.streamReconnectMinMs * 2 ** Math.max(0, attempt - 1);
+        return Math.min(this.streamReconnectMaxMs, Math.max(this.streamReconnectMinMs, exp));
+    }
+    delay(ms, signal) {
+        if (signal.aborted)
+            return Promise.resolve();
+        return new Promise(resolve => {
+            const onAbort = () => {
+                clearTimeout(timer);
+                resolve();
+            };
+            const timer = setTimeout(() => {
+                signal.removeEventListener('abort', onAbort);
+                resolve();
+            }, ms);
+            timer.unref?.();
+            signal.addEventListener('abort', onAbort, { once: true });
+        });
+    }
+    // ====== Private: Shared feed helpers ======
+    feedQuery() {
+        const query = { limit: this.feedPageLimit };
+        if (this.cursor)
+            query.cursor = this.cursor;
+        if (this.types)
+            query.types = this.types;
+        return query;
+    }
+    observeFreshness(freshness) {
+        if (!freshness)
+            return;
+        this.lastFreshness = freshness;
+        this.emit('freshness', { freshness });
+    }
+    async persistCursor() {
         if (this.cursor) {
             await this.cursorStore.setCursor(this.cursor);
         }
     }
+    setTransport(transport) {
+        if (this.activeTransport === transport)
+            return;
+        this.activeTransport = transport;
+        this.emit('transport', { transport });
+    }
     // ====== Private: Event Application ======
     applyEvent(event) {
         const payload = event.payload;
@@ -367,6 +807,19 @@ class RegistrySync extends node_events_1.EventEmitter {
                 });
                 break;
             }
+            case 'brand.hierarchy_updated':
+            case 'brand.updated':
+            case 'brand.resolved': {
+                if (this.indexBrandHierarchies)
+                    this.applyBrandHierarchyEvent(event.entity_id, payload);
+                break;
+            }
+            case 'brand.removed':
+            case 'brand.deleted': {
+                if (this.indexBrandHierarchies)
+                    this.deleteBrandHierarchy(event.entity_id, payload);
+                break;
+            }
             // Property and publisher events: no-op for v1 (no property index yet)
             default:
                 break;
@@ -377,6 +830,111 @@ class RegistrySync extends node_events_1.EventEmitter {
         this.agents.clear();
         this.authByDomain.clear();
         this.authByAgent.clear();
+        this.brandAncestorsByDomain.clear();
+        this.brandHierarchyByDomain.clear();
+        this.brandHierarchyKeysByEntity.clear();
+        this.brandHierarchyEntityByKey.clear();
+    }
+    applyBrandHierarchyEvent(entityId, payload) {
+        const resolvedChain = this.extractResolvedBrandChain(payload.chain);
+        const domainChain = resolvedChain.length > 0
+            ? resolvedChain.map(brand => this.domainFromBrand(brand)).filter((domain) => domain != null)
+            : (this.extractDomainChain(payload.chain) ??
+                this.extractDomainChain(payload.ancestor_domains) ??
+                this.extractDomainChain(payload.domains));
+        if (!domainChain || domainChain.length === 0)
+            return;
+        const keys = new Set();
+        keys.add(this.normalizeDomainKey(entityId));
+        for (const field of ['domain', 'canonical_domain', 'canonical_id']) {
+            const value = payload[field];
+            if (typeof value === 'string' && value.trim())
+                keys.add(this.normalizeDomainKey(value));
+        }
+        keys.add(this.normalizeDomainKey(domainChain[0]));
+        const entityKey = this.normalizeDomainKey(entityId);
+        const entitiesToClear = new Set([entityKey]);
+        for (const key of keys) {
+            const existingEntity = this.brandHierarchyEntityByKey.get(key);
+            if (existingEntity)
+                entitiesToClear.add(existingEntity);
+        }
+        for (const key of entitiesToClear)
+            this.clearBrandHierarchyEntity(key);
+        for (const key of keys) {
+            this.brandAncestorsByDomain.set(key, [...domainChain]);
+            if (resolvedChain.length > 0)
+                this.brandHierarchyByDomain.set(key, resolvedChain.map(brand => ({ ...brand })));
+            else
+                this.brandHierarchyByDomain.delete(key);
+            this.brandHierarchyEntityByKey.set(key, entityKey);
+        }
+        this.brandHierarchyKeysByEntity.set(entityKey, keys);
+    }
+    deleteBrandHierarchy(entityId, payload) {
+        const keys = new Set([this.normalizeDomainKey(entityId)]);
+        for (const field of ['domain', 'canonical_domain', 'canonical_id']) {
+            const value = payload[field];
+            if (typeof value === 'string' && value.trim())
+                keys.add(this.normalizeDomainKey(value));
+        }
+        const entitiesToClear = new Set();
+        for (const key of keys) {
+            const existingEntity = this.brandHierarchyEntityByKey.get(key);
+            if (existingEntity)
+                entitiesToClear.add(existingEntity);
+        }
+        if (entitiesToClear.size > 0) {
+            for (const key of entitiesToClear)
+                this.clearBrandHierarchyEntity(key);
+            return;
+        }
+        for (const key of keys) {
+            this.brandAncestorsByDomain.delete(key);
+            this.brandHierarchyByDomain.delete(key);
+            this.brandHierarchyEntityByKey.delete(key);
+        }
+    }
+    clearBrandHierarchyEntity(entityKey) {
+        const keys = this.brandHierarchyKeysByEntity.get(entityKey);
+        if (!keys)
+            return;
+        for (const key of keys) {
+            this.brandAncestorsByDomain.delete(key);
+            this.brandHierarchyByDomain.delete(key);
+            this.brandHierarchyEntityByKey.delete(key);
+        }
+        this.brandHierarchyKeysByEntity.delete(entityKey);
+    }
+    extractResolvedBrandChain(value) {
+        if (!Array.isArray(value))
+            return [];
+        if (!value.every(item => item && typeof item === 'object' && !Array.isArray(item)))
+            return [];
+        return value.filter(item => typeof item.canonical_domain === 'string');
+    }
+    extractDomainChain(value) {
+        if (!Array.isArray(value))
+            return null;
+        const domains = [];
+        for (const item of value) {
+            if (typeof item === 'string' && item.trim()) {
+                domains.push(item);
+                continue;
+            }
+            if (item && typeof item === 'object' && !Array.isArray(item)) {
+                const domain = this.domainFromBrand(item);
+                if (domain)
+                    domains.push(domain);
+            }
+        }
+        return domains.length > 0 ? domains : null;
+    }
+    domainFromBrand(brand) {
+        return brand.canonical_domain ?? brand.canonical_id ?? null;
+    }
+    normalizeDomainKey(domain) {
+        return domain.trim().toLowerCase();
     }
     setState(next) {
         const from = this._state;