@cosmicdrift/kumiko-framework 0.270.0 → 0.273.0

package/src/pipeline/system-identity-switch.ts

@@ -3,6 +3,8 @@ import { SYSTEM_ROLE, SYSTEM_USER_ID } from "../engine/system-user";
 import type {
   ActiveMembershipResult,
   EscapeHatchDeclaration,
+  EscapeHatchReporter,
+  HandlerContext,
   LifecycleHookFn,
   MemberReader,
   SessionUser,
@@ -17,7 +19,12 @@ export type ResolveActiveMembershipFn = (
   userId: string,
   tenantId: TenantId,
 ) => Promise<ActiveMembershipResult>;
+export type ProjectionReader = HandlerContext["queryProjection"];
 export type IdentitySwitch = { readonly queryAs: QueryAsFn; readonly writeAs: WriteAsFn };
+export type IdentitySwitchAudit = {
+  readonly reason: string | undefined;
+  readonly report: EscapeHatchReporter;
+};
 
 export function isSystemIdentity(user: SessionUser): boolean {
   return user.id === SYSTEM_USER_ID || user.roles.includes(SYSTEM_ROLE);
@@ -76,36 +83,69 @@ export function identitySwitchDenied(callerLabel: string, asUser: SessionUser):
   });
 }
 
+export function unsafeAllTenantsDenied(callerLabel: string): AccessDeniedError {
+  return new AccessDeniedError({
+    message:
+      `${callerLabel} may not call ctx.queryProjection(..., { unsafeAllTenants: true }) — declare ` +
+      "r.systemScope() or escapeHatch: { reason } on it",
+    details: { reason: FrameworkReasons.unsafeAllTenantsDenied },
+  });
+}
+
 type GatedIdentitySwitchSource = {
   readonly ungated: IdentitySwitch;
   readonly caller: SessionUser | undefined;
+  readonly report?: EscapeHatchReporter;
+};
+
+type MemberReaderAudit = IdentitySwitchAudit & { readonly tenantId: TenantId };
+
+type GatedMemberReaderSource = {
+  readonly ungated: MemberReader;
+  readonly audit?: MemberReaderAudit;
 };
 
 // Reverse-lookup so withHookEscapeHatchGrant can re-gate the SAME ungated pair (and caller) under a narrower grant.
 const sourceByGated = new WeakMap<QueryAsFn | WriteAsFn, GatedIdentitySwitchSource>();
 // Same idea, for ctx.queryAsMember — a single function rather than a pair.
