summer-engine 3.1.0 → 3.2.1

package/dist/core/capabilities/audit/audit.d.ts

@@ -0,0 +1,56 @@
+import { type CapabilityAdvertisingClient } from "../../capability-skew.js";
+import { type SeeingImage } from "../seeing/seeing.js";
+import { type ProbeClient } from "../seeing/probe.js";
+import { type AuditCheck, type SceneAuditArgs, type Severity } from "./args.js";
+import { type AuditIssue, type KernelResult } from "./judge.js";
+export declare const AUDIT_KERNEL_PATH: string;
+export declare function loadAuditKernel(): string;
+export declare const AUDIT_FALLBACK = "read the scene with summer_world_snapshot and look with summer_frame_nodes / summer_shot_sheet; cast single rays with summer_raycast";
+export interface AuditClient extends ProbeClient, CapabilityAdvertisingClient {
+    getSceneState(scenePath?: string, options?: {
+        depth?: number;
+        limit?: number;
+    }): Promise<unknown>;
+    getProjectRoot?(): string | undefined;
+}
+export interface AuditSuccess {
+    ok: true;
+    /** The page: at most 5 KB of JSON. */
+    summary: Record<string, unknown>;
+    image: SeeingImage | null;
+}
+export interface AuditFailure {
+    ok: false;
+    failure_reason: string;
+    error: string;
+    hint?: string;
+    detail?: Record<string, unknown>;
+}
+export type AuditResult = AuditSuccess | AuditFailure;
+export interface ValidatedAuditArgs {
+    scenePath?: string;
+    checks: AuditCheck[];
+    root?: string;
+    minSeverity: Severity;
+    offset: number;
+    limit: number;
+    render: "sheet" | "none";
+    budgetMs: number;
+    accept: Array<{
+        key: string;
+        reason: string;
+    }>;
+    showAccepted: boolean;
+}
+/** Strict validation; throws ToolInputError (nothing is sent). */
+export declare function validateAuditArgs(args: SceneAuditArgs): ValidatedAuditArgs;
+/** Raw kernel measurements -> sorted issues (all checks that ran). */
+export declare function judgeAll(result: KernelResult, checks: readonly AuditCheck[]): AuditIssue[];
+export interface JudgedAudit {
+    issues: AuditIssue[];
+    notes: string[];
+    /** Checks that ran but could measure nothing (never listed clean). */
+    unmeasured: AuditCheck[];
+}
+export declare function judgeAllDetailed(result: KernelResult, checks: readonly AuditCheck[]): JudgedAudit;
+export declare function sceneAudit(client: AuditClient, rawArgs: SceneAuditArgs): Promise<AuditResult>;

package/dist/core/capabilities/audit/audit.js

