bazis 0.136.0 → 0.138.0

package/README.md

@@ -142,7 +142,8 @@ import { dbConfig } from "../config/db.config"; // defineConfig("db", { default:
 export class AppInfra {}
 
 // src/index.ts
-await runApp(AppModule, { infra: AppInfra, http: { port: 3000, health: true } });
+@App({ modules: [AppModule], infra: AppInfra, http: { health: true } })
+export class Application {}
 ```
 
 A feature module attaches its own `DbContext` and entities with
@@ -180,11 +181,13 @@ import { CodexError, RU_CODEX_MESSAGES } from "bazis/core/infra";
 import { RU_UI_LABELS } from "bazis/core/app";
 
 CodexError.useMessages(RU_CODEX_MESSAGES); // Codex connector errors
-await runApp(AppModule, {
+@App({
+  modules: [AppModule],
   language: "ru",                          // response texts: validation, 404/405, 401/403, binding errors
   messages: { notFound: "Нет такой страницы" }, // optional: own texts for single keys
-  ui: { labels: RU_UI_LABELS, surfaces: [/* ... */] }, // generated UI texts
-});
+  ui: { labels: RU_UI_LABELS, surfaces: [/* ... */] }, // generated UI texts,
+})
+export class Application {}
 ```
 
 `language` is per application: it is applied when the response is written, so

package/cli/generateProject.ts

