@loopover/engine 1.0.0

package/dist/signals/change-guardrail.js

@@ -0,0 +1,164 @@
+// Convergence safety: the hard-guardrail path check for the auto-maintain layer (#778). Changed paths that
+// match a repo's configured hardGuardrailGlobs force MANUAL review — gittensory must never auto-merge OR
+// auto-close a PR that touches a guarded path. Ported verbatim from
+// reviewbot core/change-classifier.ts — the mechanism that prevents the awesome-claude #4196 incident class
+// (a weakened policy script auto-merging because its path wasn't guarded). Pure + dependency-free.
+// Canonicalize a path or glob so matching is case- and separator-insensitive: backslashes → `/`, drop a
+// leading `./` or `/`, and case-fold. Mirrors signals/focus-manifest `normalizePathForMatch` — without it a
+// guarded path is evaded with `.github/Workflows/` (capital W), a `./`-prefix, or a `\` separator, turning a
+// mandatory human hold on CI/policy files into an auto-merge.
+export function canonicalize(value) {
+    return value.replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "").toLowerCase();
+}
+// globToRegExp's COMPILATION is linear-time, but the COMPILED pattern's .test() can be polynomial-to-exponential
+// time on an adversarial near-miss input when MULTIPLE wildcard GROUPS chain in one glob (a "group" is one `*`
+// OR one `**` — a `**` pair compiles to a SINGLE `.*`, not two independent wildcards, so it must be counted as
+// ONE group, not two characters; see countWildcardGroups below). Both group TYPES contribute to the same danger
+// once chained — `[^/]*` groups separated by a literal that class doesn't exclude (e.g. "-", not "/") back-
+// track ambiguously, and `.*` groups back-track ambiguously EVEN when "/"-separated, since `.*` crosses `/`
+// freely. Re-benchmarked against `path` lengths GitHub can plausibly deliver via a deeply nested file path in a
+// malicious PR (both `path` and, via `.gittensory.yml`'s contentLane.*Glob fields, the glob itself can be
+// attacker-influenced in the same PR):
+//   2 wildcard groups (any mix of `*`/`**`, any arrangement): sub-second even at a wildly implausible 32,000-
+//                       char adversarial path (worst case observed: ~400ms) — quadratic, bounded, never a
+//                       realistic hang.
+//   3 wildcard groups: OVER 2 SECONDS at just ~4,000 chars for one chained-`*` shape, over 100ms at ~1,600
+//                       chars for a chained-`**` shape — already dangerous well within a plausible path length.
+//   4+ wildcard groups: confirmed catastrophic — 35 SECONDS at just 1,614 chars for 4 chained `**` groups.
+// hardGuardrailGlobs are maintainer-configured, and this compiler is also exported for reuse by other
+// maintainer-config-driven consumers (content-lane/spec-resolver.ts, whose real globs like "public/**/*.json" are
+// exactly 2 groups: this cap must stay inclusive of that legitimate shape, not just "safer than before"), so the
+// cap lives INSIDE globToRegExp itself (not just in a wrapper like matchesAny below) — every caller is
+// protected automatically rather than needing to separately remember the risk. The boundary is set at the
+// highest GROUP count proven safe by the benchmark above (2) — a boundary that itself sits inside the
+// empirically dangerous range would defeat the point of a cap.
+const MAX_GLOB_WILDCARD_GROUPS = 2;
+/** Count `*` GROUPS in `glob` — a `**` pair is ONE group (it compiles to a single `.*`, see globToRegExp), not
+ *  two. Mirrors globToRegExp's own tokenization exactly (including consuming a `**`'s trailing `/`) so the count
+ *  reflects the actual number of backtracking-capable groups the compiled RegExp will contain, not raw `*`
+ *  character count (which would double-count every globstar and reject legitimate globs like
+ *  "public/**\/*.json" — 2 real groups — as if they were 3-groups-dangerous). */
+function countWildcardGroups(glob) {
+    let count = 0;
+    for (let i = 0; i < glob.length; i += 1) {
+        if (glob.charAt(i) !== "*")
+            continue;
+        count += 1;
+        if (glob.charAt(i + 1) === "*") {
+            i += 1; // consume the second star of the "**" pair — one group, not two
+            if (glob.charAt(i + 1) === "/")
+                i += 1; // `**/` also matches zero segments, mirroring globToRegExp
+        }
+    }
+    return count;
+}
+/** 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 function hasUnsafeWildcardCount(glob) {
+    return countWildcardGroups(glob) > MAX_GLOB_WILDCARD_GROUPS;
+}
+// A RegExp that never matches any input, at any position — the safe, conservative compiled form of an
+// over-complex glob. "Never matches" (not "matches everything") is the correct default HERE because
+// globToRegExp has no context on caller intent, and a false "matches everything" would be actively wrong for a
+// non-guardrail caller (e.g. content-lane file-scope matching, where "matches everything" would misclassify
+// every changed file as a registry submission). A caller whose OWN semantics want the opposite fail direction
+// (a security guardrail, where under-protection is worse than an unnecessary hold) checks hasUnsafeWildcardCount
+// itself and overrides — see matchesAny below.
+const NEVER_MATCHES = /^(?!)$/;
+/** 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 function globToRegExp(glob) {
+    if (hasUnsafeWildcardCount(glob))
+        return NEVER_MATCHES;
+    const canonical = canonicalize(glob);
+    let re = "";
+    for (let i = 0; i < canonical.length; i += 1) {
+        const c = canonical.charAt(i);
+        if (c === "*") {
+            if (canonical.charAt(i + 1) === "*") {
+                re += ".*";
+                i += 1;
+                if (canonical.charAt(i + 1) === "/")
+                    i += 1; // `**/` also matches zero segments
+            }
+            else {
+                re += "[^/]*";
+            }
+        }
+        else if (/[.+?^${}()|[\]\\]/.test(c)) {
+            re += `\\${c}`;
+        }
+        else {
+            re += c;
+        }
+    }
+    return new RegExp(`^${re}$`);
+}
+/**
+ * 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 function matchesAny(path, globs) {
+    const canonicalPath = canonicalize(path);
+    return globs.some((g) => hasUnsafeWildcardCount(g) || globToRegExp(g).test(canonicalPath));
+}
+/**
+ * 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 function changedPathsHittingGuardrail(changedPaths, hardGuardrailGlobs) {
+    if (hardGuardrailGlobs.length === 0)
+        return [];
+    return changedPaths.filter((path) => path.length > 0 && matchesAny(path, hardGuardrailGlobs));
+}
+/**
+ * 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 function guardrailPathMatches(changedPaths, hardGuardrailGlobs) {
+    if (hardGuardrailGlobs.length === 0 || changedPaths.length === 0)
+        return [];
+    const matches = [];
+    for (const path of changedPaths) {
+        if (path.length === 0)
+            continue;
+        const canonicalPath = canonicalize(path);
+        for (const glob of hardGuardrailGlobs) {
+            if (hasUnsafeWildcardCount(glob)) {
+                matches.push({ path, glob });
+                continue;
+            }
+            if (globToRegExp(glob).test(canonicalPath)) {
+                matches.push({ path, glob });
+            }
+        }
+    }
+    return matches;
+}
+/**
+ * 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 function isGuardrailHit(changedPaths, hardGuardrailGlobs) {
+    if (hardGuardrailGlobs.length === 0)
+        return false;
+    return changedPaths.length === 0 || changedPathsHittingGuardrail(changedPaths, hardGuardrailGlobs).length > 0;
+}

package/dist/signals/check-summary.d.ts

@@ -0,0 +1,9 @@
+import type { CheckSummaryRecord } from "../scoring/types.js";
+/**
+ * Canonical "is this ONE cached check failing?" predicate, shared so every surface (readiness, the maintainer
+ * queue digest, reward-risk reviewability) classifies a check identically. A cached check may carry its outcome
+ * on `conclusion` (check runs) OR only on `status` (commit-status rows and runs that errored before concluding),
+ * so fall back to `status` when `conclusion` is absent, and case-fold both — GitHub conclusions are lowercase,
+ * but cached/commit statuses are not guaranteed to be.
+ */
+export declare function isFailingCheckSummary(check: CheckSummaryRecord): boolean;

package/dist/signals/check-summary.js

@@ -0,0 +1,12 @@
+/** Conclusion/status values that mark a single cached check as failing or attention-needing. */
+const FAILING_CHECK_STATES = ["failure", "failed", "timed_out", "cancelled", "action_required", "startup_failure"];
+/**
+ * Canonical "is this ONE cached check failing?" predicate, shared so every surface (readiness, the maintainer
+ * queue digest, reward-risk reviewability) classifies a check identically. A cached check may carry its outcome
+ * on `conclusion` (check runs) OR only on `status` (commit-status rows and runs that errored before concluding),
+ * so fall back to `status` when `conclusion` is absent, and case-fold both — GitHub conclusions are lowercase,
+ * but cached/commit statuses are not guaranteed to be.
+ */
+export function isFailingCheckSummary(check) {
+    return FAILING_CHECK_STATES.includes((check.conclusion ?? check.status).toLowerCase());
+}

package/dist/signals/contributor-calibration.d.ts

@@ -0,0 +1,23 @@
+/** Below this many historical (prediction, real-decision) pairings, a login's track record is treated as
+ *  cold-start (unweighted baseline) -- too few samples to distinguish signal from noise. */
+export declare const MIN_CALIBRATION_SAMPLES = 5;
+/** Maximum points (out of the 0-100 readinessScore scale) personalization may add or subtract. Deliberately
+ *  small relative to the 100-point scale: this is a confidence nudge, not a re-scoring. */
+export declare const MAX_READINESS_ADJUSTMENT = 10;
+export type ContributorCalibrationSignal = {
+    /** How many (prediction, real-decision) pairings this login has in predicted_gate_calibration_ledger. */
+    sampleSize: number;
+    /** Fraction of those pairings where the predicted action matched the real decision. Clamped to [0, 1]
+     *  before use, so a malformed upstream aggregate can never push the adjustment past its own clamp. */
+    agreementRate: number;
+};
+/**
+ * Adjusts a baseline readinessScore by a login's own predict-vs-real calibration history, clamped to
+ * +/-{@link MAX_READINESS_ADJUSTMENT} points and to the score's own [0, 100] range.
+ *
+ * Cold start -- no calibration signal, or fewer than {@link MIN_CALIBRATION_SAMPLES} pairings -- returns the
+ * baseline completely UNCHANGED: a never-seen (or barely-seen) actor gets no penalty and no bonus. A `null`
+ * baseline (no readiness score to begin with) stays `null` -- personalization never manufactures a score out
+ * of nothing.
+ */
+export declare function applyContributorCalibration(baselineReadinessScore: number | null, calibration: ContributorCalibrationSignal | null | undefined): number | null;

package/dist/signals/contributor-calibration.js

@@ -0,0 +1,47 @@
+// #2349: personalizes buildPredictedGateVerdict's readiness/confidence output using a contributor/miner's OWN
+// historical predict-vs-real agreement (predicted_gate_calibration_ledger, written by
+// src/review/predicted-gate-calibration-ledger.ts). Pure and D1-free by design -- this package never touches a
+// database; the caller (src/mcp/server.ts, src/api/routes.ts) reads and aggregates the ledger for one login,
+// then hands this module a plain, already-computed signal.
+//
+// SAFETY BOUNDARY (mirrors the design note in both src/review/contributor-calibration.ts and
+// src/review/predicted-gate-calibration-ledger.ts): buildPredictedGateVerdict calls applyContributorCalibration
+// strictly AFTER evaluateGateCheck has already finalized conclusion/blockers/warnings, and threads through
+// ONLY the numeric readinessScore. This function never receives blockers or conclusion, so it is structurally
+// incapable of flipping a hard blocker off -- not just clamped by convention, but by construction.
+//
+// PRIVACY: the calibration signal (sampleSize, agreementRate) is consumed here and never echoed back in
+// PredictedGateVerdict -- only its clamped, bounded DOWNSTREAM EFFECT (a shifted readinessScore, itself
+// already a public-facing concept) is returned. src/signals/redaction.ts's "no raw per-actor trust signal,
+// ever public" boundary is preserved because the raw numbers never reach the output at all.
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+/** Below this many historical (prediction, real-decision) pairings, a login's track record is treated as
+ *  cold-start (unweighted baseline) -- too few samples to distinguish signal from noise. */
+export const MIN_CALIBRATION_SAMPLES = 5;
+/** Maximum points (out of the 0-100 readinessScore scale) personalization may add or subtract. Deliberately
+ *  small relative to the 100-point scale: this is a confidence nudge, not a re-scoring. */
+export const MAX_READINESS_ADJUSTMENT = 10;
+/** Agreement rate that maps to a zero adjustment -- a coin-flip predict-vs-real track record earns neither a
+ *  bonus nor a penalty. */
+const NEUTRAL_AGREEMENT_RATE = 0.5;
+/**
+ * Adjusts a baseline readinessScore by a login's own predict-vs-real calibration history, clamped to
+ * +/-{@link MAX_READINESS_ADJUSTMENT} points and to the score's own [0, 100] range.
+ *
+ * Cold start -- no calibration signal, or fewer than {@link MIN_CALIBRATION_SAMPLES} pairings -- returns the
+ * baseline completely UNCHANGED: a never-seen (or barely-seen) actor gets no penalty and no bonus. A `null`
+ * baseline (no readiness score to begin with) stays `null` -- personalization never manufactures a score out
+ * of nothing.
+ */
+export function applyContributorCalibration(baselineReadinessScore, calibration) {
+    if (baselineReadinessScore === null)
+        return null;
+    if (!calibration || calibration.sampleSize < MIN_CALIBRATION_SAMPLES)
+        return baselineReadinessScore;
+    const agreementRate = clamp(calibration.agreementRate, 0, 1);
+    const rawAdjustment = (agreementRate - NEUTRAL_AGREEMENT_RATE) * 2 * MAX_READINESS_ADJUSTMENT;
+    const adjustment = clamp(rawAdjustment, -MAX_READINESS_ADJUSTMENT, MAX_READINESS_ADJUSTMENT);
+    return clamp(baselineReadinessScore + adjustment, 0, 100);
+}

package/dist/signals/duplicate-winner.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Duplicate-winner adjudication (#dup-winner) — thin re-export shim (#4251). This file and
+ * `../duplicate-winner.ts` were accidental byte-identical forks living inside the same package (not a
+ * `src/`-vs-engine extraction pair; both copies were already inside `gittensory-engine`). The top-level module
+ * is the source of truth; see its doc comment for the full election-order rationale (claim-time election,
+ * anti-backdating semantics). Kept as a re-export (not deleted) so `advisory/gate-advisory.ts`'s existing
+ * `../signals/duplicate-winner.js` import keeps resolving without a call-site change.
+ */
+export { isDuplicateClusterWinner, isDuplicateClusterWinnerByClaim, resolveDuplicateClusterWinnerNumber, type DuplicateClaimMember, } from "../duplicate-winner.js";

package/dist/signals/duplicate-winner.js

@@ -0,0 +1,9 @@
+/**
+ * Duplicate-winner adjudication (#dup-winner) — thin re-export shim (#4251). This file and
+ * `../duplicate-winner.ts` were accidental byte-identical forks living inside the same package (not a
+ * `src/`-vs-engine extraction pair; both copies were already inside `gittensory-engine`). The top-level module
+ * is the source of truth; see its doc comment for the full election-order rationale (claim-time election,
+ * anti-backdating semantics). Kept as a re-export (not deleted) so `advisory/gate-advisory.ts`'s existing
+ * `../signals/duplicate-winner.js` import keeps resolving without a call-site change.
+ */
+export { isDuplicateClusterWinner, isDuplicateClusterWinnerByClaim, resolveDuplicateClusterWinnerNumber, } from "../duplicate-winner.js";

package/dist/signals/path-matchers.d.ts

@@ -0,0 +1,36 @@
+import { isCodeFile } from "./test-evidence.js";
+/** Keep local scoring aligned with slop/test-evidence matchers (#561 / #1046). */
+export declare function isTestFile(file: string): boolean;
+export { isCodeFile };
+/** Machine-generated output (codegen, protobuf, source maps, typegen). */
+export declare function isGeneratedFile(path: string): boolean;
+/** Third-party / imported code that lives in the repo but is not the contributor's work. */
+export declare function isVendoredFile(path: string): boolean;
+/** Dependency lockfiles (resolved trees), e.g. `package-lock.json`, `go.sum`, `Cargo.lock`. */
+export declare function isLockfile(path: string): boolean;
+/** Minified bundles, e.g. `app.min.js`, `styles.min.css`. */
+export declare function isMinifiedFile(path: string): boolean;
+/** Documentation files (by extension or a top-level `docs/` directory). */
+export declare function isDocsFile(path: string): boolean;
+/** Dependency manifests (declare dependencies), e.g. `package.json`, `go.mod`, `pyproject.toml`. */
+export declare function isDependencyManifestFile(path: string): boolean;
+/**
+ * Build, lint, test-runner, monorepo, deploy, and environment configuration files. Distinct from
+ * dependency manifests (which declare external dependencies) and source code. Config-only diffs are
+ * lower-effort than genuine source changes, so slop signals can weight them differently (#561).
+ */
+export declare function isConfigFile(path: string): boolean;
+/**
+ * Files that masquerade as substantive source/work but are machine-produced or imported — the set a
+ * padded diff inflates its size with. Lockfiles, dependency manifests, and docs are legitimate change
+ * categories and are deliberately excluded here (they have their own matchers for reuse).
+ */
+export declare function isNonSubstantivePaddingFile(path: string): boolean;
+export type ChangedFileCategory = "minified" | "generated" | "vendored" | "lockfile" | "dependency_manifest" | "config" | "test" | "docs" | "source" | "other";
+/**
+ * Classify a changed file into a single category. Non-substantive padding categories
+ * (minified/generated/vendored) take precedence so they are never miscounted as substantive source
+ * or test effort; lockfiles and dependency manifests are recognized before generic docs/source.
+ * Normalises the path once and threads the pre-computed parts through every `isX` matcher.
+ */
+export declare function classifyChangedFile(path: string): ChangedFileCategory;