srclawyer 0.6.2 → 0.7.0

package/README.md

@@ -2,7 +2,7 @@
 
 Static analysis engine that derives privacy policy documentation directly from source code, and keeps it in sync as the code changes.
 
-> **Beta.** The CLI (`init`, `scan`), the Layer 1 static analysis engine, and markdown privacy policy generation all work today. JavaScript/TypeScript (Express, Next.js) is the most tested path; Python (Flask) is newer, with FastAPI and Django explicitly detected and flagged as unsupported rather than silently skipped — see [Supported languages and frameworks](#supported-languages-and-frameworks) and [Known gaps](#known-gaps) below. LLM-assisted reasoning for ambiguous findings (Layer 2) is available now under the bring-your-own-key tier, documented below as one optional step in `init` — a managed (hosted) tier is planned but not yet available.
+> **Beta.** The CLI (`init`, `scan`), the Layer 1 static analysis engine, and markdown privacy policy generation all work today. JavaScript/TypeScript (Express, Next.js) is the most tested path; Python (Flask) is newer, with FastAPI and Django explicitly detected and flagged as unsupported rather than silently skipped — see [Supported languages and frameworks](#supported-languages-and-frameworks) and [Known gaps](#known-gaps) below. Optional AI-assisted review of ambiguous findings (Layer 2) is available as an advanced option with your own Anthropic API key — see [AI-assisted review](#ai-assisted-review-advanced) below; a hosted tier that needs no key is planned but not yet available.
 >
 > Scanning is manual-only (`srclawyer scan`, run on demand) — this is the free/solo tier's permanent behavior, not a placeholder. Automatic CI/CD updating (a scan that runs itself on every PR, or on a schedule) isn't available yet; it's scoped for a future paid/team tier. See `PRODUCT_SPEC.md` Section 8.5 for the plan.
 
@@ -93,9 +93,65 @@ Every finding traces back to a file and line (`src/engine/types.ts#Finding`).
 - **Flask support covers direct request reads and same-function aliases only.** It detects `request.form[...]`, `request.args.get(...)`, `request.json[...]` and the like, plus one assignment hop within a function (`data = request.get_json()`, then `data['x']`). Form classes — Flask-WTF/WTForms `FlaskForm` subclasses with `StringField`/`PasswordField` declarations read via `form.email.data` — are not detected, and neither are fields rendered by template helpers such as `{{ form.email() }}`. A Flask app that collects data through WTForms may therefore show fewer collected fields than it actually has.
 - **Server-side template syntax inside HTML is not analyzed.** Jinja, Django, ERB and similar delimiters (`{{`, `{%`, `<%`, `{#`) are not interpreted: an inline `<script>` that isn't valid JavaScript until the template engine runs is skipped (listed in `--json` as `template-syntax`, with a one-line note), and form fields that a template generates rather than spells out as `<input>` tags are not seen.
 
+## AI-assisted review (advanced)
+
+Off by default, and not part of `init`'s questions. `scan` already surfaces anything it can't confidently classify under "Items Requiring Manual Review"; with AI-assisted review enabled it first asks Anthropic, under **your own API key**, to classify each such item. For each item Anthropic receives: an opaque per-scan id, the item's data category, its short description (which names the field), and the one source line it was found on with secrets redacted — plus a fixed instruction prompt and the model name. **Not sent:** the file's path, its line number, or any surrounding code (the source line itself goes as written, apart from redacted secrets). Items the model declines stay in the manual-review list, and items involving children's data are never auto-resolved.
+
+Enable it when creating the config:
+
+```bash
+srclawyer init --enable-ai-review                              # asks which env var holds your key (default ANTHROPIC_API_KEY)
+srclawyer init --enable-ai-review --api-key-env-var MY_KEY     # same, non-interactive
+export ANTHROPIC_API_KEY=...                                   # or whichever name you chose
+srclawyer scan
+```
+
+or, for an existing config (`init` never overwrites one), add this to `.srclawyer.config.yml` by hand:
+
+```yaml
+tier: byok
+llm:
+  provider: anthropic
+  apiKeyEnvVar: ANTHROPIC_API_KEY
+```
+
+Only the variable's *name* is stored in the config — the key itself is never written to disk. When it's enabled, `scan` prints a notice that redacted snippets are being sent to Anthropic; `scan --no-llm` skips it for a single run. A hosted tier, where SrcLawyer supplies the model access and no key is needed, is planned but not yet available: a config with `tier: managed` gets a clear "not available yet" error rather than silently doing nothing.
+
+## Drift check (GitHub Action)
+
+**Free during the beta.** Flags when your code starts collecting a new kind of data, or using a new third-party processor, that your privacy policy was never updated for. It compares the code against a committed baseline, `.srclawyer.inventory.json` — just the sorted data categories and processors, no file names or line numbers — not against policy text, which people edit by hand.
+
+```bash
+npx srclawyer scan --write-inventory     # once: writes the policy and the baseline; commit the baseline
+npx srclawyer check                      # exit 0 no drift, 1 drift, 2 error, 3 inconclusive
+```
+
+```yaml
+- uses: actions/checkout@v7
+- uses: SrcLawyer/srclawyer@v0.7.0
+  with:
+    srclawyer-version: 0.7.0             # required and pinned
+```
+
+Drift fails the check, and the step summary lists what was added and removed with a one-line fix. If no verdict can be reached — the confidence service is unreachable, files were skipped, or the baseline and the run used different file discovery — the result is **inconclusive**, a warning by default, and is never reported as drift. The Action needs no secrets and `contents: read`; an optional pull-request comment needs `pull-requests: write`. Inside a git repository, `check` and `--write-inventory` look only at tracked and untracked-but-not-ignored files, so a gitignored build directory can't cause phantom drift; plain `scan` is unchanged. `check` makes the same network calls as `scan` (below) and never calls an AI provider.
+
+| Exit code | `srclawyer check` | `srclawyer scan` |
+|---|---|---|
+| 0 | no drift | clean |
+| 1 | drift | completed with warnings |
+| 2 | crash, bad usage, or a missing or invalid baseline | crash or bad usage |
+| 3 | inconclusive | — |
+
+`scan`'s "completed with warnings" (1) and `check`'s "inconclusive" (3) are the same condition under different numbers; `scan`'s was left alone so existing scripts keep working. Example workflows (pull requests, a weekly schedule, manual dispatch, writing the baseline on the runner) are in [docs/github-action.md](docs/github-action.md).
+
 ## Network calls
 
-Detection itself is fully local and offline — no code leaves your machine for pattern matching. Once detection completes, `scan` makes one batched network call to grade the confidence of what it found (field names and derived yes/no signals only, never source code), and, for scans that use Zod schemas as request validators, one additional call sending a small redacted code fragment. This runs on every scan regardless of tier and is unrelated to the separate, optional LLM-assisted (Layer 2) reasoning described above. See `PRODUCT_SPEC.md`'s "Static Analysis Depth" section for the precise wording.
+Detection itself is fully local and offline — no code leaves your machine for pattern matching. Once detection completes, every `scan` makes these calls to a SrcLawyer-run service:
+
+- **Confidence grading** (one batched call). For each detected field: an opaque per-scan id (`f0`, `f1`, …), the data category its name maps to (e.g. `email`), and three derived signals — whether the name is ambiguous, whether it was read directly from the request in code (rather than inferred from a type), and how many confidently classified fields sit alongside it. **Not sent:** the field's name, file paths, line numbers, or source code.
+- **Zod-schema detection** (one more batched call, only for scans where Zod schemas appear to validate request data). Per schema: an opaque id (`c0`, `c1`, …) and a small, secret-redacted code fragment — the schema, the call that validates with it, and the imports it uses, as source text (so it includes the schema's field names and those import specifiers). **Not sent:** the schema's file path or line number.
+
+Ids are numbered per scan; the mapping back to files and lines never leaves your machine. Requests carry a shared API key (`x-api-key`) and the standard headers Node.js adds (such as `user-agent: node`); there is no install ID, machine information, or telemetry. These calls run on every scan, with or without the optional [AI-assisted review](#ai-assisted-review-advanced), and are separate from it. See `PRODUCT_SPEC.md`'s "Static Analysis Depth" section for the same wording.
 
 ## Secret handling
 

package/dist/cli.js

@@ -1,15 +1,18 @@
 #!/usr/bin/env node
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { Command } from "commander";
-import { runInit } from "./commands/init.js";
+import { Command, CommanderError } from "commander";
+import { isValidEnvVarName, runInit } from "./commands/init.js";
 import { runScan } from "./commands/scan.js";
+import { runCheck } from "./commands/check.js";
+import { DEFAULT_INVENTORY_PATH } from "./inventory/inventory.js";
+import { EXIT_CRASH } from "./exitCodes.js";
+import { readPackageVersion } from "./version.js";
 // Read from package.json rather than hardcoding, so --version can't silently drift out of sync with
 // the published version the way a literal string did through every prior release.
-const HERE = dirname(fileURLToPath(import.meta.url));
-const { version } = JSON.parse(readFileSync(join(HERE, "../package.json"), "utf8"));
+const version = readPackageVersion();
 const program = new Command();
+// Commander normally calls process.exit(1) itself on a usage error; exit codes are this CLI's contract
+// (see exitCodes.ts), so it throws instead and the handler at the bottom decides the code.
+program.exitOverride();
 program
     .name("srclawyer")
     .description("Static analysis engine that derives privacy policy documentation directly from source code")
@@ -37,7 +40,15 @@ program
     .option("--minimum-age <number>", "minimum age required to use this product")
     .option("--sends-data-to-ai-services", "declare that user data is sent to third-party AI services")
     .option("--no-sends-data-to-ai-services", "declare that user data is not sent to third-party AI services")
+    .option("--enable-ai-review", "advanced: enable optional AI-assisted review of ambiguous findings with your own Anthropic API key (sets tier: byok)")
+    .option("--api-key-env-var <name>", "with --enable-ai-review: the environment variable holding your Anthropic API key (default ANTHROPIC_API_KEY)")
     .action(async (opts) => {
+    if (opts.apiKeyEnvVar !== undefined) {
+        if (!opts.enableAiReview)
+            program.error("error: --api-key-env-var requires --enable-ai-review");
+        if (!isValidEnvVarName(opts.apiKeyEnvVar))
+            program.error(`error: --api-key-env-var must be a valid environment variable name (got "${opts.apiKeyEnvVar}")`);
+    }
     let minimumAge;
     if (opts.minimumAge !== undefined) {
         const parsed = Number(opts.minimumAge);
@@ -60,6 +71,8 @@ program
         accountDeletionInstructions: opts.accountDeletionInstructions,
         minimumAge,
         sendsDataToAiServices: opts.sendsDataToAiServices,
+        enableAiReview: opts.enableAiReview,
+        apiKeyEnvVar: opts.apiKeyEnvVar,
     });
 });
 program
@@ -68,7 +81,41 @@ program
     .option("--json", "output findings as JSON", false)
     .option("--out <path>", "path to write the generated privacy policy", "PRIVACY_POLICY.md")
     .option("--no-llm", "skip AI-assisted resolution of ambiguous findings for this run")
+    .option("--write-inventory [path]", `also write the drift baseline (data categories and processors only) to <path> (default ${DEFAULT_INVENTORY_PATH}); uses git-aware file discovery in a git repository`)
+    .option("--allow-incomplete-inventory", "with --write-inventory: write the baseline even if the scan completed with warnings")
     .action(async (opts) => {
-    await runScan(process.cwd(), { json: opts.json, out: opts.out, llm: opts.llm });
+    await runScan(process.cwd(), {
+        json: opts.json,
+        out: opts.out,
+        llm: opts.llm,
+        writeInventory: opts.writeInventory === true ? DEFAULT_INVENTORY_PATH : opts.writeInventory,
+        allowIncompleteInventory: opts.allowIncompleteInventory,
+    });
+});
+program
+    .command("check")
+    .description("Check for drift: compare the code's data categories and processors with the committed baseline (exit 0 no drift, 1 drift, 2 error, 3 inconclusive)")
+    .option("--inventory <path>", "the baseline file", DEFAULT_INVENTORY_PATH)
+    .option("--format <format>", "text or json", "text")
+    .action(async (opts) => {
+    const format = opts.format;
+    if (format !== "text" && format !== "json")
+        return program.error(`error: --format must be "text" or "json" (got "${format}")`);
+    process.exitCode = await runCheck(process.cwd(), { inventoryPath: opts.inventory, format });
+});
+// Exit 1 is reserved for "completed with warnings" (scan) and "drift" (check), so anything that ends
+// the run abnormally -- an uncaught error, an unhandled rejection, a usage error -- exits 2.
+function crash(error) {
+    console.error(error instanceof Error ? (error.stack ?? error.message) : String(error));
+    process.exit(EXIT_CRASH);
+}
+process.on("uncaughtException", crash);
+process.on("unhandledRejection", crash);
+program.parseAsync(process.argv).catch((error) => {
+    if (error instanceof CommanderError) {
+        // Help and --version also arrive here, with exitCode 0; commander has already printed its message.
+        process.exitCode = error.exitCode === 0 ? 0 : EXIT_CRASH;
+        return;
+    }
+    crash(error);
 });
-program.parseAsync(process.argv);

package/dist/cloud/protectedLogicClient.js

@@ -39,6 +39,22 @@ function chunkByCountAndBytes(items, maxCount, maxBytes) {
         batches.push(current);
     return batches;
 }
+/**
+ * The one place ids are assigned for anything sent to the Worker. Callers identify items by their own
+ * ids (finding ids embed file path, line and field name; Zod candidate ids ARE the file path), but
+ * those never leave this process: every item goes out under an opaque per-scan id (f0, f1, ... /
+ * c0, c1, ...), unique across all batches, and responses are mapped back here. The Worker only echoes
+ * ids (it never parses them), so nothing about the wire format depends on their shape.
+ */
+function toOpaque(items, prefix) {
+    const originalByOpaque = new Map();
+    const wire = items.map((item, i) => {
+        const opaque = `${prefix}${i}`;
+        originalByOpaque.set(opaque, item.id);
+        return { ...item, id: opaque };
+    });
+    return { wire, originalByOpaque };
+}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -79,11 +95,15 @@ export async function scoreFields(items, options) {
     const batchMaxBytes = options.batchMaxBytes ?? DEFAULT_BATCH_MAX_BYTES;
     const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     let error = null;
-    for (const batch of chunkByCountAndBytes(items, batchSize, batchMaxBytes)) {
+    const { wire, originalByOpaque } = toOpaque(items, "f");
+    for (const batch of chunkByCountAndBytes(wire, batchSize, batchMaxBytes)) {
         try {
             const response = await postJson(`${options.baseUrl}/v1/score-fields`, options.apiKey, { fields: batch }, timeoutMs);
-            for (const result of response.results)
-                results.set(result.id, result);
+            for (const result of response.results) {
+                const original = originalByOpaque.get(result.id);
+                if (original !== undefined)
+                    results.set(original, { ...result, id: original });
+            }
         }
         catch (err) {
             error = err instanceof Error ? err.message : String(err);
@@ -99,11 +119,15 @@ export async function detectZodSchemas(items, options) {
     const batchMaxBytes = options.batchMaxBytes ?? DEFAULT_BATCH_MAX_BYTES;
     const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     let error = null;
-    for (const batch of chunkByCountAndBytes(items, batchSize, batchMaxBytes)) {
+    const { wire, originalByOpaque } = toOpaque(items, "c");
+    for (const batch of chunkByCountAndBytes(wire, batchSize, batchMaxBytes)) {
         try {
             const response = await postJson(`${options.baseUrl}/v1/detect-zod-schema`, options.apiKey, { candidates: batch }, timeoutMs);
-            for (const result of response.results)
-                results.set(result.id, result);
+            for (const result of response.results) {
+                const original = originalByOpaque.get(result.id);
+                if (original !== undefined)
+                    results.set(original, { ...result, id: original });
+            }
         }
         catch (err) {
             error = err instanceof Error ? err.message : String(err);

package/dist/commands/check.d.ts

@@ -0,0 +1,28 @@
+import { type DiscoveryMode, type InventoryDiff } from "../inventory/inventory.js";
+export type CheckFormat = "text" | "json";
+export interface CheckOptions {
+    inventoryPath: string;
+    format: CheckFormat;
+}
+export interface CheckReport {
+    result: "no-drift" | "drift" | "inconclusive" | "error";
+    exitCode: number;
+    srclawyerVersion: string;
+    baseline: {
+        path: string;
+        srclawyerVersion: string;
+        discovery: DiscoveryMode;
+    } | null;
+    currentDiscovery: DiscoveryMode | null;
+    /** Present only for a conclusive result -- an inconclusive run never reports a diff. */
+    diff: InventoryDiff | null;
+    inconclusiveReasons: string[];
+    error: string | null;
+}
+/**
+ * Re-derives the inventory and compares it with the committed baseline. Never writes a policy, never
+ * calls an LLM provider, and never reports an incomplete scan as drift: anything that makes the scan
+ * untrustworthy (the same warnings that make `scan` exit 1, or a discovery-mode mismatch) is
+ * inconclusive and carries no diff.
+ */
+export declare function runCheck(root: string, options: CheckOptions): Promise<number>;

package/dist/commands/check.js

@@ -0,0 +1,93 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { scan } from "../engine/scanEngine.js";
+import { selectDiscovery } from "../engine/gitDiscovery.js";
+import { resolveScanProtectedLogic } from "./protectedLogicStep.js";
+import { computeInventory, diffInventories, hasDrift, inventoryBlockers, parseInventory, } from "../inventory/inventory.js";
+import { EXIT_CRASH, EXIT_DRIFT, EXIT_INCONCLUSIVE, EXIT_OK } from "../exitCodes.js";
+import { readPackageVersion } from "../version.js";
+const FIX_INSTRUCTION = 'If this change is intended, update your privacy policy, then refresh the baseline with "srclawyer scan --write-inventory" and commit it.';
+function listLine(label, values) {
+    return values.length > 0 ? [`  ${label} ${values.join(", ")}`] : [];
+}
+function renderText(report, inventoryPath) {
+    const lines = [];
+    switch (report.result) {
+        case "no-drift":
+            lines.push("Drift check: no drift.");
+            lines.push(`  Baseline ${inventoryPath} (srclawyer ${report.baseline?.srclawyerVersion}, ${report.baseline?.discovery} discovery) matches the code.`);
+            break;
+        case "drift": {
+            lines.push("Drift check: DRIFT DETECTED.");
+            const d = report.diff;
+            lines.push(...listLine("Added categories:  ", d.added.categories), ...listLine("Removed categories:", d.removed.categories));
+            lines.push(...listLine("Added processors:  ", d.added.processors), ...listLine("Removed processors:", d.removed.processors));
+            if (report.baseline && report.baseline.srclawyerVersion !== report.srclawyerVersion) {
+                lines.push(`  (The baseline was written by srclawyer ${report.baseline.srclawyerVersion}; this is ${report.srclawyerVersion}. Detection rules can change between versions.)`);
+            }
+            lines.push("", FIX_INSTRUCTION);
+            break;
+        }
+        case "inconclusive":
+            lines.push("Drift check: INCONCLUSIVE — no drift verdict, because the scan was not complete or comparable:");
+            for (const reason of report.inconclusiveReasons)
+                lines.push(`  - ${reason}`);
+            break;
+        case "error":
+            lines.push(`error: ${report.error}`);
+            break;
+    }
+    return lines.join("\n");
+}
+function finish(report, options) {
+    if (options.format === "json")
+        console.log(JSON.stringify(report, null, 2));
+    else
+        (report.result === "error" ? console.error : console.log)(renderText(report, options.inventoryPath));
+    return report.exitCode;
+}
+const baseReport = () => ({
+    result: "error",
+    exitCode: EXIT_CRASH,
+    srclawyerVersion: readPackageVersion(),
+    baseline: null,
+    currentDiscovery: null,
+    diff: null,
+    inconclusiveReasons: [],
+    error: null,
+});
+/**
+ * Re-derives the inventory and compares it with the committed baseline. Never writes a policy, never
+ * calls an LLM provider, and never reports an incomplete scan as drift: anything that makes the scan
+ * untrustworthy (the same warnings that make `scan` exit 1, or a discovery-mode mismatch) is
+ * inconclusive and carries no diff.
+ */
+export async function runCheck(root, options) {
+    const path = resolve(root, options.inventoryPath);
+    if (!existsSync(path)) {
+        return finish({ ...baseReport(), error: `no baseline found at ${options.inventoryPath}. Create one with "srclawyer scan --write-inventory" and commit it.` }, options);
+    }
+    const parsed = parseInventory(readFileSync(path, "utf8"));
+    if (!parsed.ok) {
+        return finish({ ...baseReport(), error: `the baseline at ${options.inventoryPath} is invalid: ${parsed.reason}. Re-create it with "srclawyer scan --write-inventory".` }, options);
+    }
+    const baseline = parsed.inventory;
+    const discovery = selectDiscovery(root);
+    const result = await scan(root, { onlyFiles: discovery.files });
+    const protectedLogic = await resolveScanProtectedLogic(result);
+    const reasons = inventoryBlockers(result, protectedLogic.warning);
+    if (baseline.discovery !== discovery.mode) {
+        reasons.push(`Discovery mode mismatch: the baseline was written with ${baseline.discovery} discovery, but this run used ${discovery.mode} discovery${discovery.mode === "glob" ? ` (${discovery.reason})` : ""}. The two see different files, so they can't be compared.`);
+    }
+    const report = {
+        ...baseReport(),
+        baseline: { path: options.inventoryPath, srclawyerVersion: baseline.srclawyerVersion, discovery: baseline.discovery },
+        currentDiscovery: discovery.mode,
+    };
+    if (reasons.length > 0) {
+        return finish({ ...report, result: "inconclusive", exitCode: EXIT_INCONCLUSIVE, inconclusiveReasons: reasons }, options);
+    }
+    const current = computeInventory(protectedLogic.findings, { srclawyerVersion: readPackageVersion(), discovery: discovery.mode });
+    const diff = diffInventories(baseline, current);
+    return finish(hasDrift(diff) ? { ...report, result: "drift", exitCode: EXIT_DRIFT, diff } : { ...report, result: "no-drift", exitCode: EXIT_OK, diff }, options);
+}

package/dist/commands/init.d.ts

@@ -12,5 +12,10 @@ export interface InitFlags {
     accountDeletionInstructions?: string;
     minimumAge?: number;
     sendsDataToAiServices?: boolean;
+    /** Advanced, opt-in: sets tier: byok. Never asked about in the default flow. */
+    enableAiReview?: boolean;
+    apiKeyEnvVar?: string;
 }
+export declare const DEFAULT_API_KEY_ENV_VAR = "ANTHROPIC_API_KEY";
+export declare function isValidEnvVarName(name: string): boolean;
 export declare function runInit(root: string, flags?: InitFlags): Promise<void>;

package/dist/commands/init.js

@@ -2,8 +2,13 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { CONFIG_FILENAME, DEFAULT_CONFIG, configPath, hasUnmigratedLegacyConfig, legacyConfigMessage, writeConfig, } from "../config/config.js";
-import { NETWORK_CALLS_NOTICE } from "../policy/legalNotices.js";
+import { NETWORK_CALLS_NOTICE, byokNetworkNotice } from "../policy/legalNotices.js";
 import { runScan } from "./scan.js";
+export const DEFAULT_API_KEY_ENV_VAR = "ANTHROPIC_API_KEY";
+const ENV_VAR_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export function isValidEnvVarName(name) {
+    return ENV_VAR_NAME.test(name);
+}
 function guessIndustry(root) {
     const pkgPath = join(root, "package.json");
     if (!existsSync(pkgPath))
@@ -132,17 +137,22 @@ export async function runInit(root, flags = {}) {
     // Deliberately about the SCANNED PRODUCT's own behavior (does it send its end-users' data to AI
     // services as part of its own functionality) -- not about SrcLawyer's own, separately-documented
     // BYOK network calls described in NETWORK_CALLS_NOTICE above.
-    const sendsDataToAiServices = await resolveField(flags.sendsDataToAiServices, gateYes, () => askYesNoOptional(lines, "Does this product send user data to third-party AI services (e.g. OpenAI, Anthropic) as part of its own functionality?"));
-    // "managed" is deliberately not offered here -- it's a real SrcLawyerTier value and config.ts/
-    // resolveProviderForTier.ts both still support it fully (a hand-edited config with tier: managed
-    // still gets a clear, accurate error at scan time), but there's no advertised path to it from this
-    // prompt, so a tester reading the choices here can't select a dead end during setup.
-    const enableByokRaw = await ask(lines, "Enable optional AI-assisted review with your own Anthropic key? (advanced)", "n");
-    const tier = /^y(es)?$/i.test(enableByokRaw.trim()) ? "byok" : "free";
+    const sendsDataToAiServices = await resolveField(flags.sendsDataToAiServices, gateYes, () => askYesNoOptional(lines, "Does this product send user data to third-party AI services as part of its own functionality?"));
+    // AI-assisted review (tier: byok) is an advanced opt-in, reached only via --enable-ai-review (or by
+    // hand-editing the config) -- the default flow never asks about it or mentions an API key. "managed"
+    // is likewise not offered here: it's still a real SrcLawyerTier value that config.ts and
+    // resolveProviderForTier.ts support, so a hand-edited tier: managed keeps its clear "not available
+    // yet" error at scan time, but nothing advertises a path to it.
+    const tier = flags.enableAiReview ? "byok" : "free";
     let apiKeyEnvVar = null;
     if (tier === "byok") {
-        apiKeyEnvVar = await ask(lines, "Which environment variable holds your Anthropic API key?", "ANTHROPIC_API_KEY");
+        apiKeyEnvVar = flags.apiKeyEnvVar ?? (await ask(lines, "Which environment variable holds your Anthropic API key?", DEFAULT_API_KEY_ENV_VAR));
+        if (!isValidEnvVarName(apiKeyEnvVar)) {
+            console.log(`\n"${apiKeyEnvVar}" is not a valid environment variable name; using ${DEFAULT_API_KEY_ENV_VAR} instead. Edit ${CONFIG_FILENAME} to change it.`);
+            apiKeyEnvVar = DEFAULT_API_KEY_ENV_VAR;
+        }
         console.log(`\nNote: only the name "${apiKeyEnvVar}" is written to ${CONFIG_FILENAME} — the key itself is never written to disk. It's read from your environment at scan time.`);
+        console.log(byokNetworkNotice(apiKeyEnvVar));
     }
     const config = {
         entityLocation: entityLocation || null,

package/dist/commands/protectedLogicStep.d.ts

@@ -0,0 +1,12 @@
+import type { Finding, ScanResult } from "../engine/types.js";
+/**
+ * The one place a scan result is handed to the protected-logic service. Not tier-gated, not behind
+ * --no-llm: confidence scoring and Zod-schema detection are Layer 1 capabilities, needed on every real
+ * scan. A failure degrades honestly (findings keep their safe local fallback and a warning is
+ * returned) rather than blocking the scan. Shared by `scan` and `check` so both make exactly the same
+ * calls under exactly the same conditions.
+ */
+export declare function resolveScanProtectedLogic(result: ScanResult): Promise<{
+    findings: Finding[];
+    warning: string | null;
+}>;

package/dist/commands/protectedLogicStep.js

@@ -0,0 +1,16 @@
+import { resolveProtectedLogic } from "../cloud/resolveProtectedLogic.js";
+import { resolveProtectedLogicEndpoint } from "../cloud/config.js";
+/**
+ * The one place a scan result is handed to the protected-logic service. Not tier-gated, not behind
+ * --no-llm: confidence scoring and Zod-schema detection are Layer 1 capabilities, needed on every real
+ * scan. A failure degrades honestly (findings keep their safe local fallback and a warning is
+ * returned) rather than blocking the scan. Shared by `scan` and `check` so both make exactly the same
+ * calls under exactly the same conditions.
+ */
+export async function resolveScanProtectedLogic(result) {
+    const hasScorableFindings = result.findings.some((f) => f.confidenceFactors) || result.pendingZodCandidates.length > 0 || result.oversizedZodFiles.length > 0;
+    if (!hasScorableFindings)
+        return { findings: result.findings, warning: null };
+    const resolved = await resolveProtectedLogic(result.findings, result.pendingZodCandidates, resolveProtectedLogicEndpoint(), result.oversizedZodFiles);
+    return { findings: resolved.findings, warning: resolved.warning };
+}

package/dist/commands/scan.d.ts

@@ -2,5 +2,10 @@ export interface ScanOptions {
     json: boolean;
     out: string;
     llm: boolean;
+    /** Write the drift baseline to this path (relative to root). With this set the scan uses the shared
+     *  git-aware discovery mode (see gitDiscovery.ts) for the policy as well, so the two always agree. */
+    writeInventory?: string;
+    /** Write the baseline even if the scan completed with warnings that make it untrustworthy. */
+    allowIncompleteInventory?: boolean;
 }
 export declare function runScan(root: string, options: ScanOptions): Promise<void>;

package/dist/commands/scan.js

@@ -6,8 +6,10 @@ import { formatText } from "../report/formatText.js";
 import { generatePolicyMarkdown } from "../policy/generatePolicy.js";
 import { resolveProviderForTier } from "../llm/resolveProviderForTier.js";
 import { resolveAmbiguousFindings } from "../llm/resolveAmbiguousFindings.js";
-import { resolveProtectedLogic } from "../cloud/resolveProtectedLogic.js";
-import { resolveProtectedLogicEndpoint } from "../cloud/config.js";
+import { resolveScanProtectedLogic } from "./protectedLogicStep.js";
+import { selectDiscovery } from "../engine/gitDiscovery.js";
+import { computeInventory, inventoryBlockers, serializeInventory } from "../inventory/inventory.js";
+import { readPackageVersion } from "../version.js";
 import { MAX_FRAGMENT_BYTES } from "../rules/zodPreFilter.js";
 import { SCAN_DISCLAIMER_REMINDER, byokNetworkNotice } from "../policy/legalNotices.js";
 export async function runScan(root, options) {
@@ -22,7 +24,8 @@ export async function runScan(root, options) {
             console.error(`No ${CONFIG_FILENAME} found. Run "srclawyer init" first.\n`);
         }
     }
-    const result = await scan(root);
+    const discovery = options.writeInventory ? selectDiscovery(root) : null;
+    const result = await scan(root, { onlyFiles: discovery?.files ?? null });
     let findings = result.findings;
     if (result.workspaceWarning)
         console.error(result.workspaceWarning);
@@ -33,20 +36,11 @@ export async function runScan(root, options) {
     if (result.maxZodFragmentBytes > 0) {
         console.error(`Largest Zod-schema fragment this scan: ${result.maxZodFragmentBytes} bytes (hard ceiling: ${MAX_FRAGMENT_BYTES} bytes).`);
     }
-    // Not tier-gated, not behind --no-llm: confidence scoring and Zod-schema detection are Layer 1
-    // capabilities now, needed on every real scan regardless of which LLM tier (if any) is configured.
-    // A failure here degrades honestly (findings keep their safe local fallback) rather than blocking
-    // the scan — see resolveProtectedLogic's own per-call error handling.
-    const hasScorableFindings = findings.some((f) => f.confidenceFactors) || result.pendingZodCandidates.length > 0 || result.oversizedZodFiles.length > 0;
-    let protectedLogicWarning = null;
-    if (hasScorableFindings) {
-        const endpoint = resolveProtectedLogicEndpoint();
-        const resolved = await resolveProtectedLogic(findings, result.pendingZodCandidates, endpoint, result.oversizedZodFiles);
-        findings = resolved.findings;
-        protectedLogicWarning = resolved.warning;
-        if (protectedLogicWarning)
-            console.error(protectedLogicWarning);
-    }
+    const protectedLogic = await resolveScanProtectedLogic(result);
+    findings = protectedLogic.findings;
+    const protectedLogicWarning = protectedLogic.warning;
+    if (protectedLogicWarning)
+        console.error(protectedLogicWarning);
     let llmError = null;
     if (options.llm && config) {
         const { provider, error } = resolveProviderForTier(config);
@@ -60,7 +54,7 @@ export async function runScan(root, options) {
                 if (config.tier === "byok" && config.llm) {
                     console.log(byokNetworkNotice(config.llm.apiKeyEnvVar));
                 }
-                console.log(`Sending ${ambiguous.length} ambiguous item(s) to ${provider.name}...`);
+                console.log(`Sending ${ambiguous.length} ambiguous item(s) to ${provider.name} (an opaque id, category, description and one redacted source line each)...`);
                 const resolved = await resolveAmbiguousFindings(ambiguous, provider, {
                     // Preserves today's exact override behavior bit-for-bit: a missing/legacy key already
                     // behaved as false before collectsChildrensData became nullable. Only the generated
@@ -77,14 +71,30 @@ export async function runScan(root, options) {
     const finalResult = { ...result, findings, ambiguousCount };
     const policyPath = resolve(root, options.out);
     writeFileSync(policyPath, generatePolicyMarkdown(finalResult, config, llmError, protectedLogicWarning));
+    let inventoryNote = null;
+    if (options.writeInventory && discovery) {
+        const blockers = inventoryBlockers(result, protectedLogicWarning);
+        if (blockers.length > 0 && !options.allowIncompleteInventory) {
+            inventoryNote = `Inventory not written: this scan completed with warnings (see above), so its categories may be incomplete and would read as drift later. Fix them and re-run, or pass --allow-incomplete-inventory to write it anyway.`;
+            console.error(inventoryNote);
+        }
+        else {
+            const inventory = computeInventory(finalResult.findings, { srclawyerVersion: readPackageVersion(), discovery: discovery.mode });
+            writeFileSync(resolve(root, options.writeInventory), serializeInventory(inventory));
+            inventoryNote = `Wrote the drift baseline to ${options.writeInventory} (${inventory.categories.length} categories, ${inventory.processors.length} processors; ${discovery.mode} discovery). Commit it, then run "srclawyer check" in CI.`;
+            if (discovery.mode === "glob")
+                inventoryNote += ` (${discovery.reason}; the baseline records the ordinary filesystem walk.)`;
+            console.error(inventoryNote);
+        }
+    }
     if (result.unsupportedStackWarning || result.workspaceWarning || result.skippedFilesWarning || llmError || protectedLogicWarning || legacyConfigWarning) {
         process.exitCode = 1;
     }
     if (options.json) {
-        console.log(JSON.stringify({ ...finalResult, policyPath, llmError, protectedLogicWarning, legacyConfigWarning }, null, 2));
+        console.log(JSON.stringify({ ...finalResult, policyPath, llmError, protectedLogicWarning, legacyConfigWarning, inventoryNote }, null, 2));
         return;
     }
-    console.log(formatText(finalResult));
+    console.log(formatText(finalResult, { aiReviewEnabled: config?.tier === "byok" }));
     if (protectedLogicWarning)
         console.log(`\n${protectedLogicWarning}`);
     if (legacyConfigWarning)

package/dist/engine/gitDiscovery.d.ts

@@ -0,0 +1,20 @@
+import type { DiscoveryMode } from "../inventory/inventory.js";
+/**
+ * The shared discovery mode for the drift baseline (`scan --write-inventory`) and `check`. A baseline
+ * written on a laptop and checked on a CI runner must see the same files, but the ordinary walk also
+ * sees whatever untracked, gitignored output happens to be on disk (generated code, local scratch
+ * dirs) that a clean checkout never has -- which would show up as phantom drift. So inside a git
+ * repository both sides use `git ls-files --cached --others --exclude-standard` (tracked, plus
+ * untracked-but-not-ignored); anywhere else, the ordinary walk. `scan`'s own default discovery is not
+ * changed. The mode is recorded in the baseline, and a mismatch is reported as inconclusive.
+ */
+export type DiscoverySelection = {
+    mode: "git";
+    files: Set<string>;
+} | {
+    mode: "glob";
+    files: null;
+    reason: string;
+};
+export declare function selectDiscovery(root: string): DiscoverySelection;
+export declare function discoveryMode(selection: DiscoverySelection): DiscoveryMode;

package/dist/engine/gitDiscovery.js

@@ -0,0 +1,31 @@
+import { execFileSync } from "node:child_process";
+import { resolve } from "node:path";
+function firstLine(text) {
+    return text.trim().split("\n")[0] ?? "";
+}
+export function selectDiscovery(root) {
+    const git = (args) => execFileSync("git", ["-C", root, ...args], { encoding: "buffer", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 512 * 1024 * 1024 });
+    try {
+        git(["rev-parse", "--is-inside-work-tree"]);
+    }
+    catch (error) {
+        const stderr = error.stderr?.toString() ?? "";
+        const reason = error.code === "ENOENT" ? "git is not installed" : stderr.includes("not a git repository") ? "not a git repository" : `git is not usable here (${firstLine(stderr) || "unknown error"})`;
+        return { mode: "glob", files: null, reason };
+    }
+    try {
+        const listing = git(["ls-files", "-z", "--cached", "--others", "--exclude-standard"]).toString("utf8");
+        const files = new Set();
+        for (const relative of listing.split("\0"))
+            if (relative)
+                files.add(resolve(root, relative));
+        return { mode: "git", files };
+    }
+    catch (error) {
+        const stderr = error.stderr?.toString() ?? "";
+        return { mode: "glob", files: null, reason: `git ls-files failed (${firstLine(stderr) || "unknown error"})` };
+    }
+}
+export function discoveryMode(selection) {
+    return selection.mode;
+}

package/dist/engine/globFiles.js

@@ -1,4 +1,5 @@
 import { glob } from "tinyglobby";
+import { resolve } from "node:path";
 // expandDirectories: false keeps tinyglobby's matching identical to the fast-glob behavior this
 // replaced (a pattern matches only what it names, never everything under a matched directory).
 // tinyglobby/picomatch compiles braces to regex alternation rather than expanding them, so it has no
@@ -8,5 +9,8 @@ import { glob } from "tinyglobby";
 // traversal order, which neither fast-glob nor tinyglobby guarantees.
 export async function globFiles(patterns, options) {
     const { boundary, ...globOptions } = options;
-    return (await glob(patterns, { expandDirectories: false, ...globOptions, ...(boundary ? { fs: boundary.globFs() } : {}) })).sort();
+    const found = (await glob(patterns, { expandDirectories: false, ...globOptions, ...(boundary ? { fs: boundary.globFs() } : {}) })).sort();
+    // An optional discovery restriction (git mode) is an intersection with the normal glob, so every
+    // ignore pattern and the symlink boundary above still apply unchanged.
+    return boundary ? found.filter((p) => boundary.keepsInDiscovery(resolve(options.cwd, p))) : found;
 }

package/dist/engine/rootBoundary.d.ts

@@ -10,7 +10,10 @@ export declare class RootBoundary {
     readonly realRoot: string;
     private readonly blocked;
     private readonly resolved;
+    private discoveryFilter;
     constructor(root: string);
+    restrictDiscoveryTo(files: Set<string> | null): void;
+    keepsInDiscovery(absolutePath: string): boolean;
     isInsideRealPath(resolved: string): boolean;
     /** Records a blocked link by its in-repo (lexical) path only -- never its target. */
     private recordBlocked;

package/dist/engine/rootBoundary.js

@@ -17,6 +17,9 @@ export class RootBoundary {
     // through an in-root directory loop is the same link, counted once.
     blocked = new Map();
     resolved = new Map();
+    // When set, discovery only keeps files in this set (absolute paths) -- see gitDiscovery.ts. It lives
+    // here only because this object is already threaded through every glob call.
+    discoveryFilter = null;
     constructor(root) {
         this.root = root;
         try {
@@ -26,6 +29,12 @@ export class RootBoundary {
             this.realRoot = resolve(root);
         }
     }
+    restrictDiscoveryTo(files) {
+        this.discoveryFilter = files;
+    }
+    keepsInDiscovery(absolutePath) {
+        return this.discoveryFilter === null || this.discoveryFilter.has(absolutePath);
+    }
     isInsideRealPath(resolved) {
         return resolved === this.realRoot || resolved.startsWith(this.realRoot + sep);
     }

package/dist/engine/scanEngine.d.ts

@@ -8,4 +8,8 @@ import type { ScanResult } from "./types.js";
  * rather than folded into it. Anyone auditing "does this touch the network" can still answer that by
  * reading this file alone.
  */
-export declare function scan(root: string): Promise<ScanResult>;
+export interface ScanEngineOptions {
+    /** Absolute paths discovery is restricted to (git mode, for the drift baseline); unset = ordinary discovery. */
+    onlyFiles?: Set<string> | null;
+}
+export declare function scan(root: string, options?: ScanEngineOptions): Promise<ScanResult>;

package/dist/engine/scanEngine.js

@@ -103,17 +103,9 @@ async function runPythonCodeRules(filePath, source, root) {
     }
     return { findings, failure };
 }
-/**
- * Pure, local, offline — no network access anywhere in this function or anything it calls. Zod
- * schemas and confidence scoring can no longer be fully resolved here (see pendingZodCandidates and
- * every Finding.confidenceFactors) — resolving those against the protected-logic service is a
- * separate, explicit step in src/cloud/resolveProtectedLogic.ts, called from commands/scan.ts, the
- * same way Layer 2's resolveAmbiguousFindings.ts is a separate step layered on top of this function
- * rather than folded into it. Anyone auditing "does this touch the network" can still answer that by
- * reading this file alone.
- */
-export async function scan(root) {
+export async function scan(root, options = {}) {
     const boundary = new RootBoundary(root);
+    boundary.restrictDiscoveryTo(options.onlyFiles ?? null);
     const [{ projects, workspaceWarning }, unsupportedStackWarning] = await Promise.all([
         discoverProjects(root, boundary),
         detectUnsupportedStack(root, boundary),

package/dist/exitCodes.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Process exit codes -- one table for both commands so they can't drift apart. Documented in the README.
+ *
+ *   code | srclawyer scan                  | srclawyer check
+ *   -----+---------------------------------+----------------------------------------------------------
+ *    0   | clean                           | no drift
+ *    1   | completed with warnings         | drift
+ *    2   | crash or bad usage              | crash, bad usage, or a missing / invalid baseline
+ *    3   | (not used)                      | inconclusive: a warning that makes `scan` exit 1, or a
+ *        |                                 | discovery-mode mismatch -- never reported as drift
+ *
+ * `scan`'s "warnings" (1) and `check`'s "inconclusive" (3) are the same condition under different
+ * numbers; `scan`'s was left alone so existing scripts keep working.
+ */
+export declare const EXIT_OK = 0;
+export declare const EXIT_SCAN_WARNINGS = 1;
+export declare const EXIT_DRIFT = 1;
+export declare const EXIT_CRASH = 2;
+export declare const EXIT_INCONCLUSIVE = 3;

package/dist/exitCodes.js

@@ -0,0 +1,19 @@
+/**
+ * Process exit codes -- one table for both commands so they can't drift apart. Documented in the README.
+ *
+ *   code | srclawyer scan                  | srclawyer check
+ *   -----+---------------------------------+----------------------------------------------------------
+ *    0   | clean                           | no drift
+ *    1   | completed with warnings         | drift
+ *    2   | crash or bad usage              | crash, bad usage, or a missing / invalid baseline
+ *    3   | (not used)                      | inconclusive: a warning that makes `scan` exit 1, or a
+ *        |                                 | discovery-mode mismatch -- never reported as drift
+ *
+ * `scan`'s "warnings" (1) and `check`'s "inconclusive" (3) are the same condition under different
+ * numbers; `scan`'s was left alone so existing scripts keep working.
+ */
+export const EXIT_OK = 0;
+export const EXIT_SCAN_WARNINGS = 1;
+export const EXIT_DRIFT = 1;
+export const EXIT_CRASH = 2;
+export const EXIT_INCONCLUSIVE = 3;

package/dist/inventory/inventory.d.ts

@@ -0,0 +1,54 @@
+import type { Finding, ScanResult } from "../engine/types.js";
+/**
+ * The drift baseline: WHICH data categories and third-party processors the code touches, and nothing
+ * else -- no file names, line numbers, field names or timestamps. Users hand-edit their generated
+ * policy, so drift is judged against this, never against policy text.
+ *
+ * Built from Layer 1 only (finding.dataCategories / finding.processor) over ALL findings: AI-assisted
+ * review never changes it (so it's identical on every tier), and a finding moving between "confident"
+ * and "needs review" is not drift.
+ */
+export declare const INVENTORY_SCHEMA = 1;
+export declare const DEFAULT_INVENTORY_PATH = ".srclawyer.inventory.json";
+/** "git": git ls-files --cached --others --exclude-standard; "glob": the ordinary filesystem walk. */
+export type DiscoveryMode = "git" | "glob";
+export interface Inventory {
+    schema: number;
+    /** Informational only -- never compared. Lets a drift report say "the baseline was written by an older version". */
+    srclawyerVersion: string;
+    discovery: DiscoveryMode;
+    categories: string[];
+    processors: string[];
+}
+export declare function computeInventory(findings: Finding[], meta: {
+    srclawyerVersion: string;
+    discovery: DiscoveryMode;
+}): Inventory;
+/** Fixed key order, two-space indent, trailing newline: the same inventory is always the same bytes. */
+export declare function serializeInventory(inventory: Inventory): string;
+export type ParsedInventory = {
+    ok: true;
+    inventory: Inventory;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function parseInventory(text: string): ParsedInventory;
+export interface InventoryDiff {
+    added: {
+        categories: string[];
+        processors: string[];
+    };
+    removed: {
+        categories: string[];
+        processors: string[];
+    };
+}
+export declare function diffInventories(baseline: Inventory, current: Inventory): InventoryDiff;
+export declare function hasDrift(diff: InventoryDiff): boolean;
+/**
+ * The warnings that make a drift verdict untrustworthy -- exactly the ones that make `scan` exit 1,
+ * minus the two that can't affect Layer 1 categories (an AI-review misconfiguration, and the legacy
+ * config filename). A degraded scan is missing findings, which would read as "removed" categories.
+ */
+export declare function inventoryBlockers(result: ScanResult, protectedLogicWarning: string | null): string[];

package/dist/inventory/inventory.js

@@ -0,0 +1,94 @@
+/**
+ * The drift baseline: WHICH data categories and third-party processors the code touches, and nothing
+ * else -- no file names, line numbers, field names or timestamps. Users hand-edit their generated
+ * policy, so drift is judged against this, never against policy text.
+ *
+ * Built from Layer 1 only (finding.dataCategories / finding.processor) over ALL findings: AI-assisted
+ * review never changes it (so it's identical on every tier), and a finding moving between "confident"
+ * and "needs review" is not drift.
+ */
+export const INVENTORY_SCHEMA = 1;
+export const DEFAULT_INVENTORY_PATH = ".srclawyer.inventory.json";
+// Default code-point sort, deliberately not localeCompare: locale-aware ordering differs between
+// machines (ICU data, LANG), which would make the committed file differ byte-for-byte between a laptop and CI.
+function sortedUnique(values) {
+    return [...new Set(values)].sort();
+}
+export function computeInventory(findings, meta) {
+    return {
+        schema: INVENTORY_SCHEMA,
+        srclawyerVersion: meta.srclawyerVersion,
+        discovery: meta.discovery,
+        categories: sortedUnique(findings.flatMap((f) => f.dataCategories)),
+        processors: sortedUnique(findings.flatMap((f) => (f.processor ? [f.processor] : []))),
+    };
+}
+/** Fixed key order, two-space indent, trailing newline: the same inventory is always the same bytes. */
+export function serializeInventory(inventory) {
+    const ordered = {
+        schema: inventory.schema,
+        srclawyerVersion: inventory.srclawyerVersion,
+        discovery: inventory.discovery,
+        categories: sortedUnique(inventory.categories),
+        processors: sortedUnique(inventory.processors),
+    };
+    return JSON.stringify(ordered, null, 2) + "\n";
+}
+export function parseInventory(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text.replace(/^/, ""));
+    }
+    catch {
+        return { ok: false, reason: "it is not valid JSON" };
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return { ok: false, reason: "it is not a JSON object" };
+    const o = raw;
+    if (o.schema !== INVENTORY_SCHEMA)
+        return { ok: false, reason: `unsupported schema ${JSON.stringify(o.schema)} (this version reads schema ${INVENTORY_SCHEMA})` };
+    if (o.discovery !== "git" && o.discovery !== "glob")
+        return { ok: false, reason: '"discovery" must be "git" or "glob"' };
+    const stringArray = (v) => Array.isArray(v) && v.every((x) => typeof x === "string");
+    if (!stringArray(o.categories))
+        return { ok: false, reason: '"categories" must be an array of strings' };
+    if (!stringArray(o.processors))
+        return { ok: false, reason: '"processors" must be an array of strings' };
+    return {
+        ok: true,
+        inventory: {
+            schema: INVENTORY_SCHEMA,
+            srclawyerVersion: typeof o.srclawyerVersion === "string" ? o.srclawyerVersion : "unknown",
+            discovery: o.discovery,
+            categories: sortedUnique(o.categories),
+            processors: sortedUnique(o.processors),
+        },
+    };
+}
+function difference(from, minus) {
+    const exclude = new Set(minus);
+    return from.filter((v) => !exclude.has(v));
+}
+export function diffInventories(baseline, current) {
+    return {
+        added: {
+            categories: difference(current.categories, baseline.categories),
+            processors: difference(current.processors, baseline.processors),
+        },
+        removed: {
+            categories: difference(baseline.categories, current.categories),
+            processors: difference(baseline.processors, current.processors),
+        },
+    };
+}
+export function hasDrift(diff) {
+    return Object.values(diff.added).some((v) => v.length > 0) || Object.values(diff.removed).some((v) => v.length > 0);
+}
+/**
+ * The warnings that make a drift verdict untrustworthy -- exactly the ones that make `scan` exit 1,
+ * minus the two that can't affect Layer 1 categories (an AI-review misconfiguration, and the legacy
+ * config filename). A degraded scan is missing findings, which would read as "removed" categories.
+ */
+export function inventoryBlockers(result, protectedLogicWarning) {
+    return [result.unsupportedStackWarning, result.workspaceWarning, result.skippedFilesWarning, protectedLogicWarning].filter((w) => !!w);
+}

package/dist/llm/buildRequestItem.d.ts

@@ -6,5 +6,9 @@ import type { LlmRequestItem } from "./types.js";
  * they leave this function — LlmRequestItem has no raw-evidence field, so a
  * provider implementation is structurally incapable of receiving
  * unredacted content.
+ *
+ * `requestId` is an opaque per-scan identifier (f0, f1, ...), never finding.id: finding ids embed the
+ * file path, line number and field name, and none of those may reach the provider. The caller
+ * (resolveAmbiguousFindings) owns the mapping back to findings and never sends it anywhere.
  */
-export declare function buildRequestItem(finding: Finding, collectsChildrensData: boolean): LlmRequestItem;
+export declare function buildRequestItem(finding: Finding, collectsChildrensData: boolean, requestId: string): LlmRequestItem;

package/dist/llm/buildRequestItem.js

@@ -5,10 +5,14 @@ import { redactSecrets } from "../engine/secretRedaction.js";
  * they leave this function — LlmRequestItem has no raw-evidence field, so a
  * provider implementation is structurally incapable of receiving
  * unredacted content.
+ *
+ * `requestId` is an opaque per-scan identifier (f0, f1, ...), never finding.id: finding ids embed the
+ * file path, line number and field name, and none of those may reach the provider. The caller
+ * (resolveAmbiguousFindings) owns the mapping back to findings and never sends it anywhere.
  */
-export function buildRequestItem(finding, collectsChildrensData) {
+export function buildRequestItem(finding, collectsChildrensData, requestId) {
     return {
-        findingId: finding.id,
+        findingId: requestId,
         redactedEvidence: redactSecrets(finding.evidence),
         redactedDescription: redactSecrets(finding.description),
         dataCategories: finding.dataCategories,

package/dist/llm/resolveAmbiguousFindings.js

@@ -6,8 +6,11 @@ const DEFAULT_BATCH_CHAR_BUDGET = 6000;
 export async function resolveAmbiguousFindings(findings, provider, options) {
     const batches = chunkFindings(findings, options.batchSize ?? DEFAULT_BATCH_SIZE);
     const resolvedById = new Map();
+    // Opaque per-scan ids (f0, f1, ...), unique across all batches. Finding ids embed file paths and
+    // line numbers, so only these ever go on the wire; the mapping back lives here and nowhere else.
+    const requestIdOf = new Map(findings.map((finding, i) => [finding, `f${i}`]));
     for (const batch of batches) {
-        const items = batch.map((finding) => buildRequestItem(finding, options.collectsChildrensData));
+        const items = batch.map((finding) => buildRequestItem(finding, options.collectsChildrensData, requestIdOf.get(finding)));
         const isHighStakesById = new Map(items.map((item) => [item.findingId, item.isHighStakes]));
         let responses;
         try {
@@ -27,8 +30,9 @@ export async function resolveAmbiguousFindings(findings, provider, options) {
         }
         const responseById = new Map(responses.map((response) => [response.findingId, response]));
         for (const finding of batch) {
-            const response = responseById.get(finding.id);
-            const isHighStakes = isHighStakesById.get(finding.id) ?? false;
+            const requestId = requestIdOf.get(finding);
+            const response = responseById.get(requestId);
+            const isHighStakes = isHighStakesById.get(requestId) ?? false;
             resolvedById.set(finding.id, toResolution(response, isHighStakes, provider));
         }
     }

package/dist/llm/resolveProviderForTier.js

@@ -10,7 +10,7 @@ export function resolveProviderForTier(config) {
         if (!envVar) {
             return {
                 provider: null,
-                error: `Tier is "byok" but no API key environment variable is configured in ${CONFIG_FILENAME}. Run "srclawyer init" to set one.`,
+                error: `Tier is "byok" but no API key environment variable is configured in ${CONFIG_FILENAME}. Add "llm: { provider: anthropic, apiKeyEnvVar: <ENV_VAR_NAME> }" to it, or delete the file and re-run "srclawyer init --enable-ai-review".`,
             };
         }
         const apiKey = process.env[envVar];

package/dist/policy/legalNotices.js

@@ -8,16 +8,20 @@
 // notice and disclaimer, not a substitute for either.
 export const PRIVACY_POLICY_URL = "https://github.com/SrcLawyer/srclawyer#legal";
 export const TERMS_URL = "https://github.com/SrcLawyer/srclawyer#legal";
-// Verbatim from README.md's own "Network calls" section (minus markdown backticks, since this prints
-// to a terminal) -- one wording for this claim, not a second paraphrase that can drift from the first.
+// Mirrors README.md's own "Network calls" section (condensed, minus markdown backticks since this
+// prints to a terminal) -- the same claims in the same terms, not a second paraphrase that can drift.
+// What is actually on the wire is pinned by tests/requestBodiesNoPaths.test.ts.
 export const NETWORK_CALLS_NOTICE = [
     "Heads up: SrcLawyer makes network calls.",
     "",
     "Detection itself is fully local and offline — no code leaves your machine for pattern matching.",
-    "Once detection completes, scan makes one batched network call to grade the confidence of what it",
-    "found (field names and derived yes/no signals only, never source code), and, for scans that use Zod",
-    "schemas as request validators, one additional call sending a small redacted code fragment. This runs",
-    "on every scan regardless of tier.",
+    "Once detection completes, every scan makes one batched call to grade the confidence of what it",
+    "found. For each field it sends an opaque id (f0, f1, ...), the data category the field's name maps",
+    "to, and three derived signals (is the name ambiguous, was it read directly from the request, how",
+    "many similar fields sit alongside it) -- no field names, file paths, line numbers or source code.",
+    "Scans that use Zod schemas as request validators make one additional batched call, sending an",
+    "opaque id and a small secret-redacted code fragment per schema (the schema, its validation call",
+    "and the imports it uses) -- never a file path or line number.",
     "",
     `Legal notice and disclaimer: ${PRIVACY_POLICY_URL}`,
     "(A dedicated privacy policy and terms of service are coming; this points to what exists today.)",
@@ -25,5 +29,5 @@ export const NETWORK_CALLS_NOTICE = [
 export const SCAN_DISCLAIMER_REMINDER = "Reminder: this is automated analysis, not legal advice — review the generated policy before publishing it.";
 export function byokNetworkNotice(apiKeyEnvVar) {
     const keySource = apiKeyEnvVar ? `env var ${apiKeyEnvVar}` : "your configured key";
-    return `BYOK is configured: redacted code snippets for ambiguous findings will be sent to Anthropic under your own API key (${keySource}), for AI-assisted classification only.`;
+    return `BYOK is configured: for each finding scan couldn't classify, it will send Anthropic, under your own API key (${keySource}), an opaque id, the finding's data category and description (which names the field), and the one source line it was found on with secrets redacted — not the file's path or line number, and no other code — for AI-assisted classification only.`;
 }

package/dist/report/formatText.d.ts

@@ -1,2 +1,7 @@
 import type { ScanResult } from "../engine/types.js";
-export declare function formatText(result: ScanResult): string;
+export interface FormatTextOptions {
+    /** True when the config has AI-assisted review (tier: byok) turned on -- the hint about that
+     *  advanced option is only relevant when it isn't. */
+    aiReviewEnabled?: boolean;
+}
+export declare function formatText(result: ScanResult, options?: FormatTextOptions): string;

package/dist/report/formatText.js

@@ -1,5 +1,5 @@
 const BANNER_RULE = "=".repeat(72);
-export function formatText(result) {
+export function formatText(result, options = {}) {
     const lines = [];
     if (result.unsupportedStackWarning) {
         lines.push(BANNER_RULE);
@@ -54,7 +54,12 @@ export function formatText(result) {
     }
     else if (result.ambiguousCount > 0) {
         lines.push("");
-        lines.push(`${result.ambiguousCount} item(s) require deeper analysis before they can be included in a policy. Run "srclawyer scan" with the "byok" tier configured (bring your own Anthropic key) to attempt AI-assisted resolution, or resolve manually. A "managed" tier is planned but not yet available.`);
+        const base = `${result.ambiguousCount} item(s) require deeper analysis before they can be included in a policy; review them manually.`;
+        // Only worth mentioning when the advanced option isn't already on, and only as a pointer -- it is
+        // opt-in (init --enable-ai-review, or a hand-edited config), not something to recommend to everyone.
+        lines.push(options.aiReviewEnabled
+            ? base
+            : `${base} (Optional, advanced: AI-assisted resolution with your own Anthropic API key — see "AI-assisted review" in the README.)`);
     }
     return lines.join("\n");
 }

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare function readPackageVersion(): string;

package/dist/version.js

@@ -0,0 +1,9 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+// Read from package.json rather than hardcoded, so no reported version can drift from the published
+// one. Works from both src/ (tsx, tests) and dist/: this file sits one level below package.json either way.
+export function readPackageVersion() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return JSON.parse(readFileSync(join(here, "../package.json"), "utf8")).version;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "srclawyer",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Static analysis engine that derives privacy policy documentation directly from source code",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",