agentwrangler 0.1.0

package/dist/evidence/d7/measure.js

@@ -0,0 +1,193 @@
+import { D7_FORWARD_COVERAGE_RUNNER_VERSION, } from "./types.js";
+const WINDOW_DAYS = 30;
+const THRESHOLD = 0.8;
+function fail(code) {
+    throw new Error(code);
+}
+function ratio(numerator, denominator) {
+    return denominator === 0 ? null : numerator / denominator;
+}
+function asCount(value) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+        fail("d7_aggregate_invalid");
+    return value;
+}
+function cohort(row) {
+    const sessionsN = asCount(row.sessionsN);
+    const eventsN = asCount(row.eventsN);
+    const coveredSessionsN = asCount(row.coveredSessionsN);
+    const coveredEventsN = asCount(row.coveredEventsN);
+    return {
+        cohort: row.cohort,
+        reconciledToolUsingSessionsN: sessionsN,
+        toolEventsN: eventsN,
+        coveredSessionsN,
+        coveredEventsN,
+        sessionCoverage: ratio(coveredSessionsN, sessionsN),
+        eventCoverage: ratio(coveredEventsN, eventsN),
+    };
+}
+export function assertD7AsOf(value) {
+    if (!Number.isFinite(Date.parse(value)) ||
+        !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u.test(value) ||
+        new Date(value).toISOString() !== value)
+        fail("d7_as_of_invalid");
+}
+/** Aggregate the approved query-only snapshot without returning private identifiers. */
+export function measureD7ForwardCoverage(input) {
+    if (input.windowDays !== WINDOW_DAYS)
+        fail("d7_window_days_invalid");
+    assertD7AsOf(input.asOf);
+    if (!/^[0-9a-f]{40}$/u.test(input.sourceCommit))
+        fail("d7_source_commit_invalid");
+    const from = new Date(Date.parse(input.asOf) - WINDOW_DAYS * 86_400_000).toISOString();
+    const aliases = input.repositories.map((repository) => [repository.workspaceId, repository.reportAlias]);
+    if (aliases.length === 0 ||
+        aliases.some(([workspaceId, reportAlias]) => workspaceId.length === 0 || !/^repo-[0-9]{3,}$/u.test(reportAlias)) ||
+        new Set(aliases.map(([workspaceId]) => workspaceId)).size !== aliases.length ||
+        new Set(aliases.map(([, reportAlias]) => reportAlias)).size !== aliases.length)
+        fail("d7_repository_map_invalid");
+    const values = aliases.map(() => "(?, ?)").join(", ");
+    const aliasArgs = aliases.flat();
+    const base = `
+    WITH approved(workspace_id, report_alias) AS (VALUES ${values}),
+    params(from_ts, as_of_ts) AS (VALUES (?, ?)),
+    metadata AS (
+      SELECT event_id, COUNT(*) AS metadata_rows,
+             MAX(file_path_hash) AS file_path_hash, MAX(owner_message_id) AS owner_message_id
+      FROM tool_event_metadata GROUP BY event_id
+    ),
+    owners AS (
+      SELECT message_id, COUNT(*) AS owner_rows, MAX(session_id) AS owner_session_id,
+             MAX(workspace_id) AS owner_workspace_id, MAX(ts) AS owner_ts,
+             MAX(provisional) AS owner_provisional
+      FROM turns GROUP BY message_id
+    ),
+    candidates AS (
+      SELECT e.event_id, e.session_id, e.ts AS event_ts, e.input_hash, e.exit_class,
+             s.workspace_id AS session_workspace_id, a.report_alias,
+             COALESCE(m.metadata_rows, 0) AS metadata_rows, m.file_path_hash, m.owner_message_id,
+             COALESCE(t.owner_rows, 0) AS owner_rows, t.owner_session_id,
+             t.owner_workspace_id, t.owner_ts, t.owner_provisional,
+             p.from_ts, p.as_of_ts
+      FROM tool_events e
+      JOIN sessions s ON s.session_id = e.session_id AND s.state = 'RECONCILED'
+      LEFT JOIN approved a ON a.workspace_id = s.workspace_id
+      LEFT JOIN metadata m ON m.event_id = e.event_id
+      LEFT JOIN owners t ON t.message_id = m.owner_message_id
+      CROSS JOIN params p
+    ),
+    classified AS (
+      SELECT *,
+        CASE WHEN strftime('%s', event_ts) IS NULL THEN 1 ELSE 0 END AS event_malformed,
+        CASE WHEN strftime('%s', event_ts) IS NOT NULL
+              AND julianday(event_ts) >= julianday(from_ts)
+              AND julianday(event_ts) < julianday(as_of_ts) THEN 1 ELSE 0 END AS in_window,
+        CASE WHEN metadata_rows = 1 AND owner_rows = 1
+              AND owner_session_id = session_id AND owner_workspace_id = session_workspace_id
+              AND owner_provisional = 0 AND strftime('%s', owner_ts) IS NOT NULL
+              AND julianday(owner_ts) >= julianday(from_ts)
+              AND julianday(owner_ts) < julianday(as_of_ts) THEN 1 ELSE 0 END AS owner_eligible
+      FROM candidates
+    ),
+    eligible AS (
+      SELECT *, in_window AS denominator_event,
+        CASE WHEN in_window = 1 AND metadata_rows = 1 AND owner_eligible = 1
+              AND report_alias IS NOT NULL AND (input_hash IS NOT NULL OR exit_class IS NOT NULL OR file_path_hash IS NOT NULL)
+             THEN 1 ELSE 0 END AS covered_event
+      FROM classified
+    )`;
+    const aggregateSql = `${base}
+    SELECT
+      COUNT(DISTINCT CASE WHEN denominator_event = 1 THEN session_id END) AS sessionsN,
+      COALESCE(SUM(denominator_event), 0) AS eventsN,
+      COUNT(DISTINCT CASE WHEN covered_event = 1 THEN session_id END) AS coveredSessionsN,
+      COALESCE(SUM(covered_event), 0) AS coveredEventsN,
+      COALESCE(SUM(CASE WHEN denominator_event = 1 AND metadata_rows = 0 THEN 1 ELSE 0 END), 0) AS missingMetadataN,
+      COALESCE(SUM(CASE WHEN denominator_event = 1 AND metadata_rows = 1 AND owner_eligible = 0 THEN 1 ELSE 0 END), 0) AS missingOwnerTurnN,
+      COALESCE(SUM(CASE WHEN denominator_event = 1 AND metadata_rows = 1 AND owner_eligible = 1 AND report_alias IS NOT NULL
+                    AND input_hash IS NULL AND exit_class IS NULL AND file_path_hash IS NULL THEN 1 ELSE 0 END), 0) AS noSignalInputN,
+      COALESCE(SUM(CASE
+        WHEN event_malformed = 1 THEN 1
+        WHEN denominator_event = 1 AND metadata_rows = 1 AND owner_rows = 1
+          AND strftime('%s', owner_ts) IS NULL THEN 1 ELSE 0 END), 0) AS malformedTimestampN,
+      COALESCE(SUM(CASE WHEN denominator_event = 1 AND (
+        report_alias IS NULL OR metadata_rows > 1 OR owner_rows > 1 OR
+        (metadata_rows = 1 AND owner_rows = 1 AND
+          (owner_session_id <> session_id OR owner_workspace_id <> session_workspace_id))
+      ) THEN 1 ELSE 0 END), 0) AS invariantFailureN
+    FROM eligible`;
+    const args = [...aliasArgs, from, input.asOf];
+    const aggregate = input.db.prepare(aggregateSql).get(...args);
+    const daySql = `${base}
+    SELECT strftime('%Y-%m-%d', event_ts) AS cohort, COUNT(DISTINCT session_id) AS sessionsN,
+      COUNT(*) AS eventsN, COUNT(DISTINCT CASE WHEN covered_event = 1 THEN session_id END) AS coveredSessionsN,
+      SUM(covered_event) AS coveredEventsN
+    FROM eligible WHERE denominator_event = 1 GROUP BY strftime('%Y-%m-%d', event_ts) ORDER BY cohort`;
+    const workspaceSql = `${base}
+    SELECT report_alias AS cohort, COUNT(DISTINCT session_id) AS sessionsN, COUNT(*) AS eventsN,
+      COUNT(DISTINCT CASE WHEN covered_event = 1 THEN session_id END) AS coveredSessionsN,
+      SUM(covered_event) AS coveredEventsN
+    FROM eligible WHERE denominator_event = 1 AND report_alias IS NOT NULL GROUP BY report_alias ORDER BY report_alias`;
+    const aggregateCounts = {
+        sessionsN: asCount(aggregate.sessionsN),
+        eventsN: asCount(aggregate.eventsN),
+        coveredSessionsN: asCount(aggregate.coveredSessionsN),
+        coveredEventsN: asCount(aggregate.coveredEventsN),
+        missingMetadataN: asCount(aggregate.missingMetadataN),
+        missingOwnerTurnN: asCount(aggregate.missingOwnerTurnN),
+        noSignalInputN: asCount(aggregate.noSignalInputN),
+        malformedTimestampN: asCount(aggregate.malformedTimestampN),
+        invariantFailureN: asCount(aggregate.invariantFailureN),
+    };
+    const sessionCoverage = ratio(aggregateCounts.coveredSessionsN, aggregateCounts.sessionsN);
+    const eventCoverage = ratio(aggregateCounts.coveredEventsN, aggregateCounts.eventsN);
+    const incomplete = aggregateCounts.eventsN === 0 ||
+        aggregateCounts.malformedTimestampN > 0 ||
+        aggregateCounts.invariantFailureN > 0;
+    const sufficient = !incomplete &&
+        aggregateCounts.sessionsN >= 20 &&
+        sessionCoverage !== null &&
+        eventCoverage !== null &&
+        sessionCoverage >= THRESHOLD &&
+        eventCoverage >= THRESHOLD;
+    const status = incomplete ? "DATA_INSUFFICIENT" : sufficient ? "SUFFICIENT" : "INSUFFICIENT";
+    return {
+        campaign: "D7_FORWARD_COVERAGE",
+        status,
+        identity: {
+            sourceCommit: input.sourceCommit,
+            runnerVersion: D7_FORWARD_COVERAGE_RUNNER_VERSION,
+            scratchDbSha256: input.scratchDbSha256,
+            repoMapSha256: input.repoMapSha256,
+            asOf: input.asOf,
+            windowDays: 30,
+        },
+        denominator: {
+            reconciledToolUsingSessionsN: aggregateCounts.sessionsN,
+            toolEventsN: aggregateCounts.eventsN,
+        },
+        covered: {
+            sessionsN: aggregateCounts.coveredSessionsN,
+            eventsN: aggregateCounts.coveredEventsN,
+            sessionCoverage,
+            eventCoverage,
+        },
+        exclusions: {
+            missingMetadataN: aggregateCounts.missingMetadataN,
+            missingOwnerTurnN: aggregateCounts.missingOwnerTurnN,
+            noSignalInputN: aggregateCounts.noSignalInputN,
+            malformedTimestampN: aggregateCounts.malformedTimestampN,
+            invariantFailureN: aggregateCounts.invariantFailureN,
+        },
+        byUtcDay: input.db.prepare(daySql).all(...args).map(cohort),
+        byWorkspaceAlias: input.db.prepare(workspaceSql).all(...args).map(cohort),
+        decision: {
+            minimumSessions: 20,
+            sessionCoverageThreshold: 0.8,
+            eventCoverageThreshold: 0.8,
+            replayProofEligible: status === "INSUFFICIENT",
+        },
+        privacy: { sessionIdN: 0, workspaceIdN: 0, eventIdN: 0, hashN: 0, pathN: 0, transcriptN: 0 },
+    };
+}

