@loopover/engine 1.0.0

package/dist/scoring/types.d.ts

@@ -0,0 +1,131 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type RepoTimeDecayOverrides = {
+    gracePeriodHours?: number | null | undefined;
+    sigmoidMidpointDays?: number | null | undefined;
+    sigmoidSteepness?: number | null | undefined;
+    minMultiplier?: number | null | undefined;
+};
+export type RegistryRepoConfig = {
+    repo: string;
+    emissionShare: number;
+    issueDiscoveryShare: number;
+    labelMultipliers: Record<string, number>;
+    trustedLabelPipeline?: boolean | null;
+    maintainerCut: number;
+    defaultLabelMultiplier?: number | null;
+    fixedBaseScore?: number | null;
+    eligibilityMode?: string | null;
+    timeDecay?: RepoTimeDecayOverrides | null;
+    raw: Record<string, JsonValue>;
+};
+export type RepositoryRecord = {
+    fullName: string;
+    owner: string;
+    name: string;
+    installationId?: number | null | undefined;
+    isInstalled: boolean;
+    isRegistered: boolean;
+    isPrivate: boolean;
+    htmlUrl?: string | null | undefined;
+    defaultBranch?: string | null | undefined;
+    registryConfig?: RegistryRepoConfig | null | undefined;
+};
+export type PullRequestRecord = {
+    repoFullName: string;
+    number: number;
+    title: string;
+    state: string;
+    authorLogin?: string | null | undefined;
+    authorAssociation?: string | null | undefined;
+    headSha?: string | null | undefined;
+    headRef?: string | null | undefined;
+    baseRef?: string | null | undefined;
+    htmlUrl?: string | null | undefined;
+    mergedAt?: string | null | undefined;
+    isDraft?: boolean | null | undefined;
+    mergeableState?: string | null | undefined;
+    reviewDecision?: string | null | undefined;
+    body?: string | null | undefined;
+    createdAt?: string | null | undefined;
+    updatedAt?: string | null | undefined;
+    closedAt?: string | null | undefined;
+    linkedIssueClaimedAt?: string | null | undefined;
+    labels: string[];
+    linkedIssues: number[];
+    slopRisk?: number | null | undefined;
+    slopBand?: string | null | undefined;
+    mergeAttemptCount?: number | null | undefined;
+    mergeBlockedSha?: string | null | undefined;
+    mergeBlockedReason?: string | null | undefined;
+    approvedHeadSha?: string | null | undefined;
+    lastRegatedAt?: string | null | undefined;
+    lastPublishedSurfaceSha?: string | null | undefined;
+    changedFiles?: string[] | undefined;
+};
+export type PullRequestReviewRecord = {
+    id: string;
+    repoFullName: string;
+    pullNumber: number;
+    reviewerLogin?: string | null | undefined;
+    state: string;
+    authorAssociation?: string | null | undefined;
+    submittedAt?: string | null | undefined;
+    payload: Record<string, JsonValue>;
+};
+export type CheckSummaryRecord = {
+    id: string;
+    repoFullName: string;
+    pullNumber?: number | null | undefined;
+    headSha?: string | null | undefined;
+    name: string;
+    status: string;
+    conclusion?: string | null | undefined;
+    startedAt?: string | null | undefined;
+    completedAt?: string | null | undefined;
+    detailsUrl?: string | null | undefined;
+    payload: Record<string, JsonValue>;
+};
+export type ScoringModelSnapshotRecord = {
+    id: string;
+    sourceKind: "raw-github" | "api" | "fallback" | "test";
+    sourceUrl: string;
+    fetchedAt: string;
+    activeModel: "current_density_model" | "pending_saturation_model" | "exponential_saturation_model" | "unknown";
+    constants: Record<string, number>;
+    programmingLanguages: Record<string, JsonValue>;
+    registrySnapshotId?: string | null | undefined;
+    warnings: string[];
+    payload: Record<string, JsonValue>;
+};
+export type ScorePreviewRecord = {
+    id: string;
+    scoringModelSnapshotId: string;
+    repoFullName: string;
+    targetType: "planned_pr" | "pull_request" | "local_diff" | "variant";
+    targetKey: string;
+    contributorLogin?: string | null | undefined;
+    input: Record<string, JsonValue>;
+    result: Record<string, JsonValue>;
+    generatedAt: string;
+};
+export type ContributorEvidenceRecord = {
+    login: string;
+    payload: Record<string, JsonValue>;
+    generatedAt: string;
+};
+export type ContributorRole = "outside_contributor" | "repo_maintainer" | "org_member" | "collaborator" | "owner" | "unknown";
+export type RoleContext = {
+    login: string;
+    repoFullName: string;
+    generatedAt: string;
+    role: ContributorRole;
+    maintainerLane: boolean;
+    normalContributorEvidenceAllowed: boolean;
+    source: "github_association" | "repo_owner_match" | "gittensor_api" | "cache" | "unknown";
+    association?: string | null | undefined;
+    reasons: string[];
+    guidance: string;
+};

