@cosmicdrift/kumiko-guards 0.383.0 → 0.384.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.383.0",
+  "version": "0.384.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>",
@@ -51,7 +51,7 @@
     "LICENSE"
   ],
   "peerDependencies": {
-    "@cosmicdrift/kumiko-framework": "0.383.0"
+    "@cosmicdrift/kumiko-framework": "0.384.0"
   },
   "peerDependenciesMeta": {
     "@cosmicdrift/kumiko-framework": {
@@ -59,6 +59,6 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-framework": "0.383.0"
+    "@cosmicdrift/kumiko-framework": "0.384.0"
   }
 }

package/src/changes.json

@@ -1,4 +1,32 @@
 [
+  {
+    "version": "0.384.0",
+    "type": "improvement",
+    "title": "Unsafe-Append-Event guard removed",
+    "detail": "The event store rejects unregistered event types and validates every payload against its schema at runtime, for appendEvent and unsafeAppendEvent alike, so the static guard is redundant.",
+    "migration": "Delete `.kumiko-unsafe-append-event-baseline.json`."
+  },
+  {
+    "version": "0.384.0",
+    "type": "improvement",
+    "title": "Access-Denied-Test guard replaced by a contract test helper",
+    "detail": "Roles are checked centrally before the payload is parsed. The new `expectRoleRestrictedHandlersDenyForeignRole` test helper proves this over HTTP for every role-restricted write and query handler, so the guard that searched for a matching test per handler is removed.",
+    "migration": "In an app integration test with setupTestStack and the app features, call `expectRoleRestrictedHandlersDenyForeignRole(stack)` and remove the \"Access-Denied-Test Guard\" entry from `.kumiko-security-baseline.json`."
+  },
+  {
+    "version": "0.384.0",
+    "type": "improvement",
+    "title": "i18n-Keys guard no longer checks locales",
+    "detail": "The guard only reports keys that are used without a definition. Locale completeness moved to the boot validator, which sees the real registered translations of every feature.",
+    "migration": "Delete `src/i18n-guard-locales.ts` if it exists."
+  },
+  {
+    "version": "0.384.0",
+    "type": "improvement",
+    "title": "PII-Annotations guard removed",
+    "detail": "Entity text and longText fields now have to declare their personal stance by type and at boot, so the static guard that searched for unannotated fields is redundant.",
+    "migration": "Delete `.kumiko-pii-annotations-baseline.json`."
+  },
   {
     "version": "0.383.0",
     "type": "improvement",

package/src/check-runtime-isolation.ts

@@ -46,7 +46,7 @@
 // own production surface — see kumiko-framework#2337 for the one currently
 // frozen here). Exceptions are tracked via a per-repo baseline file
 // (`.kumiko-runtime-isolation-baseline.json`, same `baselineRatchet`
-// mechanism as check-complexity/guard-pii-annotations/etc.), not a
+// mechanism as check-complexity/etc.), not a
 // hardcoded list in this source file: a consumer repo can freeze or clear
 // its own findings the same way, with `--write-baseline`.
 //

package/src/guard-i18n-keys.ts

@@ -3,13 +3,13 @@
  * Guard: i18n keys must be defined before they are used.
  *
  * Scan: t() calls in app tsx, definitions from r.translations and i18n bundles.
- * Declarative screen/nav keys: validateBoot (runtime).
+ * Declarative screen/nav keys and per-feature locale completeness: validateBoot (runtime).
  *
  * Usage:
  *   bun guards/guard-i18n-keys.ts
  */
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import * as path from "node:path";
 import {
   type Node,
@@ -37,7 +37,6 @@ interface UsedKey {
 
 interface DefinedKey {
   fullKey: string;
-  locales: Set<string>;
   file: string;
   line: number;
 }
@@ -105,10 +104,10 @@ function findEnclosingFeatureName(node: Node): string | null {
   return null;
 }
 
-function extractKeysFromTranslationsObject(
-  obj: ObjectLiteralExpression,
-): Array<{ key: string; locales: Set<string>; line: number }> {
-  const out: Array<{ key: string; locales: Set<string>; line: number }> = [];
+type KeyEntry = { key: string; line: number };
+
+function extractKeysFromTranslationsObject(obj: ObjectLiteralExpression): KeyEntry[] {
+  const out: KeyEntry[] = [];
   for (const prop of obj.getProperties()) {
     if (!prop.isKind(SyntaxKind.PropertyAssignment)) continue;
     const nameNode = prop.getNameNode();
@@ -119,23 +118,13 @@ function extractKeysFromTranslationsObject(
       keyName = nameNode.getText();
     } else continue;
 
-    const initializer = prop.getInitializer();
-    if (!initializer?.isKind(SyntaxKind.ObjectLiteralExpression)) continue;
-    const locales = new Set<string>();
-    for (const localeProp of initializer.getProperties()) {
-      if (!localeProp.isKind(SyntaxKind.PropertyAssignment)) continue;
-      const localeName = localeProp.getNameNode();
-      if (localeName.isKind(SyntaxKind.StringLiteral)) locales.add(localeName.getLiteralText());
-      else if (localeName.isKind(SyntaxKind.Identifier)) locales.add(localeName.getText());
-    }
-    out.push({ key: keyName, locales, line: prop.getStartLineNumber() });
+    if (!prop.getInitializer()?.isKind(SyntaxKind.ObjectLiteralExpression)) continue;
+    out.push({ key: keyName, line: prop.getStartLineNumber() });
   }
   return out;
 }
 
-function extractLocaleFirstKeys(
-  obj: ObjectLiteralExpression,
-): Array<{ key: string; locales: Set<string>; line: number }> {
+function extractLocaleFirstKeys(obj: ObjectLiteralExpression): KeyEntry[] {
   const localeMaps = new Map<string, ObjectLiteralExpression>();
   for (const prop of obj.getProperties()) {
     if (!prop.isKind(SyntaxKind.PropertyAssignment)) continue;
@@ -158,45 +147,26 @@ function extractLocaleFirstKeys(
     }
   }
 
-  const out: Array<{ key: string; locales: Set<string>; line: number }> = [];
-  for (const key of keySet) {
-    const locales = new Set<string>();
-    for (const [locale, map] of localeMaps) {
-      const has = map.getProperties().some((prop) => {
-        if (!prop.isKind(SyntaxKind.PropertyAssignment)) return false;
-        const nameNode = prop.getNameNode();
-        return nameNode.isKind(SyntaxKind.StringLiteral) && nameNode.getLiteralText() === key;
-      });
-      if (has) locales.add(locale);
-    }
-    out.push({ key, locales, line: obj.getStartLineNumber() });
-  }
-  return out;
+  return [...keySet].map((key) => ({ key, line: obj.getStartLineNumber() }));
 }
 
-function pushDefined(
-  defined: DefinedKey[],
-  fullKey: string,
-  locales: Set<string>,
-  file: string,
-  line: number,
-): void {
-  defined.push({ fullKey, locales, file, line });
+function pushDefined(defined: DefinedKey[], fullKey: string, file: string, line: number): void {
+  defined.push({ fullKey, file, line });
 }
 
 function addDefinedEntries(
   defined: DefinedKey[],
-  entries: Array<{ key: string; locales: Set<string>; line: number }>,
+  entries: KeyEntry[],
   file: string,
   featureName: string | null,
 ): void {
   for (const entry of entries) {
     if (entry.key.includes(":")) {
-      pushDefined(defined, entry.key, entry.locales, file, entry.line);
+      pushDefined(defined, entry.key, file, entry.line);
       continue;
     }
     if (featureName) {
-      pushDefined(defined, `${featureName}:${entry.key}`, entry.locales, file, entry.line);
+      pushDefined(defined, `${featureName}:${entry.key}`, file, entry.line);
     }
   }
 }
@@ -255,9 +225,9 @@ function collectInlineKeysInitializer(
 ): void {
   if (initializer?.isKind(SyntaxKind.ObjectLiteralExpression)) {
     for (const entry of extractKeysFromTranslationsObject(initializer)) {
-      pushDefined(defined, `${featureName}:${entry.key}`, entry.locales, file, entry.line);
+      pushDefined(defined, `${featureName}:${entry.key}`, file, entry.line);
       if (entry.key.includes(":")) {
-        pushDefined(defined, entry.key, entry.locales, file, entry.line);
+        pushDefined(defined, entry.key, file, entry.line);
       }
     }
   } else if (initializer?.isKind(SyntaxKind.Identifier)) {
@@ -305,77 +275,6 @@ export function isFrameworkMonorepo(root: string): boolean {
   return existsSync(path.join(root, "packages/framework/package.json"));
 }
 
-/** Parse `export const NAME = [...]` locale literals. Returns null if absent;
- *  throws if the export exists but is not a static string-literal array
- *  (spread / alias / region-tag-only without literals) — silent de/en fallback
- *  would hide a real declaration (infra#602). */
-export function parseLocaleConstArray(source: string, constName: string): string[] | null {
-  const exportRe = new RegExp(`export\\s+const\\s+${constName}\\s*(?::[^=]+)?=\\s*([^;]+)`);
-  const match = source.match(exportRe);
-  if (!match?.[1]) return null;
-  const rhs = match[1].trim();
-  if (!rhs.startsWith("[")) {
-    throw new Error(
-      `i18n-keys: export const ${constName} is not a static array literal — refuse silent de/en fallback`,
-    );
-  }
-  if (rhs.includes("...")) {
-    throw new Error(
-      `i18n-keys: export const ${constName} uses array spreads — refuse partial/silent locale set`,
-    );
-  }
-  const locales = [...rhs.matchAll(/["']([a-z]{2}(?:-[A-Z]{2})?)["']/g)]
-    .map((m) => m[1])
-    .filter((l): l is string => l !== undefined);
-  if (locales.length === 0) {
-    throw new Error(
-      `i18n-keys: export const ${constName} = [...] has no string locale literals — refuse silent de/en fallback`,
-    );
-  }
-  return locales;
-}
-
-/** Resolve owning repo root from a guard-relative path (may be `../…`). */
-export function repoRootForRelFile(rel: string): string {
-  const abs = path.isAbsolute(rel) ? rel : path.resolve(ROOT, rel);
-  let curr = path.dirname(abs);
-  let fallback: string | undefined;
-  while (curr !== path.dirname(curr)) {
-    const base = path.basename(curr);
-    // Never treat worktree/parent markers as a repo root (infra#602).
-    if (base === ".." || base === ".wt") {
-      curr = path.dirname(curr);
-      continue;
-    }
-    if (existsSync(path.join(curr, "packages/framework/package.json"))) {
-      return curr;
-    }
-    if (existsSync(path.join(curr, "package.json"))) {
-      // Outermost package.json wins so nested packages/* resolve to the repo.
-      fallback = curr;
-    }
-    curr = path.dirname(curr);
-  }
-  return fallback ?? ROOT;
-}
-/** Repo-declared locales for translation completeness; empty set skips the check. */
-export function resolveExpectedLocales(root: string = ROOT): Set<string> {
-  if (isFrameworkMonorepo(root)) return new Set();
-
-  const declPaths: Array<{ rel: string; constName: string }> = [
-    { rel: "src/i18n-guard-locales.ts", constName: "I18N_GUARD_LOCALES" },
-    { rel: "src/marketing/locale-routes.ts", constName: "LOCALES" },
-  ];
-  for (const { rel, constName } of declPaths) {
-    const abs = path.join(root, rel);
-    if (!existsSync(abs)) continue;
-    const locales = parseLocaleConstArray(readFileSync(abs, "utf-8"), constName);
-    if (locales) return new Set(locales);
-    // parseLocaleConstArray throws on unreadable decls; null = no export.
-  }
-  return new Set(["de", "en"]);
-}
-
 // Published packages ship `dist` (compiled JS) only; workspace links also carry `src`.
 const INSTALLED_FRAMEWORK_SOURCES = [
   "kumiko-*/{src,dist}/**/*.{ts,tsx,js}",
@@ -424,8 +323,6 @@ export function collectInstalledFrameworkKeys(root: string = ROOT): Set<string>
 export type I18nKeysRunOptions = {
   /** Inject the framework keys of the installed packages — tests must not scan node_modules. */
   readonly installedFrameworkKeys?: () => ReadonlySet<string>;
-  /** Inject expected locales per owning root — tests must not rely on process.cwd(). */
-  readonly expectedLocalesForRoot?: (root: string) => Set<string>;
 };
 
 export function checkI18nKeys(
@@ -451,47 +348,19 @@ export function checkI18nKeys(
       ? new Set<string>()
       : (options.installedFrameworkKeys ?? collectInstalledFrameworkKeys)();
   const missing = undefinedInApp.filter((u) => !installedKeys.has(u.key));
-  const resolveLocales = options.expectedLocalesForRoot ?? resolveExpectedLocales;
-  const expectedByRoot = new Map<string, Set<string>>();
-  const expectedForFile = (rel: string): Set<string> => {
-    const root = repoRootForRelFile(rel);
-    let locales = expectedByRoot.get(root);
-    if (!locales) {
-      locales = resolveLocales(root);
-      expectedByRoot.set(root, locales);
-    }
-    return locales;
-  };
-
-  const localeViolations = definedKeys.flatMap((d) => {
-    const expectedLocales = expectedForFile(d.file);
-    const missingLocales = [...expectedLocales].filter((l) => !d.locales.has(l));
-    if (missingLocales.length === 0) return [];
-    return [
-      {
-        file: d.file,
-        line: d.line,
-        message: `Key "${d.fullKey}" is missing locale: ${missingLocales.join(", ")}`,
-      },
-    ];
-  });
-
   return {
-    violations: [
-      ...missing.map((m) => ({
-        file: m.file,
-        line: m.line,
-        message: `used key without a definition: "${m.key}"`,
-      })),
-      ...localeViolations,
-    ],
+    violations: missing.map((m) => ({
+      file: m.file,
+      line: m.line,
+      message: `used key without a definition: "${m.key}"`,
+    })),
   };
 }
 
 export const guard: AstGuard = {
   name: "i18n-Keys Guard",
   scan: SCAN,
-  hint: "Used i18n key without a definition, or missing locale — add the key/locale to the feature's translations map (locales from src/i18n-guard-locales.ts or src/marketing/locale-routes.ts).",
+  hint: "Used i18n key without a definition — add the key to the feature's translations map.",
   run(files) {
     return checkI18nKeys(files);
   },

package/src/guard-no-custom-primitives.ts

@@ -173,10 +173,9 @@ export const guard: AstGuard = {
 
 // Flags are read ONLY here, not in run() — the shared runner
 // (run-guards.ts/run-ui-guards.ts) runs every guard with the same argv, a
-// --write-baseline there must not silently rewrite the baseline (same
-// pattern as guard-pii-annotations.ts).
+// --write-baseline there must not silently rewrite the baseline.
 //
-// No --no-baseline: unlike guard-pii-annotations.ts this guard has a
+// No --no-baseline: this guard has a
 // second, non-baselined rule (PRIMITIVE_NAME) — a --no-baseline that
 // discards analyse()'s return and exits 0 would silence that too. Nobody
 // reads the flag (the shared runner only calls run()).

package/src/guard-tailwind-scan-surface.ts

@@ -22,7 +22,7 @@
  * compare WITH their modifier prefixes intact (`hover:mb-2` is its own
  * Tailwind candidate, distinct from `mb-2`).
  *
- * Baseline-regression guard like guard-pii-annotations.ts: pins the
+ * Baseline-regression guard: pins the
  * currently-known violation count per file. Reductions are allowed but
  * don't auto-update the baseline. Without a baseline file the guard stays
  * warning-only (bootstrap: run `--write-baseline` once).

package/src/run-guards.ts

@@ -23,7 +23,6 @@ import { writeSecurityBaselines } from "./_lib/security-baseline-cli";
 import { guard as asCasts } from "./check-as-casts";
 import { guard as complexity } from "./check-complexity";
 import { guard as predicateExtraction } from "./check-predicates";
-import { guard as accessDeniedTest } from "./guard-access-denied-test";
 import { guard as adminApi } from "./guard-admin-api";
 import { guard as appFeatureStructure } from "./guard-app-feature-structure";
 import { guard as crossFeatureImports } from "./guard-cross-feature-imports";
@@ -42,19 +41,16 @@ import { guard as noDateApi } from "./guard-no-date-api";
 import { guard as noDirectFs } from "./guard-no-direct-fs";
 import { guard as noLogicInViews } from "./guard-no-logic-in-views";
 import { guard as noTemporalPolyfillImport } from "./guard-no-temporal-polyfill-import";
-import { guard as piiAnnotations } from "./guard-pii-annotations";
 import { guard as restrictedSymbols } from "./guard-restricted-symbols";
 import { guard as screenConventions } from "./guard-screen-conventions";
 import { guard as silentSkip } from "./guard-silent-skip";
 import { guard as tenantEscalation } from "./guard-tenant-escalation";
 import { guard as testTemplateDrift } from "./guard-test-template-drift";
 import { guard as testTimeouts } from "./guard-test-timeouts";
-import { guard as unsafeAppendEvent } from "./guard-unsafe-append-event";
 import { guard as unsafeJsonParse } from "./guard-unsafe-json-parse";
 import { guard as writeHandlerQns } from "./guard-write-handler-qns";
 
 export const GUARDS = [
-  accessDeniedTest,
   adminApi,
   directEntityWrites,
   directFetch,
@@ -74,7 +70,6 @@ export const GUARDS = [
   i18nKeys,
   i18nLocaleMount,
   i18nLocaleTerminology,
-  piiAnnotations,
   complexity,
   predicateExtraction,
   screenConventions,
@@ -85,7 +80,6 @@ export const GUARDS = [
   libTestCoverage,
   testTimeouts,
   testTemplateDrift,
-  unsafeAppendEvent,
 ];
 
 export const GUARD_FLAGS = [

package/src/guard-access-denied-test.ts

@@ -1,167 +0,0 @@
-#!/usr/bin/env bun
-/**
- * Guard: role-restricted write handlers need an access-denied test.
- *
- * Rule: any `defineWriteHandler`/`*.writeHandler` call whose `access` object
- * has a `roles` property (and no `openToAll`, and no anonymous/all role) must
- * have a test somewhere in the repo that mentions the handler AND asserts a
- * rejection (AccessDeniedError / access_denied / 403). Matching is file-level
- * and within the handler's own repo, same contract as guard-tenant-escalation.
- *
- * Tripwire: a false-negative (a weak name match hiding a real gap) is
- * tolerated; a false-positive on a clean repo is not.
- *
- * Usage:
- *   bun guards/guard-access-denied-test.ts
- *   Baseline: kumiko-guards guards --write-security-baseline
- */
-
-import * as path from "node:path";
-import {
-  type CallExpression,
-  type ObjectLiteralExpression,
-  type SourceFile,
-  SyntaxKind,
-} from "ts-morph";
-import { findRepoRootFor } from "./_lib/baseline-compare";
-import {
-  ALL_REPO_KINDS,
-  type AstGuard,
-  type GuardViolation,
-  runStandalone,
-  type ScanSpec,
-} from "./_lib/guard-kit";
-import {
-  escapeRegExp,
-  literalStringOf,
-  mentionsAsWord,
-  nameForms,
-} from "./_lib/handler-name-forms";
-import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
-import { TEST_FILE_RE } from "./_lib/test-file";
-
-const ROOT = process.cwd();
-const SCAN: ScanSpec = {
-  kinds: ALL_REPO_KINDS,
-  scope: "source+tests",
-  extensions: ["ts"],
-  frameworkWithin: ["packages/*/src/**", "samples/**"],
-};
-
-// Any role that lets an unauthenticated/unrestricted caller through means
-// nobody is actually excluded by this handler's roles.
-const OPEN_ROLE_RE = /["'`](?:anonymous|all)["'`]|\baccess\.(?:all|anonymous)\b/;
-
-type RoleRestrictedHandler = { name: string; file: string; line: number };
-
-function writeHandlerOptions(call: CallExpression): ObjectLiteralExpression | undefined {
-  const callee = call.getExpression().getText();
-  if (callee !== "defineWriteHandler" && !/\.writeHandler$/.test(callee)) return undefined;
-  const arg = call.getArguments()[0];
-  if (!arg || arg.getKind() !== SyntaxKind.ObjectLiteralExpression) return undefined;
-  return arg.asKindOrThrow(SyntaxKind.ObjectLiteralExpression);
-}
-
-function accessObjectOf(obj: ObjectLiteralExpression): ObjectLiteralExpression | undefined {
-  const accessProp = obj.getProperty("access");
-  if (!accessProp || accessProp.getKind() !== SyntaxKind.PropertyAssignment) return undefined;
-  const accessInit = accessProp.asKindOrThrow(SyntaxKind.PropertyAssignment).getInitializer();
-  if (!accessInit || accessInit.getKind() !== SyntaxKind.ObjectLiteralExpression) return undefined;
-  return accessInit.asKindOrThrow(SyntaxKind.ObjectLiteralExpression);
-}
-
-function restrictsToRoles(accessObj: ObjectLiteralExpression): boolean {
-  if (accessObj.getProperty("openToAll")) return false;
-  const rolesProp = accessObj.getProperty("roles");
-  if (!rolesProp) return false;
-  if (
-    rolesProp.getKind() !== SyntaxKind.PropertyAssignment &&
-    rolesProp.getKind() !== SyntaxKind.ShorthandPropertyAssignment
-  )
-    return false;
-  return !OPEN_ROLE_RE.test(rolesProp.getText());
-}
-
-function roleRestrictedHandlerOf(
-  call: CallExpression,
-  filePath: string,
-): RoleRestrictedHandler | undefined {
-  const obj = writeHandlerOptions(call);
-  if (!obj) return undefined;
-  const name = literalStringOf(obj.getProperty("name"));
-  if (!name) return undefined;
-  const accessObj = accessObjectOf(obj);
-  if (!accessObj || !restrictsToRoles(accessObj)) return undefined;
-  return { name, file: filePath, line: call.getStartLineNumber() };
-}
-
-export function findRoleRestrictedWriteHandlers(
-  files: readonly SourceFile[],
-): RoleRestrictedHandler[] {
-  const out: RoleRestrictedHandler[] = [];
-  for (const sf of files) {
-    if (TEST_FILE_RE.test(sf.getFilePath())) continue;
-    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
-      const handler = roleRestrictedHandlerOf(call, sf.getFilePath());
-      if (handler) out.push(handler);
-    }
-  }
-  return out;
-}
-
-const ACCESS_DENIED_ASSERTION = /\bAccessDeniedError\b|\baccess_denied\b|\b403\b/;
-
-const SHORT_WORD = /^[a-z0-9]+$/;
-
-// A single lowercase word ("create", "approve") is common enough in
-// unrelated test scaffolding (createTestStack, approveAll) that a bare word-
-// boundary match is too loose — only count it as a string-literal end
-// ("approve"/"feat:write:approve") or a property access (Handlers.approve).
-export function testMentionsHandler(text: string, handlerName: string): boolean {
-  return nameForms(handlerName).some((form) => {
-    if (!SHORT_WORD.test(form)) return mentionsAsWord(text, form);
-    const esc = escapeRegExp(form);
-    return new RegExp(`[:"'\`]${esc}["'\`]|\\.${esc}\\b`).test(text);
-  });
-}
-
-export function findHandlersWithoutAccessDeniedTest(
-  files: readonly SourceFile[],
-  roots: readonly { readonly absPath: string }[] = [],
-): RoleRestrictedHandler[] {
-  const repoKeyOf = (filePath: string): string => findRepoRootFor(filePath, roots)?.absPath ?? "";
-  const testTextsByRepo = new Map<string, string[]>();
-  for (const sf of files) {
-    if (!TEST_FILE_RE.test(sf.getFilePath())) continue;
-    const text = sf.getFullText();
-    if (!ACCESS_DENIED_ASSERTION.test(text)) continue;
-    const repoKey = repoKeyOf(sf.getFilePath());
-    const texts = testTextsByRepo.get(repoKey) ?? [];
-    texts.push(text);
-    testTextsByRepo.set(repoKey, texts);
-  }
-  return findRoleRestrictedWriteHandlers(files).filter((h) => {
-    const testTexts = testTextsByRepo.get(repoKeyOf(h.file)) ?? [];
-    return !testTexts.some((text) => testMentionsHandler(text, h.name));
-  });
-}
-
-export const guard: AstGuard = {
-  name: "Access-Denied-Test Guard",
-  scan: SCAN,
-  security: true,
-  hint: "Role-restricted write handlers need a test that references the handler and asserts a caller without the role is rejected (AccessDeniedError / access_denied / 403). Existing gaps are frozen in the security baseline; after closing one: `kumiko-guards guards --write-security-baseline`.",
-  run(files, roots: readonly RepoRoot[] = resolveRepoRoots()) {
-    // consumer CI scans only its own repo, so a sibling repo's test must not count as coverage
-    const violations: GuardViolation[] = findHandlersWithoutAccessDeniedTest(files, roots).map(
-      (h) => ({
-        file: path.relative(ROOT, h.file),
-        line: h.line,
-        message: `role-restricted write handler "${h.name}" has no access-denied test — add a test that references the handler and asserts a caller without the role is rejected (AccessDeniedError / access_denied / 403).`,
-      }),
-    );
-    return { violations };
-  },
-};
-
-if (import.meta.main) runStandalone(guard);

package/src/guard-pii-annotations.ts

@@ -1,279 +0,0 @@
-#!/usr/bin/env bun
-/**
- * Guard: PII-typical entity field names without annotation, with a baseline
- * regression guard like check-complexity.ts.
- *
- * Mirrors the boot heuristic from validatePiiAndRetention. Authors mark
- * fields with { pii: true }, { userOwned }, { tenantOwned: true },
- * { allowPlaintext: "reason" } (legacy) or { personal: ... } (0.210.0
- * successor to the four legacy subject annotations).
- *
- * `.kumiko-pii-annotations-baseline.json` in the repo root pins the frozen
- * finding count per file:
- *   - current <= baseline per file: PASS
- *   - current >  baseline per file: FAIL (new unannotated PII field)
- * Reductions do NOT update the baseline automatically — run `--write-baseline`
- * after annotation commits. Without a baseline file the guard stays
- * warning-only (bootstrap: run `--write-baseline` once).
- *
- * Usage:
- *   bun guards/guard-pii-annotations.ts                  # compare against baseline
- *   bun guards/guard-pii-annotations.ts --write-baseline # rewrite baseline
- *   bun guards/guard-pii-annotations.ts --no-baseline    # skip comparison
- */
-import * as path from "node:path";
-import {
-  type CallExpression,
-  type Node,
-  type ObjectLiteralExpression,
-  type SourceFile,
-  SyntaxKind,
-} from "ts-morph";
-import {
-  type AstGuard,
-  baselineRatchet,
-  buildSharedProject,
-  filesForGuard,
-  type GuardOutcome,
-  type GuardViolation,
-  isLocalFinding,
-  relFromRepoRoot,
-  runStandalone,
-  type ScanSpec,
-} from "./_lib/guard-kit";
-import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
-
-const ROOT = process.cwd();
-
-const SCAN: ScanSpec = {
-  scope: "source",
-  extensions: ["ts"],
-  frameworkWithin: ["packages/*/src/**"],
-};
-const EXCLUDE = /(__tests__|\.test\.tsx?$|\.integration\.tsx?$|\.d\.ts$)/;
-
-// Keep in sync with boot-validator/entity-handler.ts PII_*_NAME_HINTS.
-const PII_DIRECT_NAME_HINTS = new Set([
-  "email",
-  "phone",
-  "phonenumber",
-  "mobile",
-  "address",
-  "street",
-  "postalcode",
-  "zipcode",
-  "zip",
-  "city",
-  "displayname",
-  "firstname",
-  "lastname",
-  "fullname",
-  "birthday",
-  "birthdate",
-  "dateofbirth",
-  "dob",
-  "ssn",
-  "taxid",
-  "vatid",
-  "passport",
-  "iban",
-  "bic",
-]);
-
-const PII_USER_OWNED_NAME_HINTS = new Set([
-  "body",
-  "text",
-  "content",
-  "message",
-  "comment",
-  "description",
-  "note",
-  "notes",
-]);
-
-function relFile(sf: SourceFile, roots: readonly RepoRoot[]): string {
-  return relFromRepoRoot(sf.getFilePath(), roots);
-}
-
-function fieldFactoryOptions(call: CallExpression): ObjectLiteralExpression | undefined {
-  const first = call.getArguments()[0];
-  return first?.isKind(SyntaxKind.ObjectLiteralExpression) ? first : undefined;
-}
-
-// Subject annotations answering "is this PII" (kept in sync with the
-// author-facing PersonalAnnotations type, @cosmicdrift/kumiko-types
-// packages/types/src/fields.ts). `personal` (0.210.0) is the successor
-// to the four legacy fields below — every value counts as answered,
-// including `personal: false` (the framework requires a `reason` for
-// it). `find` is NOT a silencer: it resolves to lookupable/searchable/
-// sensitive, which never answered the PII question either. `encrypted`
-// isn't one either — the boot validator checks it only together with
-// `sensitive` (ciphertext-at-rest), never as a substitute.
-function isPiiSilencerAssignment(name: string, init: Node | undefined): boolean {
-  if (name === "personal") {
-    return (
-      init !== undefined &&
-      init.getKind() !== SyntaxKind.UndefinedKeyword &&
-      !(init.isKind(SyntaxKind.Identifier) && init.getText() === "undefined") &&
-      init.getKind() !== SyntaxKind.NullKeyword
-    );
-  }
-  if (name === "allowPlaintext") return init?.isKind(SyntaxKind.StringLiteral) ?? false;
-  if (name === "pii") return init?.getKind() === SyntaxKind.TrueKeyword;
-  if (name === "tenantOwned") return init?.getKind() === SyntaxKind.TrueKeyword;
-  if (name === "userOwned") return init?.isKind(SyntaxKind.ObjectLiteralExpression) ?? false;
-  return false;
-}
-
-function objectHasPiiSilencer(obj: ObjectLiteralExpression): boolean {
-  for (const prop of obj.getProperties()) {
-    if (!prop.isKind(SyntaxKind.PropertyAssignment)) continue;
-    if (isPiiSilencerAssignment(prop.getName(), prop.getInitializer())) return true;
-  }
-  return false;
-}
-
-function enclosingFieldName(call: CallExpression): string | null {
-  let node = call.getParent();
-  while (node) {
-    if (node.isKind(SyntaxKind.PropertyAssignment)) {
-      return node.getName();
-    }
-    node = node.getParent();
-  }
-  return null;
-}
-
-export interface Finding {
-  file: string;
-  line: number;
-  fieldName: string;
-  hint: string;
-}
-
-function scanFieldFactories(sf: SourceFile, roots: readonly RepoRoot[]): Finding[] {
-  const findings: Finding[] = [];
-  for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
-    const callee = call.getExpression().getText();
-    if (callee !== "createTextField" && callee !== "createLongTextField") continue;
-
-    const fieldName = enclosingFieldName(call);
-    if (!fieldName) continue;
-
-    const options = fieldFactoryOptions(call);
-    if (options && objectHasPiiSilencer(options)) continue;
-
-    const lower = fieldName.toLowerCase();
-    let hint: string | null = null;
-    if (PII_DIRECT_NAME_HINTS.has(lower)) {
-      hint = `{ personal: ... } or { pii: true } or { allowPlaintext: "is-business-data" }`;
-    } else if (PII_USER_OWNED_NAME_HINTS.has(lower)) {
-      hint = `{ personal: { of: "<authorIdField>" }, find: "exact" } or { userOwned: { ownerField: "<authorIdField>" } } or { allowPlaintext: "..." }`;
-    }
-    if (!hint) continue;
-
-    const line = call.getStartLineNumber();
-    const file = relFile(sf, roots);
-    findings.push({ file, line, fieldName, hint });
-  }
-  return findings;
-}
-
-export function scan(
-  files: readonly SourceFile[],
-  roots: readonly RepoRoot[] = resolveRepoRoots(),
-): {
-  findings: Finding[];
-  scanned: number;
-} {
-  const findings: Finding[] = [];
-  let scanned = 0;
-  for (const sf of files) {
-    if (EXCLUDE.test(sf.getFilePath())) continue;
-    scanned++;
-    findings.push(...scanFieldFactories(sf, roots));
-  }
-  return { findings, scanned };
-}
-
-function localFindings(findings: readonly Finding[]): readonly Finding[] {
-  return findings.filter(isLocalFinding);
-}
-
-function countByFile(findings: readonly Finding[]): Record<string, number> {
-  const counts: Record<string, number> = {};
-  for (const f of findings) counts[f.file] = (counts[f.file] ?? 0) + 1;
-  return counts;
-}
-
-const BASELINE_FILE = ".kumiko-pii-annotations-baseline.json";
-const piiBaseline = baselineRatchet({
-  file: path.join(ROOT, BASELINE_FILE),
-  formatVersion: 1,
-  unit: "PII finding(s)",
-});
-
-// One place for "what goes into the baseline", used by both the compare and
-// the write path — a sibling finding leaking into the written file would turn
-// a foreign checkout's code into a local, unfixable red.
-export function baselineCounts(findings: readonly Finding[]): Record<string, number> {
-  return countByFile(localFindings(findings));
-}
-
-function checkBaseline(findings: readonly Finding[]): GuardViolation[] {
-  const local = localFindings(findings);
-  const resolveLine = (file: string): number => local.find((f) => f.file === file)?.line ?? 1;
-  return piiBaseline.check(
-    baselineCounts(findings),
-    `Annotate the field ({ personal: ... } / { pii: true } / { userOwned: ... } / { tenantOwned: true } / { allowPlaintext: "..." }).`,
-    {
-      formatDriftRemediation: `Run \`kumiko-guards guards --write-baseline --guard="PII-Annotations Guard"\` once.`,
-      resolveLine,
-    },
-  );
-}
-
-function analyse(
-  files: readonly SourceFile[],
-  roots: readonly RepoRoot[],
-  compareBaseline: boolean,
-): GuardOutcome {
-  const { findings } = scan(files, roots);
-  if (!compareBaseline) {
-    for (const f of findings)
-      console.warn(
-        `  [pii-annotations WARN] ${f.file}:${f.line}  field "${f.fieldName}" looks like PII — mark ${f.hint}`,
-      );
-    console.log("  Baseline comparison skipped (--no-baseline).");
-    return { violations: [] };
-  }
-  return { violations: checkBaseline(findings) };
-}
-
-export const guard: AstGuard = {
-  name: "PII-Annotations Guard",
-  scan: SCAN,
-  hint: 'after a deliberate annotation: `kumiko-guards guards --write-baseline --guard="PII-Annotations Guard"`',
-  run: (files, roots = resolveRepoRoots()) => analyse(files, roots, true),
-  writeBaseline: (files) => piiBaseline.write(baselineCounts(scan(files).findings)),
-};
-
-// Flags are read ONLY here, not in run() — the shared runner
-// (run-guards.ts) drives all guards with the same argv, and a
-// --write-baseline there must not silently rewrite the
-// baseline.
-if (import.meta.main) {
-  const args = process.argv.slice(2);
-  if (args.includes("--write-baseline")) {
-    const project = buildSharedProject([guard]);
-    const { findings } = scan(filesForGuard(project, guard));
-    piiBaseline.write(baselineCounts(findings));
-    process.exit(0);
-  }
-  if (args.includes("--no-baseline")) {
-    const project = buildSharedProject([guard]);
-    analyse(filesForGuard(project, guard), resolveRepoRoots(), false);
-    process.exit(0);
-  }
-  runStandalone(guard);
-}

package/src/guard-unsafe-append-event.ts

@@ -1,125 +0,0 @@
-#!/usr/bin/env bun
-/**
- * Guard: reports `ctx.unsafeAppendEvent` (also `ctx["unsafeAppendEvent"]` and destructuring) outside `migrations/`, `upcasters/` and tests.
- *
- * `appendEvent` is the typed default, `tryAppendEvent` the optimistic variant. The untyped
- * `unsafeAppendEvent` skips payload typing and is meant for migrations and upcasters, where the
- * event type is not knowable at compile time.
- *
- * Existing call sites are frozen per file in `.kumiko-unsafe-append-event-baseline.json`; a count
- * over the baseline fails, at or under passes. Without the file (consumer repos) the guard only
- * warns.
- *
- * Usage:
- *   bun packages/guards/src/guard-unsafe-append-event.ts                  # compare to baseline
- *   bun packages/guards/src/guard-unsafe-append-event.ts --write-baseline # freeze current
- */
-
-import * as path from "node:path";
-
-import { Node, type SourceFile, SyntaxKind } from "ts-morph";
-import {
-  ALL_REPO_KINDS,
-  type AstGuard,
-  baselineRatchet,
-  buildSharedProject,
-  filesForGuard,
-  isLocalFinding,
-  relFromRepoRoot,
-  runStandalone,
-  type ScanSpec,
-} from "./_lib/guard-kit";
-import { resolveRepoRoots } from "./_lib/roots";
-
-const SCAN: ScanSpec = {
-  kinds: ALL_REPO_KINDS,
-  scope: "source",
-  extensions: ["ts"],
-  frameworkWithin: ["packages/*/src/**", "samples/**"],
-};
-
-const SYMBOL = "unsafeAppendEvent";
-const ALLOWED_PATH = /(^|\/)(migrations|upcasters|__tests__)\/|\.test\.ts$|\.d\.ts$/;
-
-function unsafeAppendEventLines(sf: SourceFile): number[] {
-  const propertyAccesses = sf
-    .getDescendantsOfKind(SyntaxKind.PropertyAccessExpression)
-    .filter((access) => access.getNameNode().getText() === SYMBOL);
-  const elementAccesses = sf
-    .getDescendantsOfKind(SyntaxKind.ElementAccessExpression)
-    .filter((access) => {
-      const argument = access.getArgumentExpression();
-      return (
-        argument !== undefined &&
-        (Node.isStringLiteral(argument) || Node.isNoSubstitutionTemplateLiteral(argument)) &&
-        argument.getLiteralText() === SYMBOL
-      );
-    });
-  const destructurings = sf
-    .getDescendantsOfKind(SyntaxKind.BindingElement)
-    .filter(
-      (element) => (element.getPropertyNameNode() ?? element.getNameNode()).getText() === SYMBOL,
-    );
-  return [...propertyAccesses, ...elementAccesses, ...destructurings].map((node) =>
-    node.getStartLineNumber(),
-  );
-}
-
-type Finding = { readonly file: string; readonly line: number };
-
-function scan(files: readonly SourceFile[], roots = resolveRepoRoots()): Finding[] {
-  const findings: Finding[] = [];
-  for (const sf of files) {
-    const file = relFromRepoRoot(sf.getFilePath(), roots);
-    if (ALLOWED_PATH.test(file)) continue;
-    for (const line of unsafeAppendEventLines(sf)) findings.push({ file, line });
-  }
-  return findings;
-}
-
-function countsPerFile(findings: readonly Finding[]): Record<string, number> {
-  const counts: Record<string, number> = {};
-  for (const f of findings.filter(isLocalFinding)) counts[f.file] = (counts[f.file] ?? 0) + 1;
-  return counts;
-}
-
-const GUARD_NAME = "Unsafe-Append-Event Guard";
-const DEFAULT_BASELINE_FILE = path.join(process.cwd(), ".kumiko-unsafe-append-event-baseline.json");
-
-const REMEDIATION =
-  "unsafeAppendEvent drops payload typing. Use ctx.appendEvent (default) or ctx.tryAppendEvent (conflict as result); the untyped variant belongs in migrations/ and upcasters/.";
-
-const REWRITE_COMMAND = `kumiko-guards guards --write-baseline --guard="${GUARD_NAME}"`;
-
-export function createUnsafeAppendEventGuard(baselineFile: string): AstGuard {
-  const baseline = baselineRatchet({
-    file: baselineFile,
-    formatVersion: 1,
-    unit: "unsafeAppendEvent call(s)",
-  });
-  return {
-    name: GUARD_NAME,
-    scan: SCAN,
-    hint: `${REMEDIATION} After a deliberate change: \`${REWRITE_COMMAND}\`.`,
-    run(files, roots = resolveRepoRoots()) {
-      const findings = scan(files, roots);
-      const violations = baseline.check(countsPerFile(findings), REMEDIATION, {
-        formatDriftRemediation: `Run \`${REWRITE_COMMAND}\` once.`,
-        resolveLine: (file) => findings.find((f) => f.file === file)?.line ?? 1,
-      });
-      return { violations };
-    },
-    writeBaseline: (files, roots) => baseline.write(countsPerFile(scan(files, roots))),
-  };
-}
-
-export const guard = createUnsafeAppendEventGuard(DEFAULT_BASELINE_FILE);
-
-if (import.meta.main) {
-  if (process.argv.slice(2).includes("--write-baseline")) {
-    const project = buildSharedProject([guard]);
-    guard.writeBaseline?.(filesForGuard(project, guard));
-    process.exit(0);
-  }
-  runStandalone(guard);
-}