package/dist/evidence/d7/types.js

@@ -0,0 +1 @@
+export const D7_FORWARD_COVERAGE_RUNNER_VERSION = "d7-forward-coverage-v1";

package/dist/evidence/discover-approval.js

@@ -0,0 +1,492 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { EvidenceBoundaryError, readFileIdentity } from "./common/boundary.js";
+import { canonicalJson } from "./common/canonical.js";
+import { openQueryOnlyDb } from "./common/sqlite.js";
+import { createScratchApprovalCandidate } from "./create-approval.js";
+const REPOSITORY_ROOT = path.resolve(fileURLToPath(new URL("../../", import.meta.url)));
+export const PATH_SLUG_SUGGESTION_VERSION = "claude-path-slug-suggestion-v1";
+const DEFAULT_MAX_ENTRIES = 20_000;
+const MAX_CONFIG_BYTES = 1024 * 1024;
+const SKIPPED_DIRECTORIES = new Set([
+    ".git",
+    ".next",
+    "build",
+    "coverage",
+    "dist",
+    "node_modules",
+    "out",
+]);
+function refuse(code) {
+    throw new EvidenceBoundaryError(code);
+}
+/** Experimental, collision-prone heuristic for confirmation-only proposal matching. */
+export function encodeCheckoutRootSuggestion(canonicalCheckoutRoot) {
+    return canonicalCheckoutRoot.replace(/[^A-Za-z0-9-]/gu, "-");
+}
+function binaryCompare(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function increment(counts, reason) {
+    counts[reason] = (counts[reason] ?? 0) + 1;
+}
+function exactIdentity(left, right) {
+    return left.device === right.device && left.inode === right.inode && left.size === right.size;
+}
+function sourceMetadataUnchanged(sourceDbPath, expectedIdentity, expectedRows) {
+    try {
+        return (exactIdentity(expectedIdentity, readFileIdentity(sourceDbPath)) &&
+            canonicalJson(expectedRows) === canonicalJson(readWorkspaces(sourceDbPath)));
+    }
+    catch {
+        return false;
+    }
+}
+function readWorkspaces(sourceDbPath) {
+    const db = openQueryOnlyDb(sourceDbPath);
+    try {
+        const rows = db
+            .prepare(`SELECT workspace_id, project_slug, repo_path, repo_owner, repo_name
+           FROM workspaces
+          ORDER BY workspace_id COLLATE BINARY`)
+            .all();
+        const seen = new Set();
+        return rows.map((row) => {
+            if (typeof row.workspace_id !== "string" ||
+                row.workspace_id.length === 0 ||
+                typeof row.project_slug !== "string" ||
+                row.project_slug.length === 0 ||
+                (row.repo_path !== null && typeof row.repo_path !== "string")) {
+                refuse("discovery_workspace_row_invalid");
+            }
+            if (seen.has(row.workspace_id))
+                refuse("discovery_workspace_duplicate");
+            seen.add(row.workspace_id);
+            const ownerMissing = row.repo_owner === null;
+            const repoMissing = row.repo_name === null;
+            if (ownerMissing !== repoMissing)
+                refuse("discovery_partial_repository_mapping");
+            if ((!ownerMissing && (typeof row.repo_owner !== "string" || row.repo_owner.length === 0)) ||
+                (!repoMissing && (typeof row.repo_name !== "string" || row.repo_name.length === 0))) {
+                refuse("discovery_repository_mapping_invalid");
+            }
+            return {
+                workspaceId: row.workspace_id,
+                projectSlug: row.project_slug,
+                repoPath: row.repo_path,
+                owner: row.repo_owner,
+                repo: row.repo_name,
+            };
+        });
+    }
+    finally {
+        db.close();
+    }
+}
+function gitConfigPath(checkoutRoot) {
+    const dotGit = path.join(checkoutRoot, ".git");
+    const stat = fs.lstatSync(dotGit);
+    if (stat.isSymbolicLink())
+        return undefined;
+    if (stat.isDirectory())
+        return path.join(dotGit, "config");
+    return undefined;
+}
+function parseGitHubOrigin(value) {
+    let owner;
+    let repo;
+    const scp = /^git@github\.com:([^/]+)\/(.+)$/iu.exec(value);
+    if (scp !== null) {
+        owner = scp[1];
+        repo = scp[2];
+    }
+    else {
+        let parsed;
+        try {
+            parsed = new URL(value);
+        }
+        catch {
+            return { reason: "origin_malformed" };
+        }
+        if (parsed.protocol !== "https:" && parsed.protocol !== "ssh:") {
+            return { reason: "origin_unsupported" };
+        }
+        if (parsed.hostname.toLowerCase() !== "github.com" || parsed.port !== "") {
+            return { reason: "origin_non_github" };
+        }
+        if (parsed.search !== "" || parsed.hash !== "")
+            return { reason: "origin_malformed" };
+        if (parsed.password !== "" || (parsed.protocol === "https:" && parsed.username !== "")) {
+            return { reason: "origin_credentials_present" };
+        }
+        if (parsed.protocol === "ssh:" && parsed.username !== "git") {
+            return { reason: "origin_malformed" };
+        }
+        const segments = parsed.pathname.split("/").filter(Boolean);
+        if (segments.length !== 2)
+            return { reason: "origin_malformed" };
+        [owner, repo] = segments;
+    }
+    repo = repo?.replace(/\.git$/u, "");
+    const component = /^[A-Za-z0-9_.-]+$/u;
+    if (owner === undefined ||
+        repo === undefined ||
+        !component.test(owner) ||
+        !component.test(repo) ||
+        owner === "." ||
+        owner === ".." ||
+        repo === "." ||
+        repo === "..") {
+        return { reason: "origin_malformed" };
+    }
+    return { identity: { owner, repo } };
+}
+function readLocalOrigin(checkoutRoot) {
+    let configPath;
+    let descriptor;
+    let configBytes;
+    try {
+        configPath = gitConfigPath(checkoutRoot);
+        if (configPath === undefined)
+            return { reason: "git_metadata_unsafe" };
+        const unresolvedStat = fs.lstatSync(configPath);
+        if (!unresolvedStat.isFile() || unresolvedStat.isSymbolicLink()) {
+            return { reason: "git_config_unsafe" };
+        }
+        const resolvedConfig = fs.realpathSync.native(configPath);
+        const relative = path.relative(checkoutRoot, resolvedConfig);
+        if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+            return { reason: "git_config_unsafe" };
+        }
+        const pathStat = fs.lstatSync(resolvedConfig, { bigint: true });
+        if (!pathStat.isFile() ||
+            pathStat.isSymbolicLink() ||
+            pathStat.size > BigInt(MAX_CONFIG_BYTES)) {
+            return { reason: "git_config_unsafe" };
+        }
+        descriptor = fs.openSync(configPath, fs.constants.O_RDONLY);
+        const before = fs.fstatSync(descriptor, { bigint: true });
+        if (!before.isFile() ||
+            before.dev !== pathStat.dev ||
+            before.ino === 0n ||
+            before.ino !== pathStat.ino ||
+            before.size !== pathStat.size) {
+            throw new Error("git_config_identity_changed");
+        }
+        configBytes = fs.readFileSync(descriptor, "utf8");
+        const after = fs.fstatSync(descriptor, { bigint: true });
+        if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size) {
+            throw new Error("git_config_identity_changed");
+        }
+        fs.closeSync(descriptor);
+        descriptor = undefined;
+    }
+    catch {
+        if (descriptor !== undefined) {
+            try {
+                fs.closeSync(descriptor);
+            }
+            catch {
+                // The aggregate refusal reason remains the same.
+            }
+        }
+        return { reason: "git_metadata_unreadable" };
+    }
+    let section = "";
+    const origins = [];
+    for (const rawLine of configBytes.split(/\r?\n/u)) {
+        const line = rawLine.trim();
+        const heading = /^\[([^\]]+)\]$/u.exec(line);
+        if (heading?.[1] !== undefined) {
+            section = heading[1].trim().toLowerCase();
+            continue;
+        }
+        if (section !== 'remote "origin"')
+            continue;
+        const value = /^url\s*=\s*(.+)$/iu.exec(line)?.[1];
+        if (value !== undefined)
+            origins.push(value.trim());
+    }
+    if (origins.length === 0)
+        return { reason: "origin_missing" };
+    if (origins.length !== 1)
+        return { reason: "origin_ambiguous" };
+    return parseGitHubOrigin(origins[0]);
+}
+function enumerateLocalRepositories(searchRoots, maxEntries, beforeVisitDirectory) {
+    if (searchRoots.length === 0)
+        refuse("discovery_search_root_required");
+    if (!Number.isSafeInteger(maxEntries) || maxEntries < 1)
+        refuse("discovery_max_entries_invalid");
+    const pending = [];
+    const roots = new Set();
+    for (const candidate of searchRoots) {
+        let resolved;
+        try {
+            resolved = fs.realpathSync.native(candidate);
+            const stat = fs.lstatSync(candidate);
+            if (!stat.isDirectory() || stat.isSymbolicLink())
+                refuse("discovery_search_root_unsafe");
+        }
+        catch (error) {
+            if (error instanceof EvidenceBoundaryError)
+                throw error;
+            refuse("discovery_search_root_unreadable");
+        }
+        if (roots.has(resolved))
+            refuse("discovery_search_root_duplicate");
+        roots.add(resolved);
+        pending.push(resolved);
+    }
+    const orderedRoots = [...roots].sort(binaryCompare);
+    for (let index = 0; index < orderedRoots.length; index += 1) {
+        for (let other = index + 1; other < orderedRoots.length; other += 1) {
+            const relative = path.relative(orderedRoots[index], orderedRoots[other]);
+            if (relative !== "" && !relative.startsWith(`..${path.sep}`) && relative !== "..") {
+                refuse("discovery_search_roots_overlap");
+            }
+        }
+    }
+    pending.sort(binaryCompare).reverse();
+    const repositories = [];
+    const visited = new Set();
+    let visitedEntries = 0;
+    while (pending.length > 0) {
+        const queued = pending.pop();
+        beforeVisitDirectory?.(queued);
+        let current;
+        try {
+            const queuedStat = fs.lstatSync(queued, { bigint: true });
+            if (!queuedStat.isDirectory() || queuedStat.isSymbolicLink())
+                continue;
+            current = fs.realpathSync.native(queued);
+            const canonicalStat = fs.lstatSync(current, { bigint: true });
+            if (!canonicalStat.isDirectory() ||
+                canonicalStat.isSymbolicLink() ||
+                queuedStat.dev !== canonicalStat.dev ||
+                queuedStat.ino === 0n ||
+                queuedStat.ino !== canonicalStat.ino) {
+                continue;
+            }
+            const contained = orderedRoots.some((root) => {
+                const relative = path.relative(root, current);
+                return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== "..");
+            });
+            if (!contained || visited.has(current))
+                continue;
+            visited.add(current);
+        }
+        catch {
+            continue;
+        }
+        const dotGit = path.join(current, ".git");
+        if (fs.existsSync(dotGit)) {
+            let canonical;
+            let before;
+            try {
+                before = fs.lstatSync(current, { bigint: true });
+                canonical = fs.realpathSync.native(current);
+                if (!before.isDirectory() || before.isSymbolicLink())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            const origin = readLocalOrigin(canonical);
+            let identityStable = false;
+            try {
+                const after = fs.lstatSync(current, { bigint: true });
+                identityStable =
+                    after.isDirectory() &&
+                        !after.isSymbolicLink() &&
+                        before.dev === after.dev &&
+                        before.ino !== 0n &&
+                        before.ino === after.ino &&
+                        fs.realpathSync.native(current) === canonical;
+            }
+            catch {
+                identityStable = false;
+            }
+            repositories.push({
+                root: canonical,
+                encodedRoot: encodeCheckoutRootSuggestion(canonical),
+                ...(identityStable ? origin : { reason: "checkout_identity_changed" }),
+            });
+            continue;
+        }
+        let entries;
+        try {
+            entries = fs.readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        entries.sort((left, right) => binaryCompare(left.name, right.name));
+        for (const entry of entries) {
+            visitedEntries += 1;
+            if (visitedEntries > maxEntries)
+                refuse("discovery_traversal_bound_exhausted");
+            if (!entry.isDirectory() || entry.isSymbolicLink() || SKIPPED_DIRECTORIES.has(entry.name)) {
+                continue;
+            }
+            pending.push(path.join(current, entry.name));
+        }
+        pending.sort(binaryCompare).reverse();
+    }
+    return repositories.sort((left, right) => binaryCompare(left.root, right.root));
+}
+export function parseDiscoverApprovalArgs(args) {
+    const single = new Set([
+        "--source-db",
+        "--scratch-db",
+        "--scratch-state",
+        "--out",
+        "--max-entries",
+    ]);
+    const values = new Map();
+    const searchRoots = [];
+    let acknowledged = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const flag = args[index];
+        if (flag === "--acknowledge-private-parent") {
+            if (acknowledged)
+                refuse("duplicate_cli_argument");
+            acknowledged = true;
+            continue;
+        }
+        const value = args[index + 1];
+        if (value === undefined || value.length === 0 || value.startsWith("--")) {
+            refuse("missing_cli_value");
+        }
+        if (flag === "--search-root")
+            searchRoots.push(value);
+        else {
+            if (flag === undefined || !single.has(flag))
+                refuse("unknown_cli_argument");
+            if (values.has(flag))
+                refuse("duplicate_cli_argument");
+            values.set(flag, value);
+        }
+        index += 1;
+    }
+    const sourceDbPath = values.get("--source-db");
+    const scratchDbPath = values.get("--scratch-db");
+    const scratchStatePath = values.get("--scratch-state");
+    const outputPath = values.get("--out");
+    if (sourceDbPath === undefined ||
+        scratchDbPath === undefined ||
+        scratchStatePath === undefined ||
+        outputPath === undefined ||
+        searchRoots.length === 0) {
+        refuse("missing_required_cli_argument");
+    }
+    if (!acknowledged)
+        refuse("private_artifact_parent_not_acknowledged");
+    const maxEntriesText = values.get("--max-entries") ?? String(DEFAULT_MAX_ENTRIES);
+    if (!/^\d+$/u.test(maxEntriesText))
+        refuse("discovery_max_entries_invalid");
+    return {
+        sourceDbPath,
+        scratchDbPath,
+        scratchStatePath,
+        searchRoots,
+        outputPath,
+        maxEntries: Number(maxEntriesText),
+        privateArtifactParentAcknowledged: true,
+    };
+}
+export async function discoverScratchApprovalCandidate(input, options = {}) {
+    const sourceIdentityBefore = readFileIdentity(input.sourceDbPath);
+    const workspaces = readWorkspaces(input.sourceDbPath);
+    const repositories = enumerateLocalRepositories(input.searchRoots, input.maxEntries, options.testHooks?.beforeVisitDirectory);
+    const storedMatches = new Map();
+    for (const workspace of workspaces) {
+        for (const value of new Set([workspace.workspaceId, workspace.projectSlug])) {
+            const matches = storedMatches.get(value) ?? new Set();
+            matches.add(workspace.workspaceId);
+            storedMatches.set(value, matches);
+        }
+    }
+    const reasonCounts = {};
+    const proposed = [];
+    let existingMappingN = 0;
+    let suggestedMappingN = 0;
+    let unresolvedWorkspaceN = 0;
+    for (const workspace of workspaces) {
+        if (workspace.owner !== null && workspace.repo !== null) {
+            existingMappingN += 1;
+            proposed.push({
+                workspaceId: workspace.workspaceId,
+                owner: workspace.owner,
+                repo: workspace.repo,
+                reportAlias: "",
+            });
+            continue;
+        }
+        const candidates = repositories.filter((repository) => repository.encodedRoot === workspace.workspaceId ||
+            repository.encodedRoot === workspace.projectSlug);
+        const storedCollision = candidates.some((candidate) => (storedMatches.get(candidate.encodedRoot)?.size ?? 0) > 1);
+        if (candidates.length !== 1 || storedCollision) {
+            unresolvedWorkspaceN += 1;
+            increment(reasonCounts, candidates.length === 0 ? "no_exact_path_match" : "path_encoding_collision");
+            continue;
+        }
+        const candidate = candidates[0];
+        if (candidate.identity === undefined) {
+            unresolvedWorkspaceN += 1;
+            increment(reasonCounts, candidate.reason ?? "origin_unresolved");
+            continue;
+        }
+        suggestedMappingN += 1;
+        proposed.push({ workspaceId: workspace.workspaceId, ...candidate.identity, reportAlias: "" });
+    }
+    proposed.sort((left, right) => binaryCompare(left.workspaceId, right.workspaceId));
+    proposed.forEach((entry, index) => {
+        entry.reportAlias = `repo-${String(index + 1).padStart(3, "0")}`;
+    });
+    if (proposed.length === 0)
+        refuse("discovery_no_repository_mappings");
+    await options.testHooks?.beforeCandidatePublication?.();
+    if (!sourceMetadataUnchanged(input.sourceDbPath, sourceIdentityBefore, workspaces)) {
+        refuse("discovery_source_changed");
+    }
+    const candidate = await createScratchApprovalCandidate({
+        sourceDbPath: input.sourceDbPath,
+        scratchDbPath: input.scratchDbPath,
+        scratchStatePath: input.scratchStatePath,
+        repositoriesJson: JSON.stringify(proposed),
+        outputPath: input.outputPath,
+        privateArtifactParentAcknowledged: true,
+    }, { repositoryRoot: options.repositoryRoot ?? REPOSITORY_ROOT });
+    await options.testHooks?.afterCandidatePublication?.();
+    if (!sourceMetadataUnchanged(input.sourceDbPath, sourceIdentityBefore, workspaces)) {
+        refuse("discovery_source_changed_candidate_retained");
+    }
+    return {
+        suggestionHeuristicVersion: PATH_SLUG_SUGGESTION_VERSION,
+        sha256: candidate.sha256,
+        mappedWorkspaceN: candidate.mappedWorkspaceN,
+        existingMappingN,
+        suggestedMappingN,
+        unresolvedWorkspaceN,
+        reasonCounts,
+    };
+}
+async function main() {
+    try {
+        const result = await discoverScratchApprovalCandidate(parseDiscoverApprovalArgs(process.argv.slice(2)));
+        process.stdout.write(`${canonicalJson({ status: "SUGGESTIONS_CONFIRMATION_REQUIRED", ...result })}\n`);
+    }
+    catch (error) {
+        const failure = error instanceof EvidenceBoundaryError ? error.code : "unexpected_failure";
+        process.stderr.write(`${canonicalJson({ status: "REFUSED", failure })}\n`);
+        process.exitCode = 1;
+    }
+}
+const invokedPath = process.argv[1];
+if (invokedPath !== undefined &&
+    pathToFileURL(path.resolve(invokedPath)).href ===
+        pathToFileURL(fileURLToPath(import.meta.url)).href) {
+    void main();
+}