package/dist/scoring/types.js

@@ -0,0 +1,7 @@
+// Local mirror of the record/type shapes `scoring/preview.ts`, `scoring/model.ts`, and
+// `scoring/pending-pr-scenarios.ts` need from the backend's `src/types.ts` and `src/signals/engine.ts`.
+// The engine package cannot import across into `src/` (see the package's own tsconfig: `rootDir: "src"`,
+// `types: []` — it stays isolated from the Cloudflare Worker/D1 ambient types the backend depends on), so
+// these shapes are duplicated here rather than imported. `src/types.ts` and `src/signals/engine.ts` stay
+// the canonical source; keep this file in sync with them by hand.
+export {};

package/dist/settings/auto-close-exempt.d.ts

@@ -0,0 +1,10 @@
+/** Normalize a raw exempt-logins value (DB JSON or `.gittensory.yml`) into a validated, de-duplicated list of
+ *  GitHub logins. Never throws: malformed entries are dropped with a warning. De-dup is case-insensitive (the
+ *  FIRST occurrence's casing is kept). */
+export declare function normalizeAutoCloseExemptLogins(input: unknown): {
+    logins: string[];
+    warnings: string[];
+};
+/** Case-insensitive membership check against the resolved exempt-logins list. Absent/empty list ⇒ never exempt
+ *  (the safe default — an unconfigured repo exempts no one beyond the standing owner/admin/bot rule). */
+export declare function isAutoCloseExempt(login: string | null | undefined, exemptLogins: readonly string[] | undefined): boolean;

package/dist/settings/auto-close-exempt.js

@@ -0,0 +1,58 @@
+// Shared repo-scoped exemption list (#2463) for gittensory's deterministic anti-abuse auto-close/throttle
+// mechanisms — currently the review-nag cooldown; intended to be reused by the per-contributor open-item cap
+// (#2270) once that lands, rather than each feature growing its own duplicate whitelist. A maintainer-named
+// GitHub login here is NEVER throttled or closed by either mechanism, on top of the standing owner/admin/
+// automation-bot exemption every such mechanism already honors. Config-driven and layered the same as other
+// settings (`.gittensory.yml` > DB), never hard-coded for any repo. Mirrors contributor-blacklist.ts's shape
+// (normalize → validated list + warnings), minus the reason/evidence metadata a ban carries that an exemption
+// doesn't need.
+// A trailing `[bot]` is a real, common GitHub App-actor login shape (e.g. `dependabot[bot]`, `sentry[bot]`) --
+// this is exactly the kind of third-party automation identity a maintainer needs to exempt (a repo-specific bot
+// integration the hardcoded, install-wide well-known-bot set in agent-actions.ts has no way to know about), so
+// the base GitHub-login pattern (1-39 chars, alphanumeric/single-hyphens) is extended with an optional literal
+// `[bot]` suffix rather than rejecting every bot-shaped login outright.
+const GITHUB_LOGIN = /^[a-zA-Z0-9](?:[a-zA-Z0-9]|-(?=[a-zA-Z0-9])){0,38}(?:\[bot\])?$/;
+const MAX_ENTRIES = 500;
+/** Normalize a raw exempt-logins value (DB JSON or `.gittensory.yml`) into a validated, de-duplicated list of
+ *  GitHub logins. Never throws: malformed entries are dropped with a warning. De-dup is case-insensitive (the
+ *  FIRST occurrence's casing is kept). */
+export function normalizeAutoCloseExemptLogins(input) {
+    const warnings = [];
+    if (input === undefined || input === null)
+        return { logins: [], warnings };
+    if (!Array.isArray(input)) {
+        warnings.push("autoCloseExemptLogins must be a list of GitHub logins; ignoring it.");
+        return { logins: [], warnings };
+    }
+    const logins = [];
+    const seen = new Set();
+    for (const [index, raw] of input.entries()) {
+        if (logins.length >= MAX_ENTRIES) {
+            warnings.push(`autoCloseExemptLogins is capped at ${MAX_ENTRIES} entries; dropping the rest.`);
+            break;
+        }
+        if (typeof raw !== "string") {
+            warnings.push(`autoCloseExemptLogins[${index}] must be a string login; ignoring it.`);
+            continue;
+        }
+        const login = raw.trim();
+        if (!GITHUB_LOGIN.test(login)) {
+            warnings.push(`autoCloseExemptLogins[${index}] is not a valid GitHub login; ignoring it.`);
+            continue;
+        }
+        const key = login.toLowerCase();
+        if (seen.has(key))
+            continue; // first occurrence wins
+        seen.add(key);
+        logins.push(login);
+    }
+    return { logins, warnings };
+}
+/** Case-insensitive membership check against the resolved exempt-logins list. Absent/empty list ⇒ never exempt
+ *  (the safe default — an unconfigured repo exempts no one beyond the standing owner/admin/bot rule). */
+export function isAutoCloseExempt(login, exemptLogins) {
+    if (!login)
+        return false;
+    const lower = login.toLowerCase();
+    return (exemptLogins ?? []).some((entry) => entry.toLowerCase() === lower);
+}