@@ -0,0 +1,287 @@
+/**
+ * summer_scene_audit — ONE implementation for both faces (MCP:
+ * src/mcp/tools/audit-tools.ts; CLI: `summer tool scene-audit`).
+ *
+ * One fast, read-only pass over every node of a 3D scene that reports likely
+ * visual and placement problems, so a build agent knows exactly where to look.
+ *
+ * How (no new engine op): the seeing tools' private-copy path. A throwaway
+ * wrapper scene in a private OS temp directory instances the SAVED scene and
+ * carries the audit kernel (assets/audit/scene_audit.gd) as a built-in @tool
+ * script; the existing ScenePreview op instantiates it in an offscreen
+ * SubViewport with its own World3D. The kernel works on that copy: the open
+ * tab, its unsaved state, its undo history and every project file stay
+ * untouched (RunSceneScript would mark the tab unsaved after every run).
+ *
+ * The kernel measures (capped ray grids and probes against a physics space
+ * built from the visible meshes, shapes cached per mesh resource); judge.ts
+ * decides; summary.ts pages the result under 5 KB. render:"sheet" renders the
+ * first 6 issues of the page through the seeing kernel in one more call.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { PACKAGE_ROOT } from "../../package-root.js";
+import { missingEngineOpResult } from "../../capability-skew.js";
+import { ToolInputError } from "../../tool-errors.js";
+import { resolveCurrentScene } from "../project-context.js";
+import { layoutGrid, validateNodePath, validateScenePath } from "../seeing/seeing.js";
+import { runProbe } from "../seeing/probe.js";
+import { AUDIT_CHECKS, AUDIT_DEFAULT_BUDGET_MS, AUDIT_DEFAULT_LIMIT, AUDIT_MAX_ACCEPT, AUDIT_MAX_BUDGET_MS, AUDIT_MAX_LIMIT, AUDIT_MIN_BUDGET_MS, } from "./args.js";
+import { AcceptStoreError, applyAccepts, mergeAccepts, parseAcceptFile, validIssueKey, writeAcceptFile } from "./accept.js";
+import { judgeGaps } from "./gaps.js";
+import { groupRepeats, judgeDuplicates, judgeFloorGaps, judgeLights, judgeLongProps, judgeOverlaps, judgeResources, judgeSupport, judgeThroughHoles, judgeTransforms, judgeUv, judgeZFight, judgeZFightGeometry, } from "./judge.js";
+import { buildPage, countIssues, filterIssues, partialChecks, sortIssues, timingPerCheck } from "./summary.js";
+import { choosePose, SHEET_TILES } from "./frame.js";
+export const AUDIT_KERNEL_PATH = join(PACKAGE_ROOT, "assets", "audit", "scene_audit.gd");
+let kernelCache = null;
+export function loadAuditKernel() {
+    if (kernelCache === null)
+        kernelCache = readFileSync(AUDIT_KERNEL_PATH, "utf-8");
+    return kernelCache;
+}
+export const AUDIT_FALLBACK = "read the scene with summer_world_snapshot and look with summer_frame_nodes / summer_shot_sheet; cast single rays with summer_raycast";
+function fail(failure_reason, error, hint, detail) {
+    return { ok: false, failure_reason, error, ...(hint ? { hint } : {}), ...(detail ? { detail } : {}) };
+}
+/** Strict validation; throws ToolInputError (nothing is sent). */
+export function validateAuditArgs(args) {
+    const checks = args.checks?.length ? [...new Set(args.checks)] : [...AUDIT_CHECKS];
+    for (const c of checks) {
+        if (!AUDIT_CHECKS.includes(c))
+            throw new ToolInputError(`checks: unknown check ${JSON.stringify(c)}. Nothing was sent.`);
+    }
+    const offset = args.offset ?? 0;
+    const limit = args.limit ?? AUDIT_DEFAULT_LIMIT;
+    if (!Number.isInteger(offset) || offset < 0)
+        throw new ToolInputError("offset must be a non-negative integer. Nothing was sent.");
+    if (!Number.isInteger(limit) || limit < 1 || limit > AUDIT_MAX_LIMIT)
+        throw new ToolInputError(`limit must be 1-${AUDIT_MAX_LIMIT}. Nothing was sent.`);
+    const budgetMs = args.budget_ms ?? AUDIT_DEFAULT_BUDGET_MS;
+    if (!Number.isInteger(budgetMs) || budgetMs < AUDIT_MIN_BUDGET_MS || budgetMs > AUDIT_MAX_BUDGET_MS) {
+        throw new ToolInputError(`budget_ms must be an integer ${AUDIT_MIN_BUDGET_MS}-${AUDIT_MAX_BUDGET_MS}. Nothing was sent.`);
+    }
+    const root = args.root !== undefined && args.root.trim() !== "" && args.root.trim() !== "." ? validateNodePath(args.root.trim(), "root") : undefined;
+    const accept = (args.accept ?? []).map((a) => {
+        if (!a || typeof a.key !== "string" || !validIssueKey(a.key)) {
+            throw new ToolInputError(`accept: ${JSON.stringify(a?.key ?? a).slice(0, 80)} is not an issue key (check:path@x,y,z, from issues[].key). Nothing was sent.`);
+        }
+        const reason = typeof a.reason === "string" ? a.reason.trim() : "";
+        if (reason.length < 3 || reason.length > 200 || /[\r\n]/.test(reason))
+            throw new ToolInputError("accept: each reason must be one line of 3-200 characters. Nothing was sent.");
+        return { key: a.key, reason };
+    });
+    if (accept.length > AUDIT_MAX_ACCEPT)
+        throw new ToolInputError(`accept: at most ${AUDIT_MAX_ACCEPT} per call. Nothing was sent.`);
+    return {
+        ...(args.scenePath !== undefined ? { scenePath: validateScenePath(args.scenePath) } : {}),
+        checks: AUDIT_CHECKS.filter((c) => checks.includes(c)),
+        ...(root ? { root } : {}),
+        minSeverity: args.min_severity ?? "look",
+        offset,
+        limit,
+        render: args.render ?? "none",
+        budgetMs,
+        accept,
+        showAccepted: args.show_accepted === true,
+    };
+}
+/** Raw kernel measurements -> sorted issues (all checks that ran). */
+export function judgeAll(result, checks) {
+    return judgeAllDetailed(result, checks).issues;
+}
+export function judgeAllDetailed(result, checks) {
+    const inst = (Array.isArray(result.instances) ? result.instances : []);
+    const want = new Set(checks);
+    const lines = Array.isArray(result.lines) ? result.lines : [];
+    const issues = [];
+    const holes = want.has("through_hole") ? judgeThroughHoles(lines, inst) : [];
+    issues.push(...holes);
+    const gaps = judgeGaps(result, inst, want, holes);
+    issues.push(...gaps.issues);
+    if (want.has("floor_gap"))
+        issues.push(...judgeFloorGaps(result.floors, inst));
+    if (want.has("floating") || want.has("sunken")) {
+        issues.push(...judgeSupport(Array.isArray(result.support) ? result.support : [], inst).filter((i) => want.has(i.check)));
+    }
+    if (want.has("interpenetration"))
+        issues.push(...judgeOverlaps(Array.isArray(result.overlaps) ? result.overlaps : [], inst));
+    if (want.has("orientation"))
+        issues.push(...judgeLongProps(Array.isArray(result.long_props) ? result.long_props : [], inst));
+    if (want.has("uv_stretch"))
+        issues.push(...judgeUv(Array.isArray(result.uv) ? result.uv : [], inst));
+    const dup = judgeDuplicates(inst);
+    if (want.has("duplicate"))
+        issues.push(...dup.issues);
+    if (want.has("z_fight")) {
+        const geo = judgeZFightGeometry(result.zfight_geo, inst, dup.pairs);
+        issues.push(...geo.issues, ...judgeZFight(lines, result.floors, inst, dup.pairs, geo.pairs));
+    }
+    if (want.has("lights"))
+        issues.push(...judgeLights(result.lights, inst));
+    if (want.has("transform"))
+        issues.push(...judgeTransforms(inst));
+    if (want.has("resource"))
+        issues.push(...judgeResources(result.resources, inst));
+    return { issues: sortIssues(groupRepeats(issues, inst)), notes: gaps.notes, unmeasured: gaps.unmeasured };
+}
+function sceneStats(result) {
+    const s = (result.stats ?? {});
+    const pick = (k) => (typeof s[k] === "number" ? s[k] : undefined);
+    return {
+        nodes: pick("nodes"),
+        instances: pick("instances"),
+        meshes: pick("mesh_instances"),
+        unique_meshes: pick("unique_meshes"),
+        tris_unique: pick("tris_unique"),
+        rays: pick("rays"),
+    };
+}
+function lightStats(result) {
+    const l = result.lights;
+    if (!l)
+        return undefined;
+    const c = (l.counts ?? {});
+    const sh = (l.shadowed ?? {});
+    const n = (v) => (typeof v === "number" ? v : 0);
+    return { renderer: l.renderer, omni: n(c.omni), spot: n(c.spot), directional: n(c.directional), shadowed: n(sh.omni) + n(sh.spot) + n(sh.directional), per_object_limit: l.limit };
+}
+export async function sceneAudit(client, rawArgs) {
+    const args = validateAuditArgs(rawArgs);
+    let scenePath = args.scenePath;
+    if (!scenePath) {
+        const current = resolveCurrentScene(undefined, await client.getSceneState(), undefined);
+        if (!current)
+            throw new ToolInputError('No scenePath given and no scene is open in the editor. Pass scenePath ("res://...tscn"). Nothing was sent.');
+        scenePath = validateScenePath(current);
+    }
+    const missing = missingEngineOpResult(client, "ScenePreview", AUDIT_FALLBACK);
+    if (missing)
+        return fail(missing.failure_reason, missing.error, missing.hint, { op: "ScenePreview", engine_version: missing.engine_version });
+    const config = {
+        mode: "audit",
+        checks: args.checks,
+        ...(args.root ? { root: args.root } : {}),
+        poses: args.render === "sheet",
+        budget_ms: args.budgetMs,
+    };
+    const started = Date.now();
+    const run = await runProbe(client, { scenePath, config, size: [16, 16], kernel: loadAuditKernel(), timeoutMs: 120_000 });
+    const roundtrip = Date.now() - started;
+    try {
+        if (!run.ok || !run.result) {
+            if (run.failureReason === "probe_did_not_run") {
+                return fail("audit_did_not_run", "The audit kernel never wrote its result: the wrapper scene loaded but the built-in @tool script did not run (a script error, or the scene failed to load). Read summer_get_console for the engine's error.", undefined, { stage: run.result?.stage ?? null });
+            }
+            return fail(run.failureReason ?? "audit_failed", run.error ?? "The audit failed.", undefined, run.result ? { stage: run.result.stage ?? null, errors: run.result.errors ?? [] } : undefined);
+        }
+        const result = run.result;
+        const judgeStarted = Date.now();
+        const judged = judgeAllDetailed(result, args.checks);
+        const judgeMs = Date.now() - judgeStarted;
+        const partial = partialChecks(result.partial, args.checks);
+        for (const c of judged.unmeasured)
+            partial.checks[c] = 0;
+        // Accepted items: merge this call's accept list into the file, then hide
+        // what is accepted (stale entries show again).
+        let acceptEntries = parseAcceptFile(result.accept);
+        let acceptResult;
+        if (args.accept.length) {
+            const merged = mergeAccepts(acceptEntries, args.accept, judged.issues, scenePath);
+            acceptResult = { added: merged.added.length, ...(merged.refused.length ? { refused: merged.refused.slice(0, 5) } : {}) };
+            if (merged.entries) {
+                try {
+                    await writeAcceptFile(client.getProjectRoot?.(), merged.entries);
+                    acceptEntries = merged.entries;
+                }
+                catch (err) {
+                    const reason = err instanceof AcceptStoreError ? err.reason : "write_failed";
+                    return fail(`accept_${reason}`, `Accepted items were not saved: ${err instanceof Error ? err.message : String(err)}`, "Run the audit without accept, or connect to the project's editor so its folder is known.");
+                }
+            }
+        }
+        const split = applyAccepts(judged.issues, acceptEntries, scenePath);
+        for (const st of split.stale)
+            st.issue.acceptStale = st.why;
+        for (const a of split.accepted)
+            a.issue.accepted = a.entry.reason;
+        const all = args.showAccepted ? judged.issues : split.shown;
+        const accepted = split.accepted.map((a) => a.issue);
+        const { counts, clean } = countIssues(split.shown, args.checks, partial.checks, accepted);
+        const matching = filterIssues(all, args.minSeverity);
+        const notes = ["Read-only: audited the SAVED file in a private copy (open tab, undo and file untouched); save first."];
+        if (accepted.length)
+            notes.push(`${accepted.length} accepted item(s) ${args.showAccepted ? "listed (show_accepted)" : "hidden (counts.<check>.accepted; show_accepted:true lists them)"}${split.stale.length ? `; ${split.stale.length} shown again because their evidence changed (accept_stale)` : ""}.`);
+        else if (split.stale.length)
+            notes.push(`${split.stale.length} accepted item(s) shown again because their evidence changed (accept_stale).`);
+        notes.push(...judged.notes);
+        if (args.minSeverity !== "look")
+            notes.push(`min_severity ${args.minSeverity}: ${all.length - matching.length} lower-severity issue(s) hidden.`);
+        const lights = lightStats(result);
+        if (lights && args.checks.includes("lights") && lights.renderer === "forward_plus")
+            notes.push("lights: forward_plus has no per-object light limit; only spot rims were checked.");
+        const stopped = Object.entries(partial.checks).map(([c, share]) => `${c} ${Math.round(share * 100)}%`);
+        if (stopped.length)
+            notes.push(`budget_ms ${args.budgetMs}: stopped early (editor time): ${stopped.join(", ")} covered; rerun those with checks:[...] or a larger budget_ms.`);
+        if (partial.other.poses !== undefined)
+            notes.push(`framing: views measured for ${Math.round(partial.other.poses * 100)}% of the pieces (budget); the rest have no sheet tile.`);
+        for (const w of Array.isArray(result.warnings) ? result.warnings.slice(0, 3) : [])
+            notes.push(String(w).slice(0, 160));
+        const base = {
+            ok: true,
+            tool: "summer_scene_audit",
+            scenePath,
+            ...(args.root ? { root: args.root } : {}),
+            budget_ms: args.budgetMs,
+            scene: sceneStats(result),
+            counts,
+            clean,
+            ms: timingPerCheck(result.ms, { judge: judgeMs, roundtrip }),
+            ...(lights ? { lights } : {}),
+            total: all.length,
+            ...(accepted.length || split.stale.length ? { accepted: { hidden: args.showAccepted ? 0 : accepted.length, stale: split.stale.length } } : {}),
+            ...(acceptResult ? { accept_result: acceptResult } : {}),
+            notes,
+        };
+        let page = buildPage({ base, issues: matching, offset: args.offset, limit: args.limit });
+        // The sheet (one more engine call): the first issues of THIS page.
+        let image = null;
+        if (args.render === "sheet") {
+            const first = page.shown.slice(0, SHEET_TILES).map((c) => ({ n: c.n, issue: matching[c.n - 1] }));
+            const posed = first.map((f) => ({ ...f, pose: choosePose(f.issue.frame) })).filter((p) => p.pose !== null);
+            const unposed = first.filter((f) => !posed.some((p) => p.n === f.n)).map((f) => f.n);
+            let sheet;
+            if (!posed.length) {
+                sheet = { tiles: [], ...(unposed.length ? { no_clear_view: unposed } : {}) };
+            }
+            else {
+                const layout = layoutGrid(posed.length, 16 / 9, 1536);
+                const tiles = posed.map((p, k) => ({
+                    kind: "shot",
+                    rect: layout.rects[k],
+                    label: `#${p.n} ${p.issue.check}`,
+                    view: "beauty",
+                    pose: { position: [...p.pose.position], look_at: [...p.pose.look_at], fov: p.pose.fov },
+                }));
+                const renderStarted = Date.now();
+                const render = await runProbe(client, { scenePath, size: layout.canvas, config: { mode: "render", canvas: layout.canvas, tiles }, timeoutMs: 120_000 });
+                try {
+                    if (render.ok && render.image) {
+                        image = { ...render.image };
+                        sheet = { tiles: posed.map((p) => p.n), ...(unposed.length ? { no_clear_view: unposed } : {}), render_ms: Date.now() - renderStarted };
+                    }
+                    else {
+                        sheet = { error: render.failureReason ?? "render_failed", detail: (render.error ?? "").slice(0, 160) };
+                    }
+                }
+                finally {
+                    await render.dispose();
+                }
+            }
+            page = buildPage({ base: { ...base, sheet }, issues: matching, offset: args.offset, limit: args.limit });
+        }
+        return { ok: true, summary: page.body, image };
+    }
+    finally {
+        await run.dispose();
+    }
+}

