@cosmicdrift/kumiko-guards 0.339.0 → 0.341.0

package/README.md

@@ -15,6 +15,25 @@ repo's root. `--explain` prints the resolved repo and per-guard scan scope
 without running any guard; `--write-security-baseline` freezes current
 findings into the baseline file.
 
+## Raw-SQL markers
+
+`guard-raw-sql` blocks `.unsafe()` / `asRawClient()` outside `db/queries/*`,
+`bun-db/query.ts` and testing code. A `// kumiko-lint-ignore raw-sql <reason>`
+marker on the call's line or the line above only suppresses while its
+(file, reason) pair is frozen in `.kumiko-raw-sql-baseline.json` at the repo
+root. A new or reworded marker without a baseline entry fails the check, so
+every exception shows up as a baseline diff in review. Without a baseline file
+the guard only warns, so consumers do not break on bump. Prefer a typed
+`bun-db` helper; freeze a deliberate exception with:
+
+```
+bunx kumiko-guards checks --write-baseline --guard=guard-raw-sql
+```
+
+Rewording the reason is a new entry: re-run the command and review the diff.
+A removed marker leaves a stale entry that does not fail; the same command
+drops it.
+
 ## `kumiko-pre-push`
 
 A POSIX-sh pre-push hook, wired by copying the package's `hooks/pre-push`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.339.0",
+  "version": "0.341.0",
   "description": "AST-based security guards for Kumiko repos: direct-fs/fetch, tenant escalation, admin-API, escape hatches and related checks, run over a shared ts-morph project.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -28,7 +28,7 @@
     "kumiko-pre-push": "./src/pre-push.sh"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-repo-manifest": "0.339.0",
+    "@cosmicdrift/kumiko-repo-manifest": "0.341.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/_lib/guard-kit.ts

