@jitsusama/agentic-harness.core 0.1.0

package/dist/observability/types.d.ts

@@ -0,0 +1,82 @@
+/** Token counts for one run, split by channel. */
+export interface RunTokens {
+    readonly input: number;
+    readonly output: number;
+    readonly cacheRead: number;
+    readonly cacheWrite: number;
+    readonly total: number;
+}
+/**
+ * Cost for one run in USD, split by channel. Sourced from pi's own
+ * per-turn usage.cost, summed across every message_end turn of the
+ * run, not from any external proxy.
+ */
+export interface RunCost {
+    readonly input: number;
+    readonly output: number;
+    readonly cacheRead: number;
+    readonly cacheWrite: number;
+    readonly total: number;
+}
+/** Verify gate outcome for one run. */
+export type VerifyOutcome = "passed" | "failed" | "none";
+/**
+ * One subagent run recorded as first-class fields. The
+ * parent session writes a record as each subagent finishes.
+ */
+export interface RunRecord {
+    /** The fleet or council run this subagent belonged to. */
+    readonly runId: string;
+    /** The subagent's stable id within the run. */
+    readonly subagentId: string;
+    /** What produced the run (e.g. council, fleet). */
+    readonly kind: string;
+    /** Resolved model id, or empty when the session default was used. */
+    readonly model: string;
+    /** Persona or reviewer label. */
+    readonly persona: string;
+    /** Whether the verify gate passed, failed, or was not in play. */
+    readonly verifyOutcome: VerifyOutcome;
+    /** Verify retries taken before a valid result (0 when first try passed). */
+    readonly retriesToValid: number;
+    /** Number of warnings the run emitted. */
+    readonly warningCount: number;
+    /** Process exit code. */
+    readonly exitCode: number;
+    /** Token counts summed across the run's turns. */
+    readonly tokens: RunTokens;
+    /** Cost summed across the run's turns. */
+    readonly cost: RunCost;
+    /** When the run started, epoch milliseconds. */
+    readonly startedAt: number;
+}
+/** Aggregate view of one run across its subagents. */
+export interface RunSummary {
+    readonly runId: string;
+    readonly subagentCount: number;
+    readonly passed: number;
+    readonly failed: number;
+    readonly totalRetries: number;
+    readonly totalWarnings: number;
+    readonly tokens: RunTokens;
+    readonly cost: RunCost;
+    /** cacheRead / (input + cacheRead); 0 when the denominator is 0. */
+    readonly cacheReadRatio: number;
+}
+/**
+ * A distilled weekly summary for one model and persona,
+ * kept long after the raw rows it was rolled from age out.
+ */
+export interface RunRollup {
+    /** Start of the week bucket, epoch milliseconds. */
+    readonly weekStart: number;
+    readonly model: string;
+    readonly persona: string;
+    readonly runCount: number;
+    readonly totalRetries: number;
+    readonly totalWarnings: number;
+    readonly tokensTotal: number;
+    readonly costTotal: number;
+    /** cacheRead / (input + cacheRead) across the bucket; 0 when the denominator is 0. */
+    readonly cacheReadRatio: number;
+}

package/dist/observability/types.js

@@ -0,0 +1 @@
+export {};

package/dist/process/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Asking the machine about a process, and saying which one you meant.
+ *
+ * The logic sits in `process.ts` rather than here, as it does for
+ * `exec` and `remote`, because the coverage config excludes every
+ * `index.ts` by name: a module whose whole implementation is its
+ * barrel reports as untested however well tested it is.
+ */
+export { askedOnce, isOwner, type Owner, ownerNow, ownerStanding, type ProcessFacts, SAME_PROCESS_MS, sameProcess, systemFacts, } from "./process.js";

package/dist/process/index.js

@@ -0,0 +1,9 @@
+/**
+ * Asking the machine about a process, and saying which one you meant.
+ *
+ * The logic sits in `process.ts` rather than here, as it does for
+ * `exec` and `remote`, because the coverage config excludes every
+ * `index.ts` by name: a module whose whole implementation is its
+ * barrel reports as untested however well tested it is.
+ */
+export { askedOnce, isOwner, ownerNow, ownerStanding, SAME_PROCESS_MS, sameProcess, systemFacts, } from "./process.js";

