@loopover/engine 1.0.0

package/dist/miner-goal-lane-fit.js

@@ -0,0 +1,76 @@
+import { computeLaneFit } from "./goal-model.js";
+/** Whether a repo's miner goal spec permits autonomous targeting (explicit opt-out only). */
+export function isMinerRepoTargetable(spec) {
+    return spec.minerEnabled;
+}
+function clamp01(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    return Math.min(1, Math.max(0, value));
+}
+function normalizeLabels(labels) {
+    return labels
+        .filter((label) => typeof label === "string")
+        .map((label) => label.trim().toLowerCase())
+        .filter(Boolean);
+}
+/**
+ * Compute a [0, 1] lane-fit score from issue labels and a parsed {@link MinerGoalSpec}. Path-based fit is
+ * intentionally omitted — discovery metadata has labels only; path gating belongs in the analyze phase.
+ */
+export function computeMinerGoalLaneFit(issue, spec) {
+    const issueLabels = normalizeLabels(issue.labels);
+    const blocked = normalizeLabels(spec.blockedLabels);
+    if (blocked.length > 0 && blocked.some((label) => issueLabels.includes(label))) {
+        return 0;
+    }
+    const preferred = normalizeLabels(spec.preferredLabels);
+    let score;
+    if (preferred.length === 0) {
+        score = 1;
+    }
+    else {
+        const preferredMatch = preferred.some((want) => issueLabels.includes(want));
+        if (preferredMatch) {
+            score = 1;
+        }
+        else if (spec.issueDiscoveryPolicy === "discouraged") {
+            score = 0.6;
+        }
+        else {
+            score = 0.25;
+        }
+    }
+    if (spec.issueDiscoveryPolicy === "encouraged") {
+        score = Math.max(score, 0.85);
+    }
+    return clamp01(score);
+}
+function normalizeCandidatePaths(paths) {
+    if (!Array.isArray(paths))
+        return [];
+    const normalized = [];
+    for (const path of paths) {
+        if (typeof path !== "string")
+            continue;
+        const trimmed = path.trim();
+        if (trimmed)
+            normalized.push(trimmed);
+    }
+    return normalized;
+}
+/**
+ * Lane-fit for metadata-ranked issues. Uses full path+label {@link computeLaneFit} when
+ * `candidatePaths` are present; otherwise falls back to label-only {@link computeMinerGoalLaneFit}.
+ */
+export function computeMetadataLaneFit(issue, spec) {
+    const candidatePaths = normalizeCandidatePaths(issue.candidatePaths);
+    if (candidatePaths.length > 0) {
+        return computeLaneFit({
+            candidatePaths,
+            candidateLabels: [...issue.labels],
+            goalSpec: spec,
+        });
+    }
+    return computeMinerGoalLaneFit(issue, spec);
+}

package/dist/miner-goal-spec.d.ts