package/dist/settings/autonomy.d.ts

@@ -0,0 +1,33 @@
+import type { AgentActionClass, AutoMaintainPolicy, AutonomyLevel, AutonomyPolicy } from "../types/manifest-deps-types.js";
+export declare const AUTONOMY_LEVELS: readonly ["observe", "auto_with_approval", "auto"];
+export declare const AGENT_ACTION_CLASSES: readonly ["review", "request_changes", "approve", "merge", "close", "label", "review_state_label", "update_branch", "assign"];
+export declare const DEFAULT_AUTONOMY_LEVEL: AutonomyLevel;
+/**
+ * Resolve the configured autonomy level for one action class on a repo. THE single gate the action layer
+ * (#778) consults before any write action. Deny-by-default: an unset (or malformed) action class is
+ * `observe` — gittensory observes but never acts. Pure.
+ */
+export declare function resolveAutonomy(autonomy: AutonomyPolicy | null | undefined, actionClass: AgentActionClass): AutonomyLevel;
+/** True when the level permits the agent to actually execute the action (directly or behind an approval). */
+export declare function isActingAutonomyLevel(level: AutonomyLevel): boolean;
+/**
+ * True when a repo has opted into the agent layer at all — i.e. at least one action class has an acting
+ * autonomy level. The deny-by-default floor (every class `observe`) is NOT configured. The scheduled
+ * re-gate sweep (#777) uses this to skip repos that never asked the agent to act. Pure.
+ */
+export declare function isAgentConfigured(autonomy: AutonomyPolicy | null | undefined): boolean;
+/** True when the action must pass a human approval gate (#779) before it executes. */
+export declare function autonomyRequiresApproval(level: AutonomyLevel): boolean;
+/**
+ * Parse/validate an arbitrary value into an AutonomyPolicy: keep only known action classes mapped to known
+ * levels, drop everything else. Deny-by-default by omission. Used for the DB row, the API body, and the
+ * `.gittensory.yml` settings block. Pure.
+ */
+export declare function normalizeAutonomyPolicy(input: unknown): AutonomyPolicy;
+export declare const AUTO_MERGE_METHODS: readonly ["merge", "squash", "rebase"];
+export declare const DEFAULT_AUTO_MAINTAIN_POLICY: AutoMaintainPolicy;
+/**
+ * Parse/validate an arbitrary value into an AutoMaintainPolicy, filling the conservative defaults for any
+ * missing/invalid field. `requireApprovals` is clamped to [0, 10]. Pure.
+ */
+export declare function normalizeAutoMaintainPolicy(input: unknown): AutoMaintainPolicy;

package/dist/settings/autonomy.js