package/dist/core/capabilities/audit/frame.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Framing for render:"sheet": a camera per issue, on the OPEN side of the
+ * problem. Each issue carries directions the kernel measured with two-sided
+ * rays (any surface counts, front or back face), so a camera placed within
+ * the measured clear distance is never behind a wall or inside geometry:
+ * walls render one-sided, and a camera behind one sees straight through it.
+ */
+import { type CameraPose } from "../seeing/math.js";
+import type { FrameHint } from "./judge.js";
+export declare const SHEET_FOV = 50;
+export declare const SHEET_TILES = 6;
+/** The pose from the best measured direction: preference x share of the
+ *  wanted distance that is actually clear. Null when nothing is clear. */
+export declare function choosePose(hint: FrameHint | undefined, fov?: number): CameraPose | null;

package/dist/core/capabilities/audit/frame.js

@@ -0,0 +1,35 @@
+/**
+ * Framing for render:"sheet": a camera per issue, on the OPEN side of the
+ * problem. Each issue carries directions the kernel measured with two-sided
+ * rays (any surface counts, front or back face), so a camera placed within
+ * the measured clear distance is never behind a wall or inside geometry:
+ * walls render one-sided, and a camera behind one sees straight through it.
+ */
+import { add, clamp, scale } from "../seeing/math.js";
+import { fitCameraDistance } from "./math.js";
+export const SHEET_FOV = 50;
+export const SHEET_TILES = 6;
+const MIN_DISTANCE = 0.7;
+const CLEARANCE_MARGIN = 0.3;
+/** The pose from the best measured direction: preference x share of the
+ *  wanted distance that is actually clear. Null when nothing is clear. */
+export function choosePose(hint, fov = SHEET_FOV) {
+    if (!hint)
+        return null;
+    if (hint.viewer)
+        return { position: hint.viewer, look_at: hint.focus, fov };
+    const want = clamp(fitCameraDistance(hint.size, fov), 1.5, 9);
+    let best = null;
+    for (const d of hint.dirs) {
+        const available = d.clear - CLEARANCE_MARGIN;
+        if (available < MIN_DISTANCE || d.pref <= 0)
+            continue;
+        const dist = Math.min(want, available);
+        const score = d.pref * (dist / want);
+        if (!best || score > best.score)
+            best = { dir: d.dir, dist, score };
+    }
+    if (!best)
+        return null;
+    return { position: add(hint.focus, scale(best.dir, best.dist)), look_at: hint.focus, fov };
+}

