@loopover/engine 1.0.0

package/dist/settings/contributor-blacklist.js

@@ -0,0 +1,86 @@
+// GitHub logins: 1–39 chars, alphanumeric or single hyphens (not leading/trailing). Anything else is dropped so a
+// malformed entry can never widen the match or break the close path.
+const GITHUB_LOGIN = /^[a-zA-Z0-9](?:[a-zA-Z0-9]|-(?=[a-zA-Z0-9])){0,38}$/;
+const MAX_ENTRIES = 1000;
+const MAX_REASON_CHARS = 200;
+const MAX_EVIDENCE = 10;
+const MAX_EVIDENCE_CHARS = 500;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Normalize a raw blacklist value (DB JSON or `.gittensory.yml`) into validated, de-duplicated entries. Never
+ *  throws: malformed entries are dropped with a warning. De-dup is by case-insensitive login (the FIRST wins, so
+ *  its richer metadata is kept). */
+export function normalizeContributorBlacklist(input) {
+    const warnings = [];
+    if (input === undefined || input === null)
+        return { entries: [], warnings };
+    if (!Array.isArray(input)) {
+        warnings.push("contributorBlacklist must be a list of entries; ignoring it.");
+        return { entries: [], warnings };
+    }
+    const entries = [];
+    const seen = new Set();
+    for (const [index, raw] of input.entries()) {
+        if (entries.length >= MAX_ENTRIES) {
+            warnings.push(`contributorBlacklist is capped at ${MAX_ENTRIES} entries; dropping the rest.`);
+            break;
+        }
+        // Accept either a bare login string or a `{ login, ... }` object.
+        const record = typeof raw === "string" ? { login: raw } : raw;
+        if (!isRecord(record) || typeof record.login !== "string") {
+            warnings.push(`contributorBlacklist[${index}] needs a string login; ignoring it.`);
+            continue;
+        }
+        const login = record.login.trim();
+        if (!GITHUB_LOGIN.test(login)) {
+            warnings.push(`contributorBlacklist[${index}].login is not a valid GitHub login; ignoring it.`);
+            continue;
+        }
+        const key = login.toLowerCase();
+        if (seen.has(key))
+            continue; // first occurrence wins
+        seen.add(key);
+        const entry = { login };
+        if (typeof record.reason === "string" && record.reason.trim().length > 0)
+            entry.reason = record.reason.trim().slice(0, MAX_REASON_CHARS);
+        if (Array.isArray(record.evidence)) {
+            const evidence = record.evidence.filter((ref) => typeof ref === "string" && ref.trim().length > 0).map((ref) => ref.trim().slice(0, MAX_EVIDENCE_CHARS)).slice(0, MAX_EVIDENCE);
+            if (evidence.length > 0)
+                entry.evidence = evidence;
+        }
+        if (typeof record.addedAt === "string" && record.addedAt.trim().length > 0)
+            entry.addedAt = record.addedAt.trim();
+        entries.push(entry);
+    }
+    return { entries, warnings };
+}
+/** The blacklist entry matching `login` (case-insensitive), or null. Tolerates an absent list (treated as empty)
+ *  so callers can pass the optional `settings.contributorBlacklist` directly. */
+export function findBlacklistEntry(login, entries) {
+    if (!login)
+        return null;
+    const key = login.toLowerCase();
+    return (entries ?? []).find((entry) => entry.login.toLowerCase() === key) ?? null;
+}
+/** True iff `login` is on the resolved blacklist. */
+export function isAuthorBlacklisted(login, entries) {
+    return findBlacklistEntry(login, entries) !== null;
+}
+/** Union multiple blacklist sources (e.g. the shared/global list + the per-repo list) by case-insensitive login.
+ *  A login on ANY source is blocked; the FIRST source's entry wins on a duplicate so earlier (more authoritative)
+ *  metadata is preserved. Already-normalized inputs in, de-duplicated entries out. */
+export function mergeContributorBlacklists(...lists) {
+    const merged = [];
+    const seen = new Set();
+    for (const list of lists) {
+        for (const entry of list) {
+            const key = entry.login.toLowerCase();
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            merged.push(entry);
+        }
+    }
+    return merged;
+}

package/dist/settings/moderation-rules.d.ts

