knodin 0.7.5 → 0.8.2

package/dist/src/progressive-evidence.js

@@ -1,7 +1,9 @@
 import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-const LEVELS = ["locate", "outline", "evidence", "expand"];
+import { compareBytes } from "./compare.js";
+import { resolveStateDir } from "./engine/state-paths.js";
+const LEVELS = new Set(["locate", "outline", "evidence", "expand"]);
 const DEFAULT_BYTES = 65_536;
 const DEFAULT_TOKENS = 16_384;
 const DEFAULT_ITEMS = 100;
@@ -37,7 +39,7 @@ function normalizeFile(repo, file) {
     return { absolute, relative, root };
 }
 function handleSecret(root) {
-    const stateDirectory = path.join(root, ".knodin");
+    const stateDirectory = resolveStateDir(root);
     if (fs.existsSync(stateDirectory) && fs.lstatSync(stateDirectory).isSymbolicLink())
         throw new Error("progressive evidence refuses a symlinked .knodin directory");
     fs.mkdirSync(stateDirectory, { recursive: true, mode: 0o700 });
@@ -96,7 +98,7 @@ function decodeHandle(value, secret) {
         (candidate.relatedOffset ?? -1) < 0 ||
         !Number.isSafeInteger(candidate.outlineOffset) ||
         (candidate.outlineOffset ?? -1) < 0 ||
-        !LEVELS.includes(candidate.nextLevel))
+        !LEVELS.has(candidate.nextLevel))
         throw new Error("invalid continuation handle");
     return candidate;
 }