package/dist/process/process.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Asking the machine about a process, and saying which one you meant.
+ *
+ * Its own module because more than one domain needs this and neither
+ * owns it: a subagent supervisor asks whether the process holding a
+ * reviewer's lease is still there, and the work broker asks whether
+ * the session holding a worktree is. They are the same question, and
+ * the second was about to be answered by a second copy of the first.
+ *
+ * A pid identifies nothing on its own, which is why the start time
+ * travels with it everywhere here. Pids are reused, and the reuse is
+ * not rare on a machine that spawns a supervisor per reviewer: acting
+ * on a bare pid means signalling, or reclaiming from, whatever process
+ * happens to be wearing that number now.
+ */
+/**
+ * How far apart two readings of one process's start time may be.
+ *
+ * `ps` reports whole seconds and the recorded value has millisecond
+ * precision, so the same process reads differently depending on which
+ * side of a second each observation landed on.
+ */
+export declare const SAME_PROCESS_MS = 2000;
+/**
+ * Asking the machine about a process.
+ *
+ * Injected because it is the one part of this that cannot be decided
+ * from a file, and because a test that exercises it for real is a test
+ * that kills something by a number it read off disk.
+ */
+export interface ProcessFacts {
+    /** When this process started, or undefined when nothing can say. */
+    startedAt(pid: number): Promise<number | undefined>;
+    /** Whether anything is wearing this pid at all. */
+    alive(pid: number): boolean;
+}
+/**
+ * Which process wrote something down.
+ *
+ * Both fields or neither. A pid on its own cannot be checked against
+ * anything later, so a record carrying one is a record that reads as
+ * whoever holds that number next.
+ */
+export interface Owner {
+    pid: number;
+    startedAt: number;
+}
+/**
+ * Whether two observations describe the same process.
+ *
+ * Two-sided on purpose. Only refusing the later ones would let a pid
+ * that has been around far longer than our child pass: a record
+ * holding a garbage or truncated pid can name `1`, and `1` started at
+ * boot, which is emphatically earlier. Signalling that process group
+ * is not a mistake anybody gets to make twice.
+ */
+export declare function sameProcess(observed: number, recorded: number): boolean;
+/** Whether a value read off disk says enough to identify a process. */
+export declare function isOwner(said: unknown): said is Owner;
+/**
+ * Who this process is, for writing down.
+ *
+ * Returns nothing when the machine will not say when we started,
+ * because half an identity is worse than none: a record carrying a
+ * pid and no start time is one a later reader must either trust
+ * blindly or discard, and both of those are decisions this can avoid
+ * forcing by declining to write it.
+ */
+export declare function ownerNow(facts?: ProcessFacts, pid?: number): Promise<Owner | undefined>;
+/**
+ * Whether the process that wrote a record is still the one running.
+ *
+ * Identity outranks liveness in both directions. A live pid whose
+ * start time disagrees is a stranger wearing the number, and is gone
+ * for our purposes; there is no case where a mismatch means present.
+ *
+ * Undecidable when the machine will not answer, which is deliberately
+ * distinct from absent: a caller reclaiming things must treat "cannot
+ * tell" as "still there", and a caller merely reporting need not.
+ */
+export declare function ownerStanding(owner: Owner, facts?: ProcessFacts): Promise<"running" | "gone" | "unknown">;
+/**
+ * Facts about processes, asked once each however often they are wanted.
+ *
+ * The cache holds what the machine said, never what a caller concluded
+ * from it. A standing is a judgement about one record, since it
+ * compares the pid's real start time against the one that record
+ * wrote down, so caching a standing under a pid lets one stale record
+ * answer for a live session that happens to be wearing the same
+ * number. The fact is per-pid and safe to share; the verdict is not,
+ * and this exists because the verdict was cached twice.
+ */
+export declare function askedOnce(facts: ProcessFacts): ProcessFacts;
+/** What the machine itself says, which is what everything but a test uses. */
+export declare const systemFacts: ProcessFacts;