@@ -0,0 +1,51 @@
+/** The anti-abuse mechanisms this engine can count violations from -- the three ORIGINAL mechanisms
+ *  (contributor cap, blacklist, review-nag) plus review-evasion (#review-evasion-protection: a contributor
+ *  closing/converting-to-draft their own PR to dodge an active review). Kept as a closed union (not an open
+ *  string) so an unrecognized value is always a normalization error, never silently accepted. */
+export type ModerationRuleType = "contributor_cap" | "blacklist" | "review_nag" | "review_evasion";
+/** The `audit_events.event_type` recorded for each rule's violation -- namespaced under `moderation.violation.*`
+ *  so a cross-eventType, cross-repo count query (see `db/repositories.ts`) can scope to exactly this family. */
+export declare const MODERATION_VIOLATION_EVENT_TYPE: Record<ModerationRuleType, string>;
+export declare const DEFAULT_MODERATION_WARNING_LABEL = "mod:warning";
+export declare const DEFAULT_MODERATION_BANNED_LABEL = "mod:banned";
+export declare const DEFAULT_MODERATION_BAN_THRESHOLD = 5;
+export declare const MAX_MODERATION_VIOLATION_DECAY_DAYS = 3650;
+export type GlobalModerationConfig = {
+    enabled: boolean;
+    rules: ModerationRuleType[];
+    warningLabel: string;
+    bannedLabel: string;
+    banThreshold: number;
+    violationDecayDays: number | null;
+    autoBlacklistOnBan: boolean;
+};
+export declare const DEFAULT_GLOBAL_MODERATION_CONFIG: GlobalModerationConfig;
+/** Normalize a raw moderation-rules list (DB JSON or `.gittensory.yml`) into a validated, de-duplicated list
+ *  of known rule types. Never throws: an unknown/malformed entry is dropped with a warning, matching the
+ *  normalize-with-warnings shape every other settings list in this codebase already uses. */
+export declare function normalizeModerationRules(input: unknown): {
+    rules: ModerationRuleType[];
+    warnings: string[];
+};
+/** Normalize a raw moderation label value: empty/whitespace-only collapses to undefined (falls back to the
+ *  caller's default), overlong is truncated. Never throws. Mirrors blacklistLabel/contributorCapLabel's
+ *  shape, minus the explicit-null-means-"no label" case those close-coupled labels use -- a moderation label
+ *  is always applied when the tier is reached, never suppressible to "no label at all". */
+export declare function normalizeModerationLabel(input: unknown): string | undefined;
+/** Effective rule set for one repo: an explicit per-repo override REPLACES the global list entirely (not a
+ *  union) -- a repo opting out of counting review-nag toward the shared tally, for example, must be able to
+ *  do so without also losing the ability to opt out of the others. Absent/undefined override ⇒ inherit the
+ *  global list unchanged. */
+export declare function resolveEffectiveModerationRules(globalRules: readonly ModerationRuleType[], perRepoOverride: readonly ModerationRuleType[] | null | undefined): ModerationRuleType[];
+export type ModerationGateMode = "inherit" | "off" | "enabled";
+/** Whether the WHOLE moderation layer runs for one repo: the global master switch is authoritative;
+ *  `off` lets a repo opt out while the global layer is enabled, and `enabled`/`inherit` both require the
+ *  global switch to be on. */
+export declare function resolveModerationGateEnabled(globalEnabled: boolean, gateMode: ModerationGateMode): boolean;
+export type ModerationTier = "none" | "warning" | "banned";
+/** Pure escalation decision: given the actor's TOTAL violation count (including the one that just fired,
+ *  already recorded by the caller) and the configured ban threshold, which tier applies. A non-positive
+ *  threshold (malformed config) can never be reached by a real count, so it degrades to "always banned once
+ *  any violation exists" rather than throwing -- still a safe, non-silent failure mode for a misconfigured
+ *  threshold, not a crash. */
+export declare function moderationTierForViolationCount(count: number, banThreshold: number): ModerationTier;

package/dist/settings/moderation-rules.js

