evolcore 0.0.10 → 0.0.12

package/dist/core/evolagent.js

@@ -52,7 +52,7 @@ export class EvolAgent {
         const ba = this.baseagent;
         // 动态读取配置（基于 fileCache + mtime），使配置变更立即体现在显示中
         try {
-            const effective = resolveEffective({ self: this.aid }, { cache: true });
+            const effective = resolveEffective({ self: this.aid }, { cache: true, expand: true });
             const block = effective.baseagents?.[ba];
             return block?.model;
         }
@@ -66,7 +66,7 @@ export class EvolAgent {
         const ba = this.baseagent;
         // 动态读取配置（基于 fileCache + mtime），使配置变更立即体现在显示中
         try {
-            const effective = resolveEffective({ self: this.aid }, { cache: true });
+            const effective = resolveEffective({ self: this.aid }, { cache: true, expand: true });
             const block = effective.baseagents?.[ba];
             if (ba === 'codex')
                 return block?.effort ?? block?.reasoning;
@@ -257,7 +257,8 @@ export class EvolAgent {
         this.persist();
     }
     setLifecycle(value) {
-        this.rawAgent = withLifecycleForWrite(this.rawAgent, value);
+        const current = cfgRead(ConfigTarget.Agent, { self: this.aid });
+        this.rawAgent = withLifecycleForWrite(current || this.rawAgent, value);
         this.rawAgent.$schema_version = Math.max(this.rawAgent.$schema_version || 0, this.merged.$schema_version || 0);
         this.merged.lifecycle = value;
         delete this.merged.initialized;
@@ -275,7 +276,8 @@ export class EvolAgent {
      */
     getPersona() {
         const personaPath = path.join(agentPersonalDir(this.aid), 'persona.md');
-        return fileCache.get(personaPath, (raw) => (raw === null ? null : (raw.trim() || null)), { policy: 'mtime', group: this.agentFilesGroup() });
+        const raw = fileCache.getText(personaPath, { policy: 'mtime', group: this.agentFilesGroup() });
+        return raw === null ? null : (raw.trim() || null);
     }
     /**
      * 读取 personal/memory/working.md 内容。走 fileCache（mtime 门控）：
@@ -284,7 +286,8 @@ export class EvolAgent {
      */
     getWorkingMemory() {
         const workingPath = path.join(agentPersonalDir(this.aid), 'memory', 'working.md');
-        return fileCache.get(workingPath, (raw) => (raw === null ? null : (raw.trim() || null)), { policy: 'mtime', group: this.agentFilesGroup() });
+        const raw = fileCache.getText(workingPath, { policy: 'mtime', group: this.agentFilesGroup() });
+        return raw === null ? null : (raw.trim() || null);
     }
     /** 清除本 agent 身份层缓存（reload 后重新读取）。只失效自己的文件组，不波及他人。 */
     invalidatePersonaCache() {
@@ -318,6 +321,10 @@ export class EvolAgent {
         this.rawAgent = rawAgent;
         this.merged = merged;
     }
+    /** Reload uses the current object references as an in-memory rollback snapshot. */
+    captureConfigSnapshot() {
+        return { rawAgent: this.rawAgent, merged: this.merged };
+    }
     // ── 内部辅助 ─────────────────────────────────────────────────────────
     /**
      * 找 rawAgent.channels 里的可变实例，用于写入。

package/dist/core/handoff/dispatcher.js

@@ -117,8 +117,9 @@ export class HandoffDispatcher {
                     if (this.pausedAgents.has(selfAid))
                         return false;
                     const current = this.store.get(selfAid, next.handoff_id);
-                    if (!current || current.state !== 'queued' || current.attention_required)
-                        return current?.state === 'target_sent';
+                    if (!current || current.state !== 'queued' || current.attention_required) {
+                        return current?.state === 'target_sent' || current?.state === 'discarded';
+                    }
                     this.store.recordSendStarted(selfAid, current.handoff_id);
                     try {
                         const send = await this.sendWithinQueueDeadline(current);
@@ -171,6 +172,8 @@ export class HandoffDispatcher {
                     await new Promise(resolve => setTimeout(resolve, this.retryDelaysMs[Math.min(attempt - 1, this.retryDelaysMs.length - 1)] ?? 0));
                 }
             }
+            if (this.store.get(selfAid, next.handoff_id)?.state === 'discarded')
+                continue;
             if (!sent) {
                 this.store.recordSendExhausted(selfAid, next.handoff_id);
                 logger.error(`[Handoff] target send retries exhausted: ${next.handoff_id}`);

package/dist/core/handoff/runtime.js

@@ -7,6 +7,7 @@ import { createRootCausation, deriveCausation, normalizeCausation } from '../cau
 import { recordCausationSpan } from '../causation/audit.js';
 import { logger } from '../../utils/logger.js';
 const HANDOFF_STALE_WARN_MS = 72 * 60 * 60 * 1000;
+const HANDOFF_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
 const HANDOFF_LARGE_AGGREGATE_COUNT = 10;
 const HANDOFF_LARGE_AGGREGATE_CHARS = 50_000;
 export class HandoffTargetBlockedError extends Error {
@@ -43,6 +44,15 @@ export class TriggerHandoffRequiredForbiddenError extends Error {
         this.name = 'TriggerHandoffRequiredForbiddenError';
     }
 }
+export class HandoffSessionReplacedError extends Error {
+    sessionId;
+    code = 'HANDOFF_SESSION_REPLACED';
+    constructor(sessionId) {
+        super(`handoff session was replaced during creation: ${sessionId}`);
+        this.sessionId = sessionId;
+        this.name = 'HandoffSessionReplacedError';
+    }
+}
 export class HandoffRuntime {
     sessionManager;
     messageQueue;
@@ -52,6 +62,8 @@ export class HandoffRuntime {
     now;
     staleWarned = new Set();
     largeAggregateWarned = new Set();
+    lifecycleSequence = 0;
+    sessionDiscardSequence = new Map();
     constructor(sessionManager, messageQueue, sender, store = new HandoffStore(), options = {}) {
         this.sessionManager = sessionManager;
         this.messageQueue = messageQueue;
@@ -60,6 +72,7 @@ export class HandoffRuntime {
         this.dispatcher = new HandoffDispatcher(store, this.mutexes, sender, options);
     }
     async createOutbound(input) {
+        const operationSequence = ++this.lifecycleSequence;
         throwIfAborted(input.signal);
         const origin = await this.sessionManager.getSessionById(input.originSessionId);
         throwIfAborted(input.signal);
@@ -81,24 +94,29 @@ export class HandoffRuntime {
         if (input.explicitReturnPolicy === 'required' && input.causation?.trigger?.path.length) {
             throw new TriggerHandoffRequiredForbiddenError();
         }
-        await this.dispatcher.expireTargetQueued(input.selfAid, target.id);
-        throwIfAborted(input.signal);
-        const head = this.store.listByTarget(input.selfAid, target.id, 'queued')[0];
-        if (head?.attention_required) {
-            throw new HandoffTargetBlockedError(head.handoff_id, head.attention_reason ?? 'UNKNOWN_ATTENTION');
-        }
         const handoffCausation = deriveCausation(normalizeCausation(input.causation) ?? createRootCausation());
-        const handoff = this.store.create({
-            selfAid: input.selfAid,
-            originSessionId: origin.id,
-            originMessageId: input.originMessageId,
-            targetSessionId: target.id,
-            payload: input.payload,
-            encrypt: input.encrypt,
-            returnPolicy: input.explicitReturnPolicy ?? 'required',
-            originAuthorization: input.originAuthorization,
-            causation: handoffCausation,
-            now: this.now?.(),
+        const handoff = await this.mutexes.forKey(this.targetKey(input.selfAid, target.id)).runExclusive(async () => {
+            const replacedSessionId = [origin.id, target.id].find(sessionId => ((this.sessionDiscardSequence.get(this.sessionKey(input.selfAid, sessionId)) ?? 0) > operationSequence));
+            if (replacedSessionId)
+                throw new HandoffSessionReplacedError(replacedSessionId);
+            this.dispatcher.expireQueued(input.selfAid, target.id);
+            throwIfAborted(input.signal);
+            const head = this.store.listByTarget(input.selfAid, target.id, 'queued')[0];
+            if (head?.attention_required) {
+                throw new HandoffTargetBlockedError(head.handoff_id, head.attention_reason ?? 'UNKNOWN_ATTENTION');
+            }
+            return this.store.create({
+                selfAid: input.selfAid,
+                originSessionId: origin.id,
+                originMessageId: input.originMessageId,
+                targetSessionId: target.id,
+                payload: input.payload,
+                encrypt: input.encrypt,
+                returnPolicy: input.explicitReturnPolicy ?? 'required',
+                originAuthorization: input.originAuthorization,
+                causation: handoffCausation,
+                now: this.now?.(),
+            });
         });
         recordCausationSpan(handoffCausation, 'handoff.request', {
             status: 'started',
@@ -106,6 +124,10 @@ export class HandoffRuntime {
         });
         await this.dispatcher.drain(input.selfAid, target.id);
         const dispatched = this.store.get(input.selfAid, handoff.handoff_id) ?? handoff;
+        const replacedSessionId = [origin.id, target.id].find(sessionId => ((this.sessionDiscardSequence.get(this.sessionKey(input.selfAid, sessionId)) ?? 0) > operationSequence));
+        if (dispatched.state === 'discarded' || replacedSessionId) {
+            throw new HandoffSessionReplacedError(replacedSessionId ?? target.id);
+        }
         if (dispatched.state === 'failed') {
             throw new HandoffDeliveryFailedError(dispatched.handoff_id);
         }
@@ -142,7 +164,9 @@ export class HandoffRuntime {
     }
     markBindingIncomplete(selfAid, handoffId) {
         const instance = this.store.get(selfAid, handoffId);
-        if (instance && !instance.attention_required) {
+        if (instance
+            && (instance.state === 'target_context_pending' || instance.state === 'return_pending')
+            && !instance.attention_required) {
             this.store.markAttention(selfAid, handoffId, 'REPLY_BINDING_INCOMPLETE');
         }
     }
@@ -207,16 +231,31 @@ export class HandoffRuntime {
                 role: origin.chatType === 'group' ? (origin.identity?.role ?? 'none') : undefined,
                 sessionKeyField: origin.sessionKey,
                 selfAID: origin.selfAID,
-                onPersisted: () => this.store.recordOriginEnqueued(selfAid, handoffId, messageId),
+                onPersisted: () => {
+                    if (this.store.get(selfAid, handoffId)?.state !== 'origin_queued') {
+                        throw new Error(`handoff is no longer deliverable: ${handoffId}`);
+                    }
+                    this.store.recordOriginEnqueued(selfAid, handoffId, messageId);
+                },
             });
         }
         catch (error) {
-            this.store.recordOriginEnqueueFailed(selfAid, handoffId, error instanceof Error ? error.message : String(error));
+            if (this.store.get(selfAid, handoffId)?.state === 'origin_queued') {
+                this.store.recordOriginEnqueueFailed(selfAid, handoffId, error instanceof Error ? error.message : String(error));
+            }
         }
     }
     buildPromptItem(message) {
         return this.buildPromptItems(message)[0] ?? null;
     }
+    isDiscardedDelivery(message) {
+        const delivery = message.handoffDelivery;
+        const selfAid = message.selfAID;
+        if (!delivery || !selfAid)
+            return false;
+        const ids = delivery.handoffIds?.length ? delivery.handoffIds : [delivery.handoffId];
+        return ids.length > 0 && ids.every(handoffId => this.store.get(selfAid, handoffId)?.state === 'discarded');
+    }
     buildPromptItems(message) {
         const delivery = message.handoffDelivery;
         const selfAid = message.selfAID;
@@ -367,9 +406,54 @@ export class HandoffRuntime {
             expired += this.dispatcher.expireQueued(selfAid).length;
         return expired;
     }
-    async recover(selfAids) {
+    async discardSession(selfAid, sessionId) {
+        this.sessionDiscardSequence.set(this.sessionKey(selfAid, sessionId), ++this.lifecycleSequence);
+        const candidates = this.store.list(selfAid)
+            .filter(instance => (instance.origin_session_id === sessionId || instance.target_session_id === sessionId) && instance.state !== 'failed' && instance.state !== 'completed' && instance.state !== 'discarded');
+        let discarded = 0;
+        for (const instance of candidates) {
+            const result = await this.discardWithTargetLock(selfAid, instance.handoff_id, 'session_replaced', {
+                session_id: sessionId,
+            });
+            if (result)
+                discarded++;
+        }
+        return discarded;
+    }
+    async discardExpired(selfAids, retentionMs = HANDOFF_RETENTION_MS) {
+        const now = this.now?.() ?? Date.now();
+        let discarded = 0;
+        for (const selfAid of selfAids) {
+            const latestEventVersions = new Map();
+            for (const event of this.store.events(selfAid)) {
+                if (!event.handoff_id || event.to_version === undefined)
+                    continue;
+                latestEventVersions.set(event.handoff_id, Math.max(latestEventVersions.get(event.handoff_id) ?? 0, event.to_version));
+            }
+            for (const instance of this.store.list(selfAid)) {
+                if (instance.state === 'failed' || instance.state === 'completed' || instance.state === 'discarded')
+                    continue;
+                if (now - instance.created_at <= retentionMs)
+                    continue;
+                if ((latestEventVersions.get(instance.handoff_id) ?? 0) !== instance.version)
+                    continue;
+                const result = await this.discardWithTargetLock(selfAid, instance.handoff_id, 'retention_expired', {
+                    retention_ms: retentionMs,
+                    age_ms: now - instance.created_at,
+                }, instance.version, now);
+                if (result) {
+                    discarded++;
+                    logger.info(`[Handoff] discarded expired handoff: ${instance.handoff_id}`);
+                }
+            }
+        }
+        return discarded;
+    }
+    async recover(selfAids, options = {}) {
         const originEnqueues = [];
         for (const selfAid of selfAids) {
+            if (options.discardExpired !== false)
+                await this.discardExpired([selfAid]);
             // v1 initially represented return=none as return_pending and required an
             // empty manual return. It has already been shown to a target turn, so
             // finish it before version reconciliation instead of prompting again.
@@ -412,6 +496,40 @@ export class HandoffRuntime {
         }
         await Promise.all(originEnqueues);
     }
+    async discardWithTargetLock(selfAid, handoffId, reason, details, expectedVersion, now = this.now?.()) {
+        const snapshot = this.store.get(selfAid, handoffId);
+        if (!snapshot)
+            return false;
+        const discarded = await this.mutexes.forKey(this.targetKey(selfAid, snapshot.target_session_id)).runExclusive(async () => {
+            const current = this.store.get(selfAid, handoffId);
+            if (!current || current.state === 'failed' || current.state === 'completed' || current.state === 'discarded') {
+                return null;
+            }
+            if (expectedVersion !== undefined && current.version !== expectedVersion)
+                return null;
+            this.store.discard(selfAid, handoffId, reason, details, now);
+            return current;
+        });
+        if (!discarded)
+            return false;
+        await this.cancelOriginDelivery(discarded);
+        return true;
+    }
+    async cancelOriginDelivery(instance) {
+        if (instance.state !== 'origin_queued' && instance.state !== 'origin_delivered')
+            return;
+        const messageId = instance.origin_delivery_message_id
+            ?? `origin-deliver:${instance.handoff_id}:${instance.origin_session_id}`;
+        const queue = this.messageQueue;
+        try {
+            const queued = queue.cancelMessageByIdInSession?.(instance.origin_session_id, messageId) ?? false;
+            if (!queued)
+                await queue.cancelActiveAndWait?.(messageId);
+        }
+        catch (error) {
+            logger.warn(`[Handoff] failed to cancel discarded origin delivery ${messageId}:`, error);
+        }
+    }
     warnIfStale(instance) {
         if (instance.state !== 'target_sent' && instance.state !== 'return_pending')
             return;
@@ -425,6 +543,12 @@ export class HandoffRuntime {
             + ` ageHours=${Math.floor(ageMs / 3_600_000)}`
             + ` originSession=${instance.origin_session_id} targetSession=${instance.target_session_id}`);
     }
+    targetKey(selfAid, targetSessionId) {
+        return `${selfAid}\u0000${targetSessionId}`;
+    }
+    sessionKey(selfAid, sessionId) {
+        return `${selfAid}\u0000${sessionId}`;
+    }
     warnIfLargeAggregate(message, instances, direction) {
         const chars = message.content.length
             + instances.reduce((total, instance) => total + this.requestSummary(instance).length, 0);

package/dist/core/handoff/store.js

@@ -9,6 +9,7 @@ import { HANDOFF_SCHEMA_VERSION, HANDOFF_QUERY_DEFAULT_LIMIT, HANDOFF_QUERY_MAX_
 import { normalizeCausation } from '../causation/context.js';
 const SAFE_ID_RE = /^[A-Za-z0-9._-]+$/;
 export const HANDOFF_ID_RE = /^h-[A-Za-z0-9._-]+$/;
+const TERMINAL_HANDOFF_STATES = new Set(['failed', 'completed', 'discarded']);
 function safeSegment(value, field) {
     if (!value || !SAFE_ID_RE.test(value) || value === '.' || value === '..') {
         throw new Error(`invalid ${field}`);
@@ -514,6 +515,29 @@ export class HandoffStore {
         this.write(selfAid, instance);
         return instance;
     }
+    discard(selfAid, handoffId, reason, details = {}, now = Date.now()) {
+        const instance = this.get(selfAid, handoffId);
+        if (!instance)
+            throw new Error('handoff not found');
+        if (TERMINAL_HANDOFF_STATES.has(instance.state))
+            return instance;
+        const previousState = instance.state;
+        const previousVersion = instance.version;
+        instance.state = 'discarded';
+        instance.attention_required = false;
+        instance.attention_reason = null;
+        instance.version++;
+        instance.updated_at = now;
+        instance.completed_at = now;
+        this.appendEvent(selfAid, 'handoff_discarded', handoffId, {
+            fromVersion: previousVersion,
+            toVersion: instance.version,
+            details: { ...details, reason, previous_state: previousState },
+            now,
+        });
+        this.write(selfAid, instance);
+        return instance;
+    }
     requireState(selfAid, handoffId, expected) {
         const instance = this.get(selfAid, handoffId);
         if (!instance)

package/dist/core/handoff/types.js

@@ -8,6 +8,7 @@ export const HANDOFF_STATES = [
     'origin_queued',
     'origin_delivered',
     'completed',
+    'discarded',
 ];
 export const HANDOFF_QUERY_DEFAULT_LIMIT = 100;
 export const HANDOFF_QUERY_MAX_LIMIT = 500;

package/dist/core/inference/text-inference.js

@@ -1,4 +1,5 @@
 import { normalizeBaseagent, resolveAnthropicDirectConfig, resolveEcagentConfig, resolveOpenaiDirectConfig, } from '../../agents/baseagent.js';
+import { buildModelRequestHeaders } from '../../agents/request-identity.js';
 function apiEndpoint(baseUrl, resource) {
     const configured = baseUrl?.trim();
     if (!configured)
@@ -119,12 +120,25 @@ export class EcagentTextInferenceProvider {
     baseagent = 'ecagent';
     constructor(config) {
         this.config = config;
+        this.config = {
+            ...config,
+            headers: buildModelRequestHeaders({
+                baseagent: 'ecagent',
+                baseUrl: config.baseUrl,
+                agentAid: config.evolcoreAgentAid,
+                configuredHeaders: config.headers,
+            }),
+        };
     }
     async completeText(request) {
         const response = await fetch(apiEndpoint(this.config.baseUrl, 'chat/completions'), {
             method: 'POST',
             signal: request.signal,
-            headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${this.config.apiKey}` },
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.config.apiKey}`,
+                ...this.config.headers,
+            },
             body: JSON.stringify({
                 model: request.model,
                 messages: [{ role: 'system', content: request.system }, { role: 'user', content: request.input }],
@@ -150,15 +164,35 @@ export function createTextInferenceProvider(baseagent, config) {
     const canonical = normalizeBaseagent(baseagent).canonical;
     if (canonical === 'claude') {
         const resolved = resolveAnthropicDirectConfig(config.baseagents?.claude);
-        return resolved ? new AnthropicTextInferenceProvider(resolved) : undefined;
+        return resolved ? new AnthropicTextInferenceProvider({
+            ...resolved,
+            headers: buildModelRequestHeaders({
+                baseagent: 'claude',
+                baseUrl: resolved.baseUrl,
+                agentAid: config.aid,
+                configuredHeaders: resolved.headers,
+            }),
+        }) : undefined;
     }
     if (canonical === 'codex') {
         const resolved = resolveOpenaiDirectConfig(config.baseagents?.codex);
-        return resolved ? new OpenAITextInferenceProvider(resolved) : undefined;
+        return resolved ? new OpenAITextInferenceProvider({
+            ...resolved,
+            headers: buildModelRequestHeaders({
+                baseagent: 'codex',
+                baseUrl: resolved.baseUrl,
+                agentAid: config.aid,
+                configuredHeaders: resolved.headers,
+            }),
+        }) : undefined;
     }
     if (canonical === 'ecagent') {
         try {
-            const resolved = resolveEcagentConfig({ agents: { ecagent: config.baseagents?.ecagent } }, config.baseagents?.ecagent);
+            const override = {
+                ...(config.baseagents?.ecagent ?? {}),
+                evolcoreAgentAid: config.aid,
+            };
+            const resolved = resolveEcagentConfig({ agents: { ecagent: override } }, override);
             return new EcagentTextInferenceProvider(resolved);
         }
         catch {

package/dist/core/message/logical-queue-bridge.js

@@ -110,6 +110,7 @@ export class LogicalQueueBridge {
             peerId: message.peerId,
             content: message.content,
             chatType: message.chatType ?? 'private',
+            mentions: message.mentions,
             isMentioned: message.isMentioned,
             mentionAids: message.mentionAids,
         };

package/dist/core/message/mention-schema.js

@@ -0,0 +1,126 @@
+export class MentionSchemaError extends Error {
+    code = 'INVALID_MENTION_SCHEMA';
+    index;
+    constructor(message, index) {
+        super(index === undefined ? message : `mentions[${index}]: ${message}`);
+        this.name = 'MentionSchemaError';
+        this.index = index;
+    }
+}
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function hasOwn(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}
+function assertMetadata(value, index) {
+    if (hasOwn(value, 'display') && typeof value.display !== 'string') {
+        throw new MentionSchemaError('display must be a string', index);
+    }
+    for (const key of ['offset', 'length']) {
+        if (!hasOwn(value, key))
+            continue;
+        const field = value[key];
+        if (typeof field !== 'number' || !Number.isInteger(field) || field < 0) {
+            throw new MentionSchemaError(`${key} must be a non-negative integer`, index);
+        }
+    }
+    for (const key of ['name', 'key']) {
+        if (hasOwn(value, key) && typeof value[key] !== 'string') {
+            throw new MentionSchemaError(`${key} must be a string`, index);
+        }
+    }
+}
+/**
+ * Validate and copy canonical mention entries.
+ *
+ * This is intentionally strict: the old string array format is rejected
+ * instead of being converted, because conversion can hide a producer bug and
+ * make routing appear to work with the wrong wire contract.
+ */
+export function normalizeMentionEntries(raw) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw)) {
+        throw new MentionSchemaError('mentions must be an array');
+    }
+    const normalized = [];
+    for (const [index, value] of raw.entries()) {
+        if (typeof value === 'string') {
+            throw new MentionSchemaError('legacy string entries are not supported; use {aid} or {scope:"all"}', index);
+        }
+        if (!isRecord(value)) {
+            throw new MentionSchemaError('entry must be an object', index);
+        }
+        const hasScope = hasOwn(value, 'scope');
+        const hasAid = hasOwn(value, 'aid');
+        const hasUserId = hasOwn(value, 'userId');
+        const discriminatorCount = Number(hasScope) + Number(hasAid) + Number(hasUserId);
+        if (discriminatorCount !== 1) {
+            throw new MentionSchemaError('entry must contain exactly one of scope, aid, or userId', index);
+        }
+        assertMetadata(value, index);
+        if (hasScope) {
+            if (value.scope !== 'all') {
+                throw new MentionSchemaError('scope must be "all"', index);
+            }
+            normalized.push({ ...value, scope: 'all' });
+            continue;
+        }
+        if (hasAid) {
+            if (typeof value.aid !== 'string' || value.aid.length === 0 || value.aid.trim() !== value.aid) {
+                throw new MentionSchemaError('aid must be a non-empty trimmed string', index);
+            }
+            if (value.aid === 'all') {
+                throw new MentionSchemaError('all is a scope, not an aid; use {scope:"all"}', index);
+            }
+            normalized.push({ ...value, aid: value.aid });
+            continue;
+        }
+        if (typeof value.userId !== 'string' || value.userId.length === 0 || value.userId.trim() !== value.userId) {
+            throw new MentionSchemaError('userId must be a non-empty trimmed string', index);
+        }
+        if (value.userId === 'all') {
+            throw new MentionSchemaError('all is a scope, not a userId; use {scope:"all"}', index);
+        }
+        normalized.push({ ...value, userId: value.userId });
+    }
+    return normalized;
+}
+export function mentionEntryIsAll(entry) {
+    return 'scope' in entry && entry.scope === 'all';
+}
+/** Return all concrete target IDs, including channel-native userId entries. */
+export function mentionEntryTargets(entries) {
+    const targets = [];
+    const seen = new Set();
+    for (const entry of entries) {
+        const target = 'aid' in entry && typeof entry.aid === 'string'
+            ? entry.aid
+            : 'userId' in entry && typeof entry.userId === 'string'
+                ? entry.userId
+                : undefined;
+        if (!target || target === 'all' || seen.has(target))
+            continue;
+        seen.add(target);
+        targets.push(target);
+    }
+    return targets;
+}
+export function hasMentionAll(entries) {
+    return entries.some(mentionEntryIsAll);
+}
+/** IDs used by renderers; keeps `all` visible as a derived value. */
+export function mentionEntryAids(entries) {
+    const aids = mentionEntryTargets(entries);
+    if (hasMentionAll(entries))
+        aids.push('all');
+    return aids;
+}
+export function mentionEntryKey(entry) {
+    if ('scope' in entry && entry.scope === 'all')
+        return 'scope:all';
+    if ('aid' in entry)
+        return `aid:${entry.aid}`;
+    return `user:${entry.userId}`;
+}