@@ -0,0 +1,80 @@
+// The graduated autonomy dial (#773), ordered least → most autonomous. Every later agent-layer phase reads
+// this BEFORE acting. `observe` is the deny-by-default floor — gittensory watches but never takes an action.
+// (#4620: `suggest`/`propose` removed -- both were 100% behaviorally identical to `observe`, see
+// AutonomyLevel's own doc comment.)
+export const AUTONOMY_LEVELS = ["observe", "auto_with_approval", "auto"];
+// The write-action classes the maintainer auto-maintain layer (#778) can take on a PR. `review_state_label`
+// (#label-scoping) is a separate class from `label`: it gates the planner's own disposition-communication
+// labels (ready-to-merge / changes-requested / manual-review / migration-collision / pending-closure /
+// new-account), independent of the anti-abuse enforcement labels (blacklist/contributor-cap/review-nag), which
+// ride on `close` instead -- see agent-actions.ts. `assign` (#3182) is its own independent class, same shape:
+// best-effort assignment of the PR's opening contributor, unrelated to merge/close/approve.
+export const AGENT_ACTION_CLASSES = ["review", "request_changes", "approve", "merge", "close", "label", "review_state_label", "update_branch", "assign"];
+// Deny-by-default: any action class with no explicit, valid level resolves to this.
+export const DEFAULT_AUTONOMY_LEVEL = "observe";
+const AUTONOMY_LEVEL_SET = new Set(AUTONOMY_LEVELS);
+/**
+ * Resolve the configured autonomy level for one action class on a repo. THE single gate the action layer
+ * (#778) consults before any write action. Deny-by-default: an unset (or malformed) action class is
+ * `observe` — gittensory observes but never acts. Pure.
+ */
+export function resolveAutonomy(autonomy, actionClass) {
+    return autonomy?.[actionClass] ?? DEFAULT_AUTONOMY_LEVEL;
+}
+/** True when the level permits the agent to actually execute the action (directly or behind an approval). */
+export function isActingAutonomyLevel(level) {
+    return level === "auto" || level === "auto_with_approval";
+}
+/**
+ * True when a repo has opted into the agent layer at all — i.e. at least one action class has an acting
+ * autonomy level. The deny-by-default floor (every class `observe`) is NOT configured. The scheduled
+ * re-gate sweep (#777) uses this to skip repos that never asked the agent to act. Pure.
+ */
+export function isAgentConfigured(autonomy) {
+    return AGENT_ACTION_CLASSES.some((actionClass) => isActingAutonomyLevel(resolveAutonomy(autonomy, actionClass)));
+}
+/** True when the action must pass a human approval gate (#779) before it executes. */
+export function autonomyRequiresApproval(level) {
+    return level === "auto_with_approval";
+}
+/**
+ * Parse/validate an arbitrary value into an AutonomyPolicy: keep only known action classes mapped to known
+ * levels, drop everything else. Deny-by-default by omission. Used for the DB row, the API body, and the
+ * `.gittensory.yml` settings block. Pure.
+ */
+export function normalizeAutonomyPolicy(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input))
+        return {};
+    const record = input;
+    const policy = {};
+    for (const actionClass of AGENT_ACTION_CLASSES) {
+        const value = record[actionClass];
+        if (typeof value === "string" && AUTONOMY_LEVEL_SET.has(value)) {
+            policy[actionClass] = value;
+        }
+    }
+    return policy;
+}
+// Auto-maintain policy (#774): how an action behaves once its autonomy level permits acting.
+export const AUTO_MERGE_METHODS = ["merge", "squash", "rebase"];
+const AUTO_MERGE_METHOD_SET = new Set(AUTO_MERGE_METHODS);
+// Conservative defaults: squash (the tidiest history) + a single human approval before any auto-merge.
+export const DEFAULT_AUTO_MAINTAIN_POLICY = { requireApprovals: 1, mergeMethod: "squash" };
+// Approvals are clamped to a sane band so a malformed config can't disable the gate (negative) or stall it.
+const MAX_REQUIRE_APPROVALS = 10;
+/**
+ * Parse/validate an arbitrary value into an AutoMaintainPolicy, filling the conservative defaults for any
+ * missing/invalid field. `requireApprovals` is clamped to [0, 10]. Pure.
+ */
+export function normalizeAutoMaintainPolicy(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input))
+        return { ...DEFAULT_AUTO_MAINTAIN_POLICY };
+    const record = input;
+    const rawApprovals = record.requireApprovals;
+    const requireApprovals = typeof rawApprovals === "number" && Number.isFinite(rawApprovals)
+        ? Math.min(MAX_REQUIRE_APPROVALS, Math.max(0, Math.trunc(rawApprovals)))
+        : DEFAULT_AUTO_MAINTAIN_POLICY.requireApprovals;
+    const rawMethod = record.mergeMethod;
+    const mergeMethod = typeof rawMethod === "string" && AUTO_MERGE_METHOD_SET.has(rawMethod) ? rawMethod : DEFAULT_AUTO_MAINTAIN_POLICY.mergeMethod;
+    return { requireApprovals, mergeMethod };
+}