@@ -0,0 +1,104 @@
+// Centralized moderation-rules engine (generic self-host feature, #selfhost-mod-engine). A single modular
+// layer over the three EXISTING anti-abuse mechanisms (contributor cap, blacklist, review-nag) that already
+// short-circuit a PR's disposition: every time one of them fires against a non-exempt contributor, it counts
+// toward that login's install-wide violation tally (the shared `audit_events` ledger, keyed by actor). At
+// >=1 lifetime violation the contributor is labeled with `warningLabel`; at >=`banThreshold` they are labeled
+// `bannedLabel` and (when `autoBlacklistOnBan`) auto-added to the existing global contributor blacklist --
+// the SAME "permanent two-strikes" enforcement an already-banned login gets.
+//
+// Config-as-code, layered the same as every other setting: a global default (the whole layer can be off,
+// which rules count, the label text, the threshold, whether a ban auto-enforces) with a PER-REPO override
+// that can turn the layer off/on for just that repo and override which rules feed IT specifically. NEVER
+// hard-coded for any one repo -- a self-hoster's own `.gittensory.yml`/dashboard settings choose everything.
+const ALL_MODERATION_RULE_TYPES = ["contributor_cap", "blacklist", "review_nag", "review_evasion"];
+/** The `audit_events.event_type` recorded for each rule's violation -- namespaced under `moderation.violation.*`
+ *  so a cross-eventType, cross-repo count query (see `db/repositories.ts`) can scope to exactly this family. */
+export const MODERATION_VIOLATION_EVENT_TYPE = {
+    contributor_cap: "moderation.violation.contributor_cap",
+    blacklist: "moderation.violation.blacklist",
+    review_nag: "moderation.violation.review_nag",
+    review_evasion: "moderation.violation.review_evasion",
+};
+export const DEFAULT_MODERATION_WARNING_LABEL = "mod:warning";
+export const DEFAULT_MODERATION_BANNED_LABEL = "mod:banned";
+export const DEFAULT_MODERATION_BAN_THRESHOLD = 5;
+// Keep the decay lookback operationally bounded, mirroring MAX_REVIEW_NAG_COOLDOWN_DAYS -- repo-controlled
+// config cannot overflow Date arithmetic.
+export const MAX_MODERATION_VIOLATION_DECAY_DAYS = 3650;
+const MAX_LABEL_CHARS = 100;
+export const DEFAULT_GLOBAL_MODERATION_CONFIG = {
+    enabled: false,
+    rules: [...ALL_MODERATION_RULE_TYPES],
+    warningLabel: DEFAULT_MODERATION_WARNING_LABEL,
+    bannedLabel: DEFAULT_MODERATION_BANNED_LABEL,
+    banThreshold: DEFAULT_MODERATION_BAN_THRESHOLD,
+    violationDecayDays: null,
+    autoBlacklistOnBan: true,
+};
+/** Normalize a raw moderation-rules list (DB JSON or `.gittensory.yml`) into a validated, de-duplicated list
+ *  of known rule types. Never throws: an unknown/malformed entry is dropped with a warning, matching the
+ *  normalize-with-warnings shape every other settings list in this codebase already uses. */
+export function normalizeModerationRules(input) {
+    const warnings = [];
+    if (input === undefined || input === null)
+        return { rules: [], warnings };
+    if (!Array.isArray(input)) {
+        warnings.push("moderationRules must be a list of rule type strings; ignoring it.");
+        return { rules: [], warnings };
+    }
+    const rules = [];
+    const seen = new Set();
+    for (const [index, raw] of input.entries()) {
+        if (typeof raw !== "string" || !ALL_MODERATION_RULE_TYPES.includes(raw)) {
+            warnings.push(`moderationRules[${index}] is not a recognized rule type (expected one of ${ALL_MODERATION_RULE_TYPES.join(", ")}); ignoring it.`);
+            continue;
+        }
+        const rule = raw;
+        if (seen.has(rule))
+            continue;
+        seen.add(rule);
+        rules.push(rule);
+    }
+    return { rules, warnings };
+}
+/** Normalize a raw moderation label value: empty/whitespace-only collapses to undefined (falls back to the
+ *  caller's default), overlong is truncated. Never throws. Mirrors blacklistLabel/contributorCapLabel's
+ *  shape, minus the explicit-null-means-"no label" case those close-coupled labels use -- a moderation label
+ *  is always applied when the tier is reached, never suppressible to "no label at all". */
+export function normalizeModerationLabel(input) {
+    if (typeof input !== "string")
+        return undefined;
+    const trimmed = input.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    return trimmed.slice(0, MAX_LABEL_CHARS);
+}
+/** Effective rule set for one repo: an explicit per-repo override REPLACES the global list entirely (not a
+ *  union) -- a repo opting out of counting review-nag toward the shared tally, for example, must be able to
+ *  do so without also losing the ability to opt out of the others. Absent/undefined override ⇒ inherit the
+ *  global list unchanged. */
+export function resolveEffectiveModerationRules(globalRules, perRepoOverride) {
+    return perRepoOverride ? [...perRepoOverride] : [...globalRules];
+}
+/** Whether the WHOLE moderation layer runs for one repo: the global master switch is authoritative;
+ *  `off` lets a repo opt out while the global layer is enabled, and `enabled`/`inherit` both require the
+ *  global switch to be on. */
+export function resolveModerationGateEnabled(globalEnabled, gateMode) {
+    if (!globalEnabled)
+        return false;
+    if (gateMode === "off")
+        return false;
+    return true;
+}
+/** Pure escalation decision: given the actor's TOTAL violation count (including the one that just fired,
+ *  already recorded by the caller) and the configured ban threshold, which tier applies. A non-positive
+ *  threshold (malformed config) can never be reached by a real count, so it degrades to "always banned once
+ *  any violation exists" rather than throwing -- still a safe, non-silent failure mode for a misconfigured
+ *  threshold, not a crash. */
+export function moderationTierForViolationCount(count, banThreshold) {
+    if (count <= 0)
+        return "none";
+    if (count >= banThreshold)
+        return "banned";
+    return "warning";
+}