@@ -169,39 +169,32 @@ function buildProjectFiles(name: string, dependency: string, frameworkMode: Fram
     ["bazis.config.json", `${JSON.stringify(codegen, null, 2)}\n`],
     // Bun reads .env, .env.local and .env.<NODE_ENV>: none of them belongs in git.
     [".gitignore", "node_modules/\nbin/\nsrc/generated/\n.env\n.env.*\n!.env.example\n"],
-    [".env.example", "# Copy to .env (Bun loads it automatically).\nBAZIS_ENV=development\nHOST=127.0.0.1\nPORT=3000\n"],
+    [".env.example", "# Copy to .env (Bun loads it automatically).\nBAZIS_ENV=development\nBAZIS_HTTP__HOST=127.0.0.1\nBAZIS_HTTP__PORT=3000\n"],
     ["src/app/test/health.test.ts", HEALTH_TEST],
     ["AGENTS.md", "# Working on this bazis project\n\nBefore changing the application, read the [module architecture](docs/architecture/MODULE_ARCHITECTURE.md). Create new modules only with `bunx bazis g module` or `bunx bazis g pack`; fill in the generated `MODULE.md` afterwards. Only codegen updates `src/generated/`.\n"],
-    ["docs/architecture/MODULE_ARCHITECTURE.md", "# Application module architecture\n\n`src/index.ts` calls `runApp`; `src/app/modules/App.module.ts` composes feature modules through `imports`. The application root owns no domain logic.\n\nOne self-contained function is an atomic module. It owns its data, services, HTTP and background handlers. A composite module is only for several independent functions; its root does composition. Layers and file counts alone do not create submodules.\n\nCreate new modules only with `bunx bazis g module <Name> --empty|--minimal|--full` or `bunx bazis g pack <Name> --parts <a,b>`; add a part to an existing composite with `bunx bazis g module <Name> --pack <Pack>`. The generated `MODULE.md` records the creation command. Before implementing, define the responsibility and public entries, then fill in the generated `MODULE.md`: fields, errors, dependencies, exports and checks. Use the public APIs of the `bazis` package and its DI and ORM. Do not edit `src/generated/` by hand; run `bunx bazis codegen`.\n\n`--minimal` creates a sample CRUD with the ORM. To run it the application needs a database provider and a ready schema. For a first function without a database use `--empty`. Check types and the binary build after changes that affect startup.\n"],
+    ["docs/architecture/MODULE_ARCHITECTURE.md", "# Application module architecture\n\n`src/index.ts` calls `runApp(Application)`; `src/app/App.ts` declares the application with `@App`: its modules, infrastructure and servers; `src/app/modules/App.module.ts` composes feature modules through `imports`. The application root owns no domain logic.\n\nOne self-contained function is an atomic module. It owns its data, services, HTTP and background handlers. A composite module is only for several independent functions; its root does composition. Layers and file counts alone do not create submodules.\n\nCreate new modules only with `bunx bazis g module <Name> --empty|--minimal|--full` or `bunx bazis g pack <Name> --parts <a,b>`; add a part to an existing composite with `bunx bazis g module <Name> --pack <Pack>`. The generated `MODULE.md` records the creation command. Before implementing, define the responsibility and public entries, then fill in the generated `MODULE.md`: fields, errors, dependencies, exports and checks. Use the public APIs of the `bazis` package and its DI and ORM. Do not edit `src/generated/` by hand; run `bunx bazis codegen`.\n\n`--minimal` creates a sample CRUD with the ORM. To run it the application needs a database provider and a ready schema. For a first function without a database use `--empty`. Check types and the binary build after changes that affect startup.\n"],
     ["src/app/modules/App.module.ts", 'import { Module } from "bazis/core/di";\n\n@Module({ imports: [], exports: [] })\nexport class AppModule {}\n'],
-    ["src/index.ts", 'import { runApp } from "bazis/core/app";\nimport { AppModule } from "./app/modules/App.module";\nimport { registerBazisGeneratedRuntime } from "./generated/bazis/runtime";\n\nawait registerBazisGeneratedRuntime();\nawait runApp(AppModule, { http: { hostname: process.env.HOST ?? "127.0.0.1", port: Number(process.env.PORT ?? 3000), health: true } });\n'],
+    ["src/app/App.ts", 'import { App } from "bazis/core/app";\nimport { AppModule } from "./modules/App.module";\n\n/** The application: its modules and the servers it starts. `src/index.ts` runs it, tests start the same one. */\n@App({\n  modules: [AppModule],\n  http: { health: true },\n})\nexport class Application {}\n'],
+    ["src/index.ts", 'import { runApp } from "bazis/core/app";\nimport { Application } from "./app/App";\nimport { registerBazisGeneratedRuntime } from "./generated/bazis/runtime";\n\nawait registerBazisGeneratedRuntime();\nawait runApp(Application);\n'],
     ["README.md", `# ${name}\n\nA [bazis](https://www.npmjs.com/package/bazis) application. ${frameworkMode === "registry"
       ? "The framework comes from npm as the `bazis` dependency; update it with `bun update bazis`."
       : frameworkMode === "snapshot"
       ? "The framework package is copied to `vendor/bazis`; keep it in Git and move it with the project. The framework checkout is no longer needed. Framework updates do not reach this copy automatically."
-      : "The `bazis` dependency links an external local checkout (`--link-framework`). Moving the project needs the same package and an updated path in `package.json`."}\nRead the [local architecture](docs/architecture/MODULE_ARCHITECTURE.md) before changing modules.\n\nNeeds Bun ≥ 1.4.0. Settings go to \`.env\` (example: \`.env.example\`).\n\n\`\`\`sh\nbun install\nbunx bazis dev\n# GET http://127.0.0.1:3000/health\n# If the port is busy: PORT=3100 bunx bazis dev\n\`\`\`\n\nAdd an atomic module from the project root: \`bunx bazis g module Task --empty\`.\nAfter filling in its passport and implementation, run \`bunx bazis codegen\`.\nTests: \`bunx bazis test\`. Typecheck: \`bunx bazis build\`. Binary: \`bunx bazis build --bin\`, run it with \`bun run start\`.\n\n\`--minimal\` creates a sample CRUD with paging (20 records by default, at most 100 over HTTP); it needs a database provider and a schema to run. The service returns \`PageResult\`; the HTTP controller builds JSON:API. \`DbContext.saveChanges()\` saves every change of its context. In ORM predicates combine conditions with \`.and()\` and \`.or()\`; codegen rejects \`&&\` and \`||\` between predicates.\n`],
+      : "The `bazis` dependency links an external local checkout (`--link-framework`). Moving the project needs the same package and an updated path in `package.json`."}\nRead the [local architecture](docs/architecture/MODULE_ARCHITECTURE.md) before changing modules.\n\nNeeds Bun ≥ 1.4.0. Settings go to \`.env\` (example: \`.env.example\`).\n\n\`\`\`sh\nbun install\nbunx bazis dev\n# GET http://127.0.0.1:3000/health\n# If the port is busy: BAZIS_HTTP__PORT=3100 bunx bazis dev\n\`\`\`\n\nAdd an atomic module from the project root: \`bunx bazis g module Task --empty\`.\nAfter filling in its passport and implementation, run \`bunx bazis codegen\`.\nTests: \`bunx bazis test\`. Typecheck: \`bunx bazis build\`. Binary: \`bunx bazis build --bin\`, run it with \`bun run start\`.\n\n\`--minimal\` creates a sample CRUD with paging (20 records by default, at most 100 over HTTP); it needs a database provider and a schema to run. The service returns \`PageResult\`; the HTTP controller builds JSON:API. \`DbContext.saveChanges()\` saves every change of its context. In ORM predicates combine conditions with \`.and()\` and \`.or()\`; codegen rejects \`&&\` and \`||\` between predicates.\n`],
   ];
 }
 
 const HEALTH_TEST = `import { expect, test } from "bun:test";
+import { startTestApp } from "bazis/core/testing";
+import { Application } from "../App";
 
-// Starts the app from source exactly as \`bazis dev\` does and checks /health.
+// Starts the application declared in src/app/App.ts on a free port and checks /health.
 test("app starts and answers /health", async () => {
-  // A free port from the operating system, not a random guess that may be taken.
-  const probe = Bun.serve({ hostname: "127.0.0.1", port: 0, fetch: () => new Response() });
-  const port = String(probe.port);
-  probe.stop(true);
-  const app = Bun.spawn([process.execPath, "run", "src/index.ts"], { env: { ...process.env, HOST: "127.0.0.1", PORT: port }, stdout: "ignore", stderr: "inherit" });
+  const app = await startTestApp(Application);
   try {
-    let status = 0;
-    for (let attempt = 0; attempt < 100 && status !== 200; attempt++) {
-      await Bun.sleep(100);
-      status = await fetch(\`http://127.0.0.1:\${port}/health\`).then((response) => response.status, () => 0);
-    }
-    expect(status).toBe(200);
+    expect((await app.fetch("/health")).status).toBe(200);
   } finally {
-    app.kill();
-    await app.exited;
+    await app.stop();
   }
 });
 `;

package/cli/main.ts