package/dist/settings/command-authorization.d.ts

@@ -0,0 +1,49 @@
+import type { CommandAuthorizationRole, RepositoryCommandAuthorizationPolicy } from "../types/manifest-deps-types.js";
+export declare const DEFAULT_COMMAND_AUTHORIZATION_POLICY: RepositoryCommandAuthorizationPolicy;
+export type CommandAuthorizationDecision = {
+    authorized: boolean;
+    reason: string;
+    actorKind: "maintainer" | "author" | "none";
+    matchedRole: CommandAuthorizationRole | null;
+    allowedRoles: CommandAuthorizationRole[];
+};
+export declare function normalizeCommandAuthorizationPolicy(input: unknown): {
+    policy: RepositoryCommandAuthorizationPolicy;
+    warnings: string[];
+};
+export declare function commandAuthorizationAllowedRoles(policy: RepositoryCommandAuthorizationPolicy | null | undefined, commandName: string): CommandAuthorizationRole[];
+export declare function commandAuthorizationNeedsMinerDetection(args: {
+    policy?: RepositoryCommandAuthorizationPolicy | null | undefined;
+    commandName: string;
+    commenterLogin?: string | null | undefined;
+    commenterAssociation?: string | null | undefined;
+    pullRequestAuthorLogin?: string | null | undefined;
+}): boolean;
+export declare function evaluateCommandAuthorization(args: {
+    policy?: RepositoryCommandAuthorizationPolicy | null | undefined;
+    commandName: string;
+    commenterLogin?: string | null | undefined;
+    commenterAssociation?: string | null | undefined;
+    pullRequestAuthorLogin?: string | null | undefined;
+    minerStatus?: "confirmed" | "not_found" | "unavailable" | undefined;
+    /** #5084: required (must be `"hold"`) for a bare `pr_author` match to actually authorize a command in
+     *  {@link PR_AUTHOR_RATE_LIMITED_COMMANDS} (currently just `chat`) -- unset/`"off"` denies exactly as if
+     *  `pr_author` weren't in the allowed-roles list at all, so a repo that hasn't turned on rate limiting
+     *  never grants contributor chat access no matter what `chat`'s configured roles say. */
+    commandRateLimitPolicy?: "off" | "hold" | undefined;
+    /** #5092: ALSO required (must be `true`) for a bare `pr_author` match to authorize a command in
+     *  {@link PR_AUTHOR_RATE_LIMITED_COMMANDS} -- the per-PR rate-limit counter (`repoFullName#issueNumber#command`)
+     *  never resets or checks PR state, so without this a contributor could keep a fresh allowance forever by
+     *  reopening/reusing a closed PR or spamming cheap draft PRs. Caller-computed (e.g. `pr.state === "open" &&
+     *  !pr.isDraft`) so this function doesn't need to know GitHub's own state-string conventions. Unset/`false`
+     *  denies exactly like a missing rate-limit policy -- maintainers/collaborators are unaffected regardless
+     *  (this bounds the less-trusted pr_author tier, not already-trusted roles). */
+    pullRequestOpenAndNotDraft?: boolean | undefined;
+}): CommandAuthorizationDecision;
+export declare function summarizeCommandAuthorizationPolicy(policy: RepositoryCommandAuthorizationPolicy | null | undefined): {
+    defaultAllowed: CommandAuthorizationRole[];
+    commandOverrides: Array<{
+        command: string;
+        allowedRoles: CommandAuthorizationRole[];
+    }>;
+};

package/dist/settings/command-authorization.js