package/dist/settings/pr-type-label.d.ts

@@ -0,0 +1,70 @@
+import type { LinkedIssueLabelPropagationConfig, PrTypeLabelSet } from "../types/manifest-deps-types.js";
+export type { PrTypeLabelSet } from "../types/manifest-deps-types.js";
+/** The gittensor: namespace Gittensor itself uses -- an EXAMPLE default config, not an engine
+ *  assumption (#label-modularity): a self-hoster's `typeLabels` fully replaces the category set these
+ *  keys are drawn from. The built-in categories are mutually exclusive by default (see
+ *  `resolvePrTypeLabel`'s `removeLabels`) unless a propagation mapping is explicitly additive. */
+export declare const DEFAULT_TYPE_LABELS: PrTypeLabelSet;
+export declare const MAX_TYPE_LABEL_CATEGORIES = 32;
+export declare const MAX_TYPE_LABEL_NAME_LENGTH = 50;
+/** feature ONLY for substantial new functionality: a feat/feature prefix plus a concrete add/support/enable
+ *  action, with small recognition/classification/cleanup-style work downgraded to bug/work. EVERYTHING else —
+ *  fix, test, docs, chore, refactor, perf, ci, build, style, revert — is bug. */
+export declare function deriveKindFromTitle(title: string | undefined): "bug" | "feature";
+/** Defaults-fill a per-repo `typeLabels` override (config-as-code), generic over an arbitrary set of
+ *  categories (#label-modularity): every key of `DEFAULT_TYPE_LABELS` (the built-in bug/feature/
+ *  priority categories) is taken independently from `input` when it is a non-empty string, else falls
+ *  back to the corresponding built-in default — so a repo can override just one built-in label name
+ *  (e.g. only `priority`) and keep the others default. Any EXTRA key present in `input` beyond the
+ *  built-in set (a self-hoster's own custom category, e.g. `security`) is included verbatim when
+ *  valid, up to `MAX_TYPE_LABEL_CATEGORIES` total categories and GitHub's 50-character label-name
+ *  limit; there is no built-in default for it to fall back to, so an invalid extra-category value is
+ *  dropped entirely (warned, not defaulted) rather than silently defaulted. A non-object input yields
+ *  the full default set; omitted is normal (no warning), present-but-wrong-shaped warns. An input that
+ *  IS a valid object but has zero own keys (`{}`) also yields the full default set here — this
+ *  function only ever defaults-fills or validates a COMPLETE settings value (the DB-persisted set, or
+ *  a from-scratch construction); `resolveEffectiveSettings` (focus-manifest.ts) is what gives a
+ *  manifest's *literal* `typeLabels: {}` its own distinct "deliberately zero categories" meaning,
+ *  since collapsing that here would also flip every legacy `type_labels_json = '{}'` DB row (the SQL
+ *  column's own default, predating any explicit customization) from full defaults to zero labels —
+ *  the exact behavior change #priority-linked-issue-gate's migration promised existing repos would
+ *  never see. Mirrors `normalizeCommandAuthorizationPolicy`'s defaults-fill pattern
+ *  (`src/settings/command-authorization.ts`). */
+export declare function normalizeTypeLabelSet(input: unknown, warnings: string[]): PrTypeLabelSet;
+/** The pure decision `resolvePrTypeLabel` returns: which label(s) to apply, which configured
+ *  type-label-set members to remove for mutual exclusivity, and why. */
+export type PrTypeLabelDecision = {
+    applyLabels: string[];
+    removeLabels: string[];
+    source: "propagation_exclusive" | "propagation_additive" | "title";
+};
+/**
+ * Resolve the TYPE label decision for a PR.
+ *  1. Linked-issue label PROPAGATION (config-driven, #priority-linked-issue-gate): when enabled, the
+ *     LAST configured EXCLUSIVE mapping whose `issueLabel` appears (case-insensitively) among the
+ *     ALREADY-FETCHED `linkedIssueLabels` wins (#5385 -- declare exclusive mappings in ascending
+ *     precedence order). This is the ONLY way a label like `gittensor:priority`
+ *     can ever be chosen — this function does no I/O and never infers it from title, changed files,
+ *     AI output, or PR labels; the caller must fetch `linkedIssueLabels` itself (see
+ *     `fetchLinkedIssueLabelsForPropagation` in `review/linked-issue-label-propagation-fetch.ts`).
+ *     - `removeOtherTypeLabels: true` (exclusive) — the mapped label REPLACES the type label,
+ *       exactly like today's bug/feature/priority classification (used for `gittensor:priority`).
+ *     - `removeOtherTypeLabels: false` (additive) — the mapped label is applied ALONGSIDE the
+ *       normal title-based bug/feature label, which is left untouched (e.g. a generic
+ *       `customer:vip` → `triage:vip` triage marker that has nothing to do with bug/feature/priority).
+ *  2. Otherwise, feature (feat/feature) / bug (everything else) by the conventional-commit title prefix
+ *     -- ONLY when `labels` actually has a name registered for that built-in category; a configured set
+ *     that omits `bug`/`feature` entirely (a self-hoster who only wants custom, propagation-driven
+ *     categories, or an explicit `typeLabels: {}` resolved to zero categories) applies nothing for that
+ *     branch rather than inventing a label name (#label-modularity).
+ * `removeLabels` is always "every member of the configured type-label set that isn't one of
+ * `applyLabels`" — generic and total over however many categories are configured, and safe even if a
+ * misconfigured additive mapping's `prLabel` happens to collide with a type-label-set name (it is
+ * excluded from removal since it is also being applied). Pure + total.
+ */
+export declare function resolvePrTypeLabel(input: {
+    title: string | undefined;
+    linkedIssueLabels?: string[] | undefined;
+    labels?: PrTypeLabelSet | undefined;
+    propagation?: LinkedIssueLabelPropagationConfig | undefined;
+}): PrTypeLabelDecision;