@@ -56,7 +56,7 @@ export type AstGuard = {
   /** `roots` are the same roots `runGuards` scanned `files` with — a guard classifying paths against repo roots (`relFromRepoRoot`) must use these, not re-derive its own single-repo `resolveRepoRoots()`, or a multi-root caller's roots never reach it. */
   run(files: readonly SourceFile[], roots?: readonly RepoRoot[]): GuardOutcome;
   /** Ratchet guards only: freeze the current findings into that guard's own baseline file. */
-  writeBaseline?(files: readonly SourceFile[]): void;
+  writeBaseline?(files: readonly SourceFile[], roots?: readonly RepoRoot[]): void;
 };
 
 export function isSecurityGuard(guard: Pick<AstGuard, "security">): boolean {
@@ -195,6 +195,8 @@ export function baselineRatchet(args: {
   readonly file: string;
   readonly formatVersion: number;
   readonly unit: string;
+  /** A missing baseline file counts as an empty baseline (every current entry is a regression) instead of a warning. For guards whose suppression must not hold without a frozen file. */
+  readonly failClosed?: boolean;
 }): {
   write(current: Readonly<Record<string, number>>): void;
   check(
@@ -229,6 +231,13 @@ export function baselineRatchet(args: {
       readonly resolveLine?: (file: string) => number;
     },
   ): GuardViolation[] => {
+    if (!existsSync(args.file) && args.failClosed === true) {
+      return compareToBaseline(current, {}).regressions.map((regression) => ({
+        file: regression.file,
+        line: opts?.resolveLine?.(regression.file) ?? 1,
+        message: `${args.unit} without a baseline file (${args.file}): ${regression.current} not frozen. ${remediation}`,
+      }));
+    }
     if (!existsSync(args.file)) {
       console.log(
         `  No baseline found (${args.file}). Freeze it first with \`--write-baseline\` — warning until then, no fail.`,
@@ -428,6 +437,8 @@ export type RepoCheck = {
   readonly name: string;
   readonly hint?: string;
   run(roots: readonly RepoRoot[]): RepoCheckOutcome | Promise<RepoCheckOutcome>;
+  /** Freezes the check's ratchet baseline(s); reachable via `checks --write-baseline --guard=<name>`. */
+  writeBaseline?(roots: readonly RepoRoot[]): void | Promise<void>;
 };
 
 const VACUOUS_MESSAGE =

package/src/_lib/sql-inventory.ts

@@ -6,7 +6,9 @@
  * Escape hatch for a justified raw-SQL call:
  *   // kumiko-lint-ignore raw-sql <reason>
  * on the call's own line or the line directly above. A bare tag with no
- * reason text after it does NOT suppress the finding.
+ * reason text after it does NOT suppress the finding. guard-raw-sql additionally
+ * requires each (file, reason) to be frozen in `.kumiko-raw-sql-baseline.json`;
+ * the hit carries `markerReason`/`markerLine` for that comparison.
  *
  * I/O: Bun.Glob + Bun.file; directoryExists uses node:fs (same as roots.ts).
  */
@@ -30,6 +32,10 @@ export type SqlInventoryHit = {
   readonly allowed: boolean;
   /** True when a `kumiko-lint-ignore raw-sql <reason>` marker suppresses this hit. */
   readonly markerSuppressed: boolean;
+  /** Trimmed reason text of the suppressing marker; set iff markerSuppressed. */
+  readonly markerReason?: string;
+  /** 1-based line of the suppressing marker; set iff markerSuppressed. */
+  readonly markerLine?: number;
   readonly snippet: string;
 };
 
@@ -62,7 +68,6 @@ export const RAW_SQL_ALLOWLIST: ReadonlyArray<RegExp> = [
   /(^|\/)(packages\/[^/]+\/)?src\/bun-db\/query\.ts$/,
   /(^|\/)(packages\/[^/]+\/)?src\/testing\//,
   // ponytail: explicit enumeration — a blanket regex would auto-allow any new .unsafe()
-  /\/bundled-features\/src\/billing-foundation\/db\/queries\/subscription-projection\.ts$/,
   /\/bundled-features\/src\/config\/db\/queries\/resolver\.ts$/,
   /\/bundled-features\/src\/custom-fields\/db\/queries\/field-access\.ts$/,
   /\/bundled-features\/src\/custom-fields\/db\/queries\/projection\.ts$/,
@@ -73,7 +78,6 @@ export const RAW_SQL_ALLOWLIST: ReadonlyArray<RegExp> = [
   /\/bundled-features\/src\/form-draft\/db\/queries\/cleanup\.ts$/,
   /\/bundled-features\/src\/form-draft\/db\/queries\/draft-count\.ts$/,
   /\/bundled-features\/src\/form-draft\/db\/queries\/owned-file-refs\.ts$/,
-  /\/bundled-features\/src\/inbound-mail-foundation\/db\/queries\/inbound-projections\.ts$/,
   /\/bundled-features\/src\/secrets\/db\/queries\/read\.ts$/,
   /\/bundled-features\/src\/sessions\/db\/queries\/cleanup\.ts$/,
   /\/bundled-features\/src\/user\/db\/queries\/stream-tenant-backfill\.ts$/,
@@ -88,7 +92,7 @@ export const RAW_SQL_ALLOWLIST: ReadonlyArray<RegExp> = [
 /** Escape-hatch tag. Must be followed by whitespace + a non-empty reason to suppress. */
 const MARKER_TAG = "kumiko-lint-ignore raw-sql";
 // Marker must appear in a // comment — string literals describing the hatch must not suppress.
-const MARKER_WITH_REASON_RE = /(^|\s)\/\/\s*kumiko-lint-ignore raw-sql\s+\S/;
+const MARKER_WITH_REASON_RE = /(^|\s)\/\/\s*kumiko-lint-ignore raw-sql\s+(\S.*)$/;
 
 const SKIP_PATH_PARTS = ["/node_modules/", "/dist/", "/.kumiko/"] as const;
 
@@ -185,13 +189,18 @@ function scanFileText(relPath: string, text: string, hits: SqlInventoryHit[]): v
     // Documented hatch: marker on the call line or the line directly above.
     // Each marker line suppresses at most one subsequent hit (consumed), so a
     // second `.unsafe()` under the same comment is not silently covered.
-    let suppressed = false;
-    if (MARKER_WITH_REASON_RE.test(line)) {
-      suppressed = true;
-    } else if (i > 0 && MARKER_WITH_REASON_RE.test(lines[i - 1] ?? "")) {
+    let markerReason: string | undefined;
+    let markerLine: number | undefined;
+    const sameLineReason = MARKER_WITH_REASON_RE.exec(line)?.[2];
+    if (sameLineReason !== undefined) {
+      markerReason = sameLineReason.trim();
+      markerLine = i + 1;
+    } else if (i > 0) {
+      const aboveReason = MARKER_WITH_REASON_RE.exec(lines[i - 1] ?? "")?.[2];
       const markerIdx = i - 1;
-      if (!consumedMarkers.has(markerIdx)) {
-        suppressed = true;
+      if (aboveReason !== undefined && !consumedMarkers.has(markerIdx)) {
+        markerReason = aboveReason.trim();
+        markerLine = i;
         consumedMarkers.add(markerIdx);
       }
     }
@@ -211,7 +220,10 @@ function scanFileText(relPath: string, text: string, hits: SqlInventoryHit[]): v
         line: i + 1,
         kind,
         allowed: isRawSqlAllowed(relPath),
-        markerSuppressed: suppressed,
+        markerSuppressed: markerReason !== undefined,
+        ...(markerReason !== undefined && markerLine !== undefined
+          ? { markerReason, markerLine }
+          : {}),
         snippet: stripMarker(trimmed).slice(0, 120),
       });
     }

package/src/changes.json

@@ -1,4 +1,18 @@
 [
+  {
+    "version": "0.341.0",
+    "type": "breaking",
+    "title": "Repo-local direct-fs exceptions with a frozen reason, bundled read-only assets",
+    "detail": "`guard-no-direct-fs` has a repo-local exception: `// kumiko-lint-ignore direct-fs <reason>` on the `node:fs` import (or the line above) suppresses the finding only while the `<file>::<reason>` pair is frozen in `.kumiko-direct-fs-baseline.json` at the repo root. It fails closed: without a baseline file, with an unreadable file, with a changed reason, or with more markers than frozen, the finding stays. A bare tag without a reason does not count. Freeze with `kumiko-guards guards --write-baseline --guard=\"No-Direct-Fs Guard\"`. The guard hint now points to the marker, `FileStorageProvider` and `readBundledAsset`. `AstGuard.writeBaseline` receives the scanned roots as an optional second argument, and `baselineRatchet` takes an opt-in `failClosed` that treats a missing baseline file as empty.\n**Migration (breaking-ish):** the framework allowlist no longer contains `src/marketing/render-landing.ts` and `src/marketing/rebuild-pages-job.ts` for every repo. Apps that have these files (today money-horse, phronexsis, show-pony, publicstatus) put `// kumiko-lint-ignore direct-fs <reason>` above the `node:fs` import in each file and run `kumiko-guards guards --write-baseline --guard=\"No-Direct-Fs Guard\"` once in the app repo. Commit the generated `.kumiko-direct-fs-baseline.json`.\n`@cosmicdrift/kumiko-server-runtime` can ship read-only files from an app's own build. Declare them in `package.json` under `kumiko.assets` (`[{ \"name\": \"inter-bold.ttf\", \"source\": \"packages/site-kit/fonts/inter-bold.ttf\" }]`, `source` relative to the app's `package.json`). `buildProdBundle` copies them to `dist/kumiko-bundled-assets/`, which the static file server does not serve, and fails the build on an invalid name, a duplicate, a source outside the package or a missing file. `readBundledAsset(name)` and `resolveBundledAsset(name)` read the dist copy in prod and the declared source in dev, so apps need no `node:fs` for it.",
+    "migration": "The allowlist no longer frees src/marketing/render-landing.ts and src/marketing/rebuild-pages-job.ts in every repo. Put // kumiko-lint-ignore direct-fs <reason> above the node:fs import in each such file, run kumiko-guards guards --write-baseline --guard=\"No-Direct-Fs Guard\" once and commit .kumiko-direct-fs-baseline.json."
+  },
+  {
+    "version": "0.340.0",
+    "type": "improvement",
+    "title": "Raw-sql markers must be listed in a baseline",
+    "detail": "`guard-raw-sql` counts the markers that suppress a blocking hit per file and reason and compares them with `.kumiko-raw-sql-baseline.json` in the repo root. A marker without a baseline entry, or with a changed reason, fails the check. Without a baseline file the guard only warns. `kumiko-guards checks --write-baseline --guard=guard-raw-sql` writes the file.",
+    "migration": "Consumer: `--write-baseline` einmal laufen lassen (`bunx kumiko-guards checks --write-baseline --guard=guard-raw-sql`) und die erzeugte `.kumiko-raw-sql-baseline.json` committen."
+  },
   {
     "version": "0.339.0",
     "type": "fix",

package/src/cli.ts

@@ -29,6 +29,9 @@ function printHelp(): void {
   for (const sub of SUBCOMMANDS) {
     const flags = SUBCOMMAND_FLAGS[sub];
     console.log(`  ${sub}${flags.length > 0 ? ` [${flags.join("|")}]` : ""}`);
+    if (flags.includes("--write-baseline")) {
+      console.log(`    --write-baseline needs --guard=<name> (freezes one guard's baseline)`);
+    }
   }
 }
 

package/src/guard-no-direct-fs.ts

@@ -19,17 +19,29 @@
  * one repo cannot silently free node:fs in another under the same relative
  * path.
  *
+ * Repo-local exception for a justified import (tooling, build-time reads):
+ *   // kumiko-lint-ignore direct-fs <reason>
+ * on the import line or the line directly above. A bare tag without a reason
+ * does not count. The marker suppresses only while its `<file>::<reason>` pair
+ * is frozen in `.kumiko-direct-fs-baseline.json` at the repo root — fail-closed:
+ * no file, an unreadable file, a changed reason or more markers than frozen
+ * all make the guard fail. Freeze with:
+ *   kumiko-guards guards --write-baseline --guard="No-Direct-Fs Guard"
+ *
  * Usage:
  *   bun guards/guard-no-direct-fs.ts
  *
  * Exit 1 on violations in non-allowlisted files, 0 when clean.
  */
 
-import { relative as pathRelative } from "node:path";
+import { existsSync } from "node:fs";
+import { join, relative as pathRelative } from "node:path";
 import { Node, type SourceFile, SyntaxKind } from "ts-morph";
 import {
   type AstGuard,
+  baselineRatchet,
   findRepoRootFor,
+  type GuardViolation,
   relFromRepoRoot,
   runStandalone,
   type ScanSpec,
@@ -86,8 +98,10 @@ const ALLOWLIST: readonly AllowEntry[] = [
   },
 
   // server-runtime: prod bundle build + static asset delivery from the
-  // build output (no user-controlled path).
+  // build output (no user-controlled path). bundled-assets.ts reads declared
+  // read-only assets, name-pattern + containment checked.
   { repo: "kumiko-framework", pattern: /^packages\/server-runtime\/src\/build-prod-bundle\.ts$/ },
+  { repo: "kumiko-framework", pattern: /^packages\/server-runtime\/src\/bundled-assets\.ts$/ },
   {
     repo: "kumiko-framework",
     pattern: /^packages\/server-runtime\/src\/run-prod-app-static-files\.ts$/,
@@ -110,12 +124,6 @@ const ALLOWLIST: readonly AllowEntry[] = [
   // walk from cwd, no user input as a path.
   { repo: "kumiko-enterprise", pattern: /^packages\/ai-foundation\/src\/prompt\/corpus\.ts$/ },
 
-  // App repos: marketing landing-page renderer, iterates over a fixed
-  // language enum (LANGS/SUPPORTED_LANGS) — no user input in the path.
-  // repo:"*" — same relative path is intentional across flat-layout apps.
-  { repo: "*", pattern: /(^|\/)src\/marketing\/render-landing\.ts$/ },
-  { repo: "*", pattern: /(^|\/)src\/marketing\/rebuild-pages-job\.ts$/ },
-
   // kumiko-enterprise publish pipeline: materialize.ts is the guarded
   // place (writeMaterializedTree — resolve()+startsWith(root+sep) check,
   // same pattern as local-provider.ts). build.ts/feature.ts/validate.ts
@@ -153,6 +161,100 @@ interface Violation {
   moduleSpecifier: string;
 }
 
+const BASELINE_FILE = ".kumiko-direct-fs-baseline.json";
+// Must sit in a // comment, so a string literal describing the marker does not suppress.
+const MARKER_WITH_REASON_RE = /(^|\s)\/\/\s*kumiko-lint-ignore direct-fs\s+(\S.*)$/;
+
+const MARKER_REMEDIATION =
+  "New, reworded or unfrozen direct-fs marker. Prefer FileStorageProvider or readBundledAsset; " +
+  'otherwise freeze the exception with `kumiko-guards guards --write-baseline --guard="No-Direct-Fs Guard"` ' +
+  "so the baseline diff shows up in review.";
+
+type RootMarkers = {
+  readonly root: RepoRoot;
+  /** `<file>::<reason>` -> distinct marker lines (1-based). */
+  readonly linesByKey: Map<string, Set<number>>;
+};
+
+function ratchetFor(root: RepoRoot) {
+  return baselineRatchet({
+    file: join(root.absPath, BASELINE_FILE),
+    formatVersion: 1,
+    unit: "direct-fs marker(s)",
+    failClosed: true,
+  });
+}
+
+function markerFor(
+  lines: readonly string[],
+  importLine: number,
+): { readonly reason: string; readonly line: number } | undefined {
+  const sameLine = MARKER_WITH_REASON_RE.exec(lines[importLine - 1] ?? "")?.[2];
+  if (sameLine !== undefined) return { reason: sameLine.trim(), line: importLine };
+  const above = MARKER_WITH_REASON_RE.exec(lines[importLine - 2] ?? "")?.[2];
+  return above === undefined ? undefined : { reason: above.trim(), line: importLine - 1 };
+}
+
+function countsOf(markers: RootMarkers): Record<string, number> {
+  return Object.fromEntries([...markers.linesByKey].map(([key, lines]) => [key, lines.size]));
+}
+
+function collect(
+  files: readonly SourceFile[],
+  roots: readonly RepoRoot[],
+): { readonly unsuppressed: GuardViolation[]; readonly markers: Map<string, RootMarkers> } {
+  const unsuppressed: GuardViolation[] = [];
+  const markers = new Map<string, RootMarkers>();
+
+  for (const sf of files) {
+    const file = sf.getFilePath();
+    const rel = relFromRepoRoot(file, roots);
+    if (EXCLUDE.test(rel)) continue;
+    const root = findRepoRootFor(file, roots);
+    if (isRepoAllowlisted(root?.name, rel)) continue;
+    const lines = sf.getFullText().split("\n");
+    for (const v of findDirectFsImports(sf)) {
+      const marker = root === undefined ? undefined : markerFor(lines, v.line);
+      if (root !== undefined && marker !== undefined) {
+        const entry = markers.get(root.absPath) ?? { root, linesByKey: new Map() };
+        const key = `${rel}::${marker.reason}`;
+        const set = entry.linesByKey.get(key) ?? new Set<number>();
+        set.add(marker.line);
+        entry.linesByKey.set(key, set);
+        markers.set(root.absPath, entry);
+        continue;
+      }
+      unsuppressed.push({
+        // cwd-relative, not repo-relative `rel` — the security baseline
+        // needs an unambiguous path to resolve back to (repo, relPath).
+        file: pathRelative(process.cwd(), file),
+        line: v.line,
+        message: `[${v.moduleSpecifier}] direct fs import outside allowlist`,
+      });
+    }
+  }
+  return { unsuppressed, markers };
+}
+
+function markerViolations(markers: ReadonlyMap<string, RootMarkers>): GuardViolation[] {
+  return [...markers.values()].flatMap((m) =>
+    ratchetFor(m.root)
+      .check(countsOf(m), MARKER_REMEDIATION, {
+        resolveLine: (key) => [...(m.linesByKey.get(key) ?? [])].sort((a, b) => a - b)[0] ?? 1,
+      })
+      .map((v) => {
+        const [relFile] = v.file.split("::");
+        const isMarkerKey = v.file.includes("::") && relFile !== undefined;
+        return {
+          ...v,
+          file: isMarkerKey ? pathRelative(process.cwd(), join(m.root.absPath, relFile)) : v.file,
+          // A frozen security baseline must never excuse an unfrozen marker.
+          neverFrozen: true,
+        };
+      }),
+  );
+}
+
 function findDynamicFsRequires(sf: SourceFile): Violation[] {
   const violations: Violation[] = [];
 
@@ -208,28 +310,20 @@ export const guard: AstGuard = {
   name: "No-Direct-Fs Guard",
   scan: SCAN,
   security: true,
-  hint: "Direct node:fs import outside the allowlist — use FileStorageProvider (packages/framework/src/files/) instead of wiring fs yourself. The path-traversal guard (resolveContainedPath) only exists there. Legitimate new tooling caller? Extend the allowlist in guard-no-direct-fs.ts, with a reason + repo scope.",
+  hint: 'Direct node:fs import outside the allowlist — use FileStorageProvider (packages/framework/src/files/) instead of wiring fs yourself; the path-traversal guard (resolveContainedPath) only exists there. Read-only files your own build ships: declare them under package.json `kumiko.assets` and use readBundledAsset(name) from @cosmicdrift/kumiko-server-runtime. Legitimate tooling exception: mark the import with `// kumiko-lint-ignore direct-fs <reason>` and freeze it with `kumiko-guards guards --write-baseline --guard="No-Direct-Fs Guard"` (.kumiko-direct-fs-baseline.json, reviewed as a diff).',
   run(files, roots: readonly RepoRoot[] = resolveRepoRoots()) {
-    const violations: Array<{ file: string; line: number; message: string }> = [];
-
-    for (const sf of files) {
-      const file = sf.getFilePath();
-      const rel = relFromRepoRoot(file, roots);
-      if (EXCLUDE.test(rel)) continue;
-      const root = findRepoRootFor(file, roots);
-      if (isRepoAllowlisted(root?.name, rel)) continue;
-      for (const v of findDirectFsImports(sf)) {
-        violations.push({
-          // cwd-relative, not repo-relative `rel` — the security baseline
-          // needs an unambiguous path to resolve back to (repo, relPath).
-          file: pathRelative(process.cwd(), file),
-          line: v.line,
-          message: `[${v.moduleSpecifier}] direct fs import outside allowlist`,
-        });
+    const { unsuppressed, markers } = collect(files, roots);
+    return { violations: [...unsuppressed, ...markerViolations(markers)] };
+  },
+  writeBaseline(files, roots: readonly RepoRoot[] = resolveRepoRoots()) {
+    const { markers } = collect(files, roots);
+    for (const m of markers.values()) ratchetFor(m.root).write(countsOf(m));
+    // A repo whose last marker is gone keeps a stale baseline unless it is shrunk too.
+    for (const root of roots) {
+      if (!markers.has(root.absPath) && existsSync(join(root.absPath, BASELINE_FILE))) {
+        ratchetFor(root).write({});
       }
     }
-
-    return { violations };
   },
 };
 

package/src/guard-raw-sql.ts

@@ -9,10 +9,23 @@
  * should otherwise route SQL through `db/queries/*` or typed
  * `bun-db/query` helpers.
  *
- * Plan: kumiko-platform/docs/plans/architecture/intern/sql-queries-consolidation.md
+ * A marker only suppresses while its (file, reason) pair is frozen in
+ * `.kumiko-raw-sql-baseline.json` at the repo root, so every new or reworded
+ * marker shows up as a baseline diff in review. Without a baseline file the
+ * guard only warns (consumers do not break on bump). Freeze with:
+ *   bun packages/guards/src/guard-raw-sql.ts --write-baseline
+ *   (or `kumiko-guards checks --write-baseline --guard=guard-raw-sql`)
  */
 
-import { type RepoCheck, reportResults, runRepoChecks } from "./_lib/guard-kit";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import {
+  baselineRatchet,
+  type GuardViolation,
+  type RepoCheck,
+  reportResults,
+  runRepoChecks,
+} from "./_lib/guard-kit";
 import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
 import {
   BLOCKING_SQL_KINDS,
@@ -29,22 +42,54 @@ export type RawSqlFinding = {
   readonly snippet: string;
 };
 
+const BASELINE_FILE = ".kumiko-raw-sql-baseline.json";
+
+type RootMarkers = {
+  readonly root: RepoRoot;
+  /** `<file>::<reason>` → distinct marker lines (1-based, ascending). */
+  readonly linesByKey: ReadonlyMap<string, readonly number[]>;
+};
+
+function ratchetFor(root: RepoRoot) {
+  return baselineRatchet({
+    file: path.join(root.absPath, BASELINE_FILE),
+    formatVersion: 1,
+    unit: "raw-sql marker(s)",
+  });
+}
+
+function countsOf(markers: RootMarkers): Record<string, number> {
+  return Object.fromEntries([...markers.linesByKey].map(([key, lines]) => [key, lines.length]));
+}
+
 async function scanAllRepos(roots: readonly RepoRoot[]): Promise<{
   readonly findings: RawSqlFinding[];
+  readonly markers: RootMarkers[];
   readonly scannedFiles: number;
 }> {
   const findings: RawSqlFinding[] = [];
+  const markers: RootMarkers[] = [];
   let scannedFiles = 0;
 
   for (const root of roots) {
     const report = await scanRepo(root.absPath, sqlScanDirsFor(root));
     scannedFiles += report.scannedFiles;
+    const markerLines = new Map<string, Set<number>>();
 
     for (const hit of report.hits) {
       if (hit.allowed) continue;
-      if (hit.markerSuppressed) continue;
       if (hit.file.includes("/__tests__/")) continue;
       if (!(BLOCKING_SQL_KINDS as readonly string[]).includes(hit.kind)) continue;
+      if (hit.markerSuppressed) {
+        // One line like `asRawClient(db).unsafe(` yields two hits for one marker.
+        if (hit.markerReason !== undefined && hit.markerLine !== undefined) {
+          const key = `${hit.file}::${hit.markerReason}`;
+          const lines = markerLines.get(key) ?? new Set<number>();
+          lines.add(hit.markerLine);
+          markerLines.set(key, lines);
+        }
+        continue;
+      }
       findings.push({
         repo: root.name,
         file: hit.file,
@@ -53,9 +98,16 @@ async function scanAllRepos(roots: readonly RepoRoot[]): Promise<{
         snippet: hit.snippet,
       });
     }
+
+    markers.push({
+      root,
+      linesByKey: new Map(
+        [...markerLines].map(([key, lines]) => [key, [...lines].sort((x, y) => x - y)]),
+      ),
+    });
   }
 
-  return { findings, scannedFiles };
+  return { findings, markers, scannedFiles };
 }
 
 export async function collectRawSqlFindings(
@@ -64,11 +116,19 @@ export async function collectRawSqlFindings(
   return (await scanAllRepos(roots)).findings;
 }
 
+const MARKER_REMEDIATION =
+  "New or reworded raw-sql marker. Use a typed bun-db helper (selectMany, selectInnerJoin, " +
+  "insertOnConflictDoNothing, upsertOnConflict, aggregateWhere, where jsonText …) if one fits; " +
+  "otherwise freeze the exception with `kumiko-guards checks --write-baseline --guard=guard-raw-sql` " +
+  "so the baseline diff shows up in review.";
+
 export const check: RepoCheck = {
   name: "guard-raw-sql",
   hint:
     "Rule: runtime SQL only in db/queries/*, bun-db/query.ts, testing/*, or with " +
-    "// kumiko-lint-ignore raw-sql <reason> on the line or the line above.",
+    "// kumiko-lint-ignore raw-sql <reason> on the line or the line above — and that " +
+    "(file, reason) must be frozen in .kumiko-raw-sql-baseline.json " +
+    "(`kumiko-guards checks --write-baseline --guard=guard-raw-sql`).",
   async run(roots) {
     // Only the deliberate exclusion is skipped; a repo whose declared source roots
     // are all missing stays in the scan so 0 files surfaces as vacuous.
@@ -76,20 +136,41 @@ export const check: RepoCheck = {
     if (applicableRoots.length === 0) {
       return { violations: [], matchedFiles: 0, notApplicable: true };
     }
-    const { findings, scannedFiles } = await scanAllRepos(applicableRoots);
+    const { findings, markers, scannedFiles } = await scanAllRepos(applicableRoots);
+    // A root without markers and without a baseline has nothing to freeze, so it
+    // skips the ratchet's "no baseline found" warning instead of nagging every consumer.
+    const markerViolations: GuardViolation[] = markers
+      .filter((m) => m.linesByKey.size > 0 || existsSync(path.join(m.root.absPath, BASELINE_FILE)))
+      .flatMap((m) =>
+        ratchetFor(m.root).check(countsOf(m), MARKER_REMEDIATION, {
+          resolveLine: (key) => m.linesByKey.get(key)?.[0] ?? 1,
+        }),
+      );
     return {
-      violations: findings.map((f) => ({
-        file: f.file,
-        line: f.line,
-        message: `[${f.kind}] ${f.snippet}`,
-      })),
+      violations: [
+        ...findings.map((f) => ({
+          file: f.file,
+          line: f.line,
+          message: `[${f.kind}] ${f.snippet}`,
+        })),
+        ...markerViolations,
+      ],
       matchedFiles: scannedFiles,
       notApplicable: false,
     };
   },
+  async writeBaseline(roots) {
+    const applicableRoots = roots.filter((r) => !isSqlScanExcluded(r));
+    const { markers } = await scanAllRepos(applicableRoots);
+    for (const m of markers) ratchetFor(m.root).write(countsOf(m));
+  },
 };
 
 if (import.meta.main) {
+  if (process.argv.slice(2).includes("--write-baseline")) {
+    await check.writeBaseline?.(resolveRepoRoots());
+    process.exit(0);
+  }
   const failed = reportResults(await runRepoChecks([check]));
   process.exit(failed > 0 ? 1 : 0);
 }

package/src/run-guards.ts

@@ -160,7 +160,10 @@ export function runGuardsCli(argv: readonly string[], deps: RunGuardsCliDeps = {
       return 1;
     }
     const project = buildSharedProject([target], deps.writeBaselineRoots);
-    target.writeBaseline(filesForGuard(project, target, deps.writeBaselineRoots));
+    target.writeBaseline(
+      filesForGuard(project, target, deps.writeBaselineRoots),
+      deps.writeBaselineRoots,
+    );
     return 0;
   }
   const strictSecurityBaseline = flags.includes("--strict-security-baseline");

package/src/run-repo-checks.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 import { cliFlagsError, printGuardKitBanner, reportResults, runRepoChecks } from "./_lib/guard-kit";
+import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
 import { check as realProviderIsolation } from "./check-real-provider-isolation";
 // Standalone-`main()` guards ported as RepoCheck — run in-process, no
 // per-guard subprocess/project.
@@ -30,22 +31,55 @@ export const REPO_CHECKS = [
   singleRuntimeInstance,
 ];
 
-// No flags today — the array stays so an unknown flag still fails loud
-// instead of silently doing nothing, and so a future flag has one place to land.
-export const REPO_CHECK_FLAGS: readonly string[] = [];
+export const REPO_CHECK_FLAGS: readonly string[] = ["--write-baseline"];
+
+const GUARD_NAME_PREFIX = "--guard=";
 
 // Shared by the direct `bun run-repo-checks.ts` invocation below and by the
 // `checks` subcommand in cli.ts.
-export async function runRepoChecksCli(argv: readonly string[]): Promise<number> {
-  const flagsError = cliFlagsError("checks", argv, REPO_CHECK_FLAGS);
+export async function runRepoChecksCli(
+  argv: readonly string[],
+  roots?: readonly RepoRoot[],
+): Promise<number> {
+  const guardNameArg = argv.find((arg) => arg.startsWith(GUARD_NAME_PREFIX));
+  const flags = guardNameArg === undefined ? argv : argv.filter((arg) => arg !== guardNameArg);
+  const flagsError = cliFlagsError("checks", flags, REPO_CHECK_FLAGS);
   if (flagsError !== undefined) {
     console.error(flagsError);
     return 1;
   }
+  const writeBaseline = flags.includes("--write-baseline");
+  if (guardNameArg !== undefined && !writeBaseline) {
+    console.error("--guard=<name> is only valid with --write-baseline");
+    return 1;
+  }
+  if (writeBaseline) {
+    // Baselines freeze deliberately, one check at a time — never a refreeze-everything.
+    if (guardNameArg === undefined) {
+      console.error(
+        "--write-baseline needs --guard=<name>. Freeze a baseline only deliberately, one check at a time.",
+      );
+      return 1;
+    }
+    const checkName = guardNameArg.slice(GUARD_NAME_PREFIX.length);
+    const target = REPO_CHECKS.find((c) => c.name === checkName);
+    if (target === undefined) {
+      console.error(
+        `Unknown check "${checkName}". Known check names: ${REPO_CHECKS.map((c) => c.name).join(", ")}`,
+      );
+      return 1;
+    }
+    if (target.writeBaseline === undefined) {
+      console.error(`Check "${checkName}" has no ratchet baseline to write.`);
+      return 1;
+    }
+    await target.writeBaseline(roots ?? resolveRepoRoots());
+    return 0;
+  }
   // No shared ts-morph Project here — RepoCheck.run() does its own file
   // walk per check, so the banner omits the "Project: N files" line.
   printGuardKitBanner(REPO_CHECKS.length);
-  return reportResults(await runRepoChecks(REPO_CHECKS));
+  return reportResults(await runRepoChecks(REPO_CHECKS, roots));
 }
 
 if (import.meta.main) {