package/dist/process/process.js

@@ -0,0 +1,153 @@
+/**
+ * Asking the machine about a process, and saying which one you meant.
+ *
+ * Its own module because more than one domain needs this and neither
+ * owns it: a subagent supervisor asks whether the process holding a
+ * reviewer's lease is still there, and the work broker asks whether
+ * the session holding a worktree is. They are the same question, and
+ * the second was about to be answered by a second copy of the first.
+ *
+ * A pid identifies nothing on its own, which is why the start time
+ * travels with it everywhere here. Pids are reused, and the reuse is
+ * not rare on a machine that spawns a supervisor per reviewer: acting
+ * on a bare pid means signalling, or reclaiming from, whatever process
+ * happens to be wearing that number now.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+/**
+ * How far apart two readings of one process's start time may be.
+ *
+ * `ps` reports whole seconds and the recorded value has millisecond
+ * precision, so the same process reads differently depending on which
+ * side of a second each observation landed on.
+ */
+export const SAME_PROCESS_MS = 2_000;
+/**
+ * How long to wait for the process table.
+ *
+ * This runs inside walks over every reviewer directory and every
+ * remembered tree, so an unbounded probe against a wedged process
+ * table stalls a session's startup rather than one item's recovery.
+ */
+const PS_TIMEOUT_MS = 2_000;
+/**
+ * Whether two observations describe the same process.
+ *
+ * Two-sided on purpose. Only refusing the later ones would let a pid
+ * that has been around far longer than our child pass: a record
+ * holding a garbage or truncated pid can name `1`, and `1` started at
+ * boot, which is emphatically earlier. Signalling that process group
+ * is not a mistake anybody gets to make twice.
+ */
+export function sameProcess(observed, recorded) {
+    return Math.abs(observed - recorded) <= SAME_PROCESS_MS;
+}
+/** Whether a value read off disk says enough to identify a process. */
+export function isOwner(said) {
+    if (said === null || typeof said !== "object")
+        return false;
+    const owner = said;
+    return (typeof owner.pid === "number" &&
+        owner.pid > 0 &&
+        typeof owner.startedAt === "number");
+}
+/**
+ * Who this process is, for writing down.
+ *
+ * Returns nothing when the machine will not say when we started,
+ * because half an identity is worse than none: a record carrying a
+ * pid and no start time is one a later reader must either trust
+ * blindly or discard, and both of those are decisions this can avoid
+ * forcing by declining to write it.
+ */
+export async function ownerNow(facts = systemFacts, pid = process.pid) {
+    const startedAt = await facts.startedAt(pid);
+    return startedAt === undefined ? undefined : { pid, startedAt };
+}
+/**
+ * Whether the process that wrote a record is still the one running.
+ *
+ * Identity outranks liveness in both directions. A live pid whose
+ * start time disagrees is a stranger wearing the number, and is gone
+ * for our purposes; there is no case where a mismatch means present.
+ *
+ * Undecidable when the machine will not answer, which is deliberately
+ * distinct from absent: a caller reclaiming things must treat "cannot
+ * tell" as "still there", and a caller merely reporting need not.
+ */
+export async function ownerStanding(owner, facts = systemFacts) {
+    if (!facts.alive(owner.pid))
+        return "gone";
+    const startedAt = await facts.startedAt(owner.pid);
+    // Alive, but the table will not say since when. Nothing here can
+    // tell our process from a stranger holding the number, and the
+    // answer that costs work is the confident one.
+    if (startedAt === undefined)
+        return "unknown";
+    return sameProcess(startedAt, owner.startedAt) ? "running" : "gone";
+}
+/**
+ * Facts about processes, asked once each however often they are wanted.
+ *
+ * The cache holds what the machine said, never what a caller concluded
+ * from it. A standing is a judgement about one record, since it
+ * compares the pid's real start time against the one that record
+ * wrote down, so caching a standing under a pid lets one stale record
+ * answer for a live session that happens to be wearing the same
+ * number. The fact is per-pid and safe to share; the verdict is not,
+ * and this exists because the verdict was cached twice.
+ */
+export function askedOnce(facts) {
+    const startedAt = new Map();
+    return {
+        alive: (pid) => facts.alive(pid),
+        startedAt: (pid) => {
+            const already = startedAt.get(pid);
+            if (already !== undefined)
+                return already;
+            const answer = facts.startedAt(pid);
+            startedAt.set(pid, answer);
+            return answer;
+        },
+    };
+}
+/** What the machine itself says, which is what everything but a test uses. */
+export const systemFacts = {
+    async startedAt(pid) {
+        try {
+            // `lstart` rather than `etime`, because elapsed time is
+            // relative to now and the comparison wants an absolute
+            // moment. LC_ALL is pinned because the output is a formatted
+            // date: under a locale Date.parse cannot read, every identity
+            // check would decline and every caller would fall back to its
+            // own worst branch without saying anything.
+            const { stdout } = await promisify(execFile)("ps", ["-o", "lstart=", "-p", String(pid)], { timeout: PS_TIMEOUT_MS, env: { ...process.env, LC_ALL: "C" } });
+            const parsed = Date.parse(stdout.trim());
+            return Number.isNaN(parsed) ? undefined : parsed;
+        }
+        catch {
+            // No such process, no ps, or a process table too wedged to
+            // answer in time. Nothing here knows what it would be talking
+            // about, and saying so is the safe answer.
+            return undefined;
+        }
+    },
+    alive(pid) {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (error) {
+            // EPERM means a process is there and is not ours to signal,
+            // which is emphatically alive. Collapsing it into "gone" was
+            // safe reasoning for a supervisor we spawned ourselves, since
+            // one we may not signal cannot be ours; it is not safe for a
+            // worktree, where the holder can be another user's session and
+            // the penalty for guessing is deleting their work.
+            if (error?.code === "EPERM")
+                return true;
+            return false;
+        }
+    },
+};