@@ -18,6 +18,8 @@ export const USAGE = `Usage:
                                              for a part of a composite module)
   bazis workflow check [--app-module <path>]  Check the processes of the modules against their Tools
   bazis workflow diagram <key>                Print a process as a Mermaid flowchart
+  bazis upgrade columns [--dry-run]           For 0.137.0: mark every column @Required() or @Nullable() by what
+                                             it was, so the schema stays as it is (--path <dir>, default src)
   bazis codegen [--target <name|all>]         Generate DI wiring into src/generated/bazis
   bazis dev [--watch]                         Codegen, then run the app from source with
                                              BAZIS_ENV=development (unless set);
@@ -46,7 +48,7 @@ Generation options:
   --minimal             Compact example CRUD and MODULE.md (default)
   --full                Example CRUD/list/cache/auth/background/AI and MODULE.md;
                         uses src/app/modules/auth helpers when the project has them.
-                        To run, the host needs a cache (runApp({ cache: memory() }))
+                        To run, the host needs a cache (@App({ cache: memory() }))
                         and a database provider. Legacy alias: --enterprise
   --parts <a,b,...>      Independent empty atomic parts; pack only, at least two
   --dry-run             Validate and list planned changes without writing
@@ -143,6 +145,12 @@ export async function runCli(argv: readonly string[], runtime: CliRuntime = defa
     if (parsed.kind === "test") return await runTest(cwd, parsed.args, codegen, ui);
     if (parsed.kind === "build") return await runBuild(cwd, { bin: parsed.bin, outfile: parsed.outfile, dotenv: parsed.dotenv, platform: parsed.platform }, codegen, ui);
     if (parsed.kind === "new") return await runNew(parsed, ui);
+    if (parsed.kind === "upgrade") {
+      // The codemod parses sources with the TypeScript API: load it for this project first.
+      useTypeScriptCompilerApi(cwd);
+      const { runUpgradeColumns } = await import("./upgrade/runUpgrade");
+      return await runUpgradeColumns(cwd, parsed.path, parsed.dryRun, runtime.log);
+    }
     if (parsed.kind === "workflow") {
       const { runWorkflowCheck, runWorkflowDiagram } = await import("./workflow");
       return parsed.action === "check" ? await runWorkflowCheck(cwd, parsed.appModule, ui) : await runWorkflowDiagram(cwd, parsed.key, parsed.appModule, runtime.log);

package/cli/parseCli.ts

@@ -37,6 +37,7 @@ export type ParseCliResult =
   | { readonly kind: "workflow"; readonly action: "check"; readonly appModule?: string }
   | { readonly kind: "workflow"; readonly action: "diagram"; readonly key: string; readonly appModule?: string }
   | { readonly kind: "codegen"; readonly target?: string }
+  | { readonly kind: "upgrade"; readonly action: "columns"; readonly path?: string; readonly dryRun: boolean }
   | { readonly kind: "dev"; readonly watch: boolean }
   | { readonly kind: "test"; readonly args: readonly string[] }
   | { readonly kind: "build"; readonly bin: boolean; readonly outfile?: string; readonly dotenv: boolean; readonly platform?: string }
@@ -127,6 +128,14 @@ export function parseCliArgs(argv: readonly string[]): ParseCliResult {
     }
     return { kind: "codegen", target };
   }
+  if (command === "upgrade") {
+    for (const option of options.keys()) {
+      if (option !== "--path" && option !== "--dry-run") return error(`Option ${option} is not supported by upgrade.`);
+    }
+    if (generatorToken !== "columns" || positional.length !== 2) return error("Use: bazis upgrade columns [--path <directory>] [--dry-run]");
+    const directory = options.get("--path");
+    return { kind: "upgrade", action: "columns", ...(directory === undefined ? {} : { path: directory }), dryRun: options.has("--dry-run") };
+  }
   if (command === "workflow") {
     for (const option of options.keys()) {
       if (option !== "--app-module") return error(`Option ${option} is not supported by workflow.`);

package/cli/templates/module.ts

@@ -68,7 +68,6 @@ function moduleFile(n: ModuleNaming, profile: ModuleTemplateProfile): string {
 
   return `${moduleImport}
 ${aiImports}${backgroundImport}import { ${n.module}Controller } from "./http/${n.module}.controller";
-import { ${n.entity} } from "./model/${n.module}.model";
 import { ${n.module}DbContext } from "./model/${n.module}.dbContext";
 import { I${n.module}Service } from "./services/I${n.module}.service";
 import { ${n.module}Service } from "./services/${n.module}.service";
