@event4u/agent-config 16.5.0 → 17.0.0

package/src/scripts/_lib/subagent_steering.ts

@@ -11,6 +11,9 @@
  * automatic stop is the per-target N=3 budget.
  */
 
+import { TIER_TO_CLAUDE_MODEL } from './model_tier.js';
+import type { DispatchOutcome, RecordInput } from './orchestration_record.js';
+
 /** Max consecutive failed attempts on one validation target before halting. */
 export const MAX_ATTEMPTS_PER_TARGET = 3;
 
@@ -389,3 +392,367 @@ export function escalateOnVerifyFail(inp: VerifyFailInputs): VerifyFailDecision
         reason: `verify-fail on ${inp.failed_tier} → re-dispatch one tier up (${above}); consumes the N=3 budget`,
     };
 }
+
+export interface LiteEscalationInput {
+    /** How the lite leg ended: it returns to the head with a named outcome, never a retry inside the leg. */
+    outcome: Exclude<DispatchOutcome, 'DONE'>;
+    /** Consecutive failed attempts on this slice including the lite one. */
+    consecutive_failures: number;
+    ts: string;
+    ids: readonly [string, string];
+}
+
+/**
+ * The records a lite leg that could not finish leaves behind: one `lite`
+ * record with its outcome and, when the cascade allows a climb, one record of
+ * the head's re-dispatch one tier up. The climb is the head's, so the lite
+ * record never carries `escalated`.
+ */
+export function liteEscalationRecords(inp: LiteEscalationInput): RecordInput[] {
+    const lite: RecordInput = {
+        spawn_count: 1,
+        token_delta: 0,
+        token_delta_provenance: 'estimated',
+        verify_mode: 'none',
+        tier_chosen: 'lite',
+        tier_source: 'inferred',
+        model_requested: TIER_TO_CLAUDE_MODEL['lite'],
+        dispatch_outcome: inp.outcome,
+        ts: inp.ts,
+        id: inp.ids[0],
+    };
+    const next = escalateOnVerifyFail({ failed_tier: 'lite', tier_source: 'inferred', consecutive_failures: inp.consecutive_failures });
+    if (next.action !== 'escalate' || next.next_tier === null) return [lite];
+    return [
+        lite,
+        {
+            spawn_count: 1,
+            token_delta: 0,
+            token_delta_provenance: 'estimated',
+            verify_mode: 'none',
+            tier_chosen: next.next_tier,
+            tier_source: 'inferred',
+            model_requested: TIER_TO_CLAUDE_MODEL[next.next_tier],
+            escalated: true,
+            escalated_from: 'lite',
+            ts: inp.ts,
+            id: inp.ids[1],
+        },
+    ];
+}
+
+/**
+ * Transient-failure handling, split by error class — the transient-failure
+ * retry rule of the `subagent-steering` contract, as two pure steps: classify
+ * the raw failure, then decide the transition and the slot's next state.
+ *
+ * Neither dispatches anything. The contract text is what a dispatching model
+ * reads; these are its tested reference, and a caller carries `next_state`
+ * forward so a sequence of failures is decided over the same counters.
+ *
+ * Only a slice declared read-only or idempotent is re-dispatched: a subagent's
+ * first run may have acted before it failed, and discarding its late result
+ * does not stop it. Any other slice escalates unretried. A slot whose N=3
+ * budget is already spent is refused. Slot counters persist across every
+ * attempt of the slot. A rate limit is never answered with a smaller model: the
+ * limiter's scope (model, account or organisation) is not known. A park is not
+ * a failed attempt; the dispatch after recovery is the same attempt at the same
+ * tier. A slot parks once — a rate limit, or a `Retry-After` the run cannot be
+ * shown to wait out — and the next park consumes an attempt, so repeated limits
+ * reach the N=3 budget. A consumed attempt is a spawn failure, never a
+ * verification failure. After a consumed attempt the next one starts at the
+ * slot's original tier, with no downshift left once one was taken.
+ */
+export type TransientErrorClass = 'rate_limit' | 'overloaded' | 'server_error' | 'timeout';
+
+export interface RawTransientFailure {
+    http_status: number | null;
+    /** Provider error type, when the response carries one. */
+    error_type: string | null;
+    /** The client deadline fired before the response completed. */
+    client_deadline: boolean;
+    /**
+     * Bytes of the model's response arrived before the failure. An error status
+     * line and its error body are not response bytes; an error event inside a
+     * stream that had already produced output is.
+     */
+    response_started: boolean;
+    /** The connection was never established (DNS failure, connection refused). */
+    connect_failed: boolean;
+}
+
+/**
+ * `null` means not transient: the failure escalates to the orchestrator
+ * unretried. Once a response byte arrived the request may have been acted on,
+ * so nothing is transient after that — no status, no error type, no deadline,
+ * which is why that check runs first. A missing status with no bytes is
+ * transient only when the connection was observed never to open — the absence
+ * alone proves nothing.
+ */
+export function classifyTransientFailure(raw: RawTransientFailure): TransientErrorClass | null {
+    const f = rawSnapshot(raw);
+    if (f === null) return null;
+    if (f.response_started) return null;
+    if (f.http_status === 429 || f.error_type === 'rate_limit_error') return 'rate_limit';
+    if (f.http_status === 529 || f.error_type === 'overloaded_error') return 'overloaded';
+    if (f.http_status !== null && f.http_status >= 500 && f.http_status <= 599) return 'server_error';
+    if (f.client_deadline) return 'timeout';
+    if (f.http_status === null && f.connect_failed) return 'server_error';
+    return null;
+}
+
+/**
+ * A plain copy of `keys`, each an own DATA property of `v`, or `null`. An
+ * inherited value, an accessor, an array or a proxy trap that throws is
+ * refused, and the copy is what gets decided over, so nothing read afterwards
+ * can change or throw. A caller may be untyped.
+ */
+function ownData(v: unknown, keys: readonly string[]): Record<string, unknown> | null {
+    if (v === null || typeof v !== 'object') return null;
+    // Inside the `try`: `Array.isArray` throws on a revoked proxy.
+    try {
+        if (Array.isArray(v)) return null;
+        const out: Record<string, unknown> = {};
+        for (const k of keys) {
+            const d = Object.getOwnPropertyDescriptor(v, k);
+            if (d === undefined || !('value' in d)) return null;
+            out[k] = d.value;
+        }
+        return out;
+    } catch {
+        return null;
+    }
+}
+
+const RAW_KEYS = ['http_status', 'error_type', 'client_deadline', 'response_started', 'connect_failed'] as const;
+
+/** The raw failure as own data with its declared types, or `null`. */
+function rawSnapshot(f: unknown): RawTransientFailure | null {
+    const o = ownData(f, RAW_KEYS);
+    if (o === null) return null;
+    const status = o['http_status'];
+    if (status !== null && !(typeof status === 'number' && Number.isInteger(status))) return null;
+    const type = o['error_type'];
+    if (type !== null && typeof type !== 'string') return null;
+    if (!['client_deadline', 'response_started', 'connect_failed'].every((k) => typeof o[k] === 'boolean')) return null;
+    return o as unknown as RawTransientFailure;
+}
+
+export interface SlotState {
+    original_tier: EscalationTier;
+    current_tier: EscalationTier;
+    /** The cap is one per slot, across every class and attempt. */
+    downshifts_used: 0 | 1;
+    /** Parks taken, of any cause; one per slot. */
+    parks: number;
+    attempts_consumed: number;
+}
+
+export interface TransientFailureInputs {
+    error_class: TransientErrorClass;
+    /** A valid `Retry-After`, in milliseconds; `null` when absent or unparseable. */
+    retry_after_ms: number | null;
+    slot: SlotState;
+    /**
+     * The slice is declared read-only or idempotent, so a re-run cannot
+     * duplicate an effect. Only the literal `true` counts. Its provenance is the
+     * dispatcher's own record from before the dispatch — the slice spec it
+     * wrote, or a definition whose tool grant holds no write tool — never the
+     * subagent's output, status envelope or self-description.
+     */
+    retry_safe: boolean;
+    /** Time left in the run, from the dispatcher's own clock; `null` when unknown. */
+    run_remaining_ms: number | null;
+}
+
+const TIER_RANK: Readonly<Record<EscalationTier, number>> = { lite: 0, medium: 1, high: 2 };
+
+/** Own keys only: `in` would admit `toString`, `constructor` and `__proto__`. */
+function isEscalationTier(t: unknown): t is EscalationTier {
+    return typeof t === 'string' && Object.hasOwn(TIER_RANK, t);
+}
+
+function isCount(n: unknown): boolean {
+    return typeof n === 'number' && Number.isInteger(n) && n >= 0;
+}
+
+/**
+ * Why the caller-supplied slot or clock cannot be decided over, or `null`. The
+ * counters are carried by the caller between calls, so this function never
+ * assumes they are well-formed: a tier outside the ladder, a downshift that did
+ * not lower the tier, or a non-integer count is refused rather than decided.
+ */
+const ERROR_CLASSES: ReadonlySet<unknown> = new Set<TransientErrorClass>(['rate_limit', 'overloaded', 'server_error', 'timeout']);
+
+const INPUT_KEYS = ['error_class', 'retry_after_ms', 'slot', 'retry_safe', 'run_remaining_ms'] as const;
+const SLOT_KEYS = ['original_tier', 'current_tier', 'downshifts_used', 'parks', 'attempts_consumed'] as const;
+
+/**
+ * The input as own data, validated, or the name of what is malformed. The
+ * returned copy — slot included — is what the decision reads, so the caller's
+ * objects are never read twice.
+ */
+function snapshotInput(inp: unknown): { ok: TransientFailureInputs } | { malformed: string } {
+    const i = ownData(inp, INPUT_KEYS);
+    if (i === null) return { malformed: 'input' };
+    if (!ERROR_CLASSES.has(i['error_class'])) return { malformed: 'error_class' };
+    if (i['retry_after_ms'] !== null && typeof i['retry_after_ms'] !== 'number') return { malformed: 'retry_after_ms' };
+    if (typeof i['retry_safe'] !== 'boolean') return { malformed: 'retry_safe' };
+    const s = ownData(i['slot'], SLOT_KEYS);
+    if (s === null) return { malformed: 'slot' };
+    const o = s['original_tier'];
+    const c = s['current_tier'];
+    if (!isEscalationTier(o)) return { malformed: 'original_tier' };
+    if (!isEscalationTier(c)) return { malformed: 'current_tier' };
+    const used = s['downshifts_used'];
+    if (used !== 0 && used !== 1) return { malformed: 'downshifts_used' };
+    const drop = TIER_RANK[o] - TIER_RANK[c];
+    // After a consumed attempt the slot is back at its original tier with its
+    // downshift still spent, so the tier sits at most one downshift below.
+    if (drop < 0 || drop > used) return { malformed: 'current_tier against downshifts_used' };
+    if (!isCount(s['parks'])) return { malformed: 'parks' };
+    if (!isCount(s['attempts_consumed'])) return { malformed: 'attempts_consumed' };
+    const r = i['run_remaining_ms'];
+    if (r !== null && !(typeof r === 'number' && Number.isFinite(r) && r >= 0)) return { malformed: 'run_remaining_ms' };
+    return { ok: { ...(i as unknown as TransientFailureInputs), slot: s as unknown as SlotState } };
+}
+
+interface TransientDecisionBase {
+    redispatch_same_turn: boolean;
+    /** Minimum wait before the next dispatch; binding over any other signal. */
+    wait_ms: number | null;
+    /** Re-run `decideWorkerReuse` before the next dispatch. */
+    rerun_reuse_decision: boolean;
+    /** One N=3 attempt and one `spawn_failure_rate` failure. */
+    attempt_consumed: boolean;
+    /** The N=3 budget is spent; the slice fails and the orchestrator replans. */
+    budget_exhausted: boolean;
+    /** A timed-out call may still return; its output is discarded unread. */
+    discard_late_result: boolean;
+    reason: string;
+}
+
+/** A decision over a well-formed input: the slot's next tier and counters. */
+export interface WellFormedTransientDecision extends TransientDecisionBase {
+    malformed: false;
+    action: 'park' | 'downshift' | 'count-failure' | 'escalate' | 'refuse';
+    /** Tier of the next dispatch of this slot. */
+    next_tier: EscalationTier;
+    next_state: SlotState;
+}
+
+/**
+ * The input could not be decided over. It carries no tier and no state: the
+ * caller's own slot is the only record, and nothing here vouches for it.
+ */
+export interface MalformedTransientDecision extends TransientDecisionBase {
+    malformed: true;
+    action: 'escalate';
+    next_tier: null;
+    next_state: null;
+}
+
+export type TransientFailureDecision = WellFormedTransientDecision | MalformedTransientDecision;
+
+const TIER_BELOW: Readonly<Record<EscalationTier, EscalationTier | null>> = {
+    lite: null,
+    medium: 'lite',
+    high: 'medium',
+};
+
+export function transientFailureAction(input: TransientFailureInputs): TransientFailureDecision {
+    // Snapshotted and validated before anything reads a field: the escalation
+    // below must not throw on the input it exists to refuse.
+    const snap = snapshotInput(input);
+    if ('malformed' in snap) {
+        const malformed = snap.malformed;
+        return {
+            malformed: true,
+            action: 'escalate',
+            redispatch_same_turn: false,
+            wait_ms: null,
+            next_tier: null,
+            rerun_reuse_decision: false,
+            attempt_consumed: false,
+            budget_exhausted: false,
+            discard_late_result: false,
+            next_state: null,
+            reason: `malformed ${malformed} — escalate unretried, no counter moved`,
+        };
+    }
+    const inp = snap.ok;
+    const s = inp.slot;
+    const wait_ms = inp.retry_after_ms !== null && Number.isFinite(inp.retry_after_ms) && inp.retry_after_ms >= 0
+        ? inp.retry_after_ms
+        : null;
+    const discard_late_result = inp.error_class === 'timeout';
+    const halt = (action: 'escalate' | 'refuse', reason: string): WellFormedTransientDecision => ({
+        malformed: false,
+        action,
+        redispatch_same_turn: false,
+        wait_ms,
+        next_tier: s.current_tier,
+        rerun_reuse_decision: false,
+        attempt_consumed: false,
+        budget_exhausted: budgetHalt(s.attempts_consumed),
+        discard_late_result,
+        next_state: s,
+        reason,
+    });
+    const consume = (reason: string): WellFormedTransientDecision => {
+        const attempts_consumed = s.attempts_consumed + 1;
+        return {
+            malformed: false,
+            action: 'count-failure',
+            redispatch_same_turn: false,
+            wait_ms,
+            next_tier: s.original_tier,
+            rerun_reuse_decision: true,
+            attempt_consumed: true,
+            budget_exhausted: budgetHalt(attempts_consumed),
+            discard_late_result,
+            next_state: { ...s, current_tier: s.original_tier, attempts_consumed },
+            reason,
+        };
+    };
+    const park = (reason: string): WellFormedTransientDecision => {
+        if (s.parks >= 1) return consume(`${inp.error_class} on a slot that already parked — one attempt consumed, no second park`);
+        return {
+            malformed: false,
+            action: 'park',
+            redispatch_same_turn: false,
+            wait_ms,
+            next_tier: s.current_tier,
+            rerun_reuse_decision: true,
+            attempt_consumed: false,
+            budget_exhausted: false,
+            discard_late_result,
+            next_state: { ...s, parks: s.parks + 1 },
+            reason,
+        };
+    };
+
+    if (budgetHalt(s.attempts_consumed)) return halt('refuse', 'the N=3 budget of this slot is already spent — no further dispatch');
+    if (inp.retry_safe !== true) return halt('escalate', `${inp.error_class} on a slice not declared read-only or idempotent — escalate unretried`);
+    if (inp.error_class === 'rate_limit') {
+        return park('rate_limit — park until a recovery signal, then re-run the reuse decision at the same tier');
+    }
+    if (wait_ms !== null && (inp.run_remaining_ms === null || wait_ms > inp.run_remaining_ms)) {
+        return park(`${inp.error_class} with a Retry-After the run cannot be shown to wait out — park, no same-turn re-dispatch`);
+    }
+    const below = TIER_BELOW[s.current_tier];
+    if (s.downshifts_used >= 1 || below === null) return consume(`${inp.error_class} with no downshift left — one attempt consumed`);
+    return {
+        malformed: false,
+        action: 'downshift',
+        redispatch_same_turn: true,
+        wait_ms,
+        next_tier: below,
+        rerun_reuse_decision: false,
+        attempt_consumed: false,
+        budget_exhausted: false,
+        discard_late_result,
+        next_state: { ...s, current_tier: below, downshifts_used: 1 },
+        reason: `${inp.error_class} — retry once at ${below}`,
+    };
+}