package/dist/prose/block.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Turns detected prose violations into a single skill-grounded
+ * instruction the guardian hands back to the author. The message
+ * names every violation and points at the prose-standard skill so
+ * the retry is informed, not a guess.
+ */
+import type { ProseViolation } from "./detect.js";
+/** Format prose violations into a block message, or "" if none. */
+export declare function formatProseBlock(violations: ProseViolation[]): string;

package/dist/prose/block.js

@@ -0,0 +1,43 @@
+/**
+ * Turns detected prose violations into a single skill-grounded
+ * instruction the guardian hands back to the author. The message
+ * names every violation and points at the prose-standard skill so
+ * the retry is informed, not a guess.
+ */
+import { count } from "../ui/count.js";
+/** Format prose violations into a block message, or "" if none. */
+export function formatProseBlock(violations) {
+    if (violations.length === 0)
+        return "";
+    const lines = [
+        "This text does not follow the prose-standard skill. Fix the",
+        "violations below and try again, applying the skill's nuance",
+        "rather than a mechanical substitution.",
+        "",
+    ];
+    const emdashes = violations.filter((v) => v.kind === "emdash");
+    if (emdashes.length > 0) {
+        const count = emdashes.length;
+        lines.push(`- ${count} emdash${count === 1 ? "" : "es"}: never use emdashes.`, "  Restructure the sentence (a colon, a semi-colon, parentheses", "  or a new sentence), per prose-standard.");
+    }
+    // Deduplicate spellings by their found -> suggestion pairing so a
+    // word that recurs is named once.
+    const spellings = new Map();
+    for (const v of violations) {
+        if (v.kind !== "spelling" || !v.suggestion)
+            continue;
+        spellings.set(v.found.toLowerCase(), `${v.found} -> ${v.suggestion}`);
+    }
+    if (spellings.size > 0) {
+        lines.push(`- Non-Canadian spelling: ${[...spellings.values()].join(", ")}.`, "  Use Canadian English spelling exclusively, per prose-standard.");
+    }
+    const curly = violations.filter((v) => v.kind === "curly-quote");
+    if (curly.length > 0) {
+        lines.push(`- ${count(curly.length, "curly quote")}: use straight quotes`, "  ('' and \"\") instead, per prose-standard.");
+    }
+    const ellipses = violations.filter((v) => v.kind === "ellipsis");
+    if (ellipses.length > 0) {
+        lines.push(`- ${count(ellipses.length, "Unicode ellipsis character")}: spell it`, "  out as three periods (...), per prose-standard.");
+    }
+    return lines.join("\n");
+}

