comber 0.1.0

package/dist/core/baseline.js

@@ -0,0 +1,85 @@
+import { readFile } from "node:fs/promises";
+function bySignature(findings) {
+    const out = new Map();
+    for (const finding of findings) {
+        out.set(finding.signature, finding);
+    }
+    return out;
+}
+export function compareBaseline(current, baseline, baselinePath) {
+    if (!baseline) {
+        const newFindings = [...current.findings];
+        return {
+            baselinePath,
+            baselineFound: false,
+            newFindings,
+            resolvedFindings: [],
+            unchangedFindings: [],
+            summary: {
+                newFail: newFindings.filter((finding) => finding.severity === "fail").length,
+                newWarn: newFindings.filter((finding) => finding.severity === "warn").length,
+                resolved: 0,
+                unchanged: 0,
+            },
+        };
+    }
+    const currentBySignature = bySignature(current.findings);
+    const baselineBySignature = bySignature(baseline.findings);
+    const newFindings = [];
+    const resolvedFindings = [];
+    const unchangedFindings = [];
+    for (const finding of current.findings) {
+        if (baselineBySignature.has(finding.signature))
+            unchangedFindings.push(finding);
+        else
+            newFindings.push(finding);
+    }
+    for (const finding of baseline.findings) {
+        if (!currentBySignature.has(finding.signature))
+            resolvedFindings.push(finding);
+    }
+    return {
+        baselinePath,
+        baselineFound: true,
+        newFindings,
+        resolvedFindings,
+        unchangedFindings,
+        summary: {
+            newFail: newFindings.filter((finding) => finding.severity === "fail").length,
+            newWarn: newFindings.filter((finding) => finding.severity === "warn").length,
+            resolved: resolvedFindings.length,
+            unchanged: unchangedFindings.length,
+        },
+    };
+}
+export async function readBaselineResult(path) {
+    // A missing OR malformed baseline must degrade to "no baseline" (the run still
+    // writes its report + result.json) — never abort the whole crawl after the fact.
+    // We warn loudly so a typo'd / corrupt baseline path is visible, not silent.
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        console.warn(`comber: baseline unreadable (${path}): ${String(err).slice(0, 120)} — treating as no baseline`);
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (!Array.isArray(parsed.findings)) {
+            console.warn(`comber: baseline has no findings array (${path}) — treating as no baseline`);
+            return undefined;
+        }
+        return parsed;
+    }
+    catch (err) {
+        console.warn(`comber: baseline not valid JSON (${path}): ${String(err).slice(0, 120)} — treating as no baseline`);
+        return undefined;
+    }
+}
+export async function compareBaselineFromPath(current, path) {
+    const baseline = await readBaselineResult(path);
+    return compareBaseline(current, baseline, path);
+}

package/dist/core/baseline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline.js","sourceRoot":"","sources":["../../src/core/baseline.ts"],"names":[],"mappings":"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"}

package/dist/core/blind-spots.js

@@ -0,0 +1,22 @@
+export function fallbackBlindSpots(count, scope, message) {
+    const out = [];
+    for (let i = 0; i < count; i++) {
+        out.push({
+            kind: "unknown-surface",
+            severity: "blocker-for-exhaustive",
+            scope,
+            message,
+        });
+    }
+    return out;
+}
+export function summarizeBlindSpots(blindSpots) {
+    const out = {};
+    for (const blindSpot of blindSpots) {
+        out[blindSpot.kind] = (out[blindSpot.kind] ?? 0) + 1;
+    }
+    return out;
+}
+export function blindSpotsBlockExhaustive(blindSpots) {
+    return blindSpots.some((blindSpot) => blindSpot.severity === "blocker-for-exhaustive");
+}

package/dist/core/blind-spots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blind-spots.js","sourceRoot":"","sources":["../../src/core/blind-spots.ts"],"names":[],"mappings":"AA0BA,MAAM,UAAU,kBAAkB,CAAC,KAAa,EAAE,KAAa,EAAE,OAAe;IAC9E,MAAM,GAAG,GAAgB,EAAE,CAAC;IAC5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/B,GAAG,CAAC,IAAI,CAAC;YACP,IAAI,EAAE,iBAAiB;YACvB,QAAQ,EAAE,wBAAwB;YAClC,KAAK;YACL,OAAO;SACR,CAAC,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,UAAgC;IAClE,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,UAAgC;IACxE,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,QAAQ,KAAK,wBAAwB,CAAC,CAAC;AACzF,CAAC"}