package/src/scripts/_lib/svg_filled_counter.ts

@@ -0,0 +1,287 @@
+/**
+ * `svg-structure-filled-counter` — step 3.2 of `road-to-type-with-a-witness`.
+ *
+ * A letter with a counter (o, e, a, B, 8) or an O-ring mark is one path with an
+ * outer and an inner contour. Under `fill-rule="nonzero"`, the default, the
+ * counter stays open only when the inner contour winds the OTHER way: a
+ * same-direction inner contour adds to the winding number and the counter
+ * paints. Measured on the repo's Chromium: two same-direction circles of radius
+ * 250 and 160 painted 196,282 px, the ring they should be 115,940.
+ *
+ * The check flattens each subpath to a polygon, sums the winding signs of the
+ * subpaths that contain a subpath's every vertex, and reports the subpath when
+ * that sum is nonzero and shares its own sign — it sits in a painted region and
+ * deepens it instead of cutting it out. It is advisory (decision A8): `warning`, never `error`, until
+ * the false-positive census of step 3.3 says otherwise.
+ *
+ * Limits, stated rather than guessed around: a transform does not change a
+ * winding sign unless it mirrors, and a mirror flips both contours alike, so
+ * transforms are ignored; `fill-rule` set from a stylesheet selector is not
+ * read — an attribute or inline style, on the path or an ancestor, is.
+ */
+
+import { tokenisePath } from './svg_geometry.js';
+import type { Finding, SvgElement } from './svg_rules.js';
+
+type Pt = [number, number];
+
+export interface FilledCounter {
+    /** The `<path>` element. */
+    element: SvgElement;
+    /** 1-based index of the subpath that should be a counter. */
+    inner: number;
+    /** 1-based index of the subpath that contains it. */
+    outer: number;
+}
+
+const CURVE_STEPS = 12;
+const MAX_SUBPATHS = 400;
+
+function styleProp(el: SvgElement, prop: string): string | undefined {
+    const direct = el.attrs[prop];
+    if (direct !== undefined) return direct.trim();
+    const m = new RegExp(`(?:^|;)\\s*${prop}\\s*:\\s*([^;]+)`, 'i').exec(el.attrs['style'] ?? '');
+    return m?.[1]?.trim();
+}
+
+function arcPoints(from: Pt, args: number[]): Pt[] {
+    const [rxIn, ryIn, rotDeg, large, sweep, x, y] = args as [number, number, number, number, number, number, number];
+    const [x1, y1] = from;
+    let rx = Math.abs(rxIn);
+    let ry = Math.abs(ryIn);
+    if (rx === 0 || ry === 0 || (x1 === x && y1 === y)) return [[x, y]];
+    const phi = (rotDeg * Math.PI) / 180;
+    const cos = Math.cos(phi);
+    const sin = Math.sin(phi);
+    const dx = (x1 - x) / 2;
+    const dy = (y1 - y) / 2;
+    const xp = cos * dx + sin * dy;
+    const yp = -sin * dx + cos * dy;
+    const lambda = (xp * xp) / (rx * rx) + (yp * yp) / (ry * ry);
+    if (lambda > 1) {
+        rx *= Math.sqrt(lambda);
+        ry *= Math.sqrt(lambda);
+    }
+    const num = rx * rx * ry * ry - rx * rx * yp * yp - ry * ry * xp * xp;
+    const den = rx * rx * yp * yp + ry * ry * xp * xp;
+    const coef = (large === sweep ? -1 : 1) * Math.sqrt(Math.max(0, num / den));
+    const cxp = (coef * rx * yp) / ry;
+    const cyp = (-coef * ry * xp) / rx;
+    const cx = cos * cxp - sin * cyp + (x1 + x) / 2;
+    const cy = sin * cxp + cos * cyp + (y1 + y) / 2;
+    const angle = (ux: number, uy: number, vx: number, vy: number): number => {
+        const a = Math.atan2(ux * vy - uy * vx, ux * vx + uy * vy);
+        return a;
+    };
+    const t1 = angle(1, 0, (xp - cxp) / rx, (yp - cyp) / ry);
+    let dt = angle((xp - cxp) / rx, (yp - cyp) / ry, (-xp - cxp) / rx, (-yp - cyp) / ry);
+    if (!sweep && dt > 0) dt -= 2 * Math.PI;
+    if (sweep && dt < 0) dt += 2 * Math.PI;
+    const out: Pt[] = [];
+    for (let k = 1; k <= CURVE_STEPS; k++) {
+        const t = t1 + (dt * k) / CURVE_STEPS;
+        const ex = rx * Math.cos(t);
+        const ey = ry * Math.sin(t);
+        out.push([cos * ex - sin * ey + cx, sin * ex + cos * ey + cy]);
+    }
+    return out;
+}
+
+function bezier(p0: Pt, p1: Pt, p2: Pt, p3: Pt): Pt[] {
+    const out: Pt[] = [];
+    for (let k = 1; k <= CURVE_STEPS; k++) {
+        const t = k / CURVE_STEPS;
+        const u = 1 - t;
+        out.push([
+            u * u * u * p0[0] + 3 * u * u * t * p1[0] + 3 * u * t * t * p2[0] + t * t * t * p3[0],
+            u * u * u * p0[1] + 3 * u * u * t * p1[1] + 3 * u * t * t * p2[1] + t * t * t * p3[1],
+        ]);
+    }
+    return out;
+}
+
+/** Each subpath of `d` as a flattened polygon, or `null` when `d` does not parse. */
+export function subpathPolygons(d: string): Pt[][] | null {
+    const tokens = tokenisePath(d);
+    if (tokens === null) return null;
+    const ARGS: Record<string, number> = { m: 2, l: 2, t: 2, h: 1, v: 1, c: 6, s: 4, q: 4, a: 7, z: 0 };
+    const polys: Pt[][] = [];
+    let poly: Pt[] = [];
+    let cur: Pt = [0, 0];
+    let start: Pt = [0, 0];
+    let lastCtrl: Pt | null = null;
+    let lastQuad: Pt | null = null;
+    let i = 0;
+    let cmd = '';
+    const flush = (): void => {
+        if (poly.length >= 3) polys.push(poly);
+        poly = [];
+    };
+    while (i < tokens.length) {
+        const tok = tokens[i] as string;
+        if (/^[a-zA-Z]$/.test(tok)) {
+            cmd = tok;
+            i += 1;
+            if (cmd.toLowerCase() === 'z') {
+                cur = start;
+                lastCtrl = lastQuad = null;
+                flush();
+                continue;
+            }
+            if (i >= tokens.length) break;
+            continue;
+        }
+        const lower = cmd.toLowerCase();
+        const n = ARGS[lower];
+        if (n === undefined || n === 0) return null;
+        const a = tokens.slice(i, i + n).map(Number);
+        if (a.length < n || a.some((v) => !Number.isFinite(v))) return null;
+        i += n;
+        const rel = cmd !== cmd.toUpperCase();
+        const ox = rel ? cur[0] : 0;
+        const oy = rel ? cur[1] : 0;
+        const at = (k: number): Pt => [(a[k] as number) + ox, (a[k + 1] as number) + oy];
+        let next: Pt = cur;
+        let pts: Pt[] = [];
+        let ctrl: Pt | null = null;
+        let quad: Pt | null = null;
+        switch (lower) {
+            case 'm':
+                flush();
+                next = at(0);
+                start = next;
+                pts = [next];
+                // Further pairs after a moveto are implicit linetos.
+                cmd = rel ? 'l' : 'L';
+                break;
+            case 'l':
+                next = at(0);
+                pts = [next];
+                break;
+            case 'h':
+                next = [(a[0] as number) + ox, cur[1]];
+                pts = [next];
+                break;
+            case 'v':
+                next = [cur[0], (a[0] as number) + oy];
+                pts = [next];
+                break;
+            case 'c':
+                ctrl = at(2);
+                next = at(4);
+                pts = bezier(cur, at(0), ctrl, next);
+                break;
+            case 's': {
+                const c1: Pt = lastCtrl ? [2 * cur[0] - lastCtrl[0], 2 * cur[1] - lastCtrl[1]] : cur;
+                ctrl = at(0);
+                next = at(2);
+                pts = bezier(cur, c1, ctrl, next);
+                break;
+            }
+            case 'q':
+            case 't': {
+                const q: Pt =
+                    lower === 'q' ? at(0) : lastQuad ? [2 * cur[0] - lastQuad[0], 2 * cur[1] - lastQuad[1]] : cur;
+                next = lower === 'q' ? at(2) : at(0);
+                quad = q;
+                const c1: Pt = [cur[0] + (2 / 3) * (q[0] - cur[0]), cur[1] + (2 / 3) * (q[1] - cur[1])];
+                const c2: Pt = [next[0] + (2 / 3) * (q[0] - next[0]), next[1] + (2 / 3) * (q[1] - next[1])];
+                pts = bezier(cur, c1, c2, next);
+                break;
+            }
+            case 'a':
+                next = [(a[5] as number) + ox, (a[6] as number) + oy];
+                pts = arcPoints(cur, [a[0], a[1], a[2], a[3], a[4], next[0], next[1]] as number[]);
+                break;
+        }
+        poly.push(...pts);
+        cur = next;
+        lastCtrl = ctrl;
+        lastQuad = quad;
+        if (polys.length > MAX_SUBPATHS) return polys;
+    }
+    flush();
+    return polys;
+}
+
+function signedArea(poly: readonly Pt[]): number {
+    let s = 0;
+    for (let k = 0; k < poly.length; k++) {
+        const [x1, y1] = poly[k] as Pt;
+        const [x2, y2] = poly[(k + 1) % poly.length] as Pt;
+        s += x1 * y2 - x2 * y1;
+    }
+    return s / 2;
+}
+
+function inside(pt: Pt, poly: readonly Pt[]): boolean {
+    let hit = false;
+    for (let k = 0, j = poly.length - 1; k < poly.length; j = k++) {
+        const [xi, yi] = poly[k] as Pt;
+        const [xj, yj] = poly[j] as Pt;
+        if (yi > pt[1] !== yj > pt[1] && pt[0] < ((xj - xi) * (pt[1] - yi)) / (yj - yi) + xi) hit = !hit;
+    }
+    return hit;
+}
+
+/**
+ * Every `<path>` painted under `nonzero` whose subpath sits in a painted region
+ * of the same path and winds with it. One entry per inner subpath; `outer` is
+ * the smallest subpath containing it.
+ */
+export function filledCounters(elements: readonly SvgElement[]): FilledCounter[] {
+    const out: FilledCounter[] = [];
+    // The fill rule and fill each element inherits, by an open-element stack.
+    const stack: Array<{ name: string; rule: string | undefined; fill: string | undefined }> = [];
+    for (const el of elements) {
+        if (el.closing) {
+            const at = stack.map((s) => s.name).lastIndexOf(el.name);
+            if (at >= 0) stack.length = at;
+            continue;
+        }
+        const parent = stack[stack.length - 1];
+        const rule = styleProp(el, 'fill-rule') ?? parent?.rule;
+        const fill = styleProp(el, 'fill') ?? parent?.fill;
+        if (!el.selfClosing) stack.push({ name: el.name, rule, fill });
+        if (el.name !== 'path') continue;
+        if ((rule ?? 'nonzero').toLowerCase() === 'evenodd' || (fill ?? '').toLowerCase() === 'none') continue;
+        const polys = subpathPolygons(el.attrs['d'] ?? '');
+        if (polys === null || polys.length < 2 || polys.length > MAX_SUBPATHS) continue;
+        const areas = polys.map(signedArea);
+        for (let inner = 0; inner < polys.length; inner++) {
+            const ia = areas[inner] as number;
+            if (Math.abs(ia) < 1e-9) continue;
+            // The winding number around the inner contour, from every subpath
+            // that contains it — not from one outer, or an island inside a
+            // counter reads as a filled counter.
+            let around = 0;
+            let nearest = -1;
+            for (let outer = 0; outer < polys.length; outer++) {
+                if (outer === inner) continue;
+                const oa = areas[outer] as number;
+                if (Math.abs(oa) <= Math.abs(ia)) continue;
+                const op = polys[outer] as Pt[];
+                if (!(polys[inner] as Pt[]).every((p) => inside(p, op))) continue;
+                around += Math.sign(oa);
+                if (nearest < 0 || Math.abs(oa) < Math.abs(areas[nearest] as number)) nearest = outer;
+            }
+            if (around !== 0 && Math.sign(around) === Math.sign(ia)) {
+                out.push({ element: el, inner: inner + 1, outer: nearest + 1 });
+            }
+        }
+    }
+    return out;
+}
+
+/** The rule as `scanSvg` runs it: one advisory finding per filled counter. */
+export function ruleFilledCounter(elements: readonly SvgElement[], file: string): Finding[] {
+    return filledCounters(elements).map((c) => ({
+        rule: 'svg-structure-filled-counter',
+        file,
+        line: c.element.line,
+        snippet:
+            `<path> subpath ${c.inner} sits inside subpath ${c.outer} with the same winding under nonzero, so ` +
+            'the counter paints — wind the inner contour the other way, or declare fill-rule="evenodd"',
+        severity: 'warning',
+    }));
+}

package/src/scripts/_lib/svg_rules.ts

@@ -29,6 +29,7 @@
  */
 
 import { attrsOf, parseDocument, tagEnd, type XmlDocument, type XmlNode } from './svg_dom.js';
+import { ruleFilledCounter } from './svg_filled_counter.js';
 import { cssUnescape, isActiveUrl, localName, rawAttrs, resolvedUrl, svgPrefixes, URL_ATTRS } from './svg_urls.js';
 import {
     type Box,
@@ -1195,6 +1196,7 @@ export function scanSvg(content: string, relPath: string, opts: ScanOptions = {}
         ...ruleMissingXmlns(elements, relPath),
         ...ruleOutsideViewBox(elements, relPath),
         ...ruleUnparseablePath(elements, relPath),
+        ...ruleFilledCounter(elements, relPath),
         ...ruleUnusedDefs(text, elements, relPath),
         ...ruleDanglingReference(text, elements, relPath),
         ...ruleActiveContent(text, elements, relPath, mode),