@@ -142,7 +144,9 @@ function findRelated(root, target, lines) {
     const visit = (directory) => {
         for (const entry of fs
             .readdirSync(directory, { withFileTypes: true })
-            .sort((a, b) => a.name.localeCompare(b.name))) {
+            // Byte order: this walk order fixes the related-evidence sequence that
+            // the integrity-checked paging handle indexes into across calls.
+            .sort((a, b) => compareBytes(a.name, b.name))) {
             if ([".git", ".knodin", "node_modules"].includes(entry.name) || entry.isSymbolicLink())
                 continue;
             const absolute = path.join(directory, entry.name);
@@ -154,7 +158,7 @@ function findRelated(root, target, lines) {
             if (!entry.isFile() || file === target || !/\.(?:[cm]?[jt]sx?|py|java|cs|go|rs)$/.test(file))
                 continue;
             for (const [index, evidence] of fs.readFileSync(absolute, "utf8").split("\n").entries()) {
-                if (!names.some((name) => new RegExp(`\\b${name}\\b`).test(evidence)))
+                if (!names.some((name) => new RegExp(String.raw `\b${name}\b`).test(evidence)))
                     continue;
                 results.push({
                     file,
@@ -195,7 +199,7 @@ function omissionPath(request, handle, currentHash, contentBytes, relative) {
  * content and a complete byte-length assertion.
  */
 export function deliverProgressiveEvidence(request) {
-    if (!LEVELS.includes(request.level))
+    if (!LEVELS.has(request.level))
         throw new Error("invalid progressive evidence level");
     const { absolute, relative, root } = normalizeFile(request.repo, request.file);
     const handleKey = handleSecret(root);
@@ -290,12 +294,12 @@ export function deliverProgressiveEvidence(request) {
                 returned = [...returned, "source"];
                 nextLine = last + 1;
                 more = last < lines.length || request.level !== "expand";
-                omitted =
-                    last < lines.length
-                        ? ["source-tail", "related"]
-                        : request.level === "expand"
-                            ? []
-                            : ["related"];
+                if (last < lines.length)
+                    omitted = ["source-tail", "related"];
+                else if (request.level === "expand")
+                    omitted = [];
+                else
+                    omitted = ["related"];
                 reason = last < lines.length ? "hard-item-budget" : "requested-level";
             }
             totalItems = lines.length;
@@ -318,15 +322,13 @@ export function deliverProgressiveEvidence(request) {
             totalItems = lines.length + allRelated.length;
         }
     }
-    const nextLevel = request.level === "locate"
-        ? "outline"
-        : request.level === "outline"
-            ? outlineOffset + (outline?.length ?? 0) < outlineTotal
-                ? "outline"
-                : "evidence"
-            : more && nextLine <= lines.length
-                ? request.level
-                : "expand";
+    let nextLevel;
+    if (request.level === "locate")
+        nextLevel = "outline";
+    else if (request.level === "outline")
+        nextLevel = outlineOffset + (outline?.length ?? 0) < outlineTotal ? "outline" : "evidence";
+    else
+        nextLevel = more && nextLine <= lines.length ? request.level : "expand";
     const evidenceHandle = encodeHandle({
         v: 1,
         path: relative,
@@ -448,11 +450,13 @@ export function deliverProgressiveEvidence(request) {
         response.reason = "hard-byte-budget";
         if (!response.omitted.includes("source-tail"))
             response.omitted.unshift("source-tail");
-        const resumeLine = response.sourceRange?.endLine
-            ? response.sourceRange.endLine + 1
-            : continuationMismatch
-                ? 1
-                : (request.startLine ?? pagingHandle?.nextLine ?? 1);
+        let resumeLine;
+        if (response.sourceRange?.endLine)
+            resumeLine = response.sourceRange.endLine + 1;
+        else if (continuationMismatch)
+            resumeLine = 1;
+        else
+            resumeLine = request.startLine ?? pagingHandle?.nextLine ?? 1;
         response.continuation = encodeHandle({
             v: 1,
             path: relative,

package/dist/src/pure-compression-cli.js

@@ -36,10 +36,11 @@ function human(result) {
     const artifact = result.artifact.retained
         ? ` Retained artifact: ${result.artifact.id} (${result.artifact.path}).`
         : " Raw retention disabled; omitted regions cannot be retrieved.";
-    return `${result.content ? `${result.content}\n` : ""}---\n${fidelity} ${result.output.lines}/${result.input.lines} lines, ${result.output.bytes}/${result.input.bytes} bytes; exit=${result.exit.code ?? "unknown"}, signal=${result.exit.signal ?? "none"}.${artifact}\n`;
+    const body = result.content ? `${result.content}\n` : "";
+    return `${body}---\n${fidelity} ${result.output.lines}/${result.input.lines} lines, ${result.output.bytes}/${result.input.bytes} bytes; exit=${result.exit.code ?? "unknown"}, signal=${result.exit.signal ?? "none"}.${artifact}\n`;
 }
 /** Handle only pure compression creation. Artifact reads/diagnosis retain the full CLI contract. */
-export async function tryPureCompressionFastPath(argv, cwd = process.cwd()) {
+export async function tryPureCompressionFastPath(argv, cwd) {
     if (argv[0] !== "compress")
         return false;
     const valueFlags = new Set([
@@ -74,7 +75,7 @@ export async function tryPureCompressionFastPath(argv, cwd = process.cwd()) {
         "cargo",
     ].includes(adapter))
         return false;
-    const repo = path.resolve(valueAfter(argv, "--repo") ?? cwd);
+    const repo = path.resolve(valueAfter(argv, "--repo") ?? cwd ?? process.cwd());
     const maxInputBytes = boundedInteger(argv, "--max-input-bytes", 16 * 1024 * 1024, 1, 64 * 1024 * 1024);
     const request = {
         exitCode: valueAfter(argv, "--exit-code")

package/dist/src/relationship-adapters.js

@@ -2,12 +2,13 @@ import childProcess from "node:child_process";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { compareBytes } from "./compare.js";
 import { gitExecutable } from "./git-executable.js";
 const MAX_FILES = 5_000;
 const MAX_CONTRACT_BYTES = 2 * 1024 * 1024;
 export function trackedRepositoryFiles(repository) {
     try {
-        return childProcess
+        return (childProcess
             .execFileSync(gitExecutable(), ["ls-files", "-z"], {
             cwd: repository,
             encoding: "utf-8",
@@ -15,8 +16,10 @@ export function trackedRepositoryFiles(repository) {
         })
             .split("\0")
             .filter(Boolean)
-            .sort((left, right) => left.localeCompare(right))
-            .slice(0, MAX_FILES);
+            // Byte order: this sort decides which files survive the MAX_FILES cap,
+            // so collation would change which files are scanned at all.
+            .sort(compareBytes)
+            .slice(0, MAX_FILES));
     }
     catch {
         return [];
@@ -41,7 +44,7 @@ function packageFindings(file, content) {
                 const dependencies = manifest[section];
                 if (typeof dependencies !== "object" || dependencies === null)
                     continue;
-                for (const name of Object.keys(dependencies).sort((left, right) => left.localeCompare(right))) {
+                for (const name of Object.keys(dependencies).sort(compareBytes)) {
                     findings.push({
                         type: "depends_on",
                         target: `pkg:npm/${encodeURIComponent(name)}`,
@@ -279,7 +282,9 @@ export function extractRepositoryRelationships(repositoryId, repository, knownPa
             });
         }
     }
-    return relationships.sort((left, right) => `${left.from}\0${left.type}\0${left.to}\0${left.evidence.location}`.localeCompare(`${right.from}\0${right.type}\0${right.to}\0${right.evidence.location}`));
+    // Byte order over a NUL-joined composite key: collation may ignore the NUL
+    // separators entirely, which blurs the field boundaries this key depends on.
+    return relationships.sort((left, right) => compareBytes(`${left.from}\0${left.type}\0${left.to}\0${left.evidence.location}`, `${right.from}\0${right.type}\0${right.to}\0${right.evidence.location}`));
 }
 /** Stream a file hash so duplicate detection never buffers an entire artifact. */
 export async function hashFileStream(file) {
@@ -294,7 +299,7 @@ export async function hashFileStream(file) {
 }
 function filesGroupedBySize(repositories) {
     const bySize = new Map();
-    const orderedRepositories = [...repositories].sort((left, right) => left.id.localeCompare(right.id));
+    const orderedRepositories = [...repositories].sort((left, right) => compareBytes(left.id, right.id));
     for (const repository of orderedRepositories) {
         for (const file of trackedRepositoryFiles(repository.path)) {
             const absolute = path.join(repository.path, file);
@@ -327,7 +332,9 @@ function duplicateRelationships(matches) {
     const repositoryIds = new Set(matches.map(({ repositoryId }) => repositoryId));
     if (repositoryIds.size < 2)
         return [];
-    const ordered = [...matches].sort((left, right) => `${left.repositoryId}\0${left.file}`.localeCompare(`${right.repositoryId}\0${right.file}`));
+    // Byte order: `ordered[0]` becomes the canonical side of every emitted
+    // duplicate_candidate, so collation would change the relationship direction.
+    const ordered = [...matches].sort((left, right) => compareBytes(`${left.repositoryId}\0${left.file}`, `${right.repositoryId}\0${right.file}`));
     const canonical = ordered[0];
     if (!canonical)
         return [];
@@ -366,5 +373,5 @@ export async function detectDuplicateCandidates(repositories) {
             relationships.push(...duplicateRelationships(matches));
         }
     }
-    return relationships.sort((left, right) => `${left.from}\0${left.to}\0${left.evidence.location}`.localeCompare(`${right.from}\0${right.to}\0${right.evidence.location}`));
+    return relationships.sort((left, right) => compareBytes(`${left.from}\0${left.to}\0${left.evidence.location}`, `${right.from}\0${right.to}\0${right.evidence.location}`));
 }

package/dist/src/release-preflight.js

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import { createHash, createPublicKey } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { compareBytes } from "./compare.js";
 import { validateRootCeremonyManifest } from "./update-ceremony.js";
 import { canonicalizeUpdateMetadata, verifyUpdateRootChain, } from "./update-trust.js";
 export const RELEASE_PREFLIGHT_DEPENDENCIES = [
@@ -21,6 +22,7 @@ export const RELEASE_PREFLIGHT_REPOSITORY_COMMANDS = [
     "npm run test",
     "npm run test:pack-install",
     "npm run check:roadmap",
+    "npm run verify:c95",
 ];
 export const RELEASE_PREFLIGHT_REPLAY_COMMANDS = {
     competitive: [
@@ -65,8 +67,8 @@ function record(value, label) {
     return value;
 }
 function exactKeys(value, expected, label) {
-    const keys = Object.keys(value).sort();
-    const wanted = [...expected].sort();
+    const keys = Object.keys(value).sort(compareBytes);
+    const wanted = [...expected].sort(compareBytes);
     if (keys.length !== wanted.length || keys.some((key, index) => key !== wanted[index]))
         fail(`${label} must contain exactly: ${wanted.join(", ")}`);
 }
@@ -317,8 +319,8 @@ function requireTaggedBytes(git, commit, relativePath, bytes, label) {
         fail(`${label} bytes do not equal the exact source-commit blob`);
 }
 function verifyRoadmap(roadmap) {
-    const activeLedger = roadmap.match(/### Track A — Active local-work ledger\n[\s\S]*?\n\| ID \| State \| Previous state \| Depends on \| Exit evidence \|\n\|---\|---\|---\|---\|---\|\n((?:\| C[^\n]+\n)*)\n### Track B — Parked external-evidence ledger/);
-    const parkedLedger = roadmap.match(/### Track B — Parked external-evidence ledger\n[\s\S]*?\n\| ID \| State \| Previous state \| Depends on \| Exit evidence \|\n\|---\|---\|---\|---\|---\|\n((?:\| C[^\n]+\n)*)\n### Goal-loop ordering/);
+    const activeLedger = /### Track A — Active local-work ledger\n[\s\S]*?\n\| ID \| State \| Previous state \| Depends on \| Exit evidence \|\n\|---\|---\|---\|---\|---\|\n((?:\| C[^\n]+\n)*)\n### Track B — Parked external-evidence ledger/.exec(roadmap);
+    const parkedLedger = /### Track B — Parked external-evidence ledger\n[\s\S]*?\n\| ID \| State \| Previous state \| Depends on \| Exit evidence \|\n\|---\|---\|---\|---\|---\|\n((?:\| C[^\n]+\n)*)\n### Goal-loop ordering/.exec(roadmap);
     if (!activeLedger || !parkedLedger)
         fail("two-track roadmap ledger is missing or malformed");
     const activeIds = new Set([...activeLedger[1].matchAll(/^\| (C\d+) \|/gm)].map((match) => match[1]));
@@ -330,17 +332,17 @@ function verifyRoadmap(roadmap) {
         if (activeIds.has(dependency))
             fail(`${dependency} remains in Track A`);
         const header = dependency === "C75" ? "C69–C75" : dependency;
-        const section = roadmap.match(new RegExp(`(^#{2,3} ${header} —[^\\n]*\\n[\\s\\S]*?)(?=^#{2,3} C(?:\\d+|\\d+–C\\d+) —|(?![\\s\\S]))`, "m"));
+        const section = new RegExp(String.raw `(^#{2,3} ${header} —[^\n]*\n[\s\S]*?)(?=^#{2,3} C(?:\d+|\d+–C\d+) —|(?![\s\S]))`, "m").exec(roadmap);
         if (!section)
             fail(`${dependency} has no authoritative item status`);
-        const statusMatch = section[1].match(/^- Status: ([^\n]+)$/m);
+        const statusMatch = /^- Status: ([^\n]+)$/m.exec(section[1]);
         if (!statusMatch)
             fail(`${dependency} has no authoritative item status`);
         const status = statusMatch[1].trim();
         if (!TERMINAL_STATUS.test(status))
             fail(`${dependency} has nonterminal status ${JSON.stringify(status)}`);
         const evidenceLabel = dependency === "C75" ? "C75 Evidence" : "Evidence";
-        const evidenceField = section[1].match(new RegExp(`^- ${evidenceLabel}: ([\\s\\S]*?)(?=\\n\\n|\\n- [A-Z][^\\n]*:|(?![\\s\\S]))`, "m"));
+        const evidenceField = new RegExp(String.raw `^- ${evidenceLabel}: ([\s\S]*?)(?=\n\n|\n- [A-Z][^\n]*:|(?![\s\S]))`, "m").exec(section[1]);
         if (!evidenceField)
             fail(`${dependency} has no explicit authoritative evidence field`);
         const paths = [...evidenceField[1].matchAll(/`([^`]+)`/g)].map((match) => match[1]);
@@ -396,7 +398,8 @@ function verifyProductionTrust(plan, evidence) {
         for (const role of ["root", "targets", "snapshot", "timestamp"]) {
             const rootRole = rootEnvelope.signed.roles[role];
             if (rootRole.threshold !== manifest.thresholds[role] ||
-                [...rootRole.keyids].sort().join("\0") !== [...manifest.roleKeyIds[role]].sort().join("\0"))
+                [...rootRole.keyids].sort(compareBytes).join("\0") !==
+                    [...manifest.roleKeyIds[role]].sort(compareBytes).join("\0"))
                 fail(`production ceremony ${role} role does not match the signed root`);
         }
         for (const key of Object.values(rootEnvelope.signed.keys)) {
@@ -477,8 +480,8 @@ export function evaluateReleasePreflight(options) {
         const authoritative = roadmapEvidence.get(dependency) ?? [];
         if (declared.length !== authoritative.length ||
             [...declared]
-                .sort()
-                .some((candidate, index) => candidate !== [...authoritative].sort()[index]))
+                .sort(compareBytes)
+                .some((candidate, index) => candidate !== [...authoritative].sort(compareBytes)[index]))
             fail(`${dependency} evidence paths must equal its complete authoritative Evidence field`);
         for (const relativePath of plan.dependencyEvidence[dependency]) {
             if (uniquePaths.has(relativePath))

package/dist/src/repair-lease.js

@@ -0,0 +1,85 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+const MAX_LEASE_BYTES = 4_096;
+function leasePath(repo) {
+    return path.join(path.resolve(repo), ".knodin", "repair.lock");
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readLease(target) {
+    try {
+        const stat = fs.statSync(target);
+        if (!stat.isFile() || stat.size <= 0 || stat.size > MAX_LEASE_BYTES)
+            return null;
+        const value = JSON.parse(fs.readFileSync(target, "utf8"));
+        if (value.schemaVersion !== 1 ||
+            !Number.isInteger(value.pid) ||
+            (value.pid ?? 0) <= 0 ||
+            typeof value.startedAt !== "string" ||
+            !Number.isFinite(Date.parse(value.startedAt)) ||
+            typeof value.nonce !== "string" ||
+            !value.nonce)
+            return null;
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+function writeLease(target, record) {
+    fs.writeFileSync(target, `${JSON.stringify(record)}\n`, {
+        encoding: "utf8",
+        flag: "wx",
+        mode: 0o600,
+    });
+}
+function removeStaleLeaseOrThrow(target) {
+    const current = readLease(target);
+    if (current && processIsAlive(current.pid)) {
+        throw new Error(`knodin repair: another repair is already in progress (pid ${current.pid}, started ${current.startedAt}); wait for it to finish, then run \`knodin status\``);
+    }
+    try {
+        fs.unlinkSync(target);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+/** Atomically serialize repair post-processing across independent CLI/MCP processes. */
+export function acquireRepairLease(repo) {
+    const target = leasePath(repo);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const record = {
+        schemaVersion: 1,
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+        nonce: crypto.randomUUID(),
+    };
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            writeLease(target, record);
+            return {
+                release() {
+                    const current = readLease(target);
+                    if (current?.nonce === record.nonce)
+                        fs.rmSync(target, { force: true });
+                },
+            };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            removeStaleLeaseOrThrow(target);
+        }
+    }
+    throw new Error("knodin repair: could not acquire the repository repair lease; retry shortly");
+}

package/dist/src/repository-init-process.js

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import process from "node:process";
-export const DEFAULT_REPOSITORY_INIT_MEMORY_LIMIT_BYTES = 768 * 1024 * 1024;
+export const MINIMUM_REPOSITORY_INIT_MEMORY_LIMIT_BYTES = 128 * 1024 * 1024;
 const MAX_DIAGNOSTIC_BYTES = 64 * 1024;
 const TERMINATION_GRACE_MS = 1_000;
 const RSS_POLL_MS = 250;
@@ -50,8 +50,10 @@ function isWorkerMessage(value) {
  * continue.
  */
 export async function runRepositoryInitializationProcess(options) {
-    const memoryLimitBytes = options.memoryLimitBytes ?? DEFAULT_REPOSITORY_INIT_MEMORY_LIMIT_BYTES;
-    if (!Number.isSafeInteger(memoryLimitBytes) || memoryLimitBytes < 128 * 1024 * 1024)
+    const { memoryLimitBytes } = options;
+    if (memoryLimitBytes !== undefined &&
+        (!Number.isSafeInteger(memoryLimitBytes) ||
+            memoryLimitBytes < MINIMUM_REPOSITORY_INIT_MEMORY_LIMIT_BYTES))
         throw new Error("repository init memory limit must be an integer of at least 128 MiB");
     if (options.command.length === 0 || !options.command[0])
         throw new Error("repository init worker command is empty");
@@ -66,10 +68,7 @@ export async function runRepositoryInitializationProcess(options) {
         const child = spawn(options.command[0], [...options.command.slice(1), "__repository-init-worker", options.repository], {
             cwd: options.repository,
             detached: process.platform !== "win32",
-            env: {
-                ...process.env,
-                KNODIN_INTERNAL_INIT_MEMORY_LIMIT_BYTES: String(memoryLimitBytes),
-            },
+            env: process.env,
             stdio: ["ignore", "ignore", "pipe", "ipc"],
         });
         child.stderr?.on("data", (chunk) => {
@@ -77,7 +76,7 @@ export async function runRepositoryInitializationProcess(options) {
         });
         const observeRss = (rssBytes) => {
             peakRssBytes = Math.max(peakRssBytes, rssBytes);
-            if (rssBytes <= memoryLimitBytes || exceeded)
+            if (memoryLimitBytes === undefined || rssBytes <= memoryLimitBytes || exceeded)
                 return;
             exceeded = true;
             const pid = child.pid ?? 0;
@@ -155,7 +154,12 @@ export async function runRepositoryInitializationProcess(options) {
                 return;
             }
             if (result) {
-                resolve({ ...result, repository: options.repository, peakRssBytes, memoryLimitBytes });
+                resolve({
+                    ...result,
+                    repository: options.repository,
+                    peakRssBytes,
+                    ...(memoryLimitBytes === undefined ? {} : { memoryLimitBytes }),
+                });
                 return;
             }
             const diagnostic = stderr.trim().replace(/\s+/g, " ");

package/dist/src/repository-management.js

@@ -2,6 +2,7 @@ import child_process from "node:child_process";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { compareBytes } from "./compare.js";
 import { gitExecutable } from "./git-executable.js";
 import { initializeRepository, isRepositoryInitializationCurrent, readRepositoryIntegrationConfig, } from "./init.js";
 import { applyResponseBudget } from "./response-budget.js";
@@ -217,7 +218,10 @@ export async function discoverRepositories(roots, options = {}) {
     const mainRepositories = legacy.repositories.filter((repository) => (mainByWorktree.get(repository) ?? repository) === repository);
     const topLevelRepositories = mainRepositories
         .filter((repository) => !mainRepositories.some((candidate) => candidate !== repository && repository.startsWith(`${candidate}${path.sep}`)))
-        .sort((left, right) => left.localeCompare(right));
+        // Byte order: `topLevelRepositories.find(...)` below decides whether a
+        // repository is classified main-worktree or unrelated, so the order picks
+        // the winner rather than only presenting it.
+        .sort(compareBytes);
     const repositories = legacy.repositories
         .map((repository) => {
         const mainWorktree = mainByWorktree.get(repository) ?? repository;
@@ -250,8 +254,11 @@ export async function discoverRepositories(roots, options = {}) {
         "nested-repository": 2,
         "unrelated-repository": 3,
     };
+    // Byte order: this listing is item- and byte-budgeted downstream and its
+    // record order is folded into the inventory cursor hash, so collation would
+    // change which repositories a page returns.
     repositories.sort((left, right) => classificationOrder[left.classification] - classificationOrder[right.classification] ||
-        left.path.localeCompare(right.path));
+        compareBytes(left.path, right.path));
     return {
         repositories,
         issues: legacy.issues,
@@ -291,6 +298,10 @@ function parseRepositoryPrefixedOrPositional(argument, index, cwd, command, stat
         state.manifestPath = path.resolve(cwd, argument.slice("--manifest=".length));
         return index;
     }
+    if (argument.startsWith("--memory-limit-mib=")) {
+        state.memoryLimitBytes = repositoryMemoryLimitBytes(argument.slice("--memory-limit-mib=".length));
+        return index;
+    }
     if (argument.startsWith("--"))
         throw new Error(`knodin repos: unknown option ${argument}`);
     if (command === "search" && state.query === undefined)
@@ -343,6 +354,9 @@ function parseRepositoryOption(args, index, cwd, command, state) {
         case "--manifest":
             state.manifestPath = path.resolve(cwd, requiredArgument(args, index, argument));
             return index + 1;
+        case "--memory-limit-mib":
+            state.memoryLimitBytes = repositoryMemoryLimitBytes(requiredArgument(args, index, argument));
+            return index + 1;
         case "--depth":
             state.depth = Number(requiredArgument(args, index, argument));
             return index + 1;
@@ -387,6 +401,8 @@ export function parseRepositoryCommandArgs(args, cwd) {
         throw new Error(`knodin repos ${command}: --dry-run applies only to init`);
     if (state.manifestPath && command !== "init")
         throw new Error(`knodin repos ${command}: --manifest applies only to init`);
+    if (state.memoryLimitBytes !== undefined && command !== "init")
+        throw new Error(`knodin repos ${command}: --memory-limit-mib applies only to init`);
     if (state.signals && command !== "discover")
         throw new Error(`knodin repos ${command}: --signals applies only to discover`);
     if (command !== "search" &&
@@ -405,6 +421,15 @@ export function parseRepositoryCommandArgs(args, cwd) {
         throw new Error("knodin repos discover: --cursor applies only to search");
     return { command, ...state };
 }
+export function repositoryMemoryLimitBytes(value) {
+    const mib = typeof value === "number" ? value : Number(value);
+    if (!Number.isSafeInteger(mib) || mib < 128)
+        throw new Error("knodin repos init: --memory-limit-mib requires an integer of at least 128");
+    const bytes = mib * 1024 * 1024;
+    if (!Number.isSafeInteger(bytes))
+        throw new Error("knodin repos init: --memory-limit-mib exceeds the supported integer range");
+    return bytes;
+}
 /**
  * Find real Git worktree roots without following child symlinks. Every supplied
  * root is resolved through realpath, so aliases are accepted but cannot create
@@ -504,7 +529,10 @@ export async function discoverGitRepositoryPaths(roots, depth = DEFAULT_DEPTH, w
             emptyRoots.push(root);
     }
     const orderedRepositories = [...repositories];
-    orderedRepositories.sort((left, right) => left.localeCompare(right));
+    // Byte order: this array is hashed into the repository initialization
+    // signature, which is persisted in the resume manifest and compared on a
+    // later run — a differing order rejects the manifest outright.
+    orderedRepositories.sort(compareBytes);
     const orderedIssues = [...issues];
     orderedIssues.sort((left, right) => left.path.localeCompare(right.path));
     const orderedEmptyRoots = [...emptyRoots];
@@ -624,7 +652,9 @@ const LANGUAGE_BY_EXTENSION = {
     ".tsx": "typescript",
 };
 function insertBoundedCandidate(candidates, file) {
-    const insertion = candidates.findIndex((candidate) => candidate.localeCompare(file) > 0);
+    // Byte order: the list is capped at MAX_DOCUMENT_CANDIDATES and the tail is
+    // dropped, so this comparison decides which candidates survive.
+    const insertion = candidates.findIndex((candidate) => compareBytes(candidate, file) > 0);
     if (insertion === -1)
         candidates.push(file);
     else

package/dist/src/response-budget.js

@@ -1,3 +1,4 @@
+import { compareBytes } from "./compare.js";
 const encoder = new TextEncoder();
 export const MIN_RESPONSE_BUDGET_BYTES = 256;
 const MAX_REPORTED_TOTAL_PATHS = 128;
@@ -61,17 +62,18 @@ export function applyResponseBudget(value, operation, request, defaults) {
     }
     const itemLimit = positiveInt(request.items, defaults.items);
     const payload = structuredClone(value);
-    const root = Array.isArray(payload)
-        ? { results: payload }
-        : payload && typeof payload === "object"
-            ? payload
-            : { result: payload };
+    const objectRoot = payload && typeof payload === "object"
+        ? payload
+        : { result: payload };
+    const root = Array.isArray(payload) ? { results: payload } : objectRoot;
     const totals = {};
     let truncated = false;
     const initialArrays = collectArrays(root);
     const reportedTotals = [...initialArrays]
+        // Byte order: this tie-break decides which paths survive the slice below,
+        // and the reported totals are serialized into the response.
         .sort((left, right) => left.path.split("/").length - right.path.split("/").length ||
-        left.path.localeCompare(right.path))
+        compareBytes(left.path, right.path))
         .slice(0, MAX_REPORTED_TOTAL_PATHS);
     for (const entry of reportedTotals)
         totals[entry.path] = entry.value.length;