package/dist/settings/pr-type-label.js

@@ -0,0 +1,149 @@
+/** The gittensor: namespace Gittensor itself uses -- an EXAMPLE default config, not an engine
+ *  assumption (#label-modularity): a self-hoster's `typeLabels` fully replaces the category set these
+ *  keys are drawn from. The built-in categories are mutually exclusive by default (see
+ *  `resolvePrTypeLabel`'s `removeLabels`) unless a propagation mapping is explicitly additive. */
+export const DEFAULT_TYPE_LABELS = {
+    bug: "gittensor:bug",
+    feature: "gittensor:feature",
+    priority: "gittensor:priority",
+};
+export const MAX_TYPE_LABEL_CATEGORIES = 32;
+export const MAX_TYPE_LABEL_NAME_LENGTH = 50;
+const FEATURE_TITLE_ACTION_RE = /\b(add|adds|added|create|creates|created|enable|enables|enabled|implement|implements|implemented|integrate|integrates|integrated|introduce|introduces|introduced|launch|launches|launched|support|supports|supported|wire|wires|wired)\b/i;
+const FEATURE_TITLE_DOWNGRADE_RE = /\b(avoid|block|bug|bugfix|cache|classify|classifies|classifying|cleanup|clean-up|clean up|detect|detects|detecting|docs?|fix|format|guard|lint|normalize|recognize|recognizes|recognizing|refactor|regression|rename|test|tests|testing|tighten|typo)\b/i;
+/** feature ONLY for substantial new functionality: a feat/feature prefix plus a concrete add/support/enable
+ *  action, with small recognition/classification/cleanup-style work downgraded to bug/work. EVERYTHING else —
+ *  fix, test, docs, chore, refactor, perf, ci, build, style, revert — is bug. */
+export function deriveKindFromTitle(title) {
+    const normalized = (title ?? "").trim();
+    const match = /^([a-zA-Z]+)/.exec(normalized);
+    const type = match?.[1]?.toLowerCase();
+    if (type !== "feat" && type !== "feature")
+        return "bug";
+    const subject = normalized.replace(/^[a-zA-Z]+(?:\([^)]*\))?:?\s*/, "");
+    if (!FEATURE_TITLE_ACTION_RE.test(subject))
+        return "bug";
+    return FEATURE_TITLE_DOWNGRADE_RE.test(subject) ? "bug" : "feature";
+}
+/** Defaults-fill a per-repo `typeLabels` override (config-as-code), generic over an arbitrary set of
+ *  categories (#label-modularity): every key of `DEFAULT_TYPE_LABELS` (the built-in bug/feature/
+ *  priority categories) is taken independently from `input` when it is a non-empty string, else falls
+ *  back to the corresponding built-in default — so a repo can override just one built-in label name
+ *  (e.g. only `priority`) and keep the others default. Any EXTRA key present in `input` beyond the
+ *  built-in set (a self-hoster's own custom category, e.g. `security`) is included verbatim when
+ *  valid, up to `MAX_TYPE_LABEL_CATEGORIES` total categories and GitHub's 50-character label-name
+ *  limit; there is no built-in default for it to fall back to, so an invalid extra-category value is
+ *  dropped entirely (warned, not defaulted) rather than silently defaulted. A non-object input yields
+ *  the full default set; omitted is normal (no warning), present-but-wrong-shaped warns. An input that
+ *  IS a valid object but has zero own keys (`{}`) also yields the full default set here — this
+ *  function only ever defaults-fills or validates a COMPLETE settings value (the DB-persisted set, or
+ *  a from-scratch construction); `resolveEffectiveSettings` (focus-manifest.ts) is what gives a
+ *  manifest's *literal* `typeLabels: {}` its own distinct "deliberately zero categories" meaning,
+ *  since collapsing that here would also flip every legacy `type_labels_json = '{}'` DB row (the SQL
+ *  column's own default, predating any explicit customization) from full defaults to zero labels —
+ *  the exact behavior change #priority-linked-issue-gate's migration promised existing repos would
+ *  never see. Mirrors `normalizeCommandAuthorizationPolicy`'s defaults-fill pattern
+ *  (`src/settings/command-authorization.ts`). */
+export function normalizeTypeLabelSet(input, warnings) {
+    if (input === undefined)
+        return { ...DEFAULT_TYPE_LABELS };
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        warnings.push("settings.typeLabels must be an object; using default label names.");
+        return { ...DEFAULT_TYPE_LABELS };
+    }
+    const record = input;
+    const keys = new Set([...Object.keys(DEFAULT_TYPE_LABELS), ...Object.keys(record)]);
+    const result = {};
+    for (const key of keys) {
+        const value = record[key];
+        const wouldAddCategory = result[key] === undefined;
+        if (wouldAddCategory && Object.keys(result).length >= MAX_TYPE_LABEL_CATEGORIES) {
+            if (value !== undefined)
+                warnings.push(`settings.typeLabels has more than ${MAX_TYPE_LABEL_CATEGORIES} categories; ignoring ${key}.`);
+            continue;
+        }
+        const builtInDefault = DEFAULT_TYPE_LABELS[key];
+        if (typeof value === "string" && value.trim().length > 0 && value.trim().length <= MAX_TYPE_LABEL_NAME_LENGTH) {
+            result[key] = value.trim();
+            continue;
+        }
+        if (value !== undefined) {
+            const reason = typeof value === "string" && value.trim().length > MAX_TYPE_LABEL_NAME_LENGTH ? `a non-empty string no longer than ${MAX_TYPE_LABEL_NAME_LENGTH} characters` : "a non-empty string";
+            warnings.push(builtInDefault !== undefined
+                ? `settings.typeLabels.${key} must be ${reason}; using the default "${builtInDefault}".`
+                : `settings.typeLabels.${key} must be ${reason}; ignoring it.`);
+        }
+        // Reached for BOTH an invalid present value and an absent one -- a built-in category (bug/feature/
+        // priority) always has a default to fall back to; an unknown custom category does not, so it is
+        // dropped entirely (warned above when it was present-but-invalid, silently absent when never named).
+        if (builtInDefault !== undefined)
+            result[key] = builtInDefault;
+    }
+    return result;
+}
+/**
+ * Resolve the TYPE label decision for a PR.
+ *  1. Linked-issue label PROPAGATION (config-driven, #priority-linked-issue-gate): when enabled, the
+ *     LAST configured EXCLUSIVE mapping whose `issueLabel` appears (case-insensitively) among the
+ *     ALREADY-FETCHED `linkedIssueLabels` wins (#5385 -- declare exclusive mappings in ascending
+ *     precedence order). This is the ONLY way a label like `gittensor:priority`
+ *     can ever be chosen — this function does no I/O and never infers it from title, changed files,
+ *     AI output, or PR labels; the caller must fetch `linkedIssueLabels` itself (see
+ *     `fetchLinkedIssueLabelsForPropagation` in `review/linked-issue-label-propagation-fetch.ts`).
+ *     - `removeOtherTypeLabels: true` (exclusive) — the mapped label REPLACES the type label,
+ *       exactly like today's bug/feature/priority classification (used for `gittensor:priority`).
+ *     - `removeOtherTypeLabels: false` (additive) — the mapped label is applied ALONGSIDE the
+ *       normal title-based bug/feature label, which is left untouched (e.g. a generic
+ *       `customer:vip` → `triage:vip` triage marker that has nothing to do with bug/feature/priority).
+ *  2. Otherwise, feature (feat/feature) / bug (everything else) by the conventional-commit title prefix
+ *     -- ONLY when `labels` actually has a name registered for that built-in category; a configured set
+ *     that omits `bug`/`feature` entirely (a self-hoster who only wants custom, propagation-driven
+ *     categories, or an explicit `typeLabels: {}` resolved to zero categories) applies nothing for that
+ *     branch rather than inventing a label name (#label-modularity).
+ * `removeLabels` is always "every member of the configured type-label set that isn't one of
+ * `applyLabels`" — generic and total over however many categories are configured, and safe even if a
+ * misconfigured additive mapping's `prLabel` happens to collide with a type-label-set name (it is
+ * excluded from removal since it is also being applied). Pure + total.
+ */
+export function resolvePrTypeLabel(input) {
+    const labels = input.labels ?? DEFAULT_TYPE_LABELS;
+    const isRealLabel = (label) => typeof label === "string" && label.length > 0;
+    const typeLabelSet = Object.values(labels).filter(isRealLabel).filter((label) => label.length <= MAX_TYPE_LABEL_NAME_LENGTH).slice(0, MAX_TYPE_LABEL_CATEGORIES);
+    const titleLabel = labels[deriveKindFromTitle(input.title)];
+    const decide = (applyLabels, source) => {
+        const apply = [...new Set(applyLabels.filter(isRealLabel))];
+        return { applyLabels: apply, removeLabels: typeLabelSet.filter((label) => !apply.includes(label)), source };
+    };
+    if (input.propagation?.enabled) {
+        const wanted = new Set((input.linkedIssueLabels ?? []).map((label) => label.toLowerCase()));
+        // Collect EVERY mapping the linked issue's labels satisfy, not just the first. An exclusive mapping
+        // (removeOtherTypeLabels: true -- e.g. bug/feature, genuinely mutually-exclusive categories) lets the
+        // LAST-configured match win, not the first (#5385 fix -- was first-match-wins, which meant a linked issue
+        // carrying BOTH gittensor:bug and gittensor:feature always resolved to bug, the lower-value label, purely
+        // because bug is declared before feature in `.gittensory.yml`). Operators must declare exclusive mappings
+        // in ASCENDING precedence order (lowest-value category first, e.g. bug then feature) so the last match
+        // encountered while iterating is the highest-precedence one that actually applies -- this mirrors the
+        // repo's own default mapping order, which is already bug/feature/priority (ascending multiplier value).
+        // An additive mapping (e.g. priority -- a maintainer-hand-picked reward tag that coexists WITH whichever
+        // type already applies, not a type of its own) must compose with that winner instead of being skipped just
+        // because an earlier mapping in the array already matched. Before the original #priority-linked-issue-gate
+        // composition fix, an additive match was unreachable whenever the SAME linked issue also carried a label an
+        // earlier (exclusive) mapping matched -- the overwhelmingly common case for gittensor:priority, which is
+        // applied ALONGSIDE gittensor:bug/gittensor:feature on the issue, never instead of it.
+        let exclusiveMatch;
+        const additiveMatches = [];
+        for (const mapping of input.propagation.mappings) {
+            if (!wanted.has(mapping.issueLabel.toLowerCase()))
+                continue;
+            if (mapping.removeOtherTypeLabels)
+                exclusiveMatch = mapping;
+            else
+                additiveMatches.push(mapping);
+        }
+        if (exclusiveMatch || additiveMatches.length > 0) {
+            const applyLabels = [exclusiveMatch ? exclusiveMatch.prLabel : titleLabel, ...additiveMatches.map((mapping) => mapping.prLabel)];
+            return decide(applyLabels, exclusiveMatch ? "propagation_exclusive" : "propagation_additive");
+        }
+    }
+    return decide([titleLabel], "title");
+}

