bazis 0.135.0 → 0.137.0

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);
@@ -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

@@ -83,7 +83,7 @@ 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,8 @@ 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 values of `in`/`notIn` a role may list; the run-time limit is `access.maxInList`. */
 const STARTUP_MAX_IN_LIST = 1000;
@@ -53,7 +57,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 +107,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) {

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" };

package/core/access/check/can.ts

@@ -1,4 +1,5 @@
 import type { AuthorizeCheck, AuthorizeContext } from "../../http";
+import type { PermissionKey } from "../catalog/permissions";
 import type { AccessObject } from "../contracts/types";
 import { IAccess } from "./IAccess.service";
 
@@ -13,7 +14,7 @@ import { IAccess } from "./IAccess.service";
  * @Post() create(ctx: HttpContext) { … }
  * ```
  */
-export function can(permission: string, objectOf?: (ctx: AuthorizeContext) => AccessObject | Promise<AccessObject>): AuthorizeCheck {
+export function can(permission: PermissionKey, objectOf?: (ctx: AuthorizeContext) => AccessObject | Promise<AccessObject>): AuthorizeCheck {
   return async (ctx) => {
     const access = await ctx.services.resolve(IAccess).for(ctx);
     return await access.can(permission, objectOf === undefined ? undefined : await objectOf(ctx));

package/core/access/index.ts

@@ -5,9 +5,19 @@
  */
 import "./catalog/moduleFields";
 import "./generated/deps";
+import type { accessPermissions } from "./Access.module";
+import type { PermissionsOf } from "./catalog/permissions";
+
+/**
+ * The permissions the application declares, by key: what `can`, `access.can`,
+ * `access.filter` and `defineRoles` accept. Nobody writes it by hand: `bazis codegen`
+ * fills it from `permissions` of the application's modules
+ * (`src/generated/bazis/permissions.ts`), a framework pack from its own.
+ */
+export interface BazisPermissions extends PermissionsOf<typeof accessPermissions> {}
 
 export { AccessModule } from "./Access.module";
-export { definePermissions, type AttributeSpec, type PermissionDeclarations, type PermissionSpec, type ScopeSource } from "./catalog/permissions";
+export { definePermissions, type AttributeSpec, type OwnPermissionKey, type PermissionDeclarations, type PermissionKey, type PermissionsOf, type PermissionSpec, type ScopeSource } from "./catalog/permissions";
 export { IAccessCatalog } from "./catalog/IAccessCatalog.service";
 export type { DeclaredRole, OwnedPermission, OwnedReferenceKind } from "./catalog/AccessCatalog";
 export { IAccess } from "./check/IAccess.service";

package/core/access/roles/roles.ts

@@ -1,3 +1,4 @@
+import type { OwnPermissionKey, PermissionKey } from "../catalog/permissions";
 import type { Condition, Grant, GrantFields, Scope } from "../contracts/types";
 
 /**
@@ -5,9 +6,10 @@ import type { Condition, Grant, GrantFields, Scope } from "../contracts/types";
  * grant with conditions.
  */
 export type RoleGrant =
-  | string
+  | PermissionKey
+  | `${OwnPermissionKey}:own`
   | {
-      readonly permission: string;
+      readonly permission: PermissionKey;
       readonly scopes?: "all" | readonly Scope[];
       readonly where?: Condition;
       readonly fields?: GrantFields;

package/core/agent/AgentToolExecutor.ts

@@ -62,6 +62,8 @@ export interface AgentToolExecutionContext {
   readonly actor?: ToolActor;
   /** A trial: the Tool, one with `dryRun: "supported"`, changes nothing (WORKFLOW-002 §5.4). */
   readonly dryRun?: boolean;
+  /** Who calls: `"agent"` or the caller id of `ToolRunner.as`. */
+  readonly caller?: string;
   readonly metadata: JsonObject;
   readonly signal: AbortSignal;
 }
@@ -1672,6 +1674,7 @@ export class AgentToolExecutor {
       approval,
       ...(options.actor !== undefined ? { actor: options.actor } : {}),
       ...(options.dryRun === true ? { dryRun: true } : {}),
+      ...(callerOf(options) === undefined ? {} : { caller: callerOf(options)! }),
       metadata,
       signal,
     });

package/core/agent/ToolRunner.ts

@@ -42,6 +42,11 @@ export class ToolRunner {
     this.executor = new AgentToolExecutor(services, this.catalog, { schemaValidator: modelValidatorAdapter, ...executorOptions }, logger);
   }
 
+  /** Every Tool of the application, whoever may call it. */
+  listTools(): readonly ToolDefinition[] {
+    return this.catalog.listTools();
+  }
+
   /** A view of the Tools this caller may run. `"agent"` is refused: agents run through `AgentRuntime`. */
   as(caller: string): BoundToolRunner {
     let id: string;