package/dist/core/contract-extras.js

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

package/dist/core/contract-extras.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-extras.js","sourceRoot":"","sources":["../../src/core/contract-extras.ts"],"names":[],"mappings":""}

package/dist/core/contract.js

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

package/dist/core/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/core/contract.ts"],"names":[],"mappings":""}

package/dist/core/coverage.js

@@ -0,0 +1,70 @@
+import { blindSpotsBlockExhaustive, fallbackBlindSpots, summarizeBlindSpots } from "./blind-spots.js";
+export class CoverageAccumulator {
+    statesVisited = 0;
+    elementsDiscovered = 0;
+    elementsExercised = 0;
+    frameBlindSpots = 0;
+    cappedNotExhaustive = false;
+    blindSpots = [];
+    skipLedger = {};
+    /** Driver sub-metrics + orchestrator-tracked link discovery. */
+    extra = {};
+    /** Element-partition skips only (denylist/disabled/file-input/idempotent/cap) — drives the
+     *  element-coverage denominator. Form/route skips go in skipLedger but NOT here. */
+    elementSkips = 0;
+    noteState() {
+        this.statesVisited++;
+    }
+    discover(n) {
+        this.elementsDiscovered += n;
+    }
+    exercise() {
+        this.elementsExercised++;
+    }
+    /** Non-element skip (forms, route-visit-cap, near-dup-state) — ledger only. */
+    skip(reason) {
+        this.skipLedger[reason] = (this.skipLedger[reason] ?? 0) + 1;
+    }
+    /** Element-partition skip — ledger AND the coverage denominator. */
+    skipElement(reason) {
+        this.elementSkips++;
+        this.skip(reason);
+    }
+    blind(n, details, scope = "unknown") {
+        this.frameBlindSpots += n;
+        if (details && details.length > 0) {
+            this.blindSpots.push(...details);
+            return;
+        }
+        this.blindSpots.push(...fallbackBlindSpots(n, scope, "surface could not be inspected"));
+    }
+    /** Bump a single driver/orchestrator sub-metric. */
+    bumpExtra(key, n = 1) {
+        this.extra[key] = (this.extra[key] ?? 0) + n;
+    }
+    /** Merge a driver's end-of-run sub-metrics into `extra`. */
+    mergeExtra(record) {
+        for (const [k, v] of Object.entries(record))
+            this.extra[k] = (this.extra[k] ?? 0) + v;
+    }
+    summary() {
+        // Honest denominator: non-link exercisable = discovered − element-skips − links.
+        // Only ELEMENT-partition skips count (not form/route skips, which aren't elements).
+        const followTargets = this.extra.followTargetsDiscovered ?? this.extra.linksDiscovered ?? 0;
+        const denom = Math.max(this.elementsExercised, this.elementsDiscovered - this.elementSkips - followTargets);
+        return {
+            statesVisited: this.statesVisited,
+            elementsDiscovered: this.elementsDiscovered,
+            elementsExercised: this.elementsExercised,
+            elementsSkipped: this.elementSkips,
+            skipLedger: { ...this.skipLedger },
+            frameBlindSpots: this.frameBlindSpots,
+            blindSpots: this.blindSpots.map((blindSpot) => ({ ...blindSpot })),
+            blindSpotSummary: summarizeBlindSpots(this.blindSpots),
+            elementCoveragePct: denom > 0 ? Math.round((100 * this.elementsExercised) / denom) : 100,
+            exhaustiveClaimAllowed: !this.cappedNotExhaustive && !blindSpotsBlockExhaustive(this.blindSpots),
+            cappedNotExhaustive: this.cappedNotExhaustive,
+            extra: { ...this.extra },
+        };
+    }
+}

package/dist/core/coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.js","sourceRoot":"","sources":["../../src/core/coverage.ts"],"names":[],"mappings":"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"}

package/dist/core/crawl.js