package/dist/signals/change-guardrail.d.ts

@@ -0,0 +1,49 @@
+export declare function canonicalize(value: string): string;
+/** True if `glob` has more wildcard GROUPS than can be safely compiled to a RegExp without risking catastrophic
+ *  backtracking (see the MAX_GLOB_WILDCARD_GROUPS rationale above). Exported so any OTHER glob-accepting config
+ *  surface (e.g. focus-manifest.ts's contentLane.*Glob parsing) can reject an over-complex glob using the SAME
+ *  predicate globToRegExp itself enforces — a caller with its own, independently-counted threshold could accept
+ *  a glob globToRegExp then silently compiles to NEVER_MATCHES, configuring a lane that can never activate. */
+export declare function hasUnsafeWildcardCount(glob: string): boolean;
+/** Convert a path glob (`*` matches within a segment, `**` matches across `/`) to an anchored RegExp. The
+ *  glob is canonicalized first, so matching is case-insensitive against a canonicalized path. Exported for
+ *  reuse anywhere a maintainer-supplied path pattern needs compiling — never compile a raw regex string from
+ *  config (ReDoS risk); this linear-time glob compiler is the one safe path pattern this codebase uses.
+ *
+ *  An over-complex glob (see MAX_GLOB_WILDCARD_GROUPS) short-circuits to NEVER_MATCHES instead of being compiled —
+ *  this function never returns a RegExp that risks catastrophic backtracking on .test(), for any input. */
+export declare function globToRegExp(glob: string): RegExp;
+/**
+ * True if `path` matches any of the globs (`*` within a segment, `**` across `/`), case-insensitively. A glob
+ * with more wildcards than can be safely compiled (see hasUnsafeWildcardCount) is treated as matching EVERY
+ * path — fail SAFE TOWARD GUARDING, mirroring isGuardrailHit's own "unknown ⇒ treat as a hit" philosophy (an
+ * over-complex guardrail glob still forces manual review) rather than the NEVER_MATCHES default globToRegExp
+ * itself falls back to, which would silently disable the maintainer's intended protection — the worse failure
+ * mode for a safety guardrail specifically (see globToRegExp's own docstring for why NEVER_MATCHES is still the
+ * right default for globToRegExp as a general-purpose compiler).
+ */
+export declare function matchesAny(path: string, globs: string[]): boolean;
+/**
+ * The changed paths (if any) that trip a hard guardrail. A non-empty result means the PR touches a guarded
+ * path and MUST fall through to a human — gittensory may neither auto-merge nor auto-close it. Pure.
+ */
+export declare function changedPathsHittingGuardrail(changedPaths: string[], hardGuardrailGlobs: string[]): string[];
+export type GuardrailPathMatch = {
+    path: string;
+    glob: string;
+};
+/**
+ * Structured guardrail match details for public review output + audit logs. Over-complex globs preserve the
+ * same fail-safe direction as {@link matchesAny}: they match every non-empty path rather than silently disabling
+ * a maintainer's guardrail. Unknown changed paths are represented by {@link isGuardrailHit}'s boolean path only,
+ * so callers can say "paths unavailable" without inventing a fake path.
+ */
+export declare function guardrailPathMatches(changedPaths: string[], hardGuardrailGlobs: string[]): GuardrailPathMatch[];
+/**
+ * Whether a PR's diff trips a hard guardrail — the BOOLEAN form shared by the disposition (held for owner
+ * review) and the public comment (so the headline reads "held", not "safe to merge"). FAIL-SAFE on unknown
+ * paths (#1062): when guardrails ARE configured but the changed-file set is empty (the cache is not yet / no
+ * longer populated), we cannot prove the PR avoids a guarded path, so treat it as a hit. No guardrails
+ * configured ⇒ never a hit. Pure.
+ */
+export declare function isGuardrailHit(changedPaths: string[], hardGuardrailGlobs: string[]): boolean;