knodin 0.7.6 → 0.8.2

package/dist/src/context-export.js

@@ -0,0 +1,423 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { RE2 } from "re2-wasm";
+import { compareBytes } from "./compare.js";
+import { measurePerfPhaseSync } from "./engine/perf.js";
+const DEFAULT_EXCLUDES = [".git/**", ".knodin/**", "node_modules/**", "dist/**", "build/**"];
+const GLOB_CACHE_LIMIT = 256;
+const globCache = new Map();
+function normalizeRelative(value) {
+    return value.replaceAll("\\", "/").replace(/^\.\//, "");
+}
+function globRegex(glob) {
+    const normalized = normalizeRelative(glob);
+    const cached = globCache.get(normalized);
+    if (cached)
+        return cached;
+    let source = "^";
+    for (let i = 0; i < normalized.length; i++) {
+        const char = normalized[i];
+        if (char === "*") {
+            if (normalized[i + 1] === "*") {
+                i++;
+                if (normalized[i + 1] === "/") {
+                    i++;
+                    source += "(?:.*/)?";
+                }
+                else
+                    source += ".*";
+            }
+            else
+                source += "[^/]*";
+        }
+        else if (char === "?")
+            source += "[^/]";
+        else
+            source += char.replace(/[\\^$+?.()|{}[\]]/g, "\\$&");
+    }
+    const compiled = new RegExp(`${source}$`);
+    if (globCache.size >= GLOB_CACHE_LIMIT) {
+        const oldest = globCache.keys().next().value;
+        if (oldest !== undefined)
+            globCache.delete(oldest);
+    }
+    globCache.set(normalized, compiled);
+    return compiled;
+}
+function matches(file, patterns) {
+    return patterns.some((pattern) => globRegex(normalizeRelative(pattern)).test(file));
+}
+function compilePatterns(patterns) {
+    return patterns.map((pattern) => globRegex(normalizeRelative(pattern)));
+}
+function matchesCompiled(file, patterns) {
+    return patterns.some((pattern) => pattern.test(file));
+}
+function walk(root, current = root, result = []) {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+        const absolute = path.join(current, entry.name);
+        const relative = normalizeRelative(path.relative(root, absolute));
+        if (matches(relative, DEFAULT_EXCLUDES) || matches(`${relative}/`, DEFAULT_EXCLUDES))
+            continue;
+        if (entry.isDirectory())
+            walk(root, absolute, result);
+        else if (entry.isFile())
+            result.push(relative);
+    }
+    return result;
+}
+function policyFor(file, policies) {
+    for (const { pattern, policy } of policies)
+        if (pattern.test(file))
+            return policy;
+    return "full";
+}
+function structureOnly(source, lineNumbers = false) {
+    return source
+        .split(/\r?\n/)
+        .map((line, index) => ({ line, index }))
+        .filter(({ line }) => /^\s*(export\s+)?(async\s+)?(class|interface|type|enum|function|const|let|var|def|module|namespace)\b/.test(line) || /^\s*(import|export)\b/.test(line))
+        .map(({ line, index }) => (lineNumbers ? `${index + 1}: ${line}` : line))
+        .join("\n");
+}
+function summarize(source, lineNumbers = false) {
+    const lines = source.split(/\r?\n/);
+    const structure = structureOnly(source, lineNumbers);
+    return [`[summary: ${lines.length} lines, ${Buffer.byteLength(source)} bytes]`, structure]
+        .filter(Boolean)
+        .join("\n");
+}
+function numbered(source) {
+    return source
+        .split(/\r?\n/)
+        .map((line, index) => `${index + 1}: ${line}`)
+        .join("\n");
+}
+function xmlEscape(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;");
+}
+function serialize(format, files, tree, git) {
+    if (format === "json")
+        return JSON.stringify({ tree, files, git }, null, 2);
+    if (format === "xml") {
+        const treeXml = tree
+            ? `<tree>${tree.map((item) => `<path>${xmlEscape(item)}</path>`).join("")}</tree>`
+            : "";
+        const filesXml = files
+            .map((file) => `<file path="${xmlEscape(file.path)}" policy="${file.policy}"><![CDATA[${file.content.replaceAll("]]>", "]]]]><![CDATA[>")}]]></file>`)
+            .join("");
+        const gitXml = git
+            ? `<git>${git.diff === undefined ? "" : `<diff><![CDATA[${git.diff.replaceAll("]]>", "]]]]><![CDATA[>")}]]></diff>`}${git.log === undefined ? "" : `<log><![CDATA[${git.log.replaceAll("]]>", "]]]]><![CDATA[>")}]]></log>`}</git>`
+            : "";
+        return `<context>${treeXml}<files>${filesXml}</files>${gitXml}</context>`;
+    }
+    const fenced = (content, language = "") => {
+        const longest = Math.max(0, ...[...content.matchAll(/`+/g)].map((match) => match[0].length));
+        const fence = "`".repeat(Math.max(3, longest + 1));
+        return [`${fence}${language}`, content, fence];
+    };
+    const chunks = ["# knodin context export"];
+    if (tree)
+        chunks.push("## Tree", ...fenced(tree.join("\n"), "text"));
+    for (const file of files)
+        chunks.push(`## ${file.path} (${file.policy})`, ...fenced(file.content));
+    if (git?.diff !== undefined)
+        chunks.push("## Git diff", ...fenced(git.diff, "diff"));
+    if (git?.log !== undefined)
+        chunks.push("## Git log", ...fenced(git.log, "text"));
+    return chunks.join("\n");
+}
+/**
+ * Exact serialized-byte contribution for one additional file. Serializing a
+ * single candidate (plus a constant sentinel for non-first entries) keeps pack
+ * selection linear in total source bytes instead of repeatedly serializing the
+ * whole growing artifact.
+ */
+function serializedFileByteDelta(format, file, hasFiles) {
+    if (!hasFiles)
+        return Buffer.byteLength(serialize(format, [file])) - Buffer.byteLength(serialize(format, []));
+    const sentinel = { path: "", policy: "full", content: "" };
+    return (Buffer.byteLength(serialize(format, [sentinel, file])) -
+        Buffer.byteLength(serialize(format, [sentinel])));
+}
+function gitSections(repo, request) {
+    if (!request)
+        return undefined;
+    const run = (args) => execFileSync("git", args, { cwd: repo, encoding: "utf8", maxBuffer: 4 * 1024 * 1024 });
+    const result = {};
+    if (request.diffScope) {
+        const revision = (value) => {
+            const hasControl = [...value].some((character) => {
+                const code = character.charCodeAt(0);
+                return code < 32 || code === 127;
+            });
+            if (!value || value.startsWith("-") || hasControl)
+                throw new Error(`knodin pack: invalid git revision: ${value}`);
+            return value;
+        };
+        const args = request.diffScope === "unstaged"
+            ? ["diff", "--"]
+            : request.diffScope === "staged"
+                ? ["diff", "--cached", "--"]
+                : request.diffScope === "compare"
+                    ? ["diff", revision(request.from ?? "HEAD~1"), revision(request.to ?? "HEAD"), "--"]
+                    : ["diff", revision(request.from ?? "HEAD"), "--"];
+        result.diff = run(args);
+    }
+    if (request.log !== undefined)
+        result.log = run([
+            "log",
+            `-${Math.max(0, Math.min(100, Math.floor(request.log)))}`,
+            "--oneline",
+        ]);
+    return result;
+}
+function safeOutput(repo, output) {
+    const absolute = path.resolve(repo, output);
+    if (absolute !== repo && !absolute.startsWith(`${repo}${path.sep}`))
+        throw new Error("knodin pack: outputPath must stay inside the repository");
+    if (fs.existsSync(absolute)) {
+        const realTarget = fs.realpathSync(absolute);
+        if (realTarget !== repo && !realTarget.startsWith(`${repo}${path.sep}`))
+            throw new Error("knodin pack: outputPath may not follow a symlink outside the repository");
+    }
+    let parent = path.dirname(absolute);
+    while (!fs.existsSync(parent) && parent !== repo)
+        parent = path.dirname(parent);
+    const realParent = fs.realpathSync(parent);
+    if (realParent !== repo && !realParent.startsWith(`${repo}${path.sep}`))
+        throw new Error("knodin pack: outputPath may not traverse a symlink outside the repository");
+    return absolute;
+}
+export function exportContext(repoPath, request = {}) {
+    const repo = fs.realpathSync(repoPath);
+    const format = request.format ?? "markdown";
+    if (!["markdown", "json", "xml"].includes(format))
+        throw new Error("knodin pack: format must be markdown, json, or xml");
+    if (request.byteBudget !== undefined &&
+        (!Number.isFinite(request.byteBudget) || request.byteBudget < 256))
+        throw new Error("knodin pack: byteBudget must be at least 256");
+    if (request.tokenBudget !== undefined &&
+        (!Number.isFinite(request.tokenBudget) || request.tokenBudget < 64))
+        throw new Error("knodin pack: tokenBudget must be at least 64");
+    if (request.git?.diffScope !== undefined &&
+        !["unstaged", "staged", "all", "compare"].includes(request.git.diffScope))
+        throw new Error("knodin pack: invalid git diff scope");
+    if (request.git?.log !== undefined &&
+        (!Number.isInteger(request.git.log) || request.git.log < 0 || request.git.log > 100))
+        throw new Error("knodin pack: git log must be an integer from 0 to 100");
+    if (Object.values(request.policies ?? {}).some((policy) => !["full", "summary", "structure-only"].includes(policy)))
+        throw new Error("knodin pack: invalid file policy");
+    const byteLimit = Math.floor(request.byteBudget ?? 65_536);
+    const tokenLimit = Math.floor(request.tokenBudget ?? 16_384);
+    const hardLimit = Math.min(byteLimit, tokenLimit * 4);
+    const include = request.include?.length ? request.include : ["**"];
+    const exclude = [...DEFAULT_EXCLUDES, ...(request.exclude ?? [])];
+    const includePatterns = compilePatterns(include);
+    const excludePatterns = compilePatterns(exclude);
+    const policyRules = request.policies ?? {};
+    const policies = Object.keys(policyRules)
+        .sort(compareBytes)
+        .map((pattern) => ({
+        pattern: globRegex(normalizeRelative(pattern)),
+        policy: policyRules[pattern],
+    }));
+    const omitted = new Set([...(request.alreadyPresent ?? []), ...(request.chatFiles ?? [])].map(normalizeRelative));
+    if (request.outputPath)
+        omitted.add(normalizeRelative(request.outputPath));
+    const candidates = measurePerfPhaseSync("pack_walk", () => walk(repo))
+        .filter((file) => matchesCompiled(file, includePatterns) &&
+        !matchesCompiled(file, excludePatterns) &&
+        !omitted.has(file))
+        .sort(compareBytes);
+    let tree = request.includeTree ? [...candidates] : undefined;
+    let git = gitSections(repo, request.git);
+    const files = [];
+    const measuredSerialize = () => measurePerfPhaseSync("pack_serialize", () => serialize(format, files, tree, git));
+    let artifact = measuredSerialize();
+    if (Buffer.byteLength(artifact) > hardLimit) {
+        git = undefined;
+        artifact = measuredSerialize();
+    }
+    if (Buffer.byteLength(artifact) > hardLimit) {
+        tree = undefined;
+        artifact = measuredSerialize();
+    }
+    let serializedSize = Buffer.byteLength(artifact);
+    for (const file of candidates) {
+        const policy = policyFor(file, policies);
+        let content = fs.readFileSync(path.join(repo, file), "utf8");
+        if (policy === "summary")
+            content = summarize(content, request.lineNumbers);
+        else if (policy === "structure-only")
+            content = structureOnly(content, request.lineNumbers);
+        else if (request.lineNumbers)
+            content = numbered(content);
+        const packed = { path: file, policy, content };
+        const delta = measurePerfPhaseSync("pack_serialize", () => serializedFileByteDelta(format, packed, files.length > 0));
+        if (serializedSize + delta > hardLimit)
+            continue;
+        files.push(packed);
+        serializedSize += delta;
+    }
+    artifact = measuredSerialize();
+    const serializedBytes = Buffer.byteLength(artifact);
+    const outputAbsolute = request.outputPath ? safeOutput(repo, request.outputPath) : undefined;
+    const result = {
+        format,
+        artifact,
+        files: files.map(({ path: filePath, policy }) => ({ path: filePath, policy })),
+        telemetry: {
+            byteLimit,
+            tokenLimit,
+            serializedBytes,
+            responseBytes: 0,
+            estimatedTokens: Math.ceil(serializedBytes / 4),
+            tokenizer: "estimate:deterministic-utf8-bytes-divided-by-4",
+            includedFiles: files.length,
+            candidateFiles: candidates.length,
+            truncated: files.length < candidates.length,
+        },
+        ...(outputAbsolute
+            ? { outputPath: normalizeRelative(path.relative(repo, outputAbsolute)) }
+            : {}),
+    };
+    const updateResponseBytes = () => {
+        for (let index = 0; index < 4; index++) {
+            const actual = Buffer.byteLength(JSON.stringify(result));
+            if (actual === result.telemetry.responseBytes)
+                break;
+            result.telemetry.responseBytes = actual;
+        }
+    };
+    updateResponseBytes();
+    while (result.telemetry.responseBytes > hardLimit && files.length > 0) {
+        files.pop();
+        result.files.pop();
+        result.artifact = measuredSerialize();
+        result.telemetry.serializedBytes = Buffer.byteLength(result.artifact);
+        result.telemetry.estimatedTokens = Math.ceil(result.telemetry.serializedBytes / 4);
+        result.telemetry.includedFiles = files.length;
+        result.telemetry.truncated = true;
+        updateResponseBytes();
+    }
+    if (result.telemetry.responseBytes > hardLimit)
+        throw new Error("knodin pack: budget is too small for the requested format and telemetry");
+    if (outputAbsolute) {
+        fs.mkdirSync(path.dirname(outputAbsolute), { recursive: true });
+        fs.writeFileSync(outputAbsolute, result.artifact);
+    }
+    return result;
+}
+function safeArtifact(repoPath, artifactPath) {
+    const repo = fs.realpathSync(repoPath);
+    const absolute = path.resolve(repo, artifactPath);
+    if (absolute !== repo && !absolute.startsWith(`${repo}${path.sep}`))
+        throw new Error("knodin pack: artifactPath must stay inside the repository");
+    const real = fs.realpathSync(absolute);
+    if (real !== repo && !real.startsWith(`${repo}${path.sep}`))
+        throw new Error("knodin pack: artifactPath may not follow a symlink outside the repository");
+    const stat = fs.statSync(real);
+    if (!stat.isFile() || stat.size > 16 * 1024 * 1024)
+        throw new Error("knodin pack: artifactPath must be a packed file no larger than 16 MiB");
+    return real;
+}
+const ARTIFACT_CACHE_ENTRY_LIMIT = 2;
+const ARTIFACT_CACHE_FILE_LIMIT = 4 * 1024 * 1024;
+const artifactLineCache = new Map();
+function artifactLines(repoPath, artifactPath) {
+    const real = safeArtifact(repoPath, artifactPath);
+    const stat = fs.statSync(real);
+    const cached = artifactLineCache.get(real);
+    if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
+        artifactLineCache.delete(real);
+        artifactLineCache.set(real, cached);
+        return cached.lines;
+    }
+    if (cached)
+        artifactLineCache.delete(real);
+    const lines = fs.readFileSync(real, "utf8").split(/\r?\n/);
+    if (stat.size <= ARTIFACT_CACHE_FILE_LIMIT) {
+        while (artifactLineCache.size >= ARTIFACT_CACHE_ENTRY_LIMIT) {
+            const oldest = artifactLineCache.keys().next().value;
+            if (oldest === undefined)
+                break;
+            artifactLineCache.delete(oldest);
+        }
+        artifactLineCache.set(real, { mtimeMs: stat.mtimeMs, size: stat.size, lines });
+    }
+    return lines;
+}
+function truncateUtf8(value, byteLimit) {
+    if (Buffer.byteLength(value) <= byteLimit)
+        return value;
+    let low = 0;
+    let high = value.length;
+    while (low < high) {
+        const midpoint = Math.ceil((low + high) / 2);
+        if (Buffer.byteLength(value.slice(0, midpoint)) <= byteLimit)
+            low = midpoint;
+        else
+            high = midpoint - 1;
+    }
+    return value.slice(0, low);
+}
+export function readPackedArtifact(repoPath, artifactPath, startLine = 1, endLine = startLine + 199, byteBudget = 16_384) {
+    if (!Number.isFinite(byteBudget) || !Number.isInteger(byteBudget) || byteBudget < 256)
+        throw new Error("knodin pack read: byteBudget must be an integer >= 256");
+    if (!Number.isInteger(startLine) ||
+        !Number.isInteger(endLine) ||
+        startLine < 1 ||
+        endLine < startLine ||
+        endLine - startLine > 999)
+        throw new Error("knodin pack read: invalid or unbounded line range");
+    const lines = measurePerfPhaseSync("artifact_read", () => artifactLines(repoPath, artifactPath).slice(startLine - 1, endLine));
+    let content = lines.join("\n");
+    const limit = Math.max(256, Math.min(65_536, Math.floor(byteBudget)));
+    content = truncateUtf8(content, limit);
+    return {
+        artifactPath: normalizeRelative(artifactPath),
+        startLine,
+        endLine: startLine + content.split(/\r?\n/).length - 1,
+        content,
+        truncated: lines.join("\n") !== content,
+    };
+}
+export function grepPackedArtifact(repoPath, artifactPath, pattern, flags = "", limit = 100) {
+    if (!Number.isFinite(limit) || !Number.isInteger(limit) || limit < 1 || limit > 1000)
+        throw new Error("knodin pack grep: limit must be an integer from 1 to 1000");
+    if (pattern.length === 0 || pattern.length > 1000 || !/^[gimsuy]*$/.test(flags))
+        throw new Error("knodin pack grep: invalid regex or flags");
+    let regex;
+    try {
+        const safeFlags = flags.replace("g", "").includes("u")
+            ? flags.replace("g", "")
+            : `${flags.replace("g", "")}u`;
+        regex = new RE2(pattern, safeFlags);
+    }
+    catch {
+        throw new Error("knodin pack grep: invalid or unsupported linear-time regex");
+    }
+    const matches = [];
+    measurePerfPhaseSync("artifact_grep", () => {
+        for (const [index, text] of artifactLines(repoPath, artifactPath).entries()) {
+            regex.lastIndex = 0;
+            if (regex.test(text))
+                matches.push({ line: index + 1, text });
+            if (matches.length >= Math.max(1, Math.min(1000, Math.floor(limit))))
+                break;
+        }
+    });
+    return {
+        artifactPath: normalizeRelative(artifactPath),
+        pattern,
+        flags,
+        matches,
+        truncated: matches.length >= limit,
+    };
+}

package/dist/src/context.js

@@ -0,0 +1,102 @@
+/**
+ * Logic for the `knodin context` operation — the "call this FIRST" ultra-
+ * compact orientation. Lives in its own neutral module, mirroring
+ * `pr-triage.ts`'s role for the `prs` operation: `bin/cli.ts` and
+ * `src/tools/knodin-tools.ts` both import from here independently, rather
+ * than the CLI reaching into the MCP-gateway module the way it previously did
+ * (code review finding — R23-R28 reuse/altitude pass).
+ */
+import { measurePerfPhase } from "./engine/perf.js";
+/** Keyword heuristic mapping a free-text `task` to a suggested next knodin
+ * operation for the `context` op. This is explicitly a hint, not a claim of
+ * understanding intent — a wrong guess must never stop the caller from reaching
+ * for any operation directly (R26). Order matters: review-shaped tasks win over
+ * map-shaped ones, and a bare single-symbol token routes to `explain`. */
+export function suggestNextOperation(task) {
+    const t = task.toLowerCase();
+    if (/\b(bug|review|diff|pr|pull request|regression|risk|approve|merge)\b/.test(t)) {
+        return "review";
+    }
+    if (/\b(batch outline|file outline|outline files?|project overview|directory overview)\b/.test(t)) {
+        return "query";
+    }
+    if (/\b(how does|how do|architecture|architectural|structure|structured|design|subsystem|boundaries|overview)\b/.test(t)) {
+        return "map";
+    }
+    // A bare identifier-shaped token (a single symbol name) → explain it directly.
+    if (/^[A-Za-z_]\w*$/.test(task.trim())) {
+        return "explain";
+    }
+    // Otherwise no exact symbol is known → fuzzy search to find a starting point.
+    return "search";
+}
+function suggestedStructuralPattern(task) {
+    const normalized = task.toLowerCase();
+    if (/\bbatch outline\b/.test(normalized))
+        return "batch_outline";
+    if (/\b(project|directory) overview\b/.test(normalized))
+        return "project_overview";
+    if (/\bfile outline\b|\boutline (?:the )?file\b/.test(normalized))
+        return "file_summary";
+    return undefined;
+}
+/**
+ * R26 `context` operation — the "call this FIRST" ultra-compact orientation.
+ * Composes EXISTING public engine methods only (`map`, `query stats`,
+ * `query flows`, `review`) so it never touches `src/engine/index.ts` and stays
+ * parallel-safe against the query-dispatch work landing there. Takes an
+ * `engine: KnodinEngine` parameter rather than constructing its own, so the
+ * `knodin-tools.ts` module-level `createEngine()` singleton is never
+ * duplicated or side-effected by this module's existence.
+ */
+export async function buildKnodinContext(eng, task, repo, base, changedFiles) {
+    return measurePerfPhase("context_composition", async () => {
+        // Establish one full graph snapshot first: stats requires that same standard
+        // map, so asking for a separate minimal map would run community analytics
+        // twice. Once initialized, the remaining read-only facets can safely share
+        // the generation and freshness lease.
+        const CONTEXT_TOP = 5;
+        const mapResult = await eng.map(repo, "standard");
+        const shouldReview = changedFiles === undefined || changedFiles.length > 0;
+        const [statsResult, flowsResult, review] = await Promise.all([
+            eng.query("stats", "", repo),
+            eng.query("flows", "", repo, undefined, CONTEXT_TOP),
+            shouldReview ? eng.review(base ?? "HEAD~1", repo, "minimal") : Promise.resolve(undefined),
+        ]);
+        // Risk score: eng.review() always re-derives the diff from `git diff <base>`;
+        // it has no seam for an explicit file list, so `changedFiles`, when supplied,
+        // is only a caller hint — an explicit empty array means "no changes, skip the
+        // diff". When there IS a diff but it touches no indexed symbols, review
+        // returns changedSymbolCount 0 and a meaningless riskScore 0; omit the field
+        // in that case rather than report a misleading 0 (R26 acceptance criterion).
+        let riskScore;
+        if (review && review.changedSymbolCount > 0)
+            riskScore = review.riskScore;
+        // Truncate aggressively — this is a ~100-300 token orientation, not a dump of
+        // map()'s full payload. Sort defensively so "top" holds even if an engine
+        // method's ordering changes; flows already arrive most-critical first (capped
+        // at CONTEXT_TOP via the query limit above).
+        return {
+            repoPath: repo,
+            task,
+            stats: statsResult.totals,
+            communities: [...mapResult.communities]
+                .sort((a, b) => b.size - a.size)
+                .slice(0, CONTEXT_TOP)
+                .map((c) => ({ name: c.name, size: c.size })),
+            hubs: [...mapResult.hubs]
+                .sort((a, b) => b.degree - a.degree)
+                .slice(0, CONTEXT_TOP)
+                .map((h) => ({ symbol: h.symbol, degree: h.degree })),
+            flows: flowsResult.results
+                .slice(0, CONTEXT_TOP)
+                .map((f) => ({ symbol: f.symbol, criticality: f.criticality })),
+            ...(riskScore !== undefined ? { riskScore } : {}),
+            suggestedOperation: suggestNextOperation(task),
+            ...(suggestedStructuralPattern(task)
+                ? { suggestedQueryPattern: suggestedStructuralPattern(task) }
+                : {}),
+            suggestionNote: "Heuristic from keywords in `task`; a hint only — any operation can be called directly regardless.",
+        };
+    });
+}

package/dist/src/deterministic-random.js

@@ -0,0 +1,34 @@
+/**
+ * Deterministic pseudo-random number generation.
+ *
+ * knodin never calls `Math.random` in production code: index topology, graph
+ * layout, and every artifact they feed must be reproducible so that a rerun
+ * over unchanged evidence produces a byte-identical result. Callers that need
+ * randomness seed one of these generators instead.
+ */
+/** Default seed (golden-ratio constant) shared by callers without their own. */
+export const DEFAULT_PRNG_SEED = 0x9e3779b9;
+/** Deterministic PRNG so derived structures are reproducible across runs. */
+export function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a |= 0;
+        a = (a + 0x6d2b79f5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/**
+ * Folds a string into a 32-bit seed (FNV-1a). Lets a caller derive a stable
+ * seed from repository-scoped evidence such as a commit id, so the same
+ * evidence always produces the same output.
+ */
+export function seedFromString(value) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < value.length; index++) {
+        hash ^= value.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 0;
+}