@@ -0,0 +1,139 @@
+import { MINER_LIVE_MODE_OPT_IN } from "./governor/action-mode.js";
+/** How strongly opening discovery issues is encouraged for this repo. Mirrors the review-side policy vocabulary. */
+export type MinerIssueDiscoveryPolicy = "encouraged" | "neutral" | "discouraged";
+/** Per-repo tuning for the feasibility gate (`buildFeasibilityVerdict`, see `feasibility.ts`) a miner consults
+ *  before starting work. This is config-parsing surface only — it does not itself change the composer's
+ *  behavior; a caller wiring the gate into a decision flow reads this policy and applies it. */
+export type FeasibilityGatePolicy = {
+    /** Whether this repo wants the feasibility gate consulted at all before a miner starts work. Setting this
+     *  `false` lets a repo opt out of the gate entirely rather than tuning it. Default: true. */
+    enabled: boolean;
+    /** Specific `buildFeasibilityVerdict` avoid/raise reason codes (e.g. `"duplicate_cluster_high"`) this repo
+     *  wants ignored — for a repo that doesn't want duplicate-cluster signals to affect feasibility, for example.
+     *  String list. Default: [] (nothing suppressed). */
+    suppressedReasons: readonly string[];
+};
+/** Per-repo self-plagiarism throttle tuning for Governor open_pr (#2345). */
+export type SelfPlagiarismPolicy = {
+    /** Jaccard similarity threshold in [0, 1] for near-duplicate diff fingerprints. Default: 0.85. */
+    similarityThreshold: number;
+};
+/** Per-repo kill-switch tuning consulted by the Governor chokepoint's kill-switch primitive (#2341). */
+export type MinerKillSwitchPolicy = {
+    /**
+     * Per-repo runtime halt: stops all miner WRITE actions for this repo without deregistering it from
+     * targeting/discovery. Distinct from `minerEnabled` (a discovery-time opt-out) — pausing preserves in-flight
+     * queue state so un-pausing resumes exactly where the queue left off. Default: false (not paused).
+     */
+    paused: boolean;
+};
+/** Per-repo dry-run/live execution tuning consulted by the Governor chokepoint's action-mode primitive (#2342). */
+export type MinerExecutionPolicy = {
+    /**
+     * Explicit opt-in to LIVE write execution for this repo. Must equal EXACTLY the literal string `"live"` — any
+     * other value (a typo, `"yes"`, `"on"`, or a boolean `true` from a malformed file) is treated as not opted
+     * in, so a fat-fingered config can never accidentally enable live writes. A miner also stays in dry-run
+     * unless its own operator separately opts in globally (`GITTENSORY_MINER_LIVE_MODE=live`) — this field alone
+     * cannot force a stranger's miner instance live. Default: null (dry-run).
+     */
+    liveModeOptIn: typeof MINER_LIVE_MODE_OPT_IN | null;
+};
+/** Per-repo miner configuration parsed from `.gittensory-miner.yml`. See {@link DEFAULT_MINER_GOAL_SPEC}. */
+export type MinerGoalSpec = {
+    /**
+     * Whether this repo permits autonomous miners at all. Explicit OPT-OUT, not opt-in: a public repo with no
+     * `.gittensory-miner.yml` is still minable, mirroring `.gittensory.yml`'s "safe by default" stance. Set `false`
+     * to halt all miner targeting of this repo. Default: true.
+     */
+    minerEnabled: boolean;
+    /**
+     * Work areas the maintainer wants a miner to focus on; a candidate touching these is preferred. Glob list.
+     * Default: [] (no preference).
+     */
+    wantedPaths: readonly string[];
+    /**
+     * Paths off-limits to a miner. A candidate touching one of these should be skipped. Glob list.
+     * Default: [] (nothing blocked).
+     */
+    blockedPaths: readonly string[];
+    /**
+     * Issue/PR labels the maintainer prefers a miner to target; a candidate carrying one is favored. String list.
+     * Default: [] (no preference).
+     */
+    preferredLabels: readonly string[];
+    /**
+     * Issue/PR labels a miner must not target; a candidate carrying one should be skipped. String list.
+     * Default: [] (nothing blocked).
+     */
+    blockedLabels: readonly string[];
+    /**
+     * Maximum number of issues a single miner may hold claimed on this repo at once, so one miner cannot monopolize
+     * a repo's queue. A positive integer (`>= 1`); the parser is expected to floor a non-integer toward zero
+     * (`Math.floor`) and reject any value below 1. Default: 1.
+     */
+    maxConcurrentClaims: number;
+    /**
+     * How strongly this repo encourages a miner to open discovery issues. Values: encouraged | neutral | discouraged.
+     * Default: neutral.
+     */
+    issueDiscoveryPolicy: MinerIssueDiscoveryPolicy;
+    /**
+     * Per-repo tuning for the feasibility gate a miner consults before starting work. See {@link FeasibilityGatePolicy}.
+     * Default: { enabled: true, suppressedReasons: [] }.
+     */
+    feasibilityGate: FeasibilityGatePolicy;
+    /**
+     * Self-plagiarism throttle consulted before open_pr (#2345). Default: { similarityThreshold: 0.85 }.
+     */
+    selfPlagiarism: SelfPlagiarismPolicy;
+    /**
+     * Per-repo kill-switch consulted by the Governor chokepoint before every write action (#2341).
+     * Default: { paused: false }.
+     */
+    killSwitch: MinerKillSwitchPolicy;
+    /**
+     * Per-repo dry-run/live execution opt-in consulted by the Governor chokepoint (#2342).
+     * Default: { liveModeOptIn: null }.
+     */
+    execution: MinerExecutionPolicy;
+};
+/** The tolerant parser result for `.gittensory-miner.yml`: the normalized spec plus parse warnings and whether the
+ *  file actually expressed any non-default goal fields. Mirrors `parseFocusManifest`'s present/warnings pattern
+ *  without forcing metadata onto downstream consumers that only need the config itself. */
+export type ParsedMinerGoalSpec = {
+    present: boolean;
+    spec: MinerGoalSpec;
+    warnings: string[];
+};
+/**
+ * The safe defaults applied when a field is absent from `.gittensory-miner.yml` (or the file itself is missing).
+ * Every value here matches the "Default: X" documented on its field above. Analogous to the defaults constant that
+ * accompanies `FocusManifest` in `src/signals/focus-manifest.ts` — a repo with no file behaves as if it declared
+ * this: minable, with no path/label preferences, one concurrent claim, and neutral discovery.
+ *
+ * Deep-frozen: this is a shared singleton, so runtime code can read it freely but must not mutate it — clone before
+ * layering repo-specific overrides on top.
+ */
+export declare const DEFAULT_MINER_GOAL_SPEC: Readonly<MinerGoalSpec>;
+/**
+ * Tolerantly normalize an already-parsed `.gittensory-miner.yml` object into a {@link ParsedMinerGoalSpec}.
+ * Never throws: malformed shapes degrade to safe defaults and accumulate warnings so callers can surface
+ * "your miner goal spec had problems" without hard-failing a run.
+ */
+export declare function parseMinerGoalSpec(raw: unknown): ParsedMinerGoalSpec;
+/**
+ * Parse raw `.gittensory-miner.yml` file content (JSON or YAML). Malformed content degrades to an absent
+ * goal spec with a warning rather than throwing, mirroring `parseFocusManifestContent`.
+ */
+export declare function parseMinerGoalSpecContent(content: string | null | undefined): ParsedMinerGoalSpec;
+/**
+ * The documented `.gittensory-miner` file-discovery order (first match wins), mirroring how `.gittensory.yml` is
+ * discovered: repo-root YAML, then `.github/` YAML, then the JSON variants.
+ */
+export declare const MINER_GOAL_SPEC_FILENAMES: readonly [".gittensory-miner.yml", ".github/gittensory-miner.yml", ".gittensory-miner.json", ".github/gittensory-miner.json"];
+/**
+ * The first {@link MINER_GOAL_SPEC_FILENAMES} candidate that exists, or null. Pure: the caller injects the existence
+ * check (e.g. `fs.existsSync`) so this module stays IO-free and unit-testable. A caller reads the returned path and
+ * feeds its content to {@link parseMinerGoalSpecContent}.
+ */
+export declare function discoverMinerGoalSpecPath(exists: (path: string) => boolean): string | null;

