@slicedearth/whoisleuth-cli 2.5.1 → 2.6.0

package/packages/workspace/brand-candidate-workflow.mjs

@@ -0,0 +1,351 @@
+import { normalizeDomain } from "../evidence/domain-name.mjs";
+import { normalizeExplicitIsoTimestamp } from "../evidence/observation.mjs";
+import { sha256IdentityHex } from "../evidence/record-identity.mjs";
+import { ordinaryWorkspaceRecord } from "./hostile-input.mjs";
+import { MAX_CANDIDATE_OBSERVATIONS, MAX_CANDIDATE_MATCHES, MAX_CANDIDATE_SOURCES, MAX_CANDIDATE_TEXT, MAX_CANDIDATE_EXCEPTIONS, MAX_CANDIDATE_EXCEPTION_HISTORY, MAX_WATCH_CONTEXTS, MAX_WATCHLIST_DOMAINS, MAX_WATCHLIST_INPUT_RECORDS, } from "../contracts/workspace-portability.mjs";
+export { MAX_CANDIDATE_OBSERVATIONS, MAX_CANDIDATE_MATCHES, MAX_CANDIDATE_SOURCES, MAX_CANDIDATE_TEXT, MAX_CANDIDATE_EXCEPTIONS, MAX_CANDIDATE_EXCEPTION_HISTORY, MAX_WATCH_CONTEXTS, } from "../contracts/workspace-portability.mjs";
+/** Analyst urgency never changes a score, collection mode or schedule. */
+export const WATCH_PRIORITIES = Object.freeze([
+    { value: 'unassigned', label: 'Unassigned' },
+    { value: 'p1', label: 'P1 immediate review' },
+    { value: 'p2', label: 'P2 prompt review' },
+    { value: 'p3', label: 'P3 routine review' },
+    { value: 'p4', label: 'P4 background watch' },
+]);
+const CONTROL = /[\u0000-\u001f\u007f]/u;
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
+function record(value) {
+    return ordinaryWorkspaceRecord(value, 'Candidate metadata') ?? {};
+}
+function text(value, maximum = MAX_CANDIDATE_TEXT) {
+    return typeof value === 'string' && !CONTROL.test(value) && value.length <= maximum * 4
+        ? value.replace(/\s+/gu, ' ').trim().slice(0, maximum)
+        : '';
+}
+function reference(value) {
+    return typeof value === 'string' && ID.test(value) ? value : '';
+}
+function time(value) {
+    return normalizeExplicitIsoTimestamp(value);
+}
+export function normalizeCandidateObservation(value) {
+    const raw = record(value), domain = normalizeDomain(raw.domain);
+    if (!domain)
+        return null;
+    if ((Array.isArray(raw.matches) && raw.matches.length > MAX_CANDIDATE_MATCHES) ||
+        (Array.isArray(raw.sources) && raw.sources.length > MAX_CANDIDATE_SOURCES)) {
+        throw new RangeError('Candidate provenance exceeds its retained bound. Reduce the exact selection; no source was silently chosen or discarded.');
+    }
+    const matches = new Map();
+    for (const entry of (Array.isArray(raw.matches) ? raw.matches : []).slice(0, MAX_CANDIDATE_MATCHES * 4)) {
+        const match = record(entry), brandProfileId = reference(match.brandProfileId), ruleKey = reference(match.ruleKey);
+        const reason = text(match.reason), term = text(match.term);
+        if (brandProfileId && ruleKey && reason) {
+            const key = `${brandProfileId}\0${ruleKey}`, next = { brandProfileId, ruleKey, term, reason }, prior = matches.get(key);
+            if (prior && JSON.stringify(prior) !== JSON.stringify(next))
+                throw new TypeError('The same Brand rule has conflicting candidate reasons. Keep its source identity separate.');
+            matches.set(key, next);
+        }
+        if (matches.size >= MAX_CANDIDATE_MATCHES)
+            break;
+    }
+    const sources = new Map();
+    for (const entry of (Array.isArray(raw.sources) ? raw.sources : []).slice(0, MAX_CANDIDATE_SOURCES * 4)) {
+        const input = record(entry), source = text(input.source, 100), observedHostname = normalizeDomain(input.observedHostname);
+        if (!source ||
+            !observedHostname ||
+            /https?:\/\/|[?]/iu.test(source) ||
+            /https?:\/\/|[?]/iu.test(String(input.revision ?? '')))
+            continue;
+        const first = time(input.sourceFirstObservedAt), last = time(input.sourceLastObservedAt);
+        const invalidInterval = Boolean(first && last && first > last);
+        const malformedClock = (input.sourceFirstObservedAt != null && !first) ||
+            (input.sourceLastObservedAt != null && !last);
+        const observation = {
+            source,
+            observedHostname,
+            revision: text(input.revision, 128) || null,
+            sourceFirstObservedAt: invalidInterval ? null : first,
+            sourceLastObservedAt: invalidInterval ? null : last,
+            firstLocalObservedAt: time(input.firstLocalObservedAt),
+            completeness: invalidInterval || malformedClock
+                ? 'partial'
+                : input.completeness === 'complete' || input.completeness === 'partial'
+                    ? input.completeness
+                    : 'unknown',
+            gap: invalidInterval
+                ? 'The source-reported interval is inconsistent.'
+                : malformedClock
+                    ? 'A supplied source observation clock is invalid or lacks an explicit timezone.'
+                    : text(input.gap),
+        };
+        sources.set(JSON.stringify(observation), observation);
+        if (sources.size >= MAX_CANDIDATE_SOURCES)
+            break;
+    }
+    return {
+        domain,
+        matches: [...matches.values()].sort((a, b) => `${a.brandProfileId}:${a.ruleKey}`.localeCompare(`${b.brandProfileId}:${b.ruleKey}`)),
+        sources: [...sources.values()],
+    };
+}
+export function candidateMaterialFingerprint(candidate, brandProfileId, ruleKey) {
+    return `material:${sha256IdentityHex(new TextEncoder().encode(JSON.stringify({
+        domain: candidate.domain,
+        matches: candidate.matches.filter((match) => match.brandProfileId === brandProfileId && (!ruleKey || match.ruleKey === ruleKey)),
+        // Local retention time is not material evidence and repeated captures do not recur.
+        sources: candidate.sources
+            .map(({ firstLocalObservedAt: _local, ...source }) => source)
+            .sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))),
+    })))}`;
+}
+export function mergeCandidateObservations(left, right) {
+    const a = normalizeCandidateObservation(left), b = normalizeCandidateObservation(right);
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    if (a.domain !== b.domain)
+        throw new TypeError('Candidate provenance can only merge for the exact same domain.');
+    const sources = new Map();
+    for (const source of [...a.sources, ...b.sources]) {
+        const { firstLocalObservedAt: _local, ...material } = source;
+        const key = JSON.stringify(material), old = sources.get(key);
+        sources.set(key, {
+            ...source,
+            firstLocalObservedAt: old?.firstLocalObservedAt && source.firstLocalObservedAt
+                ? old.firstLocalObservedAt < source.firstLocalObservedAt
+                    ? old.firstLocalObservedAt
+                    : source.firstLocalObservedAt
+                : (old?.firstLocalObservedAt ?? source.firstLocalObservedAt),
+        });
+    }
+    const matches = new Map();
+    for (const match of [...a.matches, ...b.matches]) {
+        const key = `${match.brandProfileId}\0${match.ruleKey}`, old = matches.get(key);
+        if (old && JSON.stringify(old) !== JSON.stringify(match))
+            throw new TypeError('The same Brand rule has conflicting candidate reasons. No observation was overwritten.');
+        matches.set(key, match);
+    }
+    return normalizeCandidateObservation({
+        domain: a.domain,
+        matches: [...matches.values()],
+        sources: [...sources.values()],
+    });
+}
+export function normalizeCandidateObservations(value) {
+    const output = new Map();
+    for (const raw of (Array.isArray(value) ? value : []).slice(0, MAX_CANDIDATE_OBSERVATIONS * 4)) {
+        const candidate = normalizeCandidateObservation(raw);
+        if (!candidate)
+            continue;
+        output.set(candidate.domain, mergeCandidateObservations(output.get(candidate.domain), candidate));
+        if (output.size >= MAX_CANDIDATE_OBSERVATIONS)
+            break;
+    }
+    return [...output.values()];
+}
+export function normalizeWatchDomainMetadata(value, legacyDomains = []) {
+    const output = new Map();
+    for (const raw of (Array.isArray(value) ? value : []).slice(0, MAX_WATCHLIST_INPUT_RECORDS)) {
+        const entry = record(raw), domain = normalizeDomain(entry.domain);
+        if (!domain)
+            continue;
+        const prior = output.get(domain);
+        const contexts = new Map(prior?.contexts.map((context) => [context.brandProfileId ?? '', context]) ?? []);
+        for (const item of (Array.isArray(entry.contexts) ? entry.contexts : []).slice(0, MAX_WATCH_CONTEXTS * 4)) {
+            const input = record(item), brandProfileId = reference(input.brandProfileId) || null;
+            if (input.brandProfileId !== null && !brandProfileId)
+                continue;
+            const priority = WATCH_PRIORITIES.some((option) => option.value === input.priority)
+                ? input.priority
+                : 'unassigned';
+            const context = {
+                brandProfileId,
+                priority,
+                reason: text(input.reason),
+                changedAt: time(input.changedAt),
+                reviewDueAt: time(input.reviewDueAt),
+            };
+            const key = brandProfileId ?? '', old = contexts.get(key);
+            if (!old || (context.changedAt && (!old.changedAt || context.changedAt > old.changedAt)))
+                contexts.set(key, context);
+            if (contexts.size >= MAX_WATCH_CONTEXTS)
+                break;
+        }
+        const candidate = normalizeCandidateObservation(entry.candidate);
+        output.set(domain, {
+            domain,
+            contexts: [...contexts.values()],
+            candidate: mergeCandidateObservations(prior?.candidate, candidate?.domain === domain ? candidate : null),
+        });
+        if (output.size > MAX_WATCHLIST_DOMAINS)
+            throw new RangeError(`Watchlists are limited to ${MAX_WATCHLIST_DOMAINS} active domains. No members were discarded.`);
+    }
+    for (const raw of legacyDomains.slice(0, MAX_WATCHLIST_INPUT_RECORDS)) {
+        const domain = normalizeDomain(raw);
+        if (domain && !output.has(domain))
+            output.set(domain, {
+                domain,
+                contexts: [
+                    {
+                        brandProfileId: null,
+                        priority: 'unassigned',
+                        reason: '',
+                        changedAt: null,
+                        reviewDueAt: null,
+                    },
+                ],
+                candidate: null,
+            });
+        if (output.size > MAX_WATCHLIST_DOMAINS)
+            throw new RangeError(`Watchlists are limited to ${MAX_WATCHLIST_DOMAINS} active domains. No members were discarded.`);
+    }
+    return [...output.values()];
+}
+export function mergeWatchDomainMetadata(local, imported) {
+    const output = new Map(normalizeWatchDomainMetadata(local).map((entry) => [entry.domain, entry]));
+    for (const incoming of normalizeWatchDomainMetadata(imported)) {
+        const previous = output.get(incoming.domain);
+        if (!previous) {
+            if (output.size >= MAX_WATCHLIST_DOMAINS)
+                throw new RangeError(`Watchlists are limited to ${MAX_WATCHLIST_DOMAINS} active domains. No members were discarded.`);
+            output.set(incoming.domain, incoming);
+            continue;
+        }
+        const contexts = new Map(previous.contexts.map((context) => [context.brandProfileId, context]));
+        for (const context of incoming.contexts) {
+            const old = contexts.get(context.brandProfileId);
+            if ((!old && contexts.size < MAX_WATCH_CONTEXTS) ||
+                (old && context.changedAt && (!old.changedAt || context.changedAt > old.changedAt)))
+                contexts.set(context.brandProfileId, context);
+        }
+        output.set(incoming.domain, {
+            domain: incoming.domain,
+            contexts: [...contexts.values()],
+            candidate: mergeCandidateObservations(previous.candidate, incoming.candidate),
+        });
+    }
+    return [...output.values()];
+}
+function exceptionSnapshot(value) {
+    const raw = record(value), reviewedAt = time(raw.reviewedAt), expiresAt = time(raw.expiresAt), reason = text(raw.reason);
+    if (!reviewedAt ||
+        !expiresAt ||
+        (raw.enabled === true && expiresAt <= reviewedAt) ||
+        !reason ||
+        !Number.isSafeInteger(raw.revision) ||
+        Number(raw.revision) < 1 ||
+        typeof raw.reviewedFingerprint !== 'string' ||
+        !/^material:[a-f0-9]{64}$/u.test(raw.reviewedFingerprint) ||
+        typeof raw.enabled !== 'boolean')
+        return null;
+    return {
+        revision: Number(raw.revision),
+        reviewedAt,
+        expiresAt,
+        reason,
+        reviewedFingerprint: raw.reviewedFingerprint,
+        enabled: raw.enabled,
+    };
+}
+export function normalizeCandidateExceptions(value) {
+    const output = new Map();
+    const seenRevisions = new Map();
+    const seenScopes = new Map();
+    for (const item of (Array.isArray(value) ? value : []).slice(0, MAX_CANDIDATE_EXCEPTIONS * 4)) {
+        const raw = record(item), snapshot = exceptionSnapshot(raw), id = reference(raw.id), domain = normalizeDomain(raw.domain), ruleKey = reference(raw.ruleKey);
+        if (!snapshot ||
+            !id ||
+            !domain ||
+            !ruleKey ||
+            !['irrelevant_match', 'deferred_review', 'accepted_temporary_change'].includes(String(raw.purpose)))
+            continue;
+        const history = (Array.isArray(raw.history) ? raw.history : [])
+            .slice(0, MAX_CANDIDATE_EXCEPTION_HISTORY * 4)
+            .map(exceptionSnapshot)
+            .filter((entry) => entry !== null)
+            .slice(0, MAX_CANDIDATE_EXCEPTION_HISTORY);
+        const exception = {
+            ...snapshot,
+            id,
+            domain,
+            ruleKey,
+            purpose: raw.purpose,
+            history,
+            historyOmitted: Number.isSafeInteger(raw.historyOmitted) && Number(raw.historyOmitted) >= 0
+                ? Number(raw.historyOmitted)
+                : 0,
+        };
+        const old = output.get(id);
+        const scope = JSON.stringify([domain, ruleKey, exception.purpose]);
+        const previousScope = seenScopes.get(id);
+        if (previousScope !== undefined && previousScope !== scope)
+            throw new TypeError('An exception identifier cannot change its exact domain, rule or purpose.');
+        seenScopes.set(id, scope);
+        const revisionKey = JSON.stringify([id, exception.revision]);
+        const revisionValue = JSON.stringify(exception);
+        const previousRevision = seenRevisions.get(revisionKey);
+        if (previousRevision !== undefined && previousRevision !== revisionValue)
+            throw new TypeError('The same exception identifier and revision contain conflicting decisions. No exception was imported.');
+        seenRevisions.set(revisionKey, revisionValue);
+        if ((old && exception.revision > old.revision) || (!old && output.size < MAX_CANDIDATE_EXCEPTIONS))
+            output.set(id, exception);
+    }
+    return [...output.values()];
+}
+export function candidateExceptionState(exception, candidate, brandProfileId, now) {
+    if (!exception.enabled)
+        return 'disabled';
+    if (exception.domain !== candidate.domain ||
+        !candidate.matches.some((match) => match.brandProfileId === brandProfileId && match.ruleKey === exception.ruleKey))
+        return 'unmatched';
+    const clock = time(now);
+    if (!clock || clock < exception.reviewedAt)
+        return 'clock_unavailable';
+    if (clock >= exception.expiresAt)
+        return 'expired';
+    if (candidateMaterialFingerprint(candidate, brandProfileId, exception.ruleKey) !==
+        exception.reviewedFingerprint)
+        return 'changed';
+    return 'active';
+}
+/** Updates are revision-checked; disabling preserves the previous reason and snapshot. */
+export function reviseCandidateException(existing, input, expectedRevision) {
+    if ((existing?.revision ?? null) !== expectedRevision)
+        throw new Error('The candidate exception changed. Reopen it before saving; nothing was overwritten.');
+    if (typeof input.reason !== 'string' ||
+        input.reason.length > MAX_CANDIDATE_TEXT ||
+        CONTROL.test(input.reason))
+        throw new TypeError('Exception reasons must contain 1–300 plain-text characters.');
+    const revision = (existing?.revision ?? 0) + 1;
+    const retainedReviewClock = existing
+        ? [existing.reviewedAt, ...existing.history.map(snapshot => snapshot.reviewedAt)].sort().at(-1)
+        : null;
+    const submittedReviewClock = time(input.reviewedAt);
+    if (input.enabled && retainedReviewClock && submittedReviewClock && submittedReviewClock < retainedReviewClock)
+        throw new TypeError('The review clock precedes a retained exception review. Correct the clock before renewing or re-enabling it.');
+    const reviewedAt = !input.enabled && retainedReviewClock && submittedReviewClock && submittedReviewClock < retainedReviewClock
+        ? retainedReviewClock
+        : input.reviewedAt;
+    const prior = existing ? [exceptionSnapshot(existing), ...existing.history] : [];
+    const normalized = normalizeCandidateExceptions([
+        {
+            ...input,
+            reviewedAt,
+            revision,
+            history: prior.slice(0, MAX_CANDIDATE_EXCEPTION_HISTORY),
+            historyOmitted: (existing?.historyOmitted ?? 0) +
+                Math.max(0, prior.length - MAX_CANDIDATE_EXCEPTION_HISTORY),
+        },
+    ])[0];
+    if (!normalized)
+        throw new TypeError('Use an exact domain and rule, a reason, a future expiry and current reviewed evidence.');
+    if (existing &&
+        (input.id !== existing.id ||
+            input.domain !== existing.domain ||
+            input.ruleKey !== existing.ruleKey ||
+            input.purpose !== existing.purpose))
+        throw new TypeError('An exception revision cannot widen its domain or rule scope. Create and preview another exact exception.');
+    return normalized;
+}