@@ -0,0 +1,229 @@
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { exerciseState } from "./pipeline.js";
+import { CoverageAccumulator } from "./coverage.js";
+import { ExhaustivenessLedger } from "./ledger.js";
+import { PlanRecorder } from "./plan.js";
+import { makeSafetyJudge } from "./safety-judge.js";
+import { invariants, jaccardNearDup, nameSet, stateFingerprint } from "./safety.js";
+import { compareFindings, normalizeBreakageSignals } from "./signal-normalize.js";
+/**
+ * Frontier BFS over in-scope Addresses. The frontier grows TWO ways: it FOLLOWS the
+ * driver's outbound addresses (links, never clicked) AND enqueues addresses the driver
+ * reports it NAVIGATED to while acting (`ExerciseResult.discovered` — native tap-only
+ * screens). `exerciseState` exhaustively interacts with every other node per state.
+ *
+ * TWO DISTINCT DEDUP LAYERS (contract v2), never conflated:
+ *   • FRONTIER de-dup — keyed by the GOTO HANDLE (`addr.dedupeKey ?? addr.id`): the `queued`
+ *     set, so the same handle is never `goto`'d twice.
+ *   • VISITED-by-STATE — keyed by `stateFingerprint(snapshot())`: the `visited` set, so two
+ *     handles that land on the same structural screen are processed once.
+ *
+ * The driver owns "what is a location" (Address) and "what is in scope" (inScope). Probes
+ * are driver-DECLARED with a lifecycle slot (`capabilities.probes`), and the orchestrator
+ * fires each driver's probes at the matching slot — reproducing web's original fixed
+ * ordering (after-goto: session · after-snapshot: axe/dom/links · after-exercise: forms ·
+ * finalize) while letting any driver register new phases (native: crash/logs). Hardened
+ * near-dup fingerprint + per-scope visit cap terminate infinite-feed/live pages; all global
+ * caps are authoritative backstops.
+ */
+export async function crawl(driver, cfg, runDir) {
+    const startedAt = Date.now();
+    const spend = { input: 0, output: 0 };
+    const visited = new Set(); // exact-ish state fingerprints
+    const visitedByScope = new Map(); // for Jaccard near-dup collapse
+    const queued = new Set(); // Address.id already in/through the frontier
+    const frontier = [];
+    const rawSignals = [];
+    const visitedUrls = [];
+    const triedSignatures = new Set();
+    const performedMutations = new Set();
+    const visitsPerScope = new Map();
+    const coverage = new CoverageAccumulator();
+    const ledger = new ExhaustivenessLedger();
+    // Record an ordered, driver-agnostic execution PLAN (addresses + node ids only) as the
+    // crawl runs — the cheap half of "discover once, replay cheaply". Persisted below.
+    const recorder = new PlanRecorder({ target: cfg.target, startUrl: cfg.startUrl });
+    // The LLM safety-judge is the HOSTED (strict) gate. In advisory (default) the deterministic
+    // floor's effect-based DENIES still apply, but ambiguous mutations proceed WITHOUT a per-action
+    // LLM call — preserving the LLM-free crawl and today's behavior for internal / BYO-key runs.
+    // Built once (one Anthropic client); undefined unless strict AND an LLM is configured.
+    const safetyJudge = cfg.actionGateMode === "strict" ? makeSafetyJudge(cfg) : undefined;
+    let states = 0;
+    let actions = 0;
+    let cappedBy;
+    // Hand the driver the coverage sink so its sub-metrics + target-specific skips land in
+    // the one honest ledger (BEFORE start, so any pass the driver wires at start can record).
+    driver.attachCoverage?.(coverage);
+    driver.attachRunDir?.(runDir);
+    // Driver-declared probes, fired at their lifecycle slot in registration order. `record`
+    // feeds the replay plan (no-op for the pre-beginState after-goto slot + the un-scoped
+    // finalize slot). This reproduces web's old fixed session/axe/dom/links/forms ordering
+    // exactly while letting any driver register new phases at the same slots.
+    const probesAt = (slot) => driver.capabilities.probes.filter((p) => p.slot === slot);
+    const runSlot = async (slot, record) => {
+        if (!driver.probe)
+            return [];
+        const out = [];
+        for (const reg of probesAt(slot)) {
+            if (record)
+                recorder.recordProbe(reg.name); // no-op until a state is begun
+            out.push(...(await driver.probe(reg.name)));
+        }
+        return out;
+    };
+    // Traversal itself spends NO tokens (picker is heuristic); the only model call is the
+    // post-crawl Opus judge, which enforces its own input cap (see triage.ts). So the token
+    // ceiling is not a crawl-loop backstop — these gates are wall-clock / states / actions only.
+    const overBudget = () => {
+        if (states >= cfg.maxStates)
+            return `maxStates(${cfg.maxStates})`;
+        if (actions >= cfg.maxActions)
+            return `maxActions(${cfg.maxActions})`;
+        if (Date.now() - startedAt >= cfg.maxWallClockMs)
+            return "maxWallClockMs";
+        return undefined;
+    };
+    const overActionBudget = () => {
+        if (actions >= cfg.maxActions)
+            return `maxActions(${cfg.maxActions})`;
+        if (Date.now() - startedAt >= cfg.maxWallClockMs)
+            return "maxWallClockMs";
+        return undefined;
+    };
+    // FRONTIER de-dup is by GOTO HANDLE (`dedupeKey ?? id`) — never the structural state hash
+    // (that is the `visited` fingerprint layer below). Web/API leave `dedupeKey` unset, so the
+    // key is `id` and behavior is unchanged; native sets it to a destination-screen fingerprint
+    // so two tap-paths reaching the same screen enqueue once.
+    const enqueue = (addr) => {
+        const key = addr.dedupeKey ?? addr.id;
+        if (driver.inScope(addr) && !queued.has(key)) {
+            queued.add(key);
+            frontier.push(addr);
+        }
+    };
+    // start() is INSIDE the try so a mid-start failure (e.g. WebDriver launches Chromium then
+    // throws in newContext()/route()) still hits the finally and closes the driver — otherwise a
+    // failed start leaks a headless browser process, compounding across CI runs.
+    try {
+        await driver.start();
+        const entry = driver.entryAddress();
+        enqueue(entry);
+        while (frontier.length > 0) {
+            cappedBy = overBudget();
+            if (cappedBy) {
+                coverage.cappedNotExhaustive = true;
+                break;
+            }
+            invariants({ actions, cfg });
+            const addr = frontier.shift();
+            const scope = addr.scope;
+            const visits = visitsPerScope.get(scope) ?? 0;
+            if (visits >= cfg.maxVisitsPerRoute) {
+                coverage.skip("route-visit-cap");
+                continue;
+            }
+            visitsPerScope.set(scope, visits + 1);
+            await driver.goto(addr);
+            rawSignals.push(...driver.drainSignals());
+            // AFTER-GOTO slot (web: session-bounce — emit, don't halt, avoids false-halt on
+            // legit /login routes). Fires before beginState, so it is not recorded into a state.
+            rawSignals.push(...(await runSlot("after-goto", true)));
+            const snap = await driver.snapshot();
+            const fp = stateFingerprint(snap);
+            if (visited.has(fp))
+                continue;
+            // Near-dup collapse, scoped to the same scope (so /user/1 vs /user/2 never merge).
+            const ns = nameSet(snap);
+            const priors = visitedByScope.get(scope) ?? [];
+            if (priors.some((p) => jaccardNearDup(ns, p) >= cfg.nearDupThreshold)) {
+                coverage.skip("near-dup-state");
+                continue;
+            }
+            visited.add(fp);
+            priors.push(ns);
+            visitedByScope.set(scope, priors);
+            states++;
+            coverage.noteState();
+            visitedUrls.push(snap.address.label ?? snap.address.id);
+            // Open this state's plan record BEFORE its probes/outbound/exercises so they attach to it.
+            recorder.beginState(snap.address);
+            // Screenshot the state for the report. Screenshots are RAW pixels of the target (on-screen
+            // secrets/PII can't be text-redacted), so --no-screenshots skips capture entirely.
+            if (cfg.screenshots) {
+                const shot = await driver.screenshot();
+                const shotPath = join(runDir, `state-${states}.png`);
+                if (shot.length)
+                    await writeFile(shotPath, shot).catch(() => { });
+            }
+            // AFTER-SNAPSHOT (pre-exercise) slot. Web order = axe (bounded a11y, driver
+            // self-limits) → dom (every-state sweep) → links (collect for the post-pass);
+            // registration order is preserved.
+            rawSignals.push(...(await runSlot("after-snapshot", true)));
+            // Frontier expansion #1: FOLLOW (never click) the driver's in-scope outbound targets.
+            if (driver.outboundAddresses)
+                for (const a of driver.outboundAddresses()) {
+                    if (driver.inScope(a))
+                        recorder.recordOutbound(a);
+                    enqueue(a);
+                }
+            const deps = {
+                driver,
+                cfg,
+                triedSignatures,
+                performedMutations,
+                overBudget: overActionBudget,
+                onSignal: (s) => rawSignals.push(s),
+                coverage,
+                ledger,
+                recordExercise: (id) => recorder.recordExercise(id),
+                // Frontier expansion #2: enqueue states the driver NAVIGATED to while acting
+                // (ExerciseResult.discovered), subject to inScope + caps/dedup (enqueue handles both).
+                enqueue,
+                safetyJudge,
+            };
+            actions += await exerciseState(snap, scope, deps);
+            // AFTER-EXERCISE slot (web: form testing — submits are egress-gated, state restored
+            // per-form). Gated behind dry-run / action budget exactly as the old forms call was.
+            if (!cfg.dryRun && !overActionBudget())
+                rawSignals.push(...(await runSlot("after-exercise", true)));
+        }
+        // FINALIZE slot (native: a final crash/ANR log scan) + the finalize extras (web:
+        // validate EVERY collected link) — both run while the session is still live.
+        rawSignals.push(...(await runSlot("finalize", false)));
+        if (driver.finalize)
+            rawSignals.push(...(await driver.finalize()));
+    }
+    finally {
+        await driver.close();
+    }
+    // Persist the recorded execution plan (always, cheap) for deterministic replay. Driver-
+    // agnostic (addresses + node ids only, no handles); honors --replay-out, else <runDir>/plan.json.
+    const planPath = cfg.replayOutPath ?? join(runDir, "plan.json");
+    await writeFile(planPath, JSON.stringify(recorder.toPlan(), null, 2)).catch(() => { });
+    // Pull any per-driver structured audit data (web: linkAudit) for the report/result.json.
+    const extra = driver.auditExtra ? driver.auditExtra() : undefined;
+    // Dedupe by signature → Finding[] with counts.
+    const bySig = new Map();
+    for (const s of normalizeBreakageSignals(rawSignals)) {
+        const existing = bySig.get(s.signature);
+        if (existing)
+            existing.count++;
+        else
+            bySig.set(s.signature, { ...s, count: 1 });
+    }
+    return {
+        startUrl: cfg.startUrl,
+        visitedStates: states,
+        visitedUrls,
+        actionsTaken: actions,
+        findings: [...bySig.values()].sort(compareFindings),
+        durationMs: Date.now() - startedAt,
+        tokenSpend: spend,
+        cappedBy,
+        frameBlindSpots: coverage.frameBlindSpots,
+        coverage: coverage.summary(),
+        exhaustivenessLedger: ledger.snapshot(),
+        ...(extra ? { extra } : {}),
+    };
+}