package/dist/miner-goal-spec.js

@@ -0,0 +1,281 @@
+import { parse as parseYaml } from "yaml";
+import { MINER_LIVE_MODE_OPT_IN } from "./governor/action-mode.js";
+import { DEFAULT_SELF_PLAGIARISM_SIMILARITY_THRESHOLD, resolveSelfPlagiarismConfig, } from "./governor/self-plagiarism.js";
+/**
+ * The safe defaults applied when a field is absent from `.gittensory-miner.yml` (or the file itself is missing).
+ * Every value here matches the "Default: X" documented on its field above. Analogous to the defaults constant that
+ * accompanies `FocusManifest` in `src/signals/focus-manifest.ts` — a repo with no file behaves as if it declared
+ * this: minable, with no path/label preferences, one concurrent claim, and neutral discovery.
+ *
+ * Deep-frozen: this is a shared singleton, so runtime code can read it freely but must not mutate it — clone before
+ * layering repo-specific overrides on top.
+ */
+export const DEFAULT_MINER_GOAL_SPEC = Object.freeze({
+    minerEnabled: true,
+    wantedPaths: Object.freeze([]),
+    blockedPaths: Object.freeze([]),
+    preferredLabels: Object.freeze([]),
+    blockedLabels: Object.freeze([]),
+    maxConcurrentClaims: 1,
+    issueDiscoveryPolicy: "neutral",
+    feasibilityGate: Object.freeze({ enabled: true, suppressedReasons: Object.freeze([]) }),
+    selfPlagiarism: Object.freeze({ similarityThreshold: DEFAULT_SELF_PLAGIARISM_SIMILARITY_THRESHOLD }),
+    killSwitch: Object.freeze({ paused: false }),
+    execution: Object.freeze({ liveModeOptIn: null }),
+});
+const MAX_MINER_GOAL_SPEC_BYTES = 32_768;
+const MAX_LIST_ITEMS = 100;
+const MAX_ITEM_LENGTH = 256;
+function cloneDefaultMinerGoalSpec() {
+    return {
+        ...DEFAULT_MINER_GOAL_SPEC,
+        wantedPaths: [...DEFAULT_MINER_GOAL_SPEC.wantedPaths],
+        blockedPaths: [...DEFAULT_MINER_GOAL_SPEC.blockedPaths],
+        preferredLabels: [...DEFAULT_MINER_GOAL_SPEC.preferredLabels],
+        blockedLabels: [...DEFAULT_MINER_GOAL_SPEC.blockedLabels],
+        feasibilityGate: {
+            enabled: DEFAULT_MINER_GOAL_SPEC.feasibilityGate.enabled,
+            suppressedReasons: [...DEFAULT_MINER_GOAL_SPEC.feasibilityGate.suppressedReasons],
+        },
+        selfPlagiarism: { ...DEFAULT_MINER_GOAL_SPEC.selfPlagiarism },
+        killSwitch: { ...DEFAULT_MINER_GOAL_SPEC.killSwitch },
+        execution: { ...DEFAULT_MINER_GOAL_SPEC.execution },
+    };
+}
+function emptyMinerGoalSpec(warnings = []) {
+    return { present: false, spec: cloneDefaultMinerGoalSpec(), warnings };
+}
+function normalizeStringList(value, field, warnings) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        warnings.push(`MinerGoalSpec field "${field}" must be a list; ignoring a ${typeof value} value.`);
+        return [];
+    }
+    const result = [];
+    const seen = new Set();
+    for (const [index, entry] of value.entries()) {
+        if (index >= MAX_LIST_ITEMS) {
+            warnings.push(`MinerGoalSpec field "${field}" exceeded ${MAX_LIST_ITEMS} entries; extra entries ignored.`);
+            break;
+        }
+        if (typeof entry !== "string") {
+            warnings.push(`MinerGoalSpec field "${field}" skipped a non-string entry.`);
+            continue;
+        }
+        const trimmed = entry.trim();
+        if (!trimmed)
+            continue;
+        let normalized = trimmed;
+        if (normalized.length > MAX_ITEM_LENGTH) {
+            warnings.push(`MinerGoalSpec field "${field}" truncated an over-long entry.`);
+            normalized = normalized.slice(0, MAX_ITEM_LENGTH);
+        }
+        if (seen.has(normalized))
+            continue;
+        result.push(normalized);
+        seen.add(normalized);
+    }
+    return result;
+}
+function normalizeBoolean(value, field, fallback, warnings) {
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value === "boolean")
+        return value;
+    warnings.push(`MinerGoalSpec field "${field}" must be a boolean; falling back to ${String(fallback)}.`);
+    return fallback;
+}
+function normalizeIssueDiscoveryPolicy(value, field, fallback, warnings) {
+    if (value === undefined || value === null)
+        return fallback;
+    if (value === "encouraged" || value === "neutral" || value === "discouraged")
+        return value;
+    warnings.push(`MinerGoalSpec field "${field}" must be one of encouraged, neutral, discouraged; falling back to "${fallback}".`);
+    return fallback;
+}
+function normalizeFeasibilityGatePolicy(value, field, fallback, warnings) {
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value !== "object" || Array.isArray(value)) {
+        warnings.push(`MinerGoalSpec field "${field}" must be a mapping; falling back to defaults.`);
+        return fallback;
+    }
+    const record = value;
+    return {
+        enabled: normalizeBoolean(record.enabled, `${field}.enabled`, fallback.enabled, warnings),
+        suppressedReasons: normalizeStringList(record.suppressedReasons, `${field}.suppressedReasons`, warnings),
+    };
+}
+function normalizeSelfPlagiarismPolicy(value, field, fallback, warnings) {
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value !== "object" || Array.isArray(value)) {
+        warnings.push(`MinerGoalSpec field "${field}" must be a mapping; falling back to defaults.`);
+        return fallback;
+    }
+    const resolved = resolveSelfPlagiarismConfig(value);
+    const record = value;
+    if (record.similarityThreshold !== undefined &&
+        typeof record.similarityThreshold !== "number") {
+        warnings.push(`MinerGoalSpec field "${field}.similarityThreshold" must be a number; falling back to ${fallback.similarityThreshold}.`);
+        return fallback;
+    }
+    return resolved;
+}
+function normalizeKillSwitchPolicy(value, field, fallback, warnings) {
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value !== "object" || Array.isArray(value)) {
+        warnings.push(`MinerGoalSpec field "${field}" must be a mapping; falling back to defaults.`);
+        return fallback;
+    }
+    const record = value;
+    return {
+        paused: normalizeBoolean(record.paused, `${field}.paused`, fallback.paused, warnings),
+    };
+}
+function normalizeExecutionPolicy(value, field, fallback, warnings) {
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value !== "object" || Array.isArray(value)) {
+        warnings.push(`MinerGoalSpec field "${field}" must be a mapping; falling back to defaults.`);
+        return fallback;
+    }
+    const record = value;
+    const raw = record.liveModeOptIn;
+    if (raw === undefined || raw === null)
+        return { liveModeOptIn: fallback.liveModeOptIn };
+    if (typeof raw !== "string") {
+        warnings.push(`MinerGoalSpec field "${field}.liveModeOptIn" must be a string; falling back to dry-run.`);
+        return { liveModeOptIn: fallback.liveModeOptIn };
+    }
+    // A string that isn't the exact opt-in literal is NOT malformed (it's a valid string, just not the one value
+    // that grants live mode) -- no warning, just a silent, safe fall-through to dry-run. Only a wrong TYPE above
+    // warns, matching every other field's tolerant-parse convention.
+    return { liveModeOptIn: raw === MINER_LIVE_MODE_OPT_IN ? raw : null };
+}
+function normalizePositiveInteger(value, field, fallback, warnings) {
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        warnings.push(`MinerGoalSpec field "${field}" must be a positive whole number; falling back to ${fallback}.`);
+        return fallback;
+    }
+    const normalized = Math.floor(value);
+    if (normalized >= 1)
+        return normalized;
+    warnings.push(`MinerGoalSpec field "${field}" must be >= 1 after flooring; falling back to ${fallback}.`);
+    return fallback;
+}
+function utf8ByteLength(value) {
+    let bytes = 0;
+    for (const char of value) {
+        const codePoint = char.codePointAt(0);
+        if (codePoint <= 0x7f)
+            bytes += 1;
+        else if (codePoint <= 0x7ff)
+            bytes += 2;
+        else if (codePoint <= 0xffff)
+            bytes += 3;
+        else
+            bytes += 4;
+    }
+    return bytes;
+}
+function hasConfiguredGoalFields(spec) {
+    return (spec.minerEnabled !== DEFAULT_MINER_GOAL_SPEC.minerEnabled ||
+        spec.wantedPaths.length > 0 ||
+        spec.blockedPaths.length > 0 ||
+        spec.preferredLabels.length > 0 ||
+        spec.blockedLabels.length > 0 ||
+        spec.maxConcurrentClaims !== DEFAULT_MINER_GOAL_SPEC.maxConcurrentClaims ||
+        spec.issueDiscoveryPolicy !== DEFAULT_MINER_GOAL_SPEC.issueDiscoveryPolicy ||
+        spec.feasibilityGate.enabled !== DEFAULT_MINER_GOAL_SPEC.feasibilityGate.enabled ||
+        spec.feasibilityGate.suppressedReasons.length > 0 ||
+        spec.selfPlagiarism.similarityThreshold !== DEFAULT_MINER_GOAL_SPEC.selfPlagiarism.similarityThreshold ||
+        spec.killSwitch.paused !== DEFAULT_MINER_GOAL_SPEC.killSwitch.paused ||
+        spec.execution.liveModeOptIn !== DEFAULT_MINER_GOAL_SPEC.execution.liveModeOptIn);
+}
+/**
+ * Tolerantly normalize an already-parsed `.gittensory-miner.yml` object into a {@link ParsedMinerGoalSpec}.
+ * Never throws: malformed shapes degrade to safe defaults and accumulate warnings so callers can surface
+ * "your miner goal spec had problems" without hard-failing a run.
+ */
+export function parseMinerGoalSpec(raw) {
+    if (raw === undefined || raw === null)
+        return emptyMinerGoalSpec();
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        return emptyMinerGoalSpec([
+            "MinerGoalSpec must be a mapping of fields; ignoring malformed config and falling back to safe defaults.",
+        ]);
+    }
+    const record = raw;
+    const warnings = [];
+    const spec = {
+        minerEnabled: normalizeBoolean(record.minerEnabled, "minerEnabled", DEFAULT_MINER_GOAL_SPEC.minerEnabled, warnings),
+        wantedPaths: normalizeStringList(record.wantedPaths, "wantedPaths", warnings),
+        blockedPaths: normalizeStringList(record.blockedPaths, "blockedPaths", warnings),
+        preferredLabels: normalizeStringList(record.preferredLabels, "preferredLabels", warnings),
+        blockedLabels: normalizeStringList(record.blockedLabels, "blockedLabels", warnings),
+        maxConcurrentClaims: normalizePositiveInteger(record.maxConcurrentClaims, "maxConcurrentClaims", DEFAULT_MINER_GOAL_SPEC.maxConcurrentClaims, warnings),
+        issueDiscoveryPolicy: normalizeIssueDiscoveryPolicy(record.issueDiscoveryPolicy, "issueDiscoveryPolicy", DEFAULT_MINER_GOAL_SPEC.issueDiscoveryPolicy, warnings),
+        feasibilityGate: normalizeFeasibilityGatePolicy(record.feasibilityGate, "feasibilityGate", DEFAULT_MINER_GOAL_SPEC.feasibilityGate, warnings),
+        selfPlagiarism: normalizeSelfPlagiarismPolicy(record.selfPlagiarism, "selfPlagiarism", DEFAULT_MINER_GOAL_SPEC.selfPlagiarism, warnings),
+        killSwitch: normalizeKillSwitchPolicy(record.killSwitch, "killSwitch", DEFAULT_MINER_GOAL_SPEC.killSwitch, warnings),
+        execution: normalizeExecutionPolicy(record.execution, "execution", DEFAULT_MINER_GOAL_SPEC.execution, warnings),
+    };
+    if (!hasConfiguredGoalFields(spec)) {
+        warnings.push("MinerGoalSpec contained no recognized non-default goal fields; falling back to safe defaults.");
+        return { present: false, spec: cloneDefaultMinerGoalSpec(), warnings };
+    }
+    return { present: true, spec, warnings };
+}
+/**
+ * Parse raw `.gittensory-miner.yml` file content (JSON or YAML). Malformed content degrades to an absent
+ * goal spec with a warning rather than throwing, mirroring `parseFocusManifestContent`.
+ */
+export function parseMinerGoalSpecContent(content) {
+    if (content === undefined || content === null || content.trim() === "")
+        return emptyMinerGoalSpec();
+    if (utf8ByteLength(content) > MAX_MINER_GOAL_SPEC_BYTES) {
+        return emptyMinerGoalSpec([
+            `MinerGoalSpec content exceeded ${MAX_MINER_GOAL_SPEC_BYTES} bytes; ignoring it and falling back to safe defaults.`,
+        ]);
+    }
+    const trimmed = content.trim();
+    const looksLikeJson = trimmed.startsWith("{") || trimmed.startsWith("[");
+    let parsed;
+    try {
+        parsed = looksLikeJson ? JSON.parse(trimmed) : parseYaml(trimmed);
+    }
+    catch {
+        return emptyMinerGoalSpec([
+            looksLikeJson
+                ? "MinerGoalSpec content was not valid JSON; ignoring it and falling back to safe defaults."
+                : "MinerGoalSpec content was not valid YAML; ignoring it and falling back to safe defaults.",
+        ]);
+    }
+    return parseMinerGoalSpec(parsed);
+}
+/**
+ * The documented `.gittensory-miner` file-discovery order (first match wins), mirroring how `.gittensory.yml` is
+ * discovered: repo-root YAML, then `.github/` YAML, then the JSON variants.
+ */
+export const MINER_GOAL_SPEC_FILENAMES = [
+    ".gittensory-miner.yml",
+    ".github/gittensory-miner.yml",
+    ".gittensory-miner.json",
+    ".github/gittensory-miner.json",
+];
+/**
+ * The first {@link MINER_GOAL_SPEC_FILENAMES} candidate that exists, or null. Pure: the caller injects the existence
+ * check (e.g. `fs.existsSync`) so this module stays IO-free and unit-testable. A caller reads the returned path and
+ * feeds its content to {@link parseMinerGoalSpecContent}.
+ */
+export function discoverMinerGoalSpecPath(exists) {
+    for (const name of MINER_GOAL_SPEC_FILENAMES)
+        if (exists(name))
+            return name;
+    return null;
+}