-const ungatedMemberReaderByGated = new WeakMap<MemberReader, MemberReader>();
+const ungatedMemberReaderByGated = new WeakMap<MemberReader, GatedMemberReaderSource>();
+
+function reportGrantedSwitch(
+  caller: SessionUser | undefined,
+  asUser: SessionUser,
+  hasGrant: boolean,
+  audit: IdentitySwitchAudit | undefined,
+): void {
+  // skip: no audit wired, switch wasn't grant-gated, or grant carries no reason to report
+  if (!audit || !hasGrant || audit.reason === undefined) return;
+  // skip: caller switching to themselves isn't a privilege escalation worth auditing
+  if (caller !== undefined && isSelfDelegation(caller, asUser)) return;
+  audit.report("identity-switch", audit.reason, { id: asUser.id, tenantId: asUser.tenantId });
+}
 
 export function createGatedIdentitySwitch(
   callerLabel: string,
   caller: SessionUser | undefined,
   hasGrant: boolean,
   ungated: IdentitySwitch,
+  audit?: IdentitySwitchAudit,
 ): IdentitySwitch {
   const queryAs: QueryAsFn = async (asUser, qn, payload) => {
     if (!isIdentitySwitchAllowed(caller, asUser, hasGrant)) {
       throw identitySwitchDenied(callerLabel, asUser);
     }
+    reportGrantedSwitch(caller, asUser, hasGrant, audit);
     return ungated.queryAs(asUser, qn, payload);
   };
   const writeAs: WriteAsFn = async (asUser, qn, payload) => {
     if (!isIdentitySwitchAllowed(caller, asUser, hasGrant)) {
       throw identitySwitchDenied(callerLabel, asUser);
     }
+    reportGrantedSwitch(caller, asUser, hasGrant, audit);
     return ungated.writeAs(asUser, qn, payload);
   };
   const gated: IdentitySwitch = { queryAs, writeAs };
-  const source: GatedIdentitySwitchSource = { ungated, caller };
+  const source: GatedIdentitySwitchSource = { ungated, caller, report: audit?.report };
   sourceByGated.set(queryAs, source);
   sourceByGated.set(writeAs, source);
   return gated;
@@ -117,20 +157,56 @@ export function createGatedMemberReader(
   callerLabel: string,
   allowSystemIdentity: boolean,
   ungated: MemberReader,
+  audit?: MemberReaderAudit,
 ): MemberReader {
   const gated: MemberReader = async (userId, qn, payload) => {
     if (!allowSystemIdentity) throw systemIdentitySwitchDenied(callerLabel);
+    if (audit?.reason !== undefined) {
+      audit.report("identity-switch", audit.reason, { id: userId, tenantId: audit.tenantId });
+    }
     return ungated(userId, qn, payload);
   };
-  ungatedMemberReaderByGated.set(gated, ungated);
+  ungatedMemberReaderByGated.set(gated, { ungated, audit });
+  return gated;
+}
+
+type GatedProjectionReaderSource = {
+  readonly ungated: ProjectionReader;
+  readonly report?: EscapeHatchReporter;
+};
+
+// Same idea, for ctx.queryProjection — a single function rather than a pair.
+const ungatedProjectionReaderByGated = new WeakMap<ProjectionReader, GatedProjectionReaderSource>();
+
+// ctx.queryProjection's gate: only { unsafeAllTenants: true } is grant-checked —
+// a plain call always passes through, tenant-scoped by the projection's own table.
+export function createGatedProjectionReader(
+  callerLabel: string,
+  hasGrant: boolean,
+  ungated: ProjectionReader,
+  audit?: IdentitySwitchAudit,
+): ProjectionReader {
+  const gated = async <T = Record<string, unknown>>(
+    qualifiedName: string,
+    options?: { readonly unsafeAllTenants?: boolean },
+  ): Promise<readonly T[]> => {
+    if (options?.unsafeAllTenants === true) {
+      if (!hasGrant) throw unsafeAllTenantsDenied(callerLabel);
+      if (audit?.reason !== undefined) {
+        audit.report("unsafe-all-tenants", audit.reason);
+      }
+    }
+    return ungated<T>(qualifiedName, options);
+  };
+  ungatedProjectionReaderByGated.set(gated, { ungated, report: audit?.report });
   return gated;
 }
 
 function readIdentitySwitchFn<
-  TFn extends QueryAsFn | WriteAsFn | ResolveActiveMembershipFn | MemberReader,
+  TFn extends QueryAsFn | WriteAsFn | ResolveActiveMembershipFn | MemberReader | ProjectionReader,
 >(
   context: object,
-  key: "queryAs" | "writeAs" | "resolveActiveMembership" | "queryAsMember",
+  key: "queryAs" | "writeAs" | "resolveActiveMembership" | "queryAsMember" | "queryProjection",
 ): TFn | undefined {
   if (!(key in context)) return undefined;
   const value = (context as Record<string, unknown>)[key];
@@ -195,7 +271,15 @@ function gatedIdentitySwitchFields(
   const ungatedWriteAs = ctxWriteAs && (writeSource?.ungated.writeAs ?? ctxWriteAs);
   const ungated = fallbackUngatedIdentitySwitch(callerLabel, ungatedQueryAs, ungatedWriteAs);
   const caller = resolveDispatcherCaller(querySource, writeSource);
-  const gated = createGatedIdentitySwitch(callerLabel, caller, escapeHatch !== undefined, ungated);
+  const report = (querySource ?? writeSource)?.report;
+  const audit = report ? { reason: escapeHatch?.reason, report } : undefined;
+  const gated = createGatedIdentitySwitch(
+    callerLabel,
+    caller,
+    escapeHatch !== undefined,
+    ungated,
+    audit,
+  );
   return {
     ...(ctxQueryAs && { queryAs: gated.queryAs }),
     ...(ctxWriteAs && { writeAs: gated.writeAs }),
@@ -210,9 +294,34 @@ function gatedMemberReaderField(
   ctxQueryAsMember: MemberReader | undefined,
 ): { queryAsMember?: MemberReader } {
   if (!ctxQueryAsMember) return {};
-  const ungated = ungatedMemberReaderByGated.get(ctxQueryAsMember) ?? ctxQueryAsMember;
+  const source = ungatedMemberReaderByGated.get(ctxQueryAsMember);
+  const ungated = source?.ungated ?? ctxQueryAsMember;
+  const audit = source?.audit
+    ? { reason: escapeHatch?.reason, report: source.audit.report, tenantId: source.audit.tenantId }
+    : undefined;
+  return {
+    queryAsMember: createGatedMemberReader(callerLabel, escapeHatch !== undefined, ungated, audit),
+  };
+}
+
+// Re-gates ctx.queryProjection under the hook's own escapeHatch, same
+// re-gating rule as the other fields below — see withHookEscapeHatchGrant.
+function gatedProjectionReaderField(
+  callerLabel: string,
+  escapeHatch: EscapeHatchDeclaration | undefined,
+  ctxQueryProjection: ProjectionReader | undefined,
+): { queryProjection?: ProjectionReader } {
+  if (!ctxQueryProjection) return {};
+  const source = ungatedProjectionReaderByGated.get(ctxQueryProjection);
+  const ungated = source?.ungated ?? ctxQueryProjection;
+  const audit = source?.report ? { reason: escapeHatch?.reason, report: source.report } : undefined;
   return {
-    queryAsMember: createGatedMemberReader(callerLabel, escapeHatch !== undefined, ungated),
+    queryProjection: createGatedProjectionReader(
+      callerLabel,
+      escapeHatch !== undefined,
+      ungated,
+      audit,
+    ),
   };
 }
 
@@ -228,6 +337,7 @@ export function withHookEscapeHatchGrant<TContext extends object>(
     "resolveActiveMembership",
   );
   const ctxQueryAsMember = readIdentitySwitchFn<MemberReader>(context, "queryAsMember");
+  const ctxQueryProjection = readIdentitySwitchFn<ProjectionReader>(context, "queryProjection");
   const ctxDb = readDbLikeValue(context, "db");
   const ctxDbOutsideTransaction = readDbLikeValue(context, "dbOutsideTransaction");
   if (
@@ -235,6 +345,7 @@ export function withHookEscapeHatchGrant<TContext extends object>(
     !ctxWriteAs &&
     !ctxResolveActiveMembership &&
     !ctxQueryAsMember &&
+    !ctxQueryProjection &&
     !ctxDb &&
     !ctxDbOutsideTransaction
   ) {
@@ -249,6 +360,7 @@ export function withHookEscapeHatchGrant<TContext extends object>(
         resolveActiveMembership: deniedResolveActiveMembership(callerLabel),
       }),
     ...gatedMemberReaderField(callerLabel, escapeHatch, ctxQueryAsMember),
+    ...gatedProjectionReaderField(callerLabel, escapeHatch, ctxQueryProjection),
     // @cast-boundary engine-bridge — withUnsafeRawGrant passes non-TenantDb values (e.g. a guard Proxy) through unchanged.
     ...(ctxDb && { db: withUnsafeRawGrant(ctxDb as TenantDb, escapeHatch) }),
     ...(ctxDbOutsideTransaction && {
@@ -257,7 +369,7 @@ export function withHookEscapeHatchGrant<TContext extends object>(
   };
 }
 
-// Re-gates a hook's own ctx.queryAs/ctx.writeAs/ctx.db/ctx.dbOutsideTransaction instead of inheriting the handler's grant.
+// Re-gates a hook's own ctx.queryAs/ctx.writeAs/ctx.queryProjection/ctx.db/ctx.dbOutsideTransaction instead of inheriting the handler's grant.
 export function bindHookEscapeHatchGrant(
   fn: LifecycleHookFn,
   label: string,

package/src/scripts/codemod/migrate-cross-tenant.ts

@@ -0,0 +1,335 @@
+#!/usr/bin/env bun
+// migrate-cross-tenant — rewrites `crossTenant: true` on entity-convention
+// handlers to `escapeHatch: { reason }` where the handler name and verb can
+// be derived from the call, and reports every other site for review (fw#2915).
+//
+// Usage:
+//   bun scripts/codemod/migrate-cross-tenant.ts [--dry-run] <path...>
+
+import { readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import {
+  type CallExpression,
+  Node,
+  type ObjectLiteralExpression,
+  Project,
+  type PropertyAssignment,
+  SyntaxKind,
+} from "ts-morph";
+
+export interface Rewrite {
+  readonly file: string;
+  readonly line: number;
+  readonly before: string;
+  readonly after: string;
+}
+
+export interface ManualSite {
+  readonly file: string;
+  readonly line: number;
+  readonly why: string;
+  readonly handlerName?: string;
+}
+
+export interface MigrateCrossTenantResult {
+  readonly output: string;
+  readonly rewrites: Rewrite[];
+  readonly manual: ManualSite[];
+}
+
+const VERB_IN_NAME_CALLEES: Record<string, string> = {
+  defineEntityCreateHandler: "create",
+  defineEntityUpdateHandler: "update",
+  defineEntityDeleteHandler: "delete",
+  defineEntityRestoreHandler: "restore",
+  defineEntityListHandler: "list",
+  defineEntityDetailHandler: "detail",
+};
+
+const VERB_IN_ARG_CALLEES = new Set(["defineEntityWriteHandler", "defineEntityQueryHandler"]);
+
+const READ_VERBS = new Set(["list", "detail"]);
+
+function isCrossTenantAssignment(node: Node): node is PropertyAssignment {
+  return Node.isPropertyAssignment(node) && node.getName() === "crossTenant";
+}
+
+function getCalleeName(call: CallExpression): string | undefined {
+  const expr = call.getExpression();
+  if (Node.isIdentifier(expr)) return expr.getText();
+  if (Node.isPropertyAccessExpression(expr)) return expr.getName();
+  return undefined;
+}
+
+function hasEscapeHatchProperty(obj: ObjectLiteralExpression): boolean {
+  return obj.getProperty("escapeHatch") !== undefined;
+}
+
+interface AutoRewriteTarget {
+  readonly handlerName: string;
+  readonly entityName: string;
+  readonly verb: string;
+}
+
+function deriveAutoRewriteTarget(
+  objectLiteral: ObjectLiteralExpression,
+): AutoRewriteTarget | undefined {
+  const call = objectLiteral.getParentIfKind(SyntaxKind.CallExpression);
+  if (!call) return undefined;
+  if (!call.getArguments().includes(objectLiteral)) return undefined;
+
+  const calleeName = getCalleeName(call);
+  if (!calleeName) return undefined;
+
+  const firstArg = call.getArguments()[0];
+  if (!firstArg || !Node.isStringLiteral(firstArg)) return undefined;
+  const firstArgValue = firstArg.getLiteralValue();
+
+  const verbFromName = VERB_IN_NAME_CALLEES[calleeName];
+  if (verbFromName) {
+    return {
+      handlerName: `${firstArgValue}:${verbFromName}`,
+      entityName: firstArgValue,
+      verb: verbFromName,
+    };
+  }
+
+  if (VERB_IN_ARG_CALLEES.has(calleeName)) {
+    const sep = firstArgValue.indexOf(":");
+    if (sep === -1) return undefined;
+    const entityName = firstArgValue.slice(0, sep);
+    const verb = firstArgValue.slice(sep + 1);
+    if (!entityName || !verb) return undefined;
+    return { handlerName: firstArgValue, entityName, verb };
+  }
+
+  return undefined;
+}
+
+function deriveEntityCrudContext(objectLiteral: ObjectLiteralExpression): string | undefined {
+  const verbGroupAssignment = objectLiteral.getParent();
+  if (!Node.isPropertyAssignment(verbGroupAssignment)) return undefined;
+  const verbGroup = verbGroupAssignment.getName();
+  if (verbGroup !== "write" && verbGroup !== "read") return undefined;
+
+  const optionsObject = verbGroupAssignment.getParentIfKind(SyntaxKind.ObjectLiteralExpression);
+  const call = optionsObject?.getParentIfKind(SyntaxKind.CallExpression);
+  if (!call || !optionsObject || !call.getArguments().includes(optionsObject)) return undefined;
+
+  const calleeName = getCalleeName(call);
+  if (calleeName !== "registerEntityCrud" && calleeName !== "crud") return undefined;
+
+  const args = call.getArguments();
+  const entityArg = calleeName === "crud" ? args[0] : args[1];
+  const entityName =
+    entityArg && Node.isStringLiteral(entityArg) ? entityArg.getLiteralValue() : undefined;
+  return `under ${calleeName}(${entityName ? `"${entityName}", ` : ""}...) → ${verbGroup}: multiple verbs share this crossTenant — set escapeHatch per verb manually, one reason each`;
+}
+
+function classifyManualReason(objectLiteral: ObjectLiteralExpression): string {
+  const entityCrudWhy = deriveEntityCrudContext(objectLiteral);
+  if (entityCrudWhy) return entityCrudWhy;
+
+  const call = objectLiteral.getParentIfKind(SyntaxKind.CallExpression);
+  if (!call?.getArguments().includes(objectLiteral)) {
+    return "crossTenant is not set directly in a handler call (e.g. a spread/shared object) — give each consuming handler its own escapeHatch reason";
+  }
+
+  const calleeName = getCalleeName(call);
+  if (!calleeName || (!VERB_IN_NAME_CALLEES[calleeName] && !VERB_IN_ARG_CALLEES.has(calleeName))) {
+    return `call \`${calleeName ?? "<unknown>"}\` is not a recognized entity-convention handler factory — add escapeHatch manually`;
+  }
+
+  return "handler name/verb could not be derived from the call's first argument — add escapeHatch manually";
+}
+
+function deriveBestEffortHandlerName(assignment: PropertyAssignment): string | undefined {
+  const call = assignment.getFirstAncestorByKind(SyntaxKind.CallExpression);
+  const firstArg = call?.getArguments()[0];
+  return firstArg && Node.isStringLiteral(firstArg) ? firstArg.getLiteralValue() : undefined;
+}
+
+function buildEscapeHatchReason(target: AutoRewriteTarget): string {
+  const verbKind = READ_VERBS.has(target.verb) ? "reads" : "writes";
+  return `${target.handlerName} ${verbKind} ${target.entityName} rows across every tenant (migrated from crossTenant: true; state the operator use case here)`;
+}
+
+export function migrateCrossTenantSource(
+  source: string,
+  fileName: string,
+): MigrateCrossTenantResult {
+  const project = new Project({ useInMemoryFileSystem: true, skipFileDependencyResolution: true });
+  const sourceFile = project.createSourceFile(fileName, source);
+
+  const targets = sourceFile
+    .getDescendantsOfKind(SyntaxKind.PropertyAssignment)
+    .filter(isCrossTenantAssignment);
+
+  const rewrites: Rewrite[] = [];
+  const manual: ManualSite[] = [];
+
+  for (const assignment of targets) {
+    if (assignment.wasForgotten()) continue;
+    const line = assignment.getStartLineNumber();
+    const init = assignment.getInitializer();
+
+    if (init?.getKind() === SyntaxKind.FalseKeyword) continue;
+
+    if (init?.getKind() !== SyntaxKind.TrueKeyword) {
+      manual.push({
+        file: fileName,
+        line,
+        why: `crossTenant is not a literal boolean (\`${init?.getText() ?? "<missing>"}\`) — replace manually with escapeHatch: { reason }`,
+        ...(deriveBestEffortHandlerName(assignment) !== undefined && {
+          handlerName: deriveBestEffortHandlerName(assignment),
+        }),
+      });
+      continue;
+    }
+
+    const objectLiteral = assignment.getParentIfKind(SyntaxKind.ObjectLiteralExpression);
+    if (!objectLiteral) continue;
+
+    if (hasEscapeHatchProperty(objectLiteral)) {
+      manual.push({
+        file: fileName,
+        line,
+        why: "this object already declares escapeHatch — merge the two manually and remove crossTenant",
+        ...(deriveBestEffortHandlerName(assignment) !== undefined && {
+          handlerName: deriveBestEffortHandlerName(assignment),
+        }),
+      });
+      continue;
+    }
+
+    const target = deriveAutoRewriteTarget(objectLiteral);
+    if (!target) {
+      manual.push({
+        file: fileName,
+        line,
+        why: classifyManualReason(objectLiteral),
+        ...(deriveBestEffortHandlerName(assignment) !== undefined && {
+          handlerName: deriveBestEffortHandlerName(assignment),
+        }),
+      });
+      continue;
+    }
+
+    const before = assignment.getText();
+    const after = `escapeHatch: { reason: ${JSON.stringify(buildEscapeHatchReason(target))} }`;
+    assignment.replaceWithText(after);
+    rewrites.push({ file: fileName, line, before, after });
+  }
+
+  return { output: sourceFile.getFullText(), rewrites, manual };
+}
+
+class CliError extends Error {}
+
+interface CliOptions {
+  readonly dryRun: boolean;
+  readonly paths: string[];
+}
+
+function parseArgs(argv: string[]): CliOptions {
+  let dryRun = false;
+  const paths: string[] = [];
+
+  for (const arg of argv) {
+    if (arg === "--dry-run") {
+      dryRun = true;
+      continue;
+    }
+    if (arg.startsWith("--")) throw new CliError(`unknown flag: ${arg}`);
+    paths.push(arg);
+  }
+
+  if (paths.length === 0) throw new CliError("at least one path is required");
+  return { dryRun, paths };
+}
+
+function isMigratableFile(name: string): boolean {
+  return /\.(ts|tsx)$/.test(name);
+}
+
+function walkDir(dir: string, out: string[]): void {
+  for (const name of readdirSync(dir)) {
+    if (name === "node_modules") continue;
+    const full = join(dir, name);
+    const stat = statSync(full);
+    if (stat.isDirectory()) {
+      walkDir(full, out);
+      continue;
+    }
+    if (isMigratableFile(name)) out.push(full);
+  }
+}
+
+function collectFiles(paths: string[]): string[] {
+  const files: string[] = [];
+  for (const p of paths) {
+    const abs = resolve(p);
+    const stat = statSync(abs);
+    if (stat.isDirectory()) walkDir(abs, files);
+    else if (isMigratableFile(abs)) files.push(abs);
+  }
+  return files;
+}
+
+async function main(): Promise<void> {
+  let options: CliOptions;
+  try {
+    options = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    if (err instanceof CliError) {
+      console.error(`[migrate-cross-tenant] ${err.message}`);
+      process.exit(2);
+    }
+    throw err;
+  }
+
+  const files = collectFiles(options.paths);
+  const allManual: ManualSite[] = [];
+  let filesChanged = 0;
+  let totalRewrites = 0;
+
+  for (const file of files) {
+    const before = readFileSync(file, "utf8");
+    if (!before.includes("crossTenant")) continue;
+    const result = migrateCrossTenantSource(before, file);
+    allManual.push(...result.manual);
+
+    if (result.rewrites.length === 0) continue;
+    filesChanged += 1;
+    totalRewrites += result.rewrites.length;
+
+    if (options.dryRun) {
+      console.log(`\n=== ${file} (${result.rewrites.length} rewrite(s)) ===`);
+      for (const r of result.rewrites) {
+        console.log(`${file}:${r.line}`);
+        console.log(`- ${r.before}`);
+        console.log(`+ ${r.after}`);
+      }
+    } else {
+      writeFileSync(file, result.output);
+    }
+  }
+
+  console.log(
+    `\n[migrate-cross-tenant] ${options.dryRun ? "would change" : "changed"} ${filesChanged} file(s); ` +
+      `rewrites: ${totalRewrites}`,
+  );
+
+  if (allManual.length > 0) {
+    console.log(`\n[migrate-cross-tenant] manual review needed (${allManual.length}):`);
+    for (const m of allManual) {
+      console.log(`${m.file}:${m.line}  ${m.handlerName ?? "<unknown>"}  ${m.why}`);
+    }
+  }
+
+  process.exit(0);
+}
+
+if (import.meta.main) {
+  await main();
+}

package/src/scripts/codemod/migrate-db-raw.ts

@@ -109,6 +109,15 @@ interface PendingRewrite {
   readonly line: number;
 }
 
+// The caller checks `args.length` immediately before every use — the index
+// is always in bounds; this replaces a non-null assertion with an explicit
+// invariant instead of silencing the compiler.
+function nthArg(args: Node[], index: number): Node {
+  const arg = args[index];
+  if (!arg) throw new Error(`planRewrite: expected an argument at index ${index}`);
+  return arg;
+}
+
 function planRewrite(
   callExpr: Node,
   globalTables: ReadonlySet<string>,
@@ -118,14 +127,14 @@ function planRewrite(
   if (!Node.isIdentifier(calleeExpr)) return undefined;
   const fnName = calleeExpr.getText();
   const args = callExpr.getArguments();
-  if (args.length === 0 || !isRawOnCtxDb(args[0]!)) return undefined;
+  if (args.length === 0 || !isRawOnCtxDb(nthArg(args, 0))) return undefined;
 
   const typeArgs = callExpr.getTypeArguments();
   const typeArgsText =
     typeArgs.length > 0 ? `<${typeArgs.map((t) => t.getText()).join(", ")}>` : "";
 
   if (GLOBAL_TABLE_FN_NAMES.has(fnName) && args.length >= 2) {
-    const tableArg = args[1]!;
+    const tableArg = nthArg(args, 1);
     if (Node.isIdentifier(tableArg) && globalTables.has(tableArg.getText())) {
       const rest = args.slice(2).map((a) => a.getText());
       const after = `ctx.db.global(${tableArg.getText()}).${fnName}${typeArgsText}(${rest.join(", ")})`;
@@ -140,9 +149,9 @@ function planRewrite(
   }
 
   if (OWN_TENANT_FN_NAMES.has(fnName) && args.length >= 3) {
-    const objArg = args[2]!;
+    const objArg = nthArg(args, 2);
     if (objectHasValidOwnTenantId(objArg)) {
-      const rest = [args[1]!, objArg, ...args.slice(3)].map((a) => a.getText());
+      const rest = [nthArg(args, 1), objArg, ...args.slice(3)].map((a) => a.getText());
       const after = `ctx.db.${fnName}${typeArgsText}(${rest.join(", ")})`;
       return {
         callExpr,
@@ -174,7 +183,10 @@ function isTenantDbRawAccess(pae: Node): boolean {
 function enclosingName(node: Node): string {
   let current: Node | undefined = node.getParent();
   while (current) {
-    if (Node.isFunctionDeclaration(current) && current.getName()) return current.getName()!;
+    if (Node.isFunctionDeclaration(current)) {
+      const name = current.getName();
+      if (name) return name;
+    }
     if (Node.isMethodDeclaration(current)) return current.getName();
     if (Node.isPropertyAssignment(current)) return current.getName();
     if (Node.isVariableDeclaration(current)) return current.getName();
@@ -283,7 +295,8 @@ function parseArgs(argv: string[]): CliOptions {
   const paths: string[] = [];
 
   for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i]!;
+    const arg = argv[i];
+    if (!arg) break;
     if (arg === "--dry-run") {
       dryRun = true;
       continue;

package/src/scripts/codemod/migrate-open-to-all.ts

@@ -140,7 +140,8 @@ function parseArgs(argv: string[]): CliOptions {
   const paths: string[] = [];
 
   for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i]!;
+    const arg = argv[i];
+    if (!arg) break;
     if (arg === "--dry-run") {
       dryRun = true;
       continue;

package/src/ui-types/index.ts

@@ -27,12 +27,14 @@ export type { ParsedRefTarget } from "../engine/parse-ref-target";
 export { parseRefTarget } from "../engine/parse-ref-target";
 export {
   evalFieldCondition,
+  explicitListScreenId,
   isExtensionEditSection,
   isFieldsEditSection,
   isFormatSpec,
   isWriteFormEditSection,
   normalizeEditField,
   normalizeListColumn,
+  resolveNavParentScreen,
 } from "../engine/screen-helpers";
 // Entity + field types. EntityDefinition is the canonical shape that
 // view-model builders iterate; FieldDefinition is the per-field union
@@ -99,6 +101,7 @@ export type {
   PlatformComponent,
   ProjectionDetailScreenDefinition,
   ProjectionListScreenDefinition,
+  RelatedListToolbarAction,
   RowAction,
   RowActionDrawer,
   RowActionNavigate,