package/dist/core/crawl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crawl.js","sourceRoot":"","sources":["../../src/core/crawl.ts"],"names":[],"mappings":"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"}

package/dist/core/egress.js

@@ -0,0 +1,128 @@
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+function normalizeHostname(hostname) {
+    return hostname.replace(/^\[/, "").replace(/\]$/, "").toLowerCase();
+}
+function isPrivateIpv4(address) {
+    const parts = address.split(".").map((part) => Number(part));
+    if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
+        return false;
+    }
+    const [a, b] = parts;
+    if (a === undefined || b === undefined)
+        return false;
+    return (a === 0 ||
+        a === 10 ||
+        a === 127 ||
+        (a === 100 && b >= 64 && b <= 127) ||
+        (a === 169 && b === 254) ||
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 168) ||
+        (a === 198 && (b === 18 || b === 19)) ||
+        a >= 224);
+}
+function isPrivateIpv6(address) {
+    const value = normalizeHostname(address);
+    if (value === "::" || value === "::1" || value === "")
+        return true; // unspecified / loopback
+    if (value.startsWith("::ffff:"))
+        return isPrivateIp(value.slice("::ffff:".length)); // IPv4-mapped
+    const firstHextet = Number.parseInt(value.split(":")[0] || "", 16);
+    if (!Number.isFinite(firstHextet))
+        return false;
+    if (firstHextet >= 0xfe80 && firstHextet <= 0xfebf)
+        return true; // link-local fe80::/10 (was only fe80:*)
+    if ((firstHextet & 0xfe00) === 0xfc00)
+        return true; // unique-local fc00::/7
+    return false;
+}
+export function isPrivateIp(address) {
+    const value = normalizeHostname(address);
+    const family = isIP(value);
+    if (family === 4)
+        return isPrivateIpv4(value);
+    if (family === 6)
+        return isPrivateIpv6(value);
+    return false;
+}
+// Distinct sentinel so a DNS *timeout* is told apart from a genuine no-resolution.
+class DnsTimeoutError extends Error {
+}
+async function defaultResolveHost(hostname) {
+    // 3s ceiling (was 1s — too tight, flagged legit hosts on a slow resolver). On
+    // timeout we REJECT (transient) rather than resolve [] (which read as NXDOMAIN).
+    return await Promise.race([
+        lookup(hostname, { all: true }).then((rows) => rows.map((row) => row.address)),
+        new Promise((_, reject) => setTimeout(() => reject(new DnsTimeoutError("dns timeout")), 3_000)),
+    ]);
+}
+export async function checkNetworkEgress(rawUrl, resolveHost = defaultResolveHost) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        return { allowed: false, reason: "unparseable URL" };
+    }
+    // Network schemes only — http(s) and ws(s) (WebSocket connect targets are gated
+    // too). Everything else (mailto/tel/data/blob/javascript) is not a network hop.
+    if (!/^(?:https?|wss?):$/.test(url.protocol)) {
+        return { allowed: true };
+    }
+    const hostname = normalizeHostname(url.hostname);
+    if (hostname === "localhost" || hostname.endsWith(".localhost") || hostname === "metadata.google.internal") {
+        return { allowed: false, reason: "blocked local/metadata host" };
+    }
+    if (isIP(hostname)) {
+        return isPrivateIp(hostname) ? { allowed: false, reason: "blocked private IP" } : { allowed: true };
+    }
+    let addresses;
+    try {
+        addresses = await resolveHost(hostname);
+    }
+    catch (err) {
+        const code = err.code;
+        // Permanent non-resolution → stable block. Timeout / temporary failure →
+        // fail-closed for this attempt but mark transient so it is not cached.
+        if (code === "ENOTFOUND" || code === "NXDOMAIN" || code === "EAI_NONAME") {
+            return { allowed: false, reason: "host did not resolve (NXDOMAIN)" };
+        }
+        return { allowed: false, reason: `dns resolution transient failure (${code ?? "timeout"})`, transient: true };
+    }
+    if (addresses.length === 0)
+        return { allowed: false, reason: "host did not resolve publicly" };
+    if (addresses.some((address) => isPrivateIp(address))) {
+        return { allowed: false, reason: "host resolves to private IP" };
+    }
+    return { allowed: true };
+}
+export class EgressGuard {
+    resolveHost;
+    decisions = new Map();
+    constructor(resolveHost = defaultResolveHost) {
+        this.resolveHost = resolveHost;
+    }
+    check(rawUrl) {
+        let cacheKey = rawUrl;
+        try {
+            const url = new URL(rawUrl);
+            cacheKey = `${url.protocol}//${normalizeHostname(url.hostname)}`;
+        }
+        catch {
+            /* keep raw */
+        }
+        const existing = this.decisions.get(cacheKey);
+        if (existing)
+            return existing;
+        const key = cacheKey;
+        const pending = checkNetworkEgress(rawUrl, this.resolveHost).then((decision) => {
+            // Never cache a transient (DNS-timeout) verdict — re-resolve next time so a
+            // single slow lookup can't block a legitimate host for the whole run.
+            if (decision.transient)
+                this.decisions.delete(key);
+            return decision;
+        });
+        this.decisions.set(key, pending);
+        return pending;
+    }
+}