package/packages/workspace/brand-keyword-campaign.mjs

@@ -0,0 +1,231 @@
+import { normalizeExplicitIsoTimestamp } from "../evidence/observation.mjs";
+import { sha256IdentityHex } from "../evidence/record-identity.mjs";
+import { ordinaryWorkspaceRecord, assertWorkspaceInputGraph } from "./hostile-input.mjs";
+import { WATCH_PRIORITIES, normalizeCandidateObservation, } from "./brand-candidate-workflow.mjs";
+import { MAX_BRAND_KEYWORD_CAMPAIGNS, MAX_BRAND_KEYWORD_CAMPAIGN_HISTORY, MAX_BRAND_KEYWORD_TERMS, MAX_BRAND_KEYWORD_TERM_LENGTH, MAX_PROFILE_NAME_LENGTH, } from "../contracts/workspace-portability.mjs";
+export { MAX_BRAND_KEYWORD_CAMPAIGNS, MAX_BRAND_KEYWORD_CAMPAIGN_HISTORY, MAX_BRAND_KEYWORD_TERMS, MAX_BRAND_KEYWORD_TERM_LENGTH, } from "../contracts/workspace-portability.mjs";
+const CONTROL = /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/u;
+const ID = /^[A-Za-z0-9_-]{1,64}$/u;
+/** Shared feed and campaign literals are plain substrings, never regular expressions. */
+export function normalizeBrandKeywordTerms(value) {
+    if (!Array.isArray(value) || value.length > MAX_BRAND_KEYWORD_TERMS)
+        throw new RangeError('Use at most 20 literal terms in each selection.');
+    assertWorkspaceInputGraph(value, 'Keyword literals');
+    return [
+        ...new Set(value.map((term) => {
+            if (typeof term !== 'string' ||
+                term.length < 3 ||
+                term.length > MAX_BRAND_KEYWORD_TERM_LENGTH ||
+                term !== term.trim() ||
+                CONTROL.test(term))
+                throw new TypeError('Literal feed terms must contain 3–80 characters without controls or surrounding spaces.');
+            const literal = term.toLowerCase();
+            if (literal.length > MAX_BRAND_KEYWORD_TERM_LENGTH)
+                throw new TypeError('Lowercased literal terms must remain within 80 characters.');
+            return literal;
+        })),
+    ];
+}
+/** The caller supplies a canonical hostname and already bounded literals. */
+export function matchBrandKeywordTerms(hostname, positive, negative = []) {
+    const terms = positive.filter((term) => hostname.includes(term));
+    const excludedTerms = negative.filter((term) => hostname.includes(term));
+    return { terms, excludedTerms, matched: terms.length > 0 && excludedTerms.length === 0 };
+}
+function snapshot(value) {
+    const raw = ordinaryWorkspaceRecord(value, 'Keyword campaign revision');
+    if (!raw)
+        throw new TypeError('A keyword campaign revision must be a record.');
+    const startsAt = normalizeExplicitIsoTimestamp(raw.startsAt), endsAt = normalizeExplicitIsoTimestamp(raw.endsAt), changedAt = normalizeExplicitIsoTimestamp(raw.changedAt);
+    if (!startsAt || !endsAt || !changedAt || Date.parse(endsAt) <= Date.parse(startsAt))
+        throw new TypeError('Use explicit campaign start and end timestamps, with the end after the start.');
+    if (typeof raw.name !== 'string' ||
+        !raw.name.trim() ||
+        raw.name.length > MAX_PROFILE_NAME_LENGTH ||
+        CONTROL.test(raw.name))
+        throw new TypeError('Campaign names require 1–100 plain-text characters.');
+    if (!Number.isSafeInteger(raw.revision) ||
+        Number(raw.revision) < 1 ||
+        typeof raw.paused !== 'boolean' ||
+        !WATCH_PRIORITIES.some((option) => option.value === raw.defaultPriority))
+        throw new TypeError('The campaign revision, pause state or default priority is invalid.');
+    const positiveTerms = [...normalizeBrandKeywordTerms(raw.positiveTerms)].sort(), negativeTerms = [...normalizeBrandKeywordTerms(raw.negativeTerms)].sort();
+    if (!positiveTerms.length)
+        throw new TypeError('A keyword campaign requires at least one positive literal term.');
+    if (positiveTerms.some((term) => negativeTerms.includes(term)))
+        throw new TypeError('The same literal cannot be both positive and negative in one campaign.');
+    return {
+        revision: Number(raw.revision),
+        name: raw.name.trim(),
+        positiveTerms,
+        negativeTerms,
+        startsAt,
+        endsAt,
+        paused: raw.paused,
+        defaultPriority: raw.defaultPriority,
+        changedAt,
+    };
+}
+function campaign(value) {
+    const raw = ordinaryWorkspaceRecord(value, 'Keyword campaign');
+    if (!raw || typeof raw.id !== 'string' || !ID.test(raw.id))
+        throw new TypeError('The keyword campaign identifier is invalid.');
+    const current = snapshot(raw), createdAt = normalizeExplicitIsoTimestamp(raw.createdAt);
+    if (!createdAt || Date.parse(createdAt) > Date.parse(current.changedAt))
+        throw new TypeError('The campaign creation clock is invalid.');
+    if (!Array.isArray(raw.history) || raw.history.length > MAX_BRAND_KEYWORD_CAMPAIGN_HISTORY)
+        throw new RangeError('Retain at most eight previous campaign revisions.');
+    const history = raw.history.map(snapshot).sort((a, b) => b.revision - a.revision);
+    const seen = new Set();
+    let later = current;
+    for (const item of history) {
+        if (seen.has(item.revision) ||
+            item.revision >= later.revision ||
+            Date.parse(item.changedAt) > Date.parse(later.changedAt) ||
+            Date.parse(item.changedAt) < Date.parse(createdAt))
+            throw new TypeError('Campaign revision history is repeated, out of order or has conflicting clocks.');
+        seen.add(item.revision);
+        later = item;
+    }
+    if (raw.historyOmitted !== current.revision - 1 - history.length)
+        throw new TypeError('Campaign revision omissions must account for every earlier revision.');
+    return { ...current, id: raw.id, createdAt, history, historyOmitted: Number(raw.historyOmitted) };
+}
+/** Equal revisions must agree even when a newer revision would otherwise win. */
+export function mergeBrandKeywordCampaigns(left, right) {
+    const output = new Map();
+    for (const input of [left, right]) {
+        if (input === undefined)
+            continue;
+        if (!Array.isArray(input) || input.length > MAX_BRAND_KEYWORD_CAMPAIGNS)
+            throw new RangeError('Each Brand supports at most 20 keyword campaigns.');
+        assertWorkspaceInputGraph(input, 'Brand keyword campaigns');
+        for (const raw of input) {
+            const incoming = campaign(raw), existing = output.get(incoming.id);
+            if (!existing) {
+                output.set(incoming.id, incoming);
+                continue;
+            }
+            if (incoming.createdAt !== existing.createdAt)
+                throw new TypeError('The same campaign identifier has conflicting creation identity.');
+            const revisions = new Map();
+            for (const item of [
+                snapshot(existing),
+                ...existing.history,
+                snapshot(incoming),
+                ...incoming.history,
+            ]) {
+                const previous = revisions.get(item.revision);
+                if (previous && JSON.stringify(previous) !== JSON.stringify(item))
+                    throw new TypeError('The same campaign revision contains conflicting intent. No campaign was imported.');
+                revisions.set(item.revision, item);
+            }
+            const [current, ...earlier] = [...revisions.values()].sort((a, b) => b.revision - a.revision);
+            const history = earlier.slice(0, MAX_BRAND_KEYWORD_CAMPAIGN_HISTORY);
+            output.set(incoming.id, campaign({
+                ...current,
+                id: incoming.id,
+                createdAt: incoming.createdAt,
+                history,
+                historyOmitted: current.revision - 1 - history.length,
+            }));
+        }
+    }
+    if (output.size > MAX_BRAND_KEYWORD_CAMPAIGNS)
+        throw new RangeError('The merged Brand exceeds its 20-campaign limit; no campaign was discarded.');
+    return [...output.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+export function normalizeBrandKeywordCampaigns(value) {
+    return mergeBrandKeywordCampaigns(undefined, value);
+}
+export function reviseBrandKeywordCampaign(existing, input, expectedRevision, nowRaw) {
+    assertWorkspaceInputGraph(input, 'Keyword campaign edit');
+    if ((existing?.revision ?? null) !== expectedRevision || (existing && input.id !== existing.id))
+        throw new Error('The campaign changed. Reopen its saved revision before editing; nothing was overwritten.');
+    const now = normalizeExplicitIsoTimestamp(nowRaw);
+    if (!now || (existing && Date.parse(now) < Date.parse(existing.changedAt)))
+        throw new TypeError('The campaign change clock precedes retained intent. Correct the clock before saving.');
+    if (existing && existing.revision >= Number.MAX_SAFE_INTEGER)
+        throw new RangeError('The campaign revision limit is exhausted.');
+    const history = existing
+        ? [snapshot(existing), ...existing.history].slice(0, MAX_BRAND_KEYWORD_CAMPAIGN_HISTORY)
+        : [];
+    const revision = (existing?.revision ?? 0) + 1;
+    return campaign({
+        ...input,
+        revision,
+        changedAt: now,
+        createdAt: existing?.createdAt ?? now,
+        history,
+        historyOmitted: revision - 1 - history.length,
+    });
+}
+export function brandKeywordCampaignState(value, nowRaw) {
+    const now = normalizeExplicitIsoTimestamp(nowRaw);
+    if (!now || Date.parse(now) < Date.parse(value.changedAt))
+        return 'clock_unavailable';
+    if (value.paused)
+        return 'paused';
+    if (Date.parse(now) < Date.parse(value.startsAt))
+        return 'scheduled';
+    return Date.parse(now) >= Date.parse(value.endsAt) ? 'expired' : 'active';
+}
+export function keywordCampaignFeedSelection(value, brandProfileId, now) {
+    if (brandKeywordCampaignState(value, now) !== 'active')
+        throw new Error('Choose an active campaign revision. Scheduled, paused and expired campaigns do not nominate new candidates.');
+    return {
+        hosts: [],
+        terms: [...value.positiveTerms],
+        ...(value.negativeTerms.length ? { negativeTerms: [...value.negativeTerms] } : {}),
+        brandProfileId,
+    };
+}
+/** Keep source facts unchanged; add only the exact reviewed campaign revision. */
+export function attributeKeywordCampaignCandidate(candidate, value, brandProfileId, now) {
+    keywordCampaignFeedSelection(value, brandProfileId, now);
+    const { terms, matched } = matchBrandKeywordTerms(candidate.domain, value.positiveTerms, value.negativeTerms);
+    if (!matched)
+        throw new Error('This candidate does not qualify for the selected campaign revision.');
+    const matches = terms.map((term) => ({
+        brandProfileId,
+        ruleKey: `keyword:${value.id}:${value.revision}:${sha256IdentityHex(new TextEncoder().encode(term)).slice(0, 24)}`,
+        term,
+        reason: `Literal match for keyword campaign “${value.name}”, revision ${value.revision}. Candidate nomination only; no collection or infringement finding.`,
+    }));
+    const result = normalizeCandidateObservation({ ...candidate, matches });
+    if (!result)
+        throw new Error('The campaign candidate attribution is invalid.');
+    return result;
+}
+export function keywordCampaignMatchContext(ruleKey, campaigns) {
+    const match = /^keyword:([A-Za-z0-9_-]{1,64}):(\d+):([a-f0-9]{24})$/u.exec(ruleKey);
+    if (!match)
+        return null;
+    const owner = campaigns.find((item) => item.id === match[1]);
+    const revision = owner && [owner, ...owner.history].find((item) => item.revision === Number(match[2]));
+    return owner &&
+        revision &&
+        revision.positiveTerms.some((term) => sha256IdentityHex(new TextEncoder().encode(term)).slice(0, 24) === match[3])
+        ? { id: owner.id, revision }
+        : null;
+}
+/** Only one unambiguous retained default may prefill an explicit handoff. */
+export function keywordCampaignDefaultPriority(candidates, brandProfileId, campaigns) {
+    if (!candidates.length)
+        return null;
+    const priorities = new Set();
+    for (const candidate of candidates) {
+        const matches = candidate.matches.filter((match) => match.brandProfileId === brandProfileId);
+        if (!matches.length)
+            return null;
+        for (const match of matches) {
+            const context = keywordCampaignMatchContext(match.ruleKey, campaigns);
+            if (!context ||
+                !context.revision.positiveTerms.includes(match.term) ||
+                !candidate.domain.includes(match.term))
+                return null;
+            priorities.add(context.revision.defaultPriority);
+        }
+    }
+    return priorities.size === 1 ? [...priorities][0] : null;
+}