package/dist/miner-prediction-metrics.d.ts

@@ -0,0 +1,16 @@
+export declare const MINER_PREDICTIONS_TOTAL = "gittensory_miner_predictions_total";
+export declare const MINER_PREDICTION_CORRECT_TOTAL = "gittensory_miner_prediction_correct_total";
+export declare const MINER_PREDICTION_INCORRECT_TOTAL = "gittensory_miner_prediction_incorrect_total";
+/** One prediction-ledger row for metrics: its predicted `conclusion`, plus an optional realized-outcome pairing
+ *  (`correct`: true = matched, false = differed, null/undefined = not yet resolved). */
+export type MinerPredictionMetricRow = {
+    conclusion: string;
+    correct?: boolean | null;
+};
+/**
+ * Render prediction-calibration counters as Prometheus text-exposition format. Pure and side-effect-free: a caller
+ * supplies the ledger rows (joined with any resolved outcomes) and prints the result. Deterministic — conclusion
+ * series are emitted in sorted order. Always emits HELP/TYPE for every counter, so the surface is well-formed even
+ * for an empty ledger.
+ */
+export declare function renderMinerPredictionMetrics(rows: readonly MinerPredictionMetricRow[]): string;

package/dist/miner-prediction-metrics.js

@@ -0,0 +1,61 @@
+// Miner prediction-calibration metrics (#4264). A pure Prometheus text-exposition renderer for the miner's own
+// predicted-gate accuracy, the miner-side counterpart to the server's src/selfhost/metrics.ts registry. It turns
+// prediction-ledger rows (packages/gittensory-miner/lib/prediction-ledger.js `readPredictions`) — optionally
+// joined with their realized outcome — into counters a future dashboard can scrape.
+//
+// Scoped as an on-demand RENDERER, not a live HTTP registry: gittensory-miner is a local CLI, not a daemon, so a
+// caller renders this to stdout for its own scrape/cron setup and reads the ledger itself (no data collection of
+// its own lives here — this stays a pure, side-effect-free function like the rest of gittensory-engine). It mirrors
+// the metric-naming (`gittensory_miner_*_total`) and HELP/TYPE/label conventions of src/selfhost/metrics.ts rather
+// than importing across the package boundary.
+//
+// Counters emitted:
+// - `gittensory_miner_predictions_total{conclusion="..."}` — predictions recorded, one series per predicted
+//   conclusion (e.g. merge/close/hold).
+// - `gittensory_miner_prediction_correct_total` — predictions whose realized outcome matched the prediction.
+// - `gittensory_miner_prediction_incorrect_total` — predictions whose realized outcome differed.
+// The correct/incorrect counters only move for rows carrying a resolved outcome; unresolved rows count toward
+// `predictions_total` only, so the surface is meaningful before outcome-pairing exists and grows once it does.
+export const MINER_PREDICTIONS_TOTAL = "gittensory_miner_predictions_total";
+export const MINER_PREDICTION_CORRECT_TOTAL = "gittensory_miner_prediction_correct_total";
+export const MINER_PREDICTION_INCORRECT_TOTAL = "gittensory_miner_prediction_incorrect_total";
+/** Mirror src/selfhost/metrics.ts:204 — HELP text escapes backslash and newline. */
+function escapeHelpText(help) {
+    return help.replace(/\\/g, "\\\\").replace(/\n/g, "\\n");
+}
+/** Prometheus label-value escaping (backslash, double-quote, newline), a correctness-complete superset of
+ *  src/selfhost/metrics.ts:193's `"`-only escape so an arbitrary conclusion string can never break the line. */
+function escapeLabelValue(value) {
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+}
+/**
+ * Render prediction-calibration counters as Prometheus text-exposition format. Pure and side-effect-free: a caller
+ * supplies the ledger rows (joined with any resolved outcomes) and prints the result. Deterministic — conclusion
+ * series are emitted in sorted order. Always emits HELP/TYPE for every counter, so the surface is well-formed even
+ * for an empty ledger.
+ */
+export function renderMinerPredictionMetrics(rows) {
+    const totalByConclusion = new Map();
+    let correct = 0;
+    let incorrect = 0;
+    for (const row of rows) {
+        totalByConclusion.set(row.conclusion, (totalByConclusion.get(row.conclusion) ?? 0) + 1);
+        if (row.correct === true)
+            correct += 1;
+        else if (row.correct === false)
+            incorrect += 1;
+    }
+    const lines = [];
+    lines.push(`# HELP ${MINER_PREDICTIONS_TOTAL} ${escapeHelpText("Gate-outcome predictions the miner has recorded, by predicted conclusion.")}`);
+    lines.push(`# TYPE ${MINER_PREDICTIONS_TOTAL} counter`);
+    for (const [conclusion, count] of [...totalByConclusion.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+        lines.push(`${MINER_PREDICTIONS_TOTAL}{conclusion="${escapeLabelValue(conclusion)}"} ${count}`);
+    }
+    lines.push(`# HELP ${MINER_PREDICTION_CORRECT_TOTAL} ${escapeHelpText("Predictions whose realized outcome matched the predicted conclusion.")}`);
+    lines.push(`# TYPE ${MINER_PREDICTION_CORRECT_TOTAL} counter`);
+    lines.push(`${MINER_PREDICTION_CORRECT_TOTAL} ${correct}`);
+    lines.push(`# HELP ${MINER_PREDICTION_INCORRECT_TOTAL} ${escapeHelpText("Predictions whose realized outcome differed from the predicted conclusion.")}`);
+    lines.push(`# TYPE ${MINER_PREDICTION_INCORRECT_TOTAL} counter`);
+    lines.push(`${MINER_PREDICTION_INCORRECT_TOTAL} ${incorrect}`);
+    return `${lines.join("\n")}\n`;
+}

package/dist/miner-telemetry.d.ts

@@ -0,0 +1,32 @@
+/** Immutable discovery-plane telemetry event vocabulary — an unknown value fails closed before it is recorded. */
+export declare const MINER_TELEMETRY_EVENT_TYPES: readonly ["query_issued", "candidates_returned", "soft_claim_attempted", "soft_claim_succeeded", "soft_claim_collided"];
+export type MinerTelemetryEventType = (typeof MINER_TELEMETRY_EVENT_TYPES)[number];
+/** Fixed low-cardinality outcome buckets — the discovery-plane analogue of orb-collector's `bucketReasonCode`, so a
+ *  free-text reason can never leak through the telemetry surface. */
+export declare const MINER_TELEMETRY_OUTCOME_BUCKETS: readonly ["ok", "empty", "collision", "rate_limited", "error", "other"];
+export type MinerTelemetryOutcomeBucket = (typeof MINER_TELEMETRY_OUTCOME_BUCKETS)[number];
+/** A single discovery-plane telemetry event, pre-anonymization-checked. `repoHash`/`issueHash` are the exporter's
+ *  per-instance HMAC hashes (orb-collector's `getOrCreateAnonSecret`/`hmacField` posture) — NEVER a raw
+ *  `owner/repo` or issue number. `metrics` is count-only quantitative data (e.g. `candidatesReturned`), never text. */
+export type MinerTelemetryEvent = {
+    eventType: MinerTelemetryEventType;
+    repoHash?: string | null | undefined;
+    issueHash?: string | null | undefined;
+    outcome: MinerTelemetryOutcomeBucket;
+    metrics?: Record<string, number> | undefined;
+};
+/** The normalized, storage/transport-ready form: hashes coerced to `string | null`, metrics serialized to JSON. */
+export type NormalizedMinerTelemetryEvent = {
+    eventType: MinerTelemetryEventType;
+    repoHash: string | null;
+    issueHash: string | null;
+    outcome: MinerTelemetryOutcomeBucket;
+    metricsJson: string;
+};
+/**
+ * Validate and normalize a discovery-plane telemetry event before it is recorded/exported. Fail-closed, mirroring
+ * {@link normalizeGovernorLedgerEvent}: an unknown `eventType`/`outcome`, a non-hash identifier, or a non-numeric
+ * metric throws rather than silently shipping malformed or de-anonymizing data. Defines the contract only — it does
+ * NOT perform the HMAC hashing (that is the exporter's job at #4250's boundary) or send anything.
+ */
+export declare function normalizeMinerTelemetryEvent(input: unknown): NormalizedMinerTelemetryEvent;