package/dist/core/egress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"egress.js","sourceRoot":"","sources":["../../src/core/egress.ts"],"names":[],"mappings":"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"}

package/dist/core/ledger.js

@@ -0,0 +1,41 @@
+export class ExhaustivenessLedger {
+    entries = [];
+    recordNode(address, node, intent, disposition, opts = {}) {
+        this.entries.push({
+            addressId: address.id,
+            addressScope: address.scope,
+            stateLabel: address.label,
+            nodeId: node.id,
+            nodeKind: node.kind,
+            nodeLabel: node.label,
+            intent,
+            disposition,
+            ...(opts.reason !== undefined ? { reason: opts.reason } : {}),
+            ...(opts.childTargetsDiscovered !== undefined ? { childTargetsDiscovered: opts.childTargetsDiscovered } : {}),
+        });
+    }
+    recordBlindSpot(address, blindSpot) {
+        this.entries.push({
+            addressId: address.id,
+            addressScope: address.scope,
+            stateLabel: address.label,
+            disposition: "blind-spot",
+            blindSpotKind: blindSpot.kind,
+            severity: blindSpot.severity,
+            message: blindSpot.message,
+        });
+    }
+    recordMissingNode(address, nodeId, reason) {
+        this.entries.push({
+            addressId: address.id,
+            addressScope: address.scope,
+            stateLabel: address.label,
+            nodeId,
+            disposition: "blocked",
+            reason,
+        });
+    }
+    snapshot() {
+        return this.entries.map((entry) => ({ ...entry }));
+    }
+}