@@ -76,7 +75,6 @@ import { ${n.module}Service } from "./services/${n.module}.service";
 @Module({
   ormBazis: {
     context: ${n.module}DbContext,
-    entities: [${n.entity}],
   },
   controllers: [${n.module}Controller],
   providers: [
@@ -91,15 +89,15 @@ export class ${n.moduleClass} {}
 function controllerFile(n: ModuleNaming, profile: ModuleTemplateProfile, authImportPath: string | null): string {
   const auth = profile === "full" && authImportPath !== null;
   const fullImports = profile !== "full"
-    ? "import { Controller, Created, Delete, Get, HttpContext, NoContent, NotFound, Ok, Post, Put, type FromBody, type FromQuery, type FromRoute } from \"bazis/core/http\";\n"
+    ? "import { Controller, Created, Delete, Get, HttpContext, NoContent, NotFound, Post, Put, type FromBody, type FromQuery, type FromRoute } from \"bazis/core/http\";\n"
     : auth
       ? `import { OutputCache } from "bazis/core/cache";
-import { Authorize, Controller, Created, Delete, Get, HttpContext, NoContent, NotFound, Ok, Post, Put, type FromBody, type FromQuery, type FromRoute } from "bazis/core/http";
+import { Authorize, Controller, Created, Delete, Get, HttpContext, NoContent, NotFound, Post, Put, type FromBody, type FromQuery, type FromRoute } from "bazis/core/http";
 import { TokenKind } from "${authImportPath}/tokenKinds";
 import { requireTokenKind } from "${authImportPath}/jwtAuth";
 `
       : `import { OutputCache } from "bazis/core/cache";
-import { Controller, Created, Delete, Get, HttpContext, NoContent, NotFound, Ok, Post, Put, type FromBody, type FromQuery, type FromRoute } from "bazis/core/http";
+import { Controller, Created, Delete, Get, HttpContext, NoContent, NotFound, Post, Put, type FromBody, type FromQuery, type FromRoute } from "bazis/core/http";
 // No host auth helpers (src/app/modules/auth) were found: these routes are public.
 // Add @Authorize(...) from "bazis/core/http" with your policy before exposing them.
 `;
@@ -125,28 +123,25 @@ ${authList}  @Get()
     return buildListDocument(items, query, total, { basePath: ctx.path });
   }
 
-${authRead}  @Get(":id(uuid)")
-  async getById(id: FromRoute<string>) {
-    const item = await this.${n.collection}.getById(id);
-    return item ? Ok(item) : NotFound({ error: \`${n.entity.toLowerCase()} \${id} not found\` });
+${authRead}  @Get(":id(uuid)", { nullAs: NotFound })
+  getById(id: FromRoute<string>) {
+    return this.${n.collection}.getById(id);
   }
 
 ${authWrite}  @Post()
-  async create(body: FromBody<Create${n.entity}Request>, ctx: HttpContext) {
-    const item = await this.${n.collection}.create(body);
-    return Created(\`\${ctx.path.replace(/\\/$/, "")}/\${item.id}\`, item);
+  async create(body: FromBody<Create${n.entity}Request>) {
+    const result = await this.${n.collection}.create(body);
+    return Created(result);
   }
 
-${authWrite}  @Put(":id(uuid)")
-  async update(id: FromRoute<string>, body: FromBody<Update${n.entity}Request>) {
-    const item = await this.${n.collection}.update(id, body);
-    return item ? Ok(item) : NotFound({ error: \`${n.entity.toLowerCase()} \${id} not found\` });
+${authWrite}  @Put(":id(uuid)", { nullAs: NotFound })
+  update(id: FromRoute<string>, body: FromBody<Update${n.entity}Request>) {
+    return this.${n.collection}.update(id, body);
   }
 
 ${authWrite}  @Delete(":id(uuid)")
   async delete(id: FromRoute<string>) {
-    const removed = await this.${n.collection}.delete(id);
-    return removed ? NoContent() : NotFound({ error: \`${n.entity.toLowerCase()} \${id} not found\` });
+    return await this.${n.collection}.delete(id) ? NoContent() : NotFound();
   }
 }
 `;
@@ -155,17 +150,19 @@ ${authWrite}  @Delete(":id(uuid)")
 function ormModelFile(n: ModuleNaming, profile: ModuleTemplateProfile): string {
   const schemaImport = profile === "full" ? ", Schema" : "";
   const schemaDecorator = profile === "full" ? `@Schema("${n.dbSchema}")\n` : "";
-  return `import { Column, Entity, Index, UUID${schemaImport} } from "bazis/core/orm";
+  return `import { Column, Entity, Index, Required, UUID${schemaImport} } from "bazis/core/orm";
 
 ${schemaDecorator}@Entity({ table: "${n.route}" })
 export class ${n.entity} {
   @UUID()
   id = "";
 
+  @Required()
   @Column({ type: "text" })
   name = "";
 
   @Index({ unique: true })
+  @Required()
   @Column({ type: "text" })
   email = "";
 

package/cli/templates/passport.ts

@@ -76,14 +76,14 @@ exports: [I${m}Service]. TypeScript contract: services/I${e}.service.ts;
 HTTP access is defined by the controller and the host policy, separately from DI exports.
 I${m}Service → ${m}Service, scoped lifetime. The context and DbSet belong to the ORM.
 ${profile === "full" ? `${m}SummaryTool is listed in tools: [${m}SummaryTool]; the framework registers it as scoped, the tool is not exported.
-The service is scoped; its keyed @Cacheable works when the host installs the cache (runApp cache: memory()).
+The service is scoped; its keyed @Cacheable works when the host installs the cache (@App cache: memory()).
 The background service gets its own scope per tick and disposes it in finally.
 The host also provides auth from src/app/modules/auth (TokenKind.Admin/Client)
 and an LLM connector, which registers AgentRuntime. The CLI does not create them.
 ` : ""}Constructor dependencies, including ${m}DbContext, are wired by codegen.
 No manual deps arrays. UI, events and own configuration are not used.
 
-ORM: context ${m}DbContext, entities [${e}], shared host provider.
+ORM: context ${m}DbContext with the set of ${e}, shared host provider.
 Table ${n.route}${profile === "full" ? `, schema ${n.dbSchema}` : ""}.
 Only the module decides how tables are created: \`ensureCreated: true\` or
 \`migrateOnStart: true\` in \`ormBazis\`. The scaffold sets neither, so the host

package/cli/upgrade/markColumns.ts

@@ -0,0 +1,151 @@
+import ts from "typescript";
+
+/** What {@link markColumns} did to one file. */
+export interface MarkColumnsResult {
+  readonly text: string;
+  /** Columns that got `@Nullable()`. */
+  readonly nullable: number;
+  /** Columns that got `@Required()`. */
+  readonly required: number;
+  /** What needs a look: options not written in place, a mark that could not be imported. */
+  readonly skipped: readonly string[];
+}
+
+/** Decorators of a field that make it a column. */
+const COLUMN_DECORATORS = new Set(["Column", "Index", "ForeignKey", "HasConversion"]);
+/** Decorators that make a column NOT NULL whatever else is said. */
+const ALWAYS_REQUIRED = new Set(["Key", "UUID", "CreatedAt", "UpdatedAt"]);
+/** A `uuid` column is NOT NULL only as a key; as a plain column it was nullable. */
+const REQUIRED_TYPES = new Set(["createdAt", "updatedAt"]);
+/** Names an ORM import is recognised by. */
+const ORM_NAMES = new Set(["Column", "Entity", "Index", "Key", "UUID", "ForeignKey"]);
+
+interface Edit { readonly start: number; readonly end: number; readonly text: string }
+
+function decoratorCall(decorator: ts.Decorator): { readonly name: string; readonly call: ts.CallExpression } | undefined {
+  const expression = decorator.expression;
+  if (!ts.isCallExpression(expression) || !ts.isIdentifier(expression.expression)) return undefined;
+  return { name: expression.expression.text, call: expression };
+}
+
+function propertyName(node: ts.ObjectLiteralElementLike): string | undefined {
+  const name = node.name;
+  return name && (ts.isIdentifier(name) || ts.isStringLiteralLike(name)) ? name.text : undefined;
+}
+
+/**
+ * Brings the entities of a file to 0.137.0, where every column says whether it
+ * may be empty: `@Required()` or `@Nullable()`. A column gets the mark of what it
+ * was, so the schema of the application stays as it is: `@Nullable()` for one
+ * that allowed NULL by silence or by `nullable: true`, `@Required()` for
+ * `nullable: false`. The `nullable` option, which no longer exists, is removed.
+ * Keys and timestamps are left alone: they were always NOT NULL. Works on the
+ * text of one file and changes nothing else in it.
+ */
+export function markColumns(source: string, fileName = "file.ts"): MarkColumnsResult {
+  const file = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  const edits: Edit[] = [];
+  const skipped: string[] = [];
+  const marks = { Nullable: 0, Required: 0 };
+
+  /** `, nullable: true` out of the options; an object left empty goes away whole. */
+  const dropOption = (options: ts.ObjectLiteralExpression, index: number): void => {
+    const property = options.properties[index]!;
+    if (options.properties.length === 1) {
+      edits.push({ start: options.getStart(file), end: options.end, text: "" });
+    } else if (index > 0) {
+      edits.push({ start: options.properties[index - 1]!.end, end: property.end, text: "" });
+    } else {
+      edits.push({ start: property.getStart(file), end: options.properties[1]!.getStart(file), text: "" });
+    }
+  };
+
+  /** The mark before a decorator: on its own line when the decorator has one. */
+  const addMark = (mark: "Nullable" | "Required", before: ts.Decorator): void => {
+    const start = before.getStart(file);
+    const lineStart = source.lastIndexOf("\n", start - 1) + 1;
+    const indent = source.slice(lineStart, start);
+    const ownLine = /^[ \t]*$/.test(indent) && /^[ \t]*\r?\n/.test(source.slice(before.end));
+    edits.push({ start, end: start, text: ownLine ? `@${mark}()\n${indent}` : `@${mark}() ` });
+    marks[mark] += 1;
+  };
+
+  const visitClass = (node: ts.ClassLikeDeclaration): void => {
+    // `@Key(["shopId", "code"])` on the class: these properties are the key.
+    const keyed = new Set<string>();
+    for (const decorator of ts.getDecorators(node) ?? []) {
+      const found = decoratorCall(decorator);
+      const list = found?.name === "Key" ? found.call.arguments[0] : undefined;
+      if (list && ts.isArrayLiteralExpression(list)) for (const item of list.elements) if (ts.isStringLiteralLike(item)) keyed.add(item.text);
+    }
+    for (const member of node.members) {
+      if (!ts.isPropertyDeclaration(member)) continue;
+      const decorators = (ts.getDecorators(member) ?? []).map((decorator) => ({ decorator, found: decoratorCall(decorator) }));
+      const has = (name: string) => decorators.some(({ found }) => found?.name === name);
+      const anchor = decorators.find(({ found }) => found?.name === "Column") ?? decorators.find(({ found }) => found !== undefined && COLUMN_DECORATORS.has(found.name));
+      if (!anchor?.found) continue;
+      const name = member.name.getText(file);
+      const where = `${fileName}: ${node.name?.text ?? "class"}.${name}`;
+
+      const column = decorators.find(({ found }) => found?.name === "Column")?.found?.call;
+      const options = column?.arguments[0];
+      let declared: boolean | undefined;
+      let type: string | undefined;
+      if (options !== undefined) {
+        if (!ts.isObjectLiteralExpression(options) || options.properties.some(ts.isSpreadAssignment)) {
+          skipped.push(`${where}: the options of @Column are not written in place; mark the column @Required() or @Nullable() by hand`);
+          continue;
+        }
+        const typeProperty = options.properties.find((property) => propertyName(property) === "type");
+        if (typeProperty && ts.isPropertyAssignment(typeProperty) && ts.isStringLiteralLike(typeProperty.initializer)) type = typeProperty.initializer.text;
+        const index = options.properties.findIndex((property) => propertyName(property) === "nullable");
+        if (index >= 0) {
+          const property = options.properties[index]!;
+          const value = ts.isPropertyAssignment(property) ? property.initializer.kind : undefined;
+          if (value !== ts.SyntaxKind.TrueKeyword && value !== ts.SyntaxKind.FalseKeyword) {
+            skipped.push(`${where}: nullable is not true or false here; mark the column @Required() or @Nullable() by hand`);
+            continue;
+          }
+          declared = value === ts.SyntaxKind.TrueKeyword;
+          dropOption(options, index);
+        }
+      }
+
+      // A soft-delete column is nullable by its own decorator; keys and timestamps are always NOT NULL.
+      if (has("SoftDelete") || keyed.has(name) || decorators.some(({ found }) => found !== undefined && ALWAYS_REQUIRED.has(found.name)) || (type !== undefined && REQUIRED_TYPES.has(type))) continue;
+      if (has("Required") || has("Nullable")) continue;
+      addMark(declared === false ? "Required" : "Nullable", anchor.decorator);
+    }
+  };
+
+  const visit = (node: ts.Node): void => {
+    if (ts.isClassLike(node)) visitClass(node);
+    ts.forEachChild(node, visit);
+  };
+  visit(file);
+
+  const wanted = (["Nullable", "Required"] as const).filter((mark) => marks[mark] > 0);
+  if (wanted.length > 0) {
+    const problem = importEdits(file, wanted, edits);
+    if (problem !== undefined) skipped.push(`${fileName}: ${problem}`);
+  }
+  let text = source;
+  for (const edit of edits.sort((left, right) => right.start - left.start || right.end - left.end)) text = text.slice(0, edit.start) + edit.text + text.slice(edit.end);
+  return { text, nullable: marks.Nullable, required: marks.Required, skipped };
+}
+
+/** The marks join the import the other ORM decorators of the file come from. */
+function importEdits(file: ts.SourceFile, marks: readonly string[], edits: Edit[]): string | undefined {
+  for (const statement of file.statements) {
+    if (!ts.isImportDeclaration(statement) || statement.importClause?.isTypeOnly) continue;
+    const bindings = statement.importClause?.namedBindings;
+    if (!bindings || !ts.isNamedImports(bindings)) continue;
+    const names = new Set(bindings.elements.map((element) => (element.propertyName ?? element.name).text));
+    if (![...names].some((name) => ORM_NAMES.has(name))) continue;
+    const missing = marks.filter((mark) => !names.has(mark));
+    const last = bindings.elements.at(-1);
+    if (missing.length > 0 && last) edits.push({ start: last.end, end: last.end, text: `, ${missing.join(", ")}` });
+    return undefined;
+  }
+  return `import ${marks.join(" and ")} from the ORM by hand: the file has no import of its decorators to add them to`;
+}

package/cli/upgrade/runUpgrade.ts

@@ -0,0 +1,57 @@
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import { markColumns } from "./markColumns";
+
+const SKIPPED_DIRECTORIES = new Set(["node_modules", "generated", "dist", "bin", ".git"]);
+
+async function sourceFiles(directory: string): Promise<string[]> {
+  const out: string[] = [];
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const full = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      if (!SKIPPED_DIRECTORIES.has(entry.name)) out.push(...await sourceFiles(full));
+    } else if (/\.tsx?$/.test(entry.name) && !entry.name.endsWith(".d.ts")) {
+      out.push(full);
+    }
+  }
+  return out.sort();
+}
+
+/**
+ * `bazis upgrade columns`: from 0.137.0 every column says whether it may be
+ * empty, `@Required()` or `@Nullable()`. This gives each column the mark of what
+ * it was, so the schema of the application stays as it is, and removes the
+ * `nullable` option. With `--dry-run` it only tells what it would change.
+ */
+export async function runUpgradeColumns(cwd: string, directory: string | undefined, dryRun: boolean, log: (text: string) => void): Promise<number> {
+  const root = path.resolve(cwd, directory ?? "src");
+  let files: string[];
+  try {
+    files = await sourceFiles(root);
+  } catch {
+    log(`No directory ${path.relative(cwd, root) || "."}. Pass the sources with --path <directory>.`);
+    return 1;
+  }
+  let nullable = 0;
+  let required = 0;
+  let changed = 0;
+  const skipped: string[] = [];
+  for (const file of files) {
+    const source = await Bun.file(file).text();
+    if (!/@(Column|Index|ForeignKey|HasConversion)\(/.test(source)) continue;
+    const name = path.relative(cwd, file);
+    const result = markColumns(source, name);
+    skipped.push(...result.skipped);
+    if (result.text === source) continue;
+    changed += 1;
+    nullable += result.nullable;
+    required += result.required;
+    log(`${dryRun ? "would change" : "changed"} ${name}: ${[result.nullable > 0 ? `${result.nullable} @Nullable()` : "", result.required > 0 ? `${result.required} @Required()` : "", result.nullable + result.required === 0 ? "the nullable option removed" : ""].filter(Boolean).join(", ")}`);
+    if (!dryRun) await Bun.write(file, result.text);
+  }
+  for (const line of skipped) log(`look at ${line}`);
+  log(changed === 0
+    ? "Nothing to change: every column already says whether it may be empty."
+    : `${dryRun ? "Would change" : "Changed"} ${changed} ${changed === 1 ? "file" : "files"}: ${nullable} columns marked @Nullable(), ${required} marked @Required(). The schema stays as it was. Review the diff: where a column must not be empty, write @Required() instead and migrate the data.`);
+  return 0;
+}

package/core/access/Access.module.ts

@@ -9,7 +9,7 @@ import { AccessPolicy } from "./contracts/AccessPolicy";
 import { AccessCatalogController } from "./http/AccessCatalog.controller";
 import { RolesAccessPolicy } from "./roles/RolesAccessPolicy";
 
-const accessPermissions = definePermissions({
+export const accessPermissions = definePermissions({
   "access.catalog.read": {
     title: { en: "See the permissions catalog", ru: "Видеть каталог прав" },
   },

package/core/access/catalog/moduleFields.ts

@@ -1,5 +1,7 @@
 import {
   createModuleOwnedMetadataChannel,
+  createModuleOwnedProviderChannel,
+  scoped,
   registerModuleOwnedContributionValidator,
   registerModuleOwnedProviderContributor,
   DiContainer,
@@ -22,6 +24,10 @@ interface RolePayload { readonly name: string; readonly permissions: "all" | rea
 const PERMISSION_CHANNEL = createModuleOwnedMetadataChannel<PermissionPayload>("access.permission/v1");
 const REFERENCE_CHANNEL = createModuleOwnedMetadataChannel<ReferencePayload>("access.reference/v1");
 const ROLE_CHANNEL = createModuleOwnedMetadataChannel<RolePayload>("access.role/v1");
+/** The classes of `references`: the field registers them, like `tools` and `controllers`. */
+const REFERENCE_CLASS_CHANNEL = createModuleOwnedProviderChannel<{ readonly kind: string }, object>("access.reference-class/v1");
+/** The `lookup` classes of `permissions`: the field registers them too. */
+const LOOKUP_CLASS_CHANNEL = createModuleOwnedProviderChannel<{ readonly permission: string }, object>("access.lookup-class/v1");
 
 /** The values of `in`/`notIn` a role may list; the run-time limit is `access.maxInList`. */
 const STARTUP_MAX_IN_LIST = 1000;
@@ -42,7 +48,20 @@ registerModuleOwnedProviderContributor((metadata: BazisModuleMetadata, context)
     if (!isDeclaredPermissions(fields.permissions)) throw new AccessSetupError(`${module}: permissions must be a definePermissions(...) result.`);
     const problems = Object.entries(fields.permissions).flatMap(([key, spec]) => permissionProblems(key, spec));
     if (problems.length > 0) throw setupError(module, "permissions", problems);
-    for (const [key, spec] of Object.entries(fields.permissions)) context.addMetadata(PERMISSION_CHANNEL, { key, spec });
+    const lookups = new Set<unknown>();
+    for (const [key, spec] of Object.entries(fields.permissions)) {
+      context.addMetadata(PERMISSION_CHANNEL, { key, spec });
+      for (const lookup of lookupsOf(spec)) {
+        // A lookup another module owns and exports is taken from it.
+        if (lookups.has(lookup) || importsExport(metadata, lookup)) continue;
+        lookups.add(lookup);
+        try {
+          context.registerScoped(LOOKUP_CLASS_CHANNEL, scoped(lookup as Class<object>), { permission: key });
+        } catch {
+          // The module registered the class its own way: that registration stands.
+        }
+      }
+    }
   }
   if (fields.references !== undefined) {
     const references = fields.references;
@@ -53,7 +72,17 @@ registerModuleOwnedProviderContributor((metadata: BazisModuleMetadata, context)
       if (typeof type !== "function") problems.push(`reference kind "${kind}" must name a References class`);
     }
     if (problems.length > 0) throw setupError(module, "references", problems);
-    for (const [kind, type] of Object.entries(references)) context.addMetadata(REFERENCE_CHANNEL, { kind, type: type as Class<References> });
+    const registered = new Set<unknown>();
+    for (const [kind, type] of Object.entries(references)) {
+      context.addMetadata(REFERENCE_CHANNEL, { kind, type: type as Class<References> });
+      if (registered.has(type)) continue;
+      registered.add(type);
+      try {
+        context.registerScoped(REFERENCE_CLASS_CHANNEL, scoped(type as Class<object>), { kind });
+      } catch {
+        // The module registered the class its own way (a singleton): that registration stands.
+      }
+    }
   }
   if (fields.roles !== undefined) {
     if (!isDeclaredRoles(fields.roles)) throw new AccessSetupError(`${module}: roles must be a defineRoles(...) result.`);
@@ -93,7 +122,7 @@ registerModuleOwnedContributionValidator((snapshot) => {
     const other = kinds.get(payload.kind);
     if (other !== undefined) throw new AccessSetupError(`Reference kind "${payload.kind}" is declared twice: in ${other} and in ${ownerName}.`);
     kinds.set(payload.kind, ownerName);
-    if (snapshot.countProviders(payload.type) === 0) throw new AccessSetupError(`${ownerName}: ${payload.type.name} of reference kind "${payload.kind}" is not registered: add it to the module's providers.`);
+    if (snapshot.countProviders(payload.type) === 0) throw new AccessSetupError(`${ownerName}: ${payload.type.name} of reference kind "${payload.kind}" is not registered.`);
   }
 
   for (const { payload, ownerName } of permissions) {
@@ -103,7 +132,7 @@ registerModuleOwnedContributionValidator((snapshot) => {
       }
     }
     for (const lookup of lookupsOf(payload.spec)) {
-      if (snapshot.countProviders(lookup) === 0) throw new AccessSetupError(`${ownerName}: ${lookup.name} of permission "${payload.key}" is not registered: add it to the module's providers.`);
+      if (snapshot.countProviders(lookup) === 0) throw new AccessSetupError(`${ownerName}: ${lookup.name} of permission "${payload.key}" is not registered.`);
     }
   }
 
@@ -122,6 +151,14 @@ registerModuleOwnedContributionValidator((snapshot) => {
   }
 });
 
+/** Whether a module the given one imports exports this class. */
+function importsExport(metadata: BazisModuleMetadata, type: unknown): boolean {
+  return (metadata.imports ?? []).some((imported) => {
+    const exported = (imported as { readonly exports?: unknown }).exports;
+    return Array.isArray(exported) && exported.includes(type);
+  });
+}
+
 /** What the modules of the application's container declared. */
 export function declarationsOf(services: ServiceProvider): { permissions: OwnedPermission[]; kinds: OwnedReferenceKind[]; roles: DeclaredRole[] } {
   if (!(services instanceof DiContainer)) throw new AccessSetupError("Access declarations require the framework DiContainer.");

package/core/access/catalog/permissions.ts

@@ -1,6 +1,7 @@
 import type { Class } from "../../di";
 import type { AttributeLookup } from "../contracts/AttributeLookup";
 import type { LocalizedText } from "../contracts/types";
+import type { BazisPermissions } from "../index";
 
 /** An attribute of the object of a permission: what a condition may test (ACCESS-001 §3). */
 export interface AttributeSpec {
@@ -39,6 +40,15 @@ export interface PermissionSpec {
 
 export type PermissionDeclarations = Readonly<Record<string, PermissionSpec>>;
 
+/** The declarations of `definePermissions(...)` as a part of {@link BazisPermissions}. */
+export type PermissionsOf<T extends PermissionDeclarations> = { readonly [K in keyof T]: T[K] };
+
+/** A declared permission. */
+export type PermissionKey = Extract<keyof BazisPermissions, string>;
+
+/** A permission with an `owner`: the only kind `"<key>:own"` makes sense for. */
+export type OwnPermissionKey = { [K in keyof BazisPermissions]: BazisPermissions[K] extends { readonly owner: string } ? Extract<K, string> : never }[keyof BazisPermissions];
+
 const DECLARED = new WeakSet<object>();
 
 /**

package/core/access/check/Access.ts

@@ -3,7 +3,7 @@ import { UnauthorizedError, type AuthorizeContext } from "../../http";
 import { LOGGER, type ConfigView } from "../../kernel";
 import type { AccessConfig } from "./accessConfig";
 import type { IAccessCatalog } from "../catalog/IAccessCatalog.service";
-import type { PermissionSpec } from "../catalog/permissions";
+import type { PermissionKey, PermissionSpec } from "../catalog/permissions";
 import { AccessPolicy, type ScopePrincipals } from "../contracts/AccessPolicy";
 import type { AttributeLookup } from "../contracts/AttributeLookup";
 import type { AccessObject, AccessSubject, Condition, Grant, Grants, Scope } from "../contracts/types";
@@ -70,7 +70,7 @@ export class SubjectAccess {
   ) {}
 
   /** The grants of the permission; a grant the permission cannot use is dropped with a warning. */
-  grants(permission: string): Promise<Grants> {
+  grants(permission: PermissionKey): Promise<Grants> {
     let grants = this.grantCache.get(permission);
     if (grants === undefined) {
       grants = this.load(permission);
@@ -83,7 +83,7 @@ export class SubjectAccess {
    * Whether the subject may do `permission` on `object`. Without an object —
    * whether it has the permission anywhere (a route before the object is known).
    */
-  async can(permission: string, object?: AccessObject): Promise<boolean> {
+  async can(permission: PermissionKey, object?: AccessObject): Promise<boolean> {
     const spec = this.catalog.require(permission).spec;
     const grants = await this.grants(permission);
     if (grants === "all") return true;
@@ -92,7 +92,7 @@ export class SubjectAccess {
   }
 
   /** Which rows of a list the subject may see; `scope` — the partition of the request for `scope: "request"`. */
-  async filter(permission: string, options: { readonly scope?: Scope } = {}): Promise<AccessFilter> {
+  async filter(permission: PermissionKey, options: { readonly scope?: Scope } = {}): Promise<AccessFilter> {
     const spec = this.catalog.require(permission).spec;
     const grants = await this.grants(permission);
     return await buildFilter({
@@ -107,7 +107,7 @@ export class SubjectAccess {
   }
 
   /** The fields of `object` the subject may read and write (ACCESS-001 §4.4). */
-  async fields(permission: string, object: AccessObject): Promise<FieldAccess> {
+  async fields(permission: PermissionKey, object: AccessObject): Promise<FieldAccess> {
     const spec = this.catalog.require(permission).spec;
     const grants = await this.grants(permission);
     if (grants === "all") return { read: "all", write: "all" };