pixivflow 3.0.2 → 3.1.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "type": "commonjs",
   "name": "pixivflow",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "private": true
 }

package/dist/topic/TopicPipeline.d.ts

@@ -1,10 +1,16 @@
 import type { TargetConfig } from '../config';
 import type { TopicResolver } from './TopicResolver';
-import type { TopicCandidate, TopicClient, TopicCollectOptions, TopicContentType, TopicDiscoveryOptions, WorkLike } from './types';
+import type { RelatedTagMode, ResolvedTag, TopicCandidate, TopicClient, TopicCollectOptions, TopicContentType, TopicDiscoveryOptions, TopicRelationsOptions, WorkLike } from './types';
 export interface TopicSelection {
     candidates: TopicCandidate[];
     selected: TopicCandidate[];
     resolvedTagCount: number;
+    /**
+     * Tags actually searched for the day. Under `relatedTags: 'always'` this is
+     * the whole resolved space; under the seed-first modes it is the seed tag and
+     * only the related tags that were really needed (§topic-recall).
+     */
+    searchedTags?: string[];
     rawCount: number;
     dedupedCount: number;
     acceptedCount: number;
@@ -12,6 +18,26 @@ export interface TopicSelection {
     /** Works seen more than once across the topic tag space (recorded, dropped). */
     duplicateRemovedCount: number;
 }
+/**
+ * The tag the operator asked for, even when `tagRelations` filters it out.
+ *
+ * `deny` may drop the seed, but a space filtered down to nothing must still be
+ * usable: the pipeline then falls back to the seed tag alone, exactly like the
+ * resolver's `seedOnly()` degradation. `weight` defaults to the tag's `score`
+ * for spaces persisted before provenance existed.
+ */
+export declare function seedFallbackTag(seedTag: ResolvedTag): ResolvedTag;
+/**
+ * Applies `topicDiscovery.tagRelations` to a resolved space (§tag-provenance).
+ *
+ * Deny beats allow, and deny is the only thing that can drop the seed tag. A
+ * tag whose provenance is unknown (a space persisted before `source` existed, or
+ * a hand-written space) is treated as `cooccurrence` so that `allowSources` can
+ * still narrow it while the default (all sources) keeps walking everything.
+ */
+export declare function selectWalkedTags(tags: readonly ResolvedTag[], seedKey: string, relations?: TopicRelationsOptions): ResolvedTag[];
+/** Which of the walked tags a `relatedTags` mode will actually search today. */
+export declare function recallChannels(walked: readonly ResolvedTag[], seedKey: string, relatedMode: RelatedTagMode): ResolvedTag[];
 /**
  * Resolves a topic to a tag space, collects that day's works across the tags,
  * filters by lightweight metadata relevance and ranks by local popularity, then
@@ -44,10 +70,29 @@ export declare class TopicPipeline {
     }>;
     private searchDay;
     private toCandidate;
+    /**
+     * Applies the metadata gate to everything collected so far. When nothing at
+     * all clears the threshold but the seed tag is present, the seed-tag works are
+     * kept anyway: a sparse day must stay usable instead of reporting "no
+     * candidates" for a topic that visibly has works. Extracted from selection so
+     * the seed pass can be evaluated before deciding whether the related channel
+     * is needed at all (§topic-recall).
+     */
+    private acceptedWorks;
     /**
      * Lightweight metadata relevance. Tags dominate (Pixiv's own taxonomy);
      * title/caption add smaller boosts. The seed tag is strong evidence.
      * No text model — case/symbol-insensitive substring matching only.
+     *
+     * `matchTranslatedNames` (default false) additionally counts a work's
+     * `translated_name` as a hit for the resolved tag it translates to, so a
+     * topic written in one language can still match works tagged in another. The
+     * translated name is matched against the resolved space — never added to
+     * `candidate.tags` — so the work is not reported as carrying a tag it lacks.
+     *
+     * A resolved tag counts at most ONCE per work, whether it matched through the
+     * tag name or through its translation (and a work that repeats a tag, as Pixiv
+     * payloads do for a tag plus its translation, does not double its weight).
      */
     private metadataScore;
     /**
@@ -56,8 +101,17 @@ export declare class TopicPipeline {
      * as on-topic, and the choice between accepted works is decided by popularity
      * alone. A work with a higher metadata score does NOT outrank a more popular
      * accepted work.
+     *
+     * `seedKey` adds a single tier in front of that popularity order and is
+     * passed by the seed-first recall modes (§topic-recall) and by
+     * `topicDiscovery.seedTier: 'on'` (§tag-provenance): a work that actually
+     * carries the topic tag outranks a related-only work, however popular the
+     * latter is, and popularity decides within each tier. With `seedTier: 'off'`
+     * and the default `relatedTags: 'always'` no `seedKey` is passed, so the
+     * documented popularity-only ranking is unchanged.
      */
     private popCompare;
+    private rankCompare;
     private topByPopularity;
     private onDay;
     private normalize;

package/dist/topic/TopicPipeline.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TopicPipeline = void 0;
+exports.seedFallbackTag = seedFallbackTag;
+exports.selectWalkedTags = selectWalkedTags;
+exports.recallChannels = recallChannels;
 const promises_1 = require("node:timers/promises");
 const logger_1 = require("../logger");
 const pixiv_utils_1 = require("../utils/pixiv-utils");
@@ -14,6 +17,105 @@ const STOP_TAGS = new Set([
     '1000users入り', '5000users入り', '10000users入り', '500users入り', '100users入り',
     'pixiv', 'commission', 'skeb', '依頼絵', '仕事絵',
 ]);
+/** Normalization shared by the tag-relation filter and the pipeline itself. */
+function normalizeKey(value) {
+    return value.trim().normalize('NFKC').toLocaleLowerCase();
+}
+/**
+ * The tag the operator asked for, even when `tagRelations` filters it out.
+ *
+ * `deny` may drop the seed, but a space filtered down to nothing must still be
+ * usable: the pipeline then falls back to the seed tag alone, exactly like the
+ * resolver's `seedOnly()` degradation. `weight` defaults to the tag's `score`
+ * for spaces persisted before provenance existed.
+ */
+function seedFallbackTag(seedTag) {
+    if (seedTag.source === 'seed' && seedTag.weight !== undefined)
+        return seedTag;
+    return { ...seedTag, source: 'seed', weight: seedTag.weight ?? seedTag.score, seed: true };
+}
+/**
+ * Applies `topicDiscovery.tagRelations` to a resolved space (§tag-provenance).
+ *
+ * Deny beats allow, and deny is the only thing that can drop the seed tag. A
+ * tag whose provenance is unknown (a space persisted before `source` existed, or
+ * a hand-written space) is treated as `cooccurrence` so that `allowSources` can
+ * still narrow it while the default (all sources) keeps walking everything.
+ */
+function selectWalkedTags(tags, seedKey, relations = {}) {
+    const seedTag = tags.find((tag) => normalizeKey(tag.name) === seedKey);
+    const allowed = tags.filter((tag) => normalizeKey(tag.name) !== seedKey);
+    const deny = (relations.deny ?? []).map(normalizeKey);
+    const deniedKeys = new Set(deny);
+    const seedDenied = seedTag !== undefined && deniedKeys.has(seedKey);
+    if (seedDenied)
+        deniedKeys.clear(); // the seed fallback ignores deny
+    const allow = (relations.allow ?? []).map(normalizeKey);
+    const allowKeys = new Set(allow);
+    const open = allowKeys.size === 0;
+    const sources = relations.allowSources;
+    const sourceAllowed = (tag) => {
+        if (!sources || sources.length === 0)
+            return true;
+        const name = normalizeKey(tag.name);
+        if (allowKeys.has(name))
+            return true; // an explicit allow beats allowSources
+        const provenance = tag.source;
+        if (provenance === undefined)
+            return sources.includes('cooccurrence');
+        if (provenance === 'cooccurrence+autocomplete') {
+            return sources.includes('cooccurrence') || sources.includes('autocomplete');
+        }
+        return sources.includes(provenance);
+    };
+    const walked = allowed.filter((tag) => {
+        const name = normalizeKey(tag.name);
+        if (deniedKeys.has(name))
+            return false;
+        if (!open && !allowKeys.has(name))
+            return false;
+        return sourceAllowed(tag);
+    });
+    // No seed tag in the space at all: there is nothing to dominate, so fall back
+    // to walking the whole (filtered) space — the pre-provenance behaviour.
+    if (!seedTag)
+        return walked;
+    // A denied seed empties the space, exactly like the resolver's seedOnly():
+    // the operator still gets their own topic, and no related tag is walked.
+    if (seedDenied)
+        return [seedFallbackTag(seedTag)];
+    return [seedTag, ...walked];
+}
+/** Every spelling under which a set of resolved tags can be recognized. */
+function buildTagAliases(tags, matchTranslatedNames) {
+    const aliases = new Map();
+    for (const tag of tags) {
+        const primary = normalizeKey(tag.name);
+        const entry = { primary, weight: tag.weight ?? tag.score };
+        if (!aliases.has(primary))
+            aliases.set(primary, entry);
+        if (!matchTranslatedNames)
+            continue;
+        // The work-side `translated_name` for this tag is the same resolved tag: the
+        // space still exposes one tag, it is simply recognized under two keys.
+        const translated = tag.translatedName ? normalizeKey(tag.translatedName) : '';
+        if (translated && !aliases.has(translated))
+            aliases.set(translated, entry);
+    }
+    return aliases;
+}
+/** Which of the walked tags a `relatedTags` mode will actually search today. */
+function recallChannels(walked, seedKey, relatedMode) {
+    const seedTags = walked.filter((tag) => normalizeKey(tag.name) === seedKey);
+    // A space with no seed tag has nothing to protect: every remaining tag is the
+    // only channel there is, so the whole space is walked whatever the mode
+    // (pre-provenance fallback for a hand-written space).
+    if (seedTags.length === 0)
+        return [...walked];
+    if (relatedMode === 'never' || relatedMode === 'when_seed_insufficient')
+        return seedTags;
+    return [...seedTags, ...walked.filter((tag) => normalizeKey(tag.name) !== seedKey)];
+}
 /**
  * Resolves a topic to a tag space, collects that day's works across the tags,
  * filters by lightweight metadata relevance and ranks by local popularity, then
@@ -42,23 +144,39 @@ class TopicPipeline {
     async selectWorks(target, contentType, day, limit, discovery, collect) {
         const topic = (target.topic ?? '').trim();
         const { space } = await this.resolver.resolve(topic, contentType, discovery);
-        const tagScores = new Map(space.tags.map((t) => [this.key(t.name), t.score]));
         const maxPerTag = this.bound(collect.maxPerTag, COLLECT_DEFAULTS.maxPerTag, 5, 100);
         const maxCandidates = this.bound(collect.maxCandidates, COLLECT_DEFAULTS.maxCandidates, 20, 500);
         const minMetadataScore = collect.minMetadataScore ?? COLLECT_DEFAULTS.minMetadataScore;
         const includeR18 = discovery.includeR18 === true;
+        // An unknown mode (hand-written config bypassing validation) falls back to
+        // the historical behaviour rather than silently narrowing recall.
+        const requestedMode = discovery.relatedTags;
+        const relatedMode = requestedMode === 'when_seed_insufficient' || requestedMode === 'never' ? requestedMode : 'always';
         const byId = new Map();
         let rawCount = 0;
         let aiExcludedCount = 0;
         let duplicateRemovedCount = 0;
-        const tagNames = space.tags.map((t) => t.name);
-        for (let i = 0; i < tagNames.length; i++) {
-            if (byId.size >= maxCandidates)
-                break;
+        const seedKey = this.key(topic);
+        // §tag-provenance: apply tagRelations where the walked list is built, so the
+        // filter governs seedTags/relatedTags BEFORE any search is issued. The seed
+        // tag survives allow/allowSources; a deny entry that empties the space falls
+        // back to the seed tag alone, exactly like the resolver's seedOnly().
+        const matchTranslatedNames = discovery.matchTranslatedNames === true;
+        const walked = selectWalkedTags(space.tags, seedKey, discovery.tagRelations);
+        const tagNames = walked.map((t) => t.name);
+        const seedTags = tagNames.filter((name) => this.key(name) === seedKey);
+        const relatedTags = tagNames.filter((name) => this.key(name) !== seedKey);
+        // Ranking reads the documented semantic weight, falling back to `score` for
+        // spaces persisted before provenance existed. The two are always equal.
+        const tagScores = buildTagAliases(walked, matchTranslatedNames);
+        const searchedTags = [];
+        // A hard seed tier: 'on' always, and the seed-first modes keep their layer.
+        const hardSeedTier = discovery.seedTier === 'on' || relatedMode !== 'always';
+        const collectTag = async (tag) => {
             // Cancellation is checked between tags, so a cancelled run stops issuing
             // new searches even when the aborted request itself had already returned.
             (0, errors_1.throwIfAborted)(this.signal, 'topic collection cancelled');
-            const tag = tagNames[i];
+            searchedTags.push(tag);
             const works = await this.searchDay(contentType, tag, day, maxPerTag, includeR18);
             rawCount += works.length;
             for (const work of works) {
@@ -75,37 +193,57 @@ class TopicPipeline {
                     break;
             }
             logger_1.logger.debug('[TopicCollector] type=' + contentType + ' tag=' + tag + ' day=' + day + ' fetched=' + works.length + ' pool=' + byId.size);
-            if (i < tagNames.length - 1 && this.requestDelayMs > 0)
-                await (0, promises_1.setTimeout)(this.requestDelayMs);
-        }
-        const dedupedCount = byId.size;
-        logger_1.logger.info('[TopicCollector] type=' + contentType + ' raw=' + rawCount + ' deduplicated=' + dedupedCount + ' aiExcluded=' + aiExcludedCount);
-        const seedKey = this.key(topic);
-        const accepted = [];
-        for (const entry of byId.values()) {
-            entry.candidate.metadataScore = this.metadataScore(entry.candidate, seedKey, tagScores);
-            if (entry.candidate.metadataScore >= minMetadataScore)
-                accepted.push(entry);
+        };
+        const runTags = async (names) => {
+            for (let i = 0; i < names.length; i++) {
+                if (byId.size >= maxCandidates)
+                    break;
+                await collectTag(names[i]);
+                if (i < names.length - 1 && this.requestDelayMs > 0)
+                    await (0, promises_1.setTimeout)(this.requestDelayMs);
+            }
+        };
+        // §topic-recall: a resolved tag space is a hierarchy, not a bag of
+        // interchangeable tags. 'always' keeps the historical behaviour — every
+        // resolved tag is a recall channel for the day. The seed-first modes search
+        // the topic tag the operator actually asked for and only walk the related
+        // channel when that cannot fill the target, so a second high-weight tag
+        // (丸吞) cannot take the only slot of a 西瓜肚 target.
+        if (seedTags.length === 0 || relatedMode === 'always') {
+            // No seed tag in the space (hand-written space): keep walking everything
+            // rather than returning nothing.
+            await runTags(recallChannels(walked, seedKey, relatedMode).map((t) => t.name));
         }
-        if (accepted.length === 0 && byId.size > 0) {
-            const fallback = [...byId.values()]
-                .filter((e) => e.candidate.tags.some((t) => this.key(t) === seedKey))
-                .sort((a, b) => b.candidate.popularity - a.candidate.popularity);
-            accepted.push(...fallback.slice(0, Math.max(limit, 1)));
-            logger_1.logger.warn('[MetadataTopicFilter] type=' + contentType + ' none above threshold ' + minMetadataScore + '; kept ' + accepted.length + ' seed-tag fallback');
+        else {
+            await runTags(seedTags);
+            const seedAccepted = this.acceptedWorks(byId, seedKey, tagScores, minMetadataScore, limit, contentType, matchTranslatedNames).length;
+            if (relatedMode === 'never') {
+                logger_1.logger.info('[TopicRecall] mode=never tag=' + topic + ' day=' + day + ' accepted=' + seedAccepted);
+            }
+            else if (seedAccepted < limit) {
+                logger_1.logger.info('[TopicRecall] mode=when_seed_insufficient tag=' + topic + ' seedAccepted=' + seedAccepted + '/' + limit + ' relatedTags=' + relatedTags.length + '; expanding');
+                await runTags(relatedTags);
+            }
+            else {
+                logger_1.logger.info('[TopicRecall] mode=when_seed_insufficient tag=' + topic + ' seedAccepted=' + seedAccepted + '/' + limit + '; related tags not searched');
+            }
         }
-        const chosen = this.topByPopularity(accepted, limit);
+        const dedupedCount = byId.size;
+        logger_1.logger.info('[TopicCollector] type=' + contentType + ' raw=' + rawCount + ' deduplicated=' + dedupedCount + ' aiExcluded=' + aiExcludedCount + ' searchedTags=' + searchedTags.length);
+        const accepted = this.acceptedWorks(byId, seedKey, tagScores, minMetadataScore, limit, contentType, matchTranslatedNames);
+        const chosen = this.topByPopularity(accepted, limit, hardSeedTier ? seedKey : undefined);
         const selected = chosen.map((e) => e.candidate);
         logger_1.logger.info('[MetadataTopicFilter] accepted=' + accepted.length);
         if (selected[0]) {
-            logger_1.logger.info('[PopularityRanker] selected=' + selected[0].id + ' popularity=' + selected[0].popularity.toFixed(1) + ' meta=' + selected[0].metadataScore.toFixed(2) + ' title=' + selected[0].title);
+            logger_1.logger.info('[PopularityRanker] selected=' + selected[0].id + ' popularity=' + selected[0].popularity.toFixed(1) + ' meta=' + selected[0].metadataScore.toFixed(2) + (hardSeedTier ? ' seedTier=on' : '') + ' title=' + selected[0].title);
         }
         return {
             works: chosen.map((e) => e.work),
             selection: {
                 candidates: [...byId.values()].map((e) => e.candidate),
                 selected,
-                resolvedTagCount: space.tags.length,
+                resolvedTagCount: walked.length,
+                searchedTags,
                 rawCount,
                 dedupedCount,
                 acceptedCount: accepted.length,
@@ -137,12 +275,16 @@ class TopicPipeline {
     }
     toCandidate(work, type) {
         const popularity = (0, pixiv_utils_1.calculatePopularityScore)(work);
+        const translatedTags = (work.tags ?? [])
+            .map((t) => t.translated_name)
+            .filter((name) => Boolean(name));
         return {
             id: work.id,
             type,
             title: work.title ?? '',
             caption: work.caption ?? '',
             tags: (work.tags ?? []).map((t) => t.name).filter(Boolean),
+            ...(translatedTags.length > 0 ? { translatedTags } : {}),
             bookmarks: Number(work.total_bookmarks ?? work.bookmark_count ?? 0) || 0,
             views: Number(work.total_view ?? work.view_count ?? 0) || 0,
             popularity,
@@ -150,29 +292,84 @@ class TopicPipeline {
             ...(work.illust_ai_type !== undefined ? { aiType: work.illust_ai_type } : {}),
         };
     }
+    /**
+     * Applies the metadata gate to everything collected so far. When nothing at
+     * all clears the threshold but the seed tag is present, the seed-tag works are
+     * kept anyway: a sparse day must stay usable instead of reporting "no
+     * candidates" for a topic that visibly has works. Extracted from selection so
+     * the seed pass can be evaluated before deciding whether the related channel
+     * is needed at all (§topic-recall).
+     */
+    acceptedWorks(byId, seedKey, tagScores, minMetadataScore, limit, contentType, matchTranslatedNames) {
+        const accepted = [];
+        const hitsSeed = (candidate) => {
+            if (candidate.tags.some((t) => this.key(t) === seedKey))
+                return true;
+            if (!matchTranslatedNames)
+                return false;
+            return (candidate.translatedTags ?? []).some((t) => this.key(t) === seedKey);
+        };
+        for (const entry of byId.values()) {
+            entry.candidate.metadataScore = this.metadataScore(entry.candidate, seedKey, tagScores, matchTranslatedNames);
+            if (entry.candidate.metadataScore >= minMetadataScore)
+                accepted.push(entry);
+        }
+        if (accepted.length === 0 && byId.size > 0) {
+            const fallback = [...byId.values()]
+                .filter((e) => hitsSeed(e.candidate))
+                .sort((a, b) => b.candidate.popularity - a.candidate.popularity);
+            accepted.push(...fallback.slice(0, Math.max(limit, 1)));
+            logger_1.logger.warn('[MetadataTopicFilter] type=' + contentType + ' none above threshold ' + minMetadataScore + '; kept ' + accepted.length + ' seed-tag fallback');
+        }
+        return accepted;
+    }
     /**
      * Lightweight metadata relevance. Tags dominate (Pixiv's own taxonomy);
      * title/caption add smaller boosts. The seed tag is strong evidence.
      * No text model — case/symbol-insensitive substring matching only.
+     *
+     * `matchTranslatedNames` (default false) additionally counts a work's
+     * `translated_name` as a hit for the resolved tag it translates to, so a
+     * topic written in one language can still match works tagged in another. The
+     * translated name is matched against the resolved space — never added to
+     * `candidate.tags` — so the work is not reported as carrying a tag it lacks.
+     *
+     * A resolved tag counts at most ONCE per work, whether it matched through the
+     * tag name or through its translation (and a work that repeats a tag, as Pixiv
+     * payloads do for a tag plus its translation, does not double its weight).
      */
-    metadataScore(candidate, seedKey, tagScores) {
+    metadataScore(candidate, seedKey, tagScores, matchTranslatedNames) {
         let seedHit = false;
         let relatedSum = 0;
         let relatedHits = 0;
-        for (const tag of candidate.tags) {
-            const k = this.key(tag);
-            if (STOP_TAGS.has(k))
-                continue;
-            if (k === seedKey) {
+        let strongRelated = false;
+        // A resolved tag is matched through its own name, and — when the caller
+        // opted in — through the work-side translation of that tag. Either spelling
+        // maps back to the SAME resolved tag, so a work carrying both spellings
+        // counts once and never gets a double weight.
+        const countedTagKeys = new Set();
+        const consider = (candidateKey) => {
+            if (candidateKey === '' || STOP_TAGS.has(candidateKey))
+                return;
+            if (candidateKey === seedKey) {
                 seedHit = true;
-                continue;
-            }
-            const related = tagScores.get(k);
-            if (related !== undefined) {
-                relatedSum += Math.min(related, 0.6);
-                relatedHits += 1;
+                return;
             }
+            const aliases = tagScores.get(candidateKey);
+            if (!aliases || countedTagKeys.has(aliases.primary))
+                return;
+            countedTagKeys.add(aliases.primary);
+            relatedSum += Math.min(aliases.weight, 0.6);
+            relatedHits += 1;
+            if (aliases.weight >= 0.6)
+                strongRelated = true;
+        };
+        if (matchTranslatedNames) {
+            for (const tag of candidate.translatedTags ?? [])
+                consider(this.key(tag));
         }
+        for (const tag of candidate.tags)
+            consider(this.key(tag));
         const hayTitle = this.normalize(candidate.title);
         const hayCaption = this.normalize(candidate.caption);
         const titleSeed = !!seedKey && hayTitle.includes(seedKey);
@@ -189,7 +386,6 @@ class TopicPipeline {
         // deliberately does NOT clear the bar, so a hugely popular tangential work
         // cannot crowd out core topic works.
         let score = 0;
-        const strongRelated = [...tagScores.entries()].some(([k, w]) => w >= 0.6 && candidate.tags.some((t) => this.key(t) === k));
         if (titleSeed)
             score += 0.8;
         if (captionSeed)
@@ -205,13 +401,32 @@ class TopicPipeline {
      * as on-topic, and the choice between accepted works is decided by popularity
      * alone. A work with a higher metadata score does NOT outrank a more popular
      * accepted work.
+     *
+     * `seedKey` adds a single tier in front of that popularity order and is
+     * passed by the seed-first recall modes (§topic-recall) and by
+     * `topicDiscovery.seedTier: 'on'` (§tag-provenance): a work that actually
+     * carries the topic tag outranks a related-only work, however popular the
+     * latter is, and popularity decides within each tier. With `seedTier: 'off'`
+     * and the default `relatedTags: 'always'` no `seedKey` is passed, so the
+     * documented popularity-only ranking is unchanged.
      */
     popCompare(a, b) {
         return b.popularity - a.popularity;
     }
-    topByPopularity(items, limit) {
+    rankCompare(seedKey) {
+        if (!seedKey)
+            return (a, b) => this.popCompare(a, b);
+        const tier = (c) => (c.tags.some((t) => this.key(t) === seedKey) ? 0 : 1);
+        return (a, b) => {
+            const diff = tier(a) - tier(b);
+            return diff !== 0 ? diff : this.popCompare(a, b);
+        };
+    }
+    topByPopularity(items, limit, seedKey) {
         if (items.length <= limit)
-            return items.sort((a, b) => this.popCompare(a.candidate, b.candidate));
+            return items.sort((a, b) => this.rankCompare(seedKey)(a.candidate, b.candidate));
+        if (seedKey)
+            return items.sort((a, b) => this.rankCompare(seedKey)(a.candidate, b.candidate)).slice(0, limit);
         // O(n) top-`limit` selection (limit is tiny, e.g. 1); avoids a full sort.
         const top = [];
         for (const item of items) {

package/dist/topic/TopicResolver.js

@@ -97,6 +97,9 @@ class TopicResolver {
             name: seed,
             translatedName: suggested.find((t) => this.scorer.key(t.name) === this.scorer.key(seed))?.translated_name,
             score: 1,
+            weight: 1,
+            // The tag the operator asked for: the strongest provenance, never a hint.
+            source: 'seed',
             occurrences: topicWorks.length,
             coverage: 1,
             specificity: 1,
@@ -168,7 +171,7 @@ class TopicResolver {
             expiresAt: new Date(now + cacheDays * 24 * 60 * 60_000).toISOString(),
             sampleSize: 0,
             sampledWorks: 0,
-            tags: [{ name: seed, score: 1, occurrences: 0, coverage: 1, specificity: 1, suggested: false, seed: true }],
+            tags: [{ name: seed, score: 1, weight: 1, source: 'seed', occurrences: 0, coverage: 1, specificity: 1, suggested: false, seed: true }],
         };
     }
     ageDays(space) {

package/dist/topic/TopicTagScorer.js

@@ -99,10 +99,17 @@ class TopicTagScorer {
             const suggestionWeight = stat.suggested ? 1.1 : 1.0;
             const genericPenalty = GENERIC_TAG_PENALTY.has(k) ? 0.4 : 1.0;
             const raw = recall * specificity * suggestionWeight * genericPenalty;
+            const score = Number(raw.toFixed(4));
             resolved.push({
                 name: stat.name,
                 translatedName: stat.translatedName,
-                score: Number(raw.toFixed(4)),
+                score,
+                // `weight` is the same semantic number; ranking and diagnostics read it
+                // while `score` stays for backward compatibility (§tag-provenance).
+                weight: score,
+                // Both channels may agree on a tag; the combined provenance records
+                // that, which is strictly more informative than either alone.
+                source: stat.suggested ? 'cooccurrence+autocomplete' : 'cooccurrence',
                 occurrences: stat.topicDocs,
                 coverage: Number(coverage.toFixed(4)),
                 specificity: Number(specificity.toFixed(4)),
@@ -127,6 +134,10 @@ class TopicTagScorer {
                 name: name,
                 translatedName: sug.translated_name?.trim() || undefined,
                 score: AUTOCOMPLETE_ONLY_SCORE,
+                weight: AUTOCOMPLETE_ONLY_SCORE,
+                // Pixiv autocomplete is the only evidence for this tag: it never
+                // co-occurred in the bounded sample.
+                source: 'autocomplete',
                 occurrences: 0,
                 coverage: 0,
                 specificity: 1.0, // Pixiv-endorsed related; treated as specific but unobserved

package/dist/topic/types.d.ts

@@ -4,12 +4,34 @@
  * local models are used anywhere in this module.
  */
 export type TopicContentType = 'illustration' | 'novel';
+/**
+ * Where a resolved tag came from. Provenance is what lets a caller treat a weak
+ * expansion differently from the topic it was asked for (§tag-provenance):
+ *
+ * - `'seed'`: the tag the operator asked for. Always the strongest key.
+ * - `'cooccurrence'`: sampled together with the seed, but Pixiv autocomplete
+ *   does not relate it to the seed. Co-occurrence evidence only.
+ * - `'autocomplete'`: Pixiv autocomplete relates it to the seed, but it never
+ *   appeared in the sample. No co-occurrence evidence.
+ * - `'cooccurrence+autocomplete'`: both channels agree — the strongest related
+ *   provenance available.
+ */
+export type TagSource = 'seed' | 'cooccurrence' | 'autocomplete' | 'cooccurrence+autocomplete';
 /** A single related tag with a 0..1 relatedness score and provenance. */
 export interface ResolvedTag {
     name: string;
     translatedName?: string;
     /** Combined relatedness score (co-occurrence * specificity * suggestion). */
     score: number;
+    /**
+     * Semantic weight used for ranking, filtering and diagnostics. Always the
+     * same number as `score`; kept as a separate, documented field so ranking can
+     * be explained (and, later, adjusted) without redefining `score`.
+     * Optional: spaces persisted before provenance existed have neither field.
+     */
+    weight?: number;
+    /** Provenance of the tag. Optional for the same reason as `weight`. */
+    source?: TagSource;
     /** How many sampled works (of the seed search) carried this tag. */
     occurrences: number;
     /** Coverage of the sampled seed works (occurrences / sample size). */
@@ -35,6 +57,8 @@ export interface TopicSpace {
     sampledWorks: number;
     tags: ResolvedTag[];
 }
+/** When related tags may be used as their own recall channel (§topic-recall). */
+export type RelatedTagMode = 'always' | 'when_seed_insufficient' | 'never';
 export interface TopicDiscoveryOptions {
     /** Include R-18 works in topic sampling and collection (default false). */
     includeR18?: boolean;
@@ -43,6 +67,38 @@ export interface TopicDiscoveryOptions {
     cacheDays?: number;
     minScore?: number;
     refresh?: boolean;
+    /**
+     * Related-tag recall mode (default `'always'`).
+     *
+     * A resolved tag space is a hierarchy, not a bag of interchangeable tags: the
+     * seed tag is the topic the operator asked for and every other tag is a hint.
+     * Under `'always'` each resolved tag is searched for the day's works, so a
+     * second high-weight tag (丸吞) can occupy the only slot of a 西瓜肚 target.
+     * `'when_seed_insufficient'` searches the seed tag first and only walks the
+     * related channel when the seed cannot fill the limit for that day;
+     * `'never'` searches the seed tag alone.
+     */
+    relatedTags?: RelatedTagMode;
+    /**
+     * Which resolved tags may become recall channels (§tag-provenance). Deny wins
+     * over allow; the seed tag is never dropped by `allow`/`allowSources`.
+     */
+    tagRelations?: TopicRelationsOptions;
+    /** Make the seed tag a hard ranking tier (default `'off'`). */
+    seedTier?: 'off' | 'on';
+    /** Count a work's translated tag names as tag hits (default false). */
+    matchTranslatedNames?: boolean;
+}
+/**
+ * Runtime shape of `TopicDiscoveryConfig.tagRelations`, declared here so the
+ * topic module does not depend on the config layer (the topic pipeline is also
+ * driven by hand-written targets in tests and by callers that never load a
+ * config file).
+ */
+export interface TopicRelationsOptions {
+    allowSources?: TagSource[];
+    allow?: string[];
+    deny?: string[];
 }
 export interface TopicCollectOptions {
     maxPerTag?: number;
@@ -62,6 +118,12 @@ export interface TopicCandidate {
     popularity: number;
     /** Metadata topic-relevance score computed by the filter stage. */
     metadataScore: number;
+    /**
+     * Translated tag names carried by the work, kept beside `tags` so
+     * `matchTranslatedNames` can compare them WITHOUT claiming the work itself
+     * carries a tag it does not (§tag-provenance). Default-off.
+     */
+    translatedTags?: string[];
     /** Pixiv AI classification copied from illustration search metadata. */
     aiType?: number;
 }

package/dist/utils/imageDimensions.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Intrinsic image dimensions read straight from the container header.
+ *
+ * PixivFlow ships no image decoder on purpose (§novel-cover): the only question
+ * it ever asks about a remote image is "what canvas is this?", and a handful of
+ * header bytes answer it for JPEG/PNG/GIF without decoding any pixels. Unknown
+ * containers, truncated input and non-image payloads return `undefined` so
+ * callers can fail open instead of guessing.
+ */
+export interface ImageDimensions {
+    width: number;
+    height: number;
+}
+/**
+ * Reads the intrinsic canvas of a JPEG, PNG or GIF payload.
+ * Returns `undefined` when the format is unknown or the header is incomplete.
+ */
+export declare function readImageDimensions(input: ArrayBuffer | Uint8Array | null | undefined): ImageDimensions | undefined;
+//# sourceMappingURL=imageDimensions.d.ts.map