package/dist/core/ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../../src/core/ledger.ts"],"names":[],"mappings":"AAqBA,MAAM,OAAO,oBAAoB;IACd,OAAO,GAAgC,EAAE,CAAC;IAE3D,UAAU,CACR,OAAgB,EAChB,IAAiB,EACjB,MAAuB,EACvB,WAA6D,EAC7D,OAA6D,EAAE;QAE/D,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;YAChB,SAAS,EAAE,OAAO,CAAC,EAAE;YACrB,YAAY,EAAE,OAAO,CAAC,KAAK;YAC3B,UAAU,EAAE,OAAO,CAAC,KAAK;YACzB,MAAM,EAAE,IAAI,CAAC,EAAE;YACf,QAAQ,EAAE,IAAI,CAAC,IAAI;YACnB,SAAS,EAAE,IAAI,CAAC,KAAK;YACrB,MAAM;YACN,WAAW;YACX,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7D,GAAG,CAAC,IAAI,CAAC,sBAAsB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,sBAAsB,EAAE,IAAI,CAAC,sBAAsB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9G,CAAC,CAAC;IACL,CAAC;IAED,eAAe,CAAC,OAAgB,EAAE,SAAoB;QACpD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;YAChB,SAAS,EAAE,OAAO,CAAC,EAAE;YACrB,YAAY,EAAE,OAAO,CAAC,KAAK;YAC3B,UAAU,EAAE,OAAO,CAAC,KAAK;YACzB,WAAW,EAAE,YAAY;YACzB,aAAa,EAAE,SAAS,CAAC,IAAI;YAC7B,QAAQ,EAAE,SAAS,CAAC,QAAQ;YAC5B,OAAO,EAAE,SAAS,CAAC,OAAO;SAC3B,CAAC,CAAC;IACL,CAAC;IAED,iBAAiB,CAAC,OAAgB,EAAE,MAAc,EAAE,MAAc;QAChE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;YAChB,SAAS,EAAE,OAAO,CAAC,EAAE;YACrB,YAAY,EAAE,OAAO,CAAC,KAAK;YAC3B,UAAU,EAAE,OAAO,CAAC,KAAK;YACzB,MAAM;YACN,WAAW,EAAE,SAAS;YACtB,MAAM;SACP,CAAC,CAAC;IACL,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC;IACrD,CAAC;CACF"}