package/dist/core/capabilities/audit/gaps.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Judgment for the gap detectors of summer_scene_audit. The kernel
+ * measures; this file decides.
+ *
+ * - exposed_edge (A): open outline edges of walls and facade members (bands,
+ *   piers, joints: the kernel's geometric roles) that nothing covers within
+ *   4-7 mm, seen from walkable space, with a 2-60 cm reveal behind them or a
+ *   coplanar continuation within 4 cm (seam) or 35 cm (bridged gap).
+ * - open_fixture_end: open ends of run pieces (two or more open rims of one
+ *   size) nothing joins within a sleeve tolerance, seen from the open side.
+ * - depth_step (C): runs of recessed or proud depth along each facade row.
+ *
+ * Severity: exposed_edge warns on band pieces (and on walls when depth_step
+ * agrees), else look; open_fixture_end warns; depth_step is look, and a
+ * depth_step hole next to a through_hole confirms it (warn -> error). A
+ * confirming flag is folded into the issue it confirms.
+ */
+import { type Vec3 } from "../seeing/math.js";
+import type { AuditCheck } from "./args.js";
+import type { AuditIssue, InstRow, KernelResult } from "./judge.js";
+import { type Box } from "./math.js";
+export declare const CONFIRM_RADIUS = 0.6;
+/** exposed_edge classes that count (sky, far and mixed are silhouettes, not gaps). */
+export declare const EDGE_CLASSES: Set<string>;
+export interface GkLine {
+    b: number;
+    ax: 0 | 2;
+    c: number;
+    lo: number;
+    hi: number;
+    y0: number;
+    y1: number;
+    tmin: number;
+    tmax: number;
+    sides: number[];
+    pieces: number[];
+}
+export interface EdgeFlag {
+    owner: number;
+    cls: string;
+    len: number;
+    n: number;
+    c: Vec3;
+    box: Box;
+    step: number;
+    counts: {
+        gap: number;
+        seam: number;
+        bridge: number;
+        sky: number;
+        far: number;
+    };
+    eye: Vec3;
+    hit: number;
+}
+export interface FixtureEnd {
+    i: number;
+    c: Vec3;
+    out: Vec3;
+    r: number;
+    eye: Vec3;
+}
+export interface DepthFlag {
+    kind: string;
+    line: number;
+    side: number;
+    s0: number;
+    s1: number;
+    y0: number;
+    y1: number;
+    rows: number;
+    depth: number;
+    c: Vec3;
+}
+export declare function parseGkLines(raw: unknown): GkLine[];
+/** Door-like openings the kernel found (inserts reaching the floor, 1.8 m
+ *  or taller): world boxes. */
+export declare function parseDoors(raw: unknown): Box[];
+export declare function parseEdgeFlags(raw: unknown): EdgeFlag[];
+export declare function parseFixtureEnds(raw: unknown): FixtureEnd[];
+export declare function parseDepthFlags(raw: unknown): DepthFlag[];
+export declare function instBox(r: InstRow): Box;
+/** The world box a depth_step run covers (its rows, 10 cm deep at the facade). */
+export declare function depthBox(f: DepthFlag, lines: readonly GkLine[]): Box;
+export interface GapJudgement {
+    issues: AuditIssue[];
+    /** Checks that ran but could measure nothing (no walkable eye points). */
+    unmeasured: AuditCheck[];
+    notes: string[];
+}
+/**
+ * exposed_edge, open_fixture_end and depth_step issues,
+ * with confirmation folded in. `holes` (the through_hole issues) are
+ * updated in place when a depth_step hole confirms one.
+ */
+export declare function judgeGaps(result: KernelResult, inst: readonly InstRow[], want: ReadonlySet<AuditCheck>, holes?: AuditIssue[]): GapJudgement;