@@ -0,0 +1,222 @@
+export const DEFAULT_COMMAND_AUTHORIZATION_POLICY = {
+    default: ["maintainer", "collaborator", "confirmed_miner"],
+    commands: {
+        "queue-summary": ["maintainer", "collaborator"],
+        "confirmed-miners": ["maintainer", "collaborator"],
+        "review-now": ["maintainer", "collaborator"],
+        "needs-author": ["maintainer", "collaborator"],
+        "duplicate-clusters": ["maintainer", "collaborator"],
+        "burden-forecast": ["maintainer", "collaborator"],
+        "intake-health": ["maintainer", "collaborator"],
+        "outcome-patterns": ["maintainer", "collaborator"],
+        "noise-report": ["maintainer", "collaborator"],
+        "gate-override": ["maintainer", "collaborator"],
+        plan: ["maintainer", "collaborator"],
+        // #4595/#5084: chat is Ollama-only grounded LLM generation, a materially larger surface than ask's
+        // deterministic-only answer, so v1 started maintainer/collaborator-only. #5084 widens this to the PR's
+        // OWN author (never an arbitrary commenter on someone else's PR) -- but ONLY when commandRateLimitPolicy
+        // is "hold" for the repo, enforced in evaluateCommandAuthorization below, not just by operator convention.
+        // Explicit registration here (rather than falling through to `default`) also activates the
+        // MAINTAINER_ONLY_DEFAULT_COMMANDS clamp in normalizeCommandRoleList, so a self-hoster can't yml
+        // themselves into "any confirmed_miner" or similar widening beyond what's shipped here.
+        chat: ["maintainer", "collaborator", "pr_author"],
+        // #1960 PR control-surface verbs. "review" is deliberately widenable to confirmed_miner (same self-rerun
+        // precedent already applied to review-now, #824) — a confirmed miner may re-trigger review on their own PR.
+        // The rest (pause/resume/resolve/configuration/explain) are conservative maintainer/collaborator-only
+        // defaults out of the box; a maintainer who wants to widen them can do so via commandAuthorization overrides.
+        review: ["maintainer", "collaborator", "confirmed_miner"],
+        pause: ["maintainer", "collaborator"],
+        resume: ["maintainer", "collaborator"],
+        resolve: ["maintainer", "collaborator"],
+        configuration: ["maintainer", "collaborator"],
+        explain: ["maintainer", "collaborator"],
+        // #4195 (part of the #4189 E2E-test-generation epic): deliberately NARROWER than every command above --
+        // "maintainer" ONLY, excluding "collaborator" and "confirmed_miner". This command can write real content
+        // (a generated test) attributed to the PR; a repo could grant a contributor/miner collaborator-level
+        // push access, and that tier must not be able to invoke test generation for their own scored PR (the
+        // exact loophole a click-to-generate button would otherwise open). The existing
+        // `maintainer_command_requires_maintainer` guard below already denies the PR's own author when they
+        // don't independently hold the `maintainer` role, so no bespoke pr_author check is needed here.
+        "generate-tests": ["maintainer"],
+    },
+};
+const COMMAND_AUTHORIZATION_ROLES = new Set(["maintainer", "collaborator", "pr_author", "confirmed_miner"]);
+// Roles that may remain configured on a maintainer-only command. The clamp drops only the spoofable
+// plain `pr_author` role; `confirmed_miner` survives so a detected miner can self-trigger reruns (#824).
+const MAINTAINER_COMMAND_AUTHORIZATION_ROLES = new Set(["maintainer", "collaborator", "confirmed_miner"]);
+const MAINTAINER_ONLY_DEFAULT_COMMANDS = new Set(Object.keys(DEFAULT_COMMAND_AUTHORIZATION_POLICY.commands));
+// #5084: commands where a `pr_author` match is only actually granted when commandRateLimitPolicy is "hold" for
+// the repo -- checked in evaluateCommandAuthorization. Currently just `chat` (Ollama-only LLM generation);
+// deliberately a narrow, explicit allowlist rather than inferring this from isAiCostBearingCommand, so widening
+// it to another command later is a deliberate one-line addition, not an implicit side effect of an unrelated set.
+const PR_AUTHOR_RATE_LIMITED_COMMANDS = new Set(["chat"]);
+export function normalizeCommandAuthorizationPolicy(input) {
+    const warnings = [];
+    if (!isRecord(input)) {
+        if (input !== null && input !== undefined)
+            warnings.push("commandAuthorization must be an object; using secure defaults.");
+        return { policy: clonePolicy(DEFAULT_COMMAND_AUTHORIZATION_POLICY), warnings };
+    }
+    const defaultRoles = normalizeRoleList(input.default, DEFAULT_COMMAND_AUTHORIZATION_POLICY.default, "default", warnings);
+    const commands = { ...DEFAULT_COMMAND_AUTHORIZATION_POLICY.commands };
+    if (input.commands !== undefined) {
+        if (isRecord(input.commands)) {
+            for (const [command, roles] of Object.entries(input.commands)) {
+                const commandName = command.trim().toLowerCase();
+                if (!/^[a-z][a-z-]{0,63}$/.test(commandName)) {
+                    warnings.push(`Ignored malformed command authorization key: ${command.slice(0, 64)}`);
+                    continue;
+                }
+                commands[commandName] = normalizeCommandRoleList(commandName, normalizeRoleList(roles, defaultRoles, commandName, warnings), warnings);
+            }
+        }
+        else {
+            warnings.push("commandAuthorization.commands must be an object; using command defaults.");
+        }
+    }
+    return { policy: { default: defaultRoles, commands }, warnings };
+}
+export function commandAuthorizationAllowedRoles(policy, commandName) {
+    const normalized = normalizeCommandAuthorizationPolicy(policy).policy;
+    // Policy command keys are stored normalized (trimmed + lowercased) by normalizeCommandAuthorizationPolicy,
+    // so the lookup MUST normalize the probe too. A raw mixed-case name (e.g. "Gate-Override") otherwise misses
+    // its restrictive override and silently falls back to the permissive default — under-stating the restriction.
+    const key = normalizeCommandName(commandName);
+    const commandRoles = Object.hasOwn(normalized.commands, key) ? normalized.commands[key] : undefined;
+    return dedupeRoles(commandRoles ?? normalized.default);
+}
+function normalizeCommandName(commandName) {
+    return commandName.trim().toLowerCase();
+}
+export function commandAuthorizationNeedsMinerDetection(args) {
+    const allowedRoles = commandAuthorizationAllowedRoles(args.policy, args.commandName);
+    if (!allowedRoles.includes("confirmed_miner"))
+        return false;
+    if (!isSameLogin(args.commenterLogin, args.pullRequestAuthorLogin))
+        return false;
+    const rolesWithoutMiner = actorRoles({ ...args, minerStatus: undefined });
+    return !rolesWithoutMiner.some((role) => allowedRoles.includes(role));
+}
+export function evaluateCommandAuthorization(args) {
+    const allowedRoles = commandAuthorizationAllowedRoles(args.policy, args.commandName);
+    const roles = actorRoles(args);
+    const matchedRole = roles.find((role) => allowedRoles.includes(role)) ?? null;
+    const prAuthorGatedCommand = matchedRole === "pr_author" && PR_AUTHOR_RATE_LIMITED_COMMANDS.has(normalizeCommandName(args.commandName));
+    if (prAuthorGatedCommand && args.commandRateLimitPolicy !== "hold") {
+        return { authorized: false, reason: "pr_author_requires_rate_limiting", actorKind: "author", matchedRole: null, allowedRoles };
+    }
+    if (prAuthorGatedCommand && args.pullRequestOpenAndNotDraft !== true) {
+        return { authorized: false, reason: "pr_author_requires_open_pr", actorKind: "author", matchedRole: null, allowedRoles };
+    }
+    if (matchedRole) {
+        return {
+            authorized: true,
+            reason: authorizationReason(matchedRole),
+            actorKind: matchedRole === "maintainer" || matchedRole === "collaborator" ? "maintainer" : "author",
+            matchedRole,
+            allowedRoles,
+        };
+    }
+    const ownPrAuthor = isSameLogin(args.commenterLogin, args.pullRequestAuthorLogin);
+    if (ownPrAuthor && allowedRoles.includes("confirmed_miner")) {
+        return {
+            authorized: false,
+            reason: args.minerStatus === "unavailable" || !args.minerStatus ? "miner_detection_unavailable" : "pr_author_not_confirmed_miner",
+            actorKind: "author",
+            matchedRole: null,
+            allowedRoles,
+        };
+    }
+    if (ownPrAuthor && MAINTAINER_ONLY_DEFAULT_COMMANDS.has(normalizeCommandName(args.commandName)) && allowedRoles.every((role) => role === "maintainer" || role === "collaborator")) {
+        return { authorized: false, reason: "maintainer_command_requires_maintainer", actorKind: "author", matchedRole: null, allowedRoles };
+    }
+    return {
+        authorized: false,
+        reason: ownPrAuthor ? "command_policy_denied" : "not_maintainer_or_pr_author",
+        actorKind: ownPrAuthor ? "author" : "none",
+        matchedRole: null,
+        allowedRoles,
+    };
+}
+export function summarizeCommandAuthorizationPolicy(policy) {
+    const normalized = normalizeCommandAuthorizationPolicy(policy).policy;
+    return {
+        defaultAllowed: normalized.default,
+        commandOverrides: Object.entries(normalized.commands)
+            .map(([command, allowedRoles]) => ({ command, allowedRoles }))
+            .sort((left, right) => left.command.localeCompare(right.command)),
+    };
+}
+function normalizeCommandRoleList(commandName, roles, warnings) {
+    if (!MAINTAINER_ONLY_DEFAULT_COMMANDS.has(commandName))
+        return roles;
+    // #5084: a role also survives the clamp if it's explicitly part of THIS command's own shipped default
+    // (chat's own default now includes pr_author) -- so a maintainer restating or narrowing a command's own
+    // default via yml never gets silently mangled, while every OTHER maintainer-only command whose own default
+    // excludes pr_author still can't have it added via override (this is a per-command union, not a blanket
+    // relaxation: the clamp still can't be conjured up on generate-tests/pause/etc.).
+    /* v8 ignore next -- defensive: MAINTAINER_ONLY_DEFAULT_COMMANDS is derived from these keys, so a maintainer-only command always resolves a default list. */
+    const commandOwnDefaultRoles = DEFAULT_COMMAND_AUTHORIZATION_POLICY.commands[commandName] ?? [];
+    const allowedClampRoles = new Set([...MAINTAINER_COMMAND_AUTHORIZATION_ROLES, ...commandOwnDefaultRoles]);
+    const maintainerRoles = roles.filter((role) => allowedClampRoles.has(role));
+    if (maintainerRoles.length === roles.length)
+        return roles;
+    warnings.push(`Ignored author command authorization roles for maintainer-only command: ${commandName}.`);
+    if (maintainerRoles.length > 0)
+        return dedupeRoles(maintainerRoles);
+    const defaultRoles = DEFAULT_COMMAND_AUTHORIZATION_POLICY.commands[commandName];
+    /* v8 ignore next -- defensive: MAINTAINER_ONLY_DEFAULT_COMMANDS is derived from these keys, so a maintainer-only command always resolves a default list. */
+    return [...(defaultRoles ?? ["maintainer", "collaborator"])];
+}
+function actorRoles(args) {
+    const roles = [];
+    if (args.commenterAssociation === "OWNER" || args.commenterAssociation === "MEMBER")
+        roles.push("maintainer");
+    if (args.commenterAssociation === "COLLABORATOR")
+        roles.push("collaborator");
+    if (isSameLogin(args.commenterLogin, args.pullRequestAuthorLogin)) {
+        roles.push("pr_author");
+        if (args.minerStatus === "confirmed")
+            roles.push("confirmed_miner");
+    }
+    return roles;
+}
+function normalizeRoleList(input, fallback, label, warnings) {
+    if (!Array.isArray(input)) {
+        if (input !== undefined)
+            warnings.push(`commandAuthorization.${label} must be an array of roles; using fallback roles.`);
+        return dedupeRoles(fallback);
+    }
+    const roles = input.filter((role) => {
+        const valid = typeof role === "string" && COMMAND_AUTHORIZATION_ROLES.has(role);
+        if (!valid)
+            warnings.push(`Ignored invalid command authorization role for ${label}.`);
+        return valid;
+    });
+    if (roles.length === 0) {
+        warnings.push(`commandAuthorization.${label} had no valid roles; using fallback roles.`);
+        return dedupeRoles(fallback);
+    }
+    return dedupeRoles(roles);
+}
+function dedupeRoles(roles) {
+    return [...new Set(roles)];
+}
+function clonePolicy(policy) {
+    return { default: [...policy.default], commands: Object.fromEntries(Object.entries(policy.commands).map(([command, roles]) => [command, [...roles]])) };
+}
+function authorizationReason(role) {
+    if (role === "maintainer")
+        return "maintainer_invocation";
+    if (role === "collaborator")
+        return "collaborator_invocation";
+    if (role === "confirmed_miner")
+        return "confirmed_miner_pr_author";
+    return "allowed_pr_author";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isSameLogin(left, right) {
+    return Boolean(left && right && left.toLowerCase() === right.toLowerCase());
+}

package/dist/settings/contributor-blacklist.d.ts

@@ -0,0 +1,17 @@
+import type { ContributorBlacklistEntry } from "../types/manifest-deps-types.js";
+/** 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 declare function normalizeContributorBlacklist(input: unknown): {
+    entries: ContributorBlacklistEntry[];
+    warnings: string[];
+};
+/** 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 declare function findBlacklistEntry(login: string | null | undefined, entries: ContributorBlacklistEntry[] | undefined): ContributorBlacklistEntry | null;
+/** True iff `login` is on the resolved blacklist. */
+export declare function isAuthorBlacklisted(login: string | null | undefined, entries: ContributorBlacklistEntry[] | undefined): boolean;
+/** 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 declare function mergeContributorBlacklists(...lists: ContributorBlacklistEntry[][]): ContributorBlacklistEntry[];