package/dist/prose/detect.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Prose convention detection: finds the mechanically certain
+ * violations of the writing voice (emdashes and non-Canadian
+ * spelling) so a guardian can block and point the author at the
+ * skill. Detection never rewrites; it names what is wrong and
+ * leaves the nuanced repair to the author.
+ */
+/** A single prose convention violation. */
+export interface ProseViolation {
+    /** Which rule was broken. */
+    readonly kind: "emdash" | "spelling" | "curly-quote" | "ellipsis";
+    /** The offending text as it appears. */
+    readonly found: string;
+    /** The Canadian replacement, when there is a single right one. */
+    readonly suggestion?: string;
+    /** A short statement of the rule, for the block message. */
+    readonly rule: string;
+}
+/**
+ * Curated American/British to Canadian spelling pairs. This is a
+ * deliberate allowlist, not a rule. A rule-based `-ize`/`-ise`
+ * or `-or`/`-our` check produces a flood of false positives
+ * (`size`, `noise`, `surprise`, `otherwise`, `doctor`,
+ * `anchor`), so each pair here is one we are certain about. The
+ * key is the form to flag; the value is the Canadian form.
+ *
+ * This list is the enforced half of a bound pair: the prose-standard
+ * skill carries the same table for a human to read, and
+ * tests/lib/prose/spelling-binding.test.ts asserts the two are
+ * identical, so neither can drift from the other. To change what
+ * the gate flags, change the skill and this list together.
+ *
+ * Meaning-dependent words are deliberately excluded so the gate
+ * never flags a correct spelling: `licence`/`license`,
+ * `practice`/`practise` and `cheque`/`check` turn on part of
+ * speech or sense; `meter` (the instrument) is correct while
+ * `metre` (the unit) is not; `aluminum`, `program` and `dialog`
+ * (the UI element) are the spellings Canadian English keeps. A
+ * miss is a missed block, never a wrong rewrite.
+ *
+ * Stored lowercase; matching is case-insensitive and the
+ * suggestion preserves the original's leading-capital shape.
+ */
+export declare const SPELLING_PAIRS: ReadonlyArray<readonly [string, string]>;
+/**
+ * Find every emdash and non-Canadian spelling in prose, skipping
+ * regions where the text is not prose (code fences, inline code,
+ * URLs, paths).
+ */
+export declare function detectProseViolations(text: string): ProseViolation[];

package/dist/prose/detect.js

@@ -0,0 +1,217 @@
+/**
+ * Prose convention detection: finds the mechanically certain
+ * violations of the writing voice (emdashes and non-Canadian
+ * spelling) so a guardian can block and point the author at the
+ * skill. Detection never rewrites; it names what is wrong and
+ * leaves the nuanced repair to the author.
+ */
+const EMDASH_RULE = "prose-standard: never use emdashes; restructure the sentence (a colon, semi-colon, parentheses or a new sentence).";
+const SPELLING_RULE = "prose-standard: use Canadian English spelling exclusively.";
+const CURLY_QUOTE_RULE = "prose-standard: use straight quotes, not curly ones.";
+const ELLIPSIS_RULE = "prose-standard: spell out an ellipsis as three periods, not the Unicode character.";
+/**
+ * Curated American/British to Canadian spelling pairs. This is a
+ * deliberate allowlist, not a rule. A rule-based `-ize`/`-ise`
+ * or `-or`/`-our` check produces a flood of false positives
+ * (`size`, `noise`, `surprise`, `otherwise`, `doctor`,
+ * `anchor`), so each pair here is one we are certain about. The
+ * key is the form to flag; the value is the Canadian form.
+ *
+ * This list is the enforced half of a bound pair: the prose-standard
+ * skill carries the same table for a human to read, and
+ * tests/lib/prose/spelling-binding.test.ts asserts the two are
+ * identical, so neither can drift from the other. To change what
+ * the gate flags, change the skill and this list together.
+ *
+ * Meaning-dependent words are deliberately excluded so the gate
+ * never flags a correct spelling: `licence`/`license`,
+ * `practice`/`practise` and `cheque`/`check` turn on part of
+ * speech or sense; `meter` (the instrument) is correct while
+ * `metre` (the unit) is not; `aluminum`, `program` and `dialog`
+ * (the UI element) are the spellings Canadian English keeps. A
+ * miss is a missed block, never a wrong rewrite.
+ *
+ * Stored lowercase; matching is case-insensitive and the
+ * suggestion preserves the original's leading-capital shape.
+ */
+export const SPELLING_PAIRS = [
+    // -our (American -or)
+    ["color", "colour"],
+    ["colors", "colours"],
+    ["colored", "coloured"],
+    ["behavior", "behaviour"],
+    ["behaviors", "behaviours"],
+    ["honor", "honour"],
+    ["honored", "honoured"],
+    ["favor", "favour"],
+    ["favored", "favoured"],
+    ["favorite", "favourite"],
+    ["favorites", "favourites"],
+    ["neighbor", "neighbour"],
+    ["neighbors", "neighbours"],
+    ["labor", "labour"],
+    ["flavor", "flavour"],
+    ["flavors", "flavours"],
+    ["valor", "valour"],
+    ["vapor", "vapour"],
+    ["rumor", "rumour"],
+    ["humor", "humour"],
+    ["harbor", "harbour"],
+    ["armor", "armour"],
+    ["endeavor", "endeavour"],
+    ["savior", "saviour"],
+    // -re (American -er)
+    ["center", "centre"],
+    ["centers", "centres"],
+    ["centered", "centred"],
+    ["theater", "theatre"],
+    ["theaters", "theatres"],
+    ["fiber", "fibre"],
+    ["fibers", "fibres"],
+    ["liter", "litre"],
+    ["liters", "litres"],
+    // -ce noun (American -se)
+    ["defense", "defence"],
+    ["defenses", "defences"],
+    ["offense", "offence"],
+    ["offenses", "offences"],
+    // -ize (British -ise; Canadian keeps -ize like American)
+    ["organise", "organize"],
+    ["organised", "organized"],
+    ["organising", "organizing"],
+    ["recognise", "recognize"],
+    ["recognised", "recognized"],
+    ["summarise", "summarize"],
+    ["summarised", "summarized"],
+    ["analyse", "analyze"],
+    ["analysed", "analyzed"],
+    ["prioritise", "prioritize"],
+    ["prioritised", "prioritized"],
+    ["realise", "realize"],
+    ["realised", "realized"],
+    ["minimise", "minimize"],
+    ["maximise", "maximize"],
+    ["optimise", "optimize"],
+    ["initialise", "initialize"],
+    ["initialised", "initialized"],
+    ["standardise", "standardize"],
+    ["customise", "customize"],
+    ["generalise", "generalize"],
+    ["specialise", "specialize"],
+    ["normalise", "normalize"],
+    ["serialise", "serialize"],
+    ["synchronise", "synchronize"],
+    // doubled consonant before a suffix (Canadian doubles the l)
+    ["traveler", "traveller"],
+    ["traveled", "travelled"],
+    ["traveling", "travelling"],
+    ["canceled", "cancelled"],
+    ["canceling", "cancelling"],
+    ["modeling", "modelling"],
+    ["modeled", "modelled"],
+    ["labeling", "labelling"],
+    ["labeled", "labelled"],
+    ["fueled", "fuelled"],
+    // -ogue (American -og)
+    ["catalog", "catalogue"],
+    ["catalogs", "catalogues"],
+    // grey (American gray)
+    ["gray", "grey"],
+    ["grays", "greys"],
+    // single l (American doubles)
+    ["enroll", "enrol"],
+    ["enrollment", "enrolment"],
+    ["fulfill", "fulfil"],
+    ["fulfillment", "fulfilment"],
+];
+/** Build the case-insensitive, whole-word spelling regex once. */
+const SPELLING_LOOKUP = new Map(SPELLING_PAIRS);
+const SPELLING_REGEX = new RegExp(`\\b(${SPELLING_PAIRS.map(([from]) => from).join("|")})\\b`, "gi");
+const EMDASH_REGEX = /\u2014/g;
+// The literal six-character escape an author types when they
+// meant an emdash. prose-standard bans it as an emdash in
+// disguise, so it is reported under the same kind.
+const EMDASH_ESCAPE_REGEX = /\\u2014/gi;
+const CURLY_QUOTE_REGEX = /[\u2018\u2019\u201C\u201D]/g;
+const ELLIPSIS_REGEX = /\u2026/g;
+const FENCE_REGEX = /```[\s\S]*?```/g;
+/** Map a curly quote to its straight ASCII equivalent. */
+const STRAIGHT_QUOTE = {
+    "\u2018": "'",
+    "\u2019": "'",
+    "\u201C": '"',
+    "\u201D": '"',
+};
+const INLINE_CODE_REGEX = /`[^`\n]*`/g;
+const URL_REGEX = /https?:\/\/\S+/g;
+// Deliberately conservative: only tokens that clearly open as a
+// path or home reference (`~/`, `./`, `/`) are masked. Masking
+// every slash-joined token would eat ordinary prose like
+// "and/or" and "3/4" and could swallow a real spelling violation
+// that follows. A bare relative path that slips through is
+// almost always backticked anyway, and the worst case is a false
+// block the author clears by wrapping the path in backticks.
+const PATH_REGEX = /(?:^|\s)[~./][\w./-]*\/[\w./-]+/g;
+/**
+ * Replace every match of a pattern with spaces of the same
+ * length, so later offset-based scans see blanks where the
+ * non-prose region was without the surrounding text shifting.
+ */
+function blankOut(text, pattern) {
+    return text.replace(pattern, (match) => " ".repeat(match.length));
+}
+/** Preserve the original's leading-capital shape on a suggestion. */
+function matchCase(found, suggestion) {
+    if (found[0] && found[0] === found[0].toUpperCase()) {
+        return suggestion[0].toUpperCase() + suggestion.slice(1);
+    }
+    return suggestion;
+}
+/**
+ * Find every emdash and non-Canadian spelling in prose, skipping
+ * regions where the text is not prose (code fences, inline code,
+ * URLs, paths).
+ */
+export function detectProseViolations(text) {
+    // Mask non-prose regions first so their contents never match.
+    let prose = blankOut(text, FENCE_REGEX);
+    prose = blankOut(prose, INLINE_CODE_REGEX);
+    prose = blankOut(prose, URL_REGEX);
+    prose = blankOut(prose, PATH_REGEX);
+    const violations = [];
+    for (const match of prose.matchAll(EMDASH_REGEX)) {
+        violations.push({ kind: "emdash", found: match[0], rule: EMDASH_RULE });
+    }
+    for (const match of prose.matchAll(EMDASH_ESCAPE_REGEX)) {
+        violations.push({ kind: "emdash", found: match[0], rule: EMDASH_RULE });
+    }
+    for (const match of prose.matchAll(CURLY_QUOTE_REGEX)) {
+        violations.push({
+            kind: "curly-quote",
+            found: match[0],
+            suggestion: STRAIGHT_QUOTE[match[0]],
+            rule: CURLY_QUOTE_RULE,
+        });
+    }
+    for (const match of prose.matchAll(ELLIPSIS_REGEX)) {
+        violations.push({
+            kind: "ellipsis",
+            found: match[0],
+            suggestion: "...",
+            rule: ELLIPSIS_RULE,
+        });
+    }
+    for (const match of prose.matchAll(SPELLING_REGEX)) {
+        const found = match[0];
+        const canadian = SPELLING_LOOKUP.get(found.toLowerCase());
+        if (!canadian)
+            continue;
+        violations.push({
+            kind: "spelling",
+            found,
+            suggestion: matchCase(found, canadian),
+            rule: SPELLING_RULE,
+        });
+    }
+    return violations;
+}