bazis 0.98.21 → 0.98.23

package/core/di/errors/NamedDependencyNotFoundError.ts

@@ -1,7 +1,18 @@
 import { DiError } from "./DiError";
 
+/** Returns a hint for a named dependency nobody registers, or `undefined`. */
+export type NamedDependencyHint = (name: string) => string | undefined;
+
+const hints: NamedDependencyHint[] = [];
+
+/** Infrastructure extensions (ORM repositories, …) explain their own named dependencies here. */
+export function registerNamedDependencyHint(hint: NamedDependencyHint): void {
+  hints.push(hint);
+}
+
 export class NamedDependencyNotFoundError extends DiError {
   public constructor(name: string) {
-    super(`No provider token found for named dependency "${name}".`);
+    const hint = hints.map((item) => item(name)).find((text) => text !== undefined);
+    super(`No provider token found for named dependency "${name}".${hint ? ` ${hint}` : ""}`);
   }
 }

package/core/di/module/encapsulation.ts

@@ -84,7 +84,9 @@ export function validateModuleEncapsulation(
         if (isFamilyExport(ref)) {
           continue;
         }
-        if (record.providedTokens.has(ref) || visible.has(ref)) {
+        // A closed token of a visible family (`repositoryFor(Product)` next to an
+        // `ormBazis` that exports the whole `IRepository` family) may be passed on alone.
+        if (record.providedTokens.has(ref) || visible.has(ref) || (typeof ref !== "function" && ref.genericFamilyId !== undefined && allProvidedTokens.has(ref) && visibleFamilies(record).has(ref.genericFamilyId))) {
           result.add(ref);
         } else {
           issues.push(
@@ -173,6 +175,10 @@ export function validateModuleEncapsulation(
   // Why a provided token is not visible: the owner does not export it, or the
   // consumer module does not import the owner. Both used to read "not exported".
   const explainHidden = (token: Token<unknown>, consumer: ModuleGraphRecord): string => {
+    if (typeof token !== "function" && token.genericFamilyId !== undefined) {
+      const family = explainHiddenFamily(token, token.genericFamilyId, consumer);
+      if (family !== undefined) return family;
+    }
     // A module the consumer imports already sees the token but does not pass it
     // on. That export is the fix, whatever inner module (an `ormBazis` feature
     // module, say) registered the token.
@@ -188,6 +194,31 @@ export function validateModuleEncapsulation(
       : `which module "${owner.name}" provides but does not export. Add it to the exports of "${owner.name}".`;
   };
 
+  // A closed token (`IRepository<Product>`) travels with its family export, so
+  // the fix is named in family terms and skips unnamed inner modules such as
+  // the one `ormBazis` creates.
+  const explainHiddenFamily = (token: Token<unknown>, familyId: symbol, consumer: ModuleGraphRecord): string | undefined => {
+    const closed = tokenToDebugName(token);
+    const family = closed.includes("<") ? closed.slice(0, closed.indexOf("<")) : closed;
+    const exportFix = `${family} (or only ${closed})`;
+    const sees = (record: ModuleGraphRecord) => visibleFamilies(record).has(familyId) || visibleTokens(record).has(token);
+    const passes = (record: ModuleGraphRecord) => exportedFamilies(record).has(familyId) || exportedTokens(record).has(token);
+    const named = (record: ModuleGraphRecord) => !/^module#\d+$/.test(record.name);
+    const blocking = consumer.imports.find((imported) => named(imported) && sees(imported) && !passes(imported));
+    if (blocking !== undefined) {
+      return `which its import "${blocking.name}" receives from its own imports but does not export. Add ${exportFix} to the exports of "${blocking.name}".`;
+    }
+    const exporter = records.find((record) => record !== consumer && named(record) && passes(record));
+    if (exporter !== undefined) {
+      return `which module "${exporter.name}" exports, but "${consumer.name}" does not list "${exporter.name}" in its imports. Add "${exporter.name}" to the imports of "${consumer.name}".`;
+    }
+    const host = records.find((record) => record !== consumer && named(record) && sees(record));
+    if (host !== undefined) {
+      return `which module "${host.name}" receives from its own imports but does not export. Add ${exportFix} to the exports of "${host.name}" and "${host.name}" to the imports of "${consumer.name}".`;
+    }
+    return undefined;
+  };
+
   const contexts = new Map<ModuleGraphRecord, DependencyCheckContext>();
   for (let recordIndex = 0; recordIndex < records.length; recordIndex += 1) {
     const record = records[recordIndex] as ModuleGraphRecord;
@@ -302,7 +333,7 @@ function checkDependency(
       !context.familiesVisible.has(token.genericFamilyId)
     ) {
       context.issues.push(
-        `Module "${record.name}": "${consumer}" depends on open generic "${tokenToDebugName(token)}", whose family is not exported by any imported module.`,
+        `Module "${record.name}": "${consumer}" depends on "${tokenToDebugName(token)}", ${context.explainHidden(token, record)}`,
       );
     }
     return;
@@ -363,6 +394,7 @@ export function computeModuleVisibleTokens(
 ): Map<ModuleGraphRecord, Set<Token<unknown>>> {
   const exportedMemo = new Map<ModuleGraphRecord, Set<Token<unknown>>>();
   const visiting = new Set<ModuleGraphRecord>();
+  const allProvided = new Set<Token<unknown>>(records.flatMap((record) => [...record.providedTokens]));
 
   const visibleOf = (record: ModuleGraphRecord): Set<Token<unknown>> => {
     const result = new Set<Token<unknown>>(record.providedTokens);
@@ -401,7 +433,8 @@ export function computeModuleVisibleTokens(
         if (isFamilyExport(ref)) {
           continue;
         }
-        if (record.providedTokens.has(ref) || visible.has(ref)) {
+        // Validation already admitted closed tokens re-exported from a visible family.
+        if (record.providedTokens.has(ref) || visible.has(ref) || (typeof ref !== "function" && ref.genericFamilyId !== undefined && allProvided.has(ref))) {
           result.add(ref);
         }
       }

package/core/infra/connectors/codex/CodexAppServerClient.ts

@@ -232,7 +232,7 @@ export class CodexAppServerClient implements CodexClient {
         if (method === "account/updated") this.modelCache = undefined;
       }, () => { this.clearLogin(); this.modelCache = undefined; });
       const initialized = await client.request("initialize", {
-        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.21" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.23" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

package/core/kernel/startupFailure.ts

@@ -37,6 +37,9 @@ export function formatStartupFailure(error: unknown): string {
 }
 
 function codeOf(error: Error): string {
+  const own = (error as unknown as Record<string, unknown>).code;
+  // A message that already starts with its code ("ORM_X: …") is not prefixed twice.
+  if (typeof own === "string" && error.message.startsWith(own)) return "";
   // Node style: `Error [ERR_X]: message`; a database error code such as 42P01 follows it.
   const fields = ["code", "errno"].flatMap((name) => {
     const value = (error as unknown as Record<string, unknown>)[name];

package/core/orm/encapsulationHook.ts

@@ -1,9 +1,13 @@
 import { registerNamedDependencyEncapsulationHook } from "../di/module/encapsulationHooks";
+import { registerNamedDependencyHint } from "../di/errors/NamedDependencyNotFoundError";
 import { IRepository } from "./repository";
 
 let registered = false;
 
-/** Allows closed `IRepository<Entity>` named deps when the module exports open generic `IRepository`. */
+/**
+ * Allows closed `IRepository<Entity>` named deps when the module exports open
+ * generic `IRepository`, and explains a repository nobody registers.
+ */
 export function registerRepositoryEncapsulationHook(): void {
   if (registered) {
     return;
@@ -16,4 +20,10 @@ export function registerRepositoryEncapsulationHook(): void {
     }
     return undefined;
   });
+
+  registerNamedDependencyHint((name) => {
+    const match = /^IRepository<(.+)>$/.exec(name);
+    if (!match) return undefined;
+    return `Repositories are registered by ormBazis for the entities of its context: add ${match[1]} to the entities of an ormBazis module and keep registerRepositories on (the default), or inject that module's DbContext instead.`;
+  });
 }

package/core/orm/ormModule.ts

@@ -110,8 +110,14 @@ function defineConnectionModule(provider: DatabaseProvider, healthCheck: boolean
 /** Single ORM registration entry point (see {@link OrmModuleConfig}). */
 export function ormModule<TContext extends DbContext>(config: OrmModuleConfig<TContext>): BazisModuleRef {
   if (config.ownedStore !== undefined) {
-    if (!config.context || !config.entities || config.entities.length === 0 || config.provider || config.ensureCreated || config.migrateOnStart || config.runMigrationsOnStart || config.migrations !== undefined) {
-      throw new OrmError("ORM owned store requires a context and entities and cannot compose startup schema or migration authority.");
+    if (!config.context || !config.entities || config.entities.length === 0) {
+      throw new OrmError("ORM owned store requires a context and entities.");
+    }
+    if (config.provider) {
+      throw new OrmError("ORM owned store uses the shared DATABASE_PROVIDER from @Infra; remove provider from this ormBazis entry.");
+    }
+    if (config.ensureCreated || config.migrateOnStart || config.runMigrationsOnStart || config.migrations !== undefined) {
+      throw new OrmError("ORM owned store creates and verifies its own tables; remove ensureCreated, migrateOnStart and migrations from this ormBazis entry.");
     }
     // Provider factories outlive this call. Keep their context/entity view
     // registration-local so a caller cannot mutate the descriptor afterwards

package/core/orm/ownedStoreContributions.ts

@@ -41,9 +41,13 @@ const PAYLOAD = Symbol("bazis.orm.owned-store");
 const CHANNEL = createModuleOwnedMetadataChannel<OrmGraphContribution>("orm.owned-store");
 const compiled = new WeakMap<object, CompiledOwnedStoreGraph>();
 
-function fail(code: "ORM_OWNED_STORE_IDENTITY_MISMATCH" | "ORM_OWNED_STORE_OWNERSHIP_CONFLICT"): never {
-  throw new OrmOwnedStoreAdmissionError(code, code);
+/** Names here come from the application's own declarations, never from the database. */
+function fail(code: "ORM_OWNED_STORE_IDENTITY_MISMATCH" | "ORM_OWNED_STORE_OWNERSHIP_CONFLICT", reason?: string): never {
+  throw new OrmOwnedStoreAdmissionError(code, reason === undefined ? code : `${code}: ${reason}.`);
 }
+const storeName = (definition: Readonly<OrmOwnedStoreDefinitionV1>) => `Owned store "${definition.storeKey}" (schema "${definition.ownedScope.schema}", prefix "${definition.ownedScope.tablePrefix}")`;
+const scopeName = (scope: { readonly schema: string; readonly tablePrefix: string }) => `schema "${scope.schema}", prefix "${scope.tablePrefix}"`;
+const OVERLAP_HINT = "two prefixes overlap when one starts with the other, so \"notes_\" and \"notes_v2_\" overlap while \"notes_\" and \"notesv2_\" do not";
 
 function overlaps(a: { readonly schema: string; readonly tablePrefix: string }, b: { readonly schema: string; readonly tablePrefix: string }): boolean {
   return a.schema === b.schema && (a.tablePrefix.startsWith(b.tablePrefix) || b.tablePrefix.startsWith(a.tablePrefix));
@@ -52,7 +56,7 @@ function overlaps(a: { readonly schema: string; readonly tablePrefix: string },
 function snapshot<TContext extends DbContext>(context: ContextClass<TContext>, entities: readonly EntityClass[], source: unknown): OwnedStoreRegistration<TContext> {
   const definition = isDefinedOrmOwnedStoreV1(source) ? source : defineOrmOwnedStoreV1(source as OrmOwnedStoreDefinitionV1);
   const expected = compileExpectedSchema(new OrmModel(entities));
-  if (expected.tables.length === 0 || expected.tables.length > 512) fail("ORM_OWNED_STORE_IDENTITY_MISMATCH");
+  if (expected.tables.length === 0 || expected.tables.length > 512) fail("ORM_OWNED_STORE_IDENTITY_MISMATCH", `${storeName(definition)} needs 1 to 512 entities, got ${expected.tables.length}`);
   return Object.freeze({ identity: Object.freeze({}), context, entities: Object.freeze([...entities]), definition, expected, source });
 }
 
@@ -91,11 +95,11 @@ export function revalidateOwnedStoreRegistration(registration: OwnedStoreRegistr
     && current.definition.ownedScope.schema === registration.definition.ownedScope.schema
     && current.definition.ownedScope.tablePrefix === registration.definition.ownedScope.tablePrefix
     && JSON.stringify(current.definition.rejectIfPresent ?? []) === JSON.stringify(registration.definition.rejectIfPresent ?? []);
-  if (!sameDefinition || current.expected.tables.length !== registration.expected.tables.length) fail("ORM_OWNED_STORE_IDENTITY_MISMATCH");
+  if (!sameDefinition || current.expected.tables.length !== registration.expected.tables.length) fail("ORM_OWNED_STORE_IDENTITY_MISMATCH", `${storeName(registration.definition)}: its definition or entities changed after the module was declared; declare them once`);
   for (let index = 0; index < current.expected.tables.length; index += 1) {
     const before = registration.expected.tables[index];
     const after = current.expected.tables[index];
-    if (before?.schema !== after?.schema || before?.table !== after?.table) fail("ORM_OWNED_STORE_IDENTITY_MISMATCH");
+    if (before?.schema !== after?.schema || before?.table !== after?.table) fail("ORM_OWNED_STORE_IDENTITY_MISMATCH", `${storeName(registration.definition)}: its entities changed after the module was declared; declare them once`);
   }
 }
 
@@ -106,30 +110,37 @@ export function ownedStoreRegistrations(snapshot: ModuleOwnedContributionSnapsho
   const graph = contributions.map((entry) => entry.payload);
   const records = graph.flatMap((entry) => entry.owned === undefined ? [] : [entry.owned]);
   if (records.length === 0) return Object.freeze([]);
-  if (records.length > 128) fail("ORM_OWNED_STORE_OWNERSHIP_CONFLICT");
+  if (records.length > 128) fail("ORM_OWNED_STORE_OWNERSHIP_CONFLICT", `An application may declare at most 128 owned stores, got ${records.length}`);
   const keys = new Set<string>();
   const tables = new Set<string>();
   for (const record of records) {
     revalidateOwnedStoreRegistration(record);
     if (record.definition.ownedScope.schema === "public"
       && ["__bazis_orm_owned_stores_v1", "__bazis_orm_owned_stores_v1_pkey"].some((name) => name.startsWith(record.definition.ownedScope.tablePrefix))) {
-      fail("ORM_OWNED_STORE_OWNERSHIP_CONFLICT");
+      fail("ORM_OWNED_STORE_OWNERSHIP_CONFLICT", `${storeName(record.definition)} would own the bazis registry table __bazis_orm_owned_stores_v1; choose another tablePrefix`);
     }
     if ((record.definition.rejectIfPresent ?? []).some((scope) => scope.schema === "public"
       && ["__bazis_orm_owned_stores_v1", "__bazis_orm_owned_stores_v1_pkey"].some((name) => name.startsWith(scope.tablePrefix)))) {
-      fail("ORM_OWNED_STORE_OWNERSHIP_CONFLICT");
+      fail("ORM_OWNED_STORE_OWNERSHIP_CONFLICT", `${storeName(record.definition)}: rejectIfPresent would cover the bazis registry table __bazis_orm_owned_stores_v1`);
     }
-    if ((record.definition.rejectIfPresent ?? []).some((scope) => overlaps(record.definition.ownedScope, scope))) {
-      fail("ORM_OWNED_STORE_OWNERSHIP_CONFLICT");
+    const rejectedOwn = (record.definition.rejectIfPresent ?? []).find((scope) => overlaps(record.definition.ownedScope, scope));
+    if (rejectedOwn) {
+      fail("ORM_OWNED_STORE_OWNERSHIP_CONFLICT", `${storeName(record.definition)}: rejectIfPresent (${scopeName(rejectedOwn)}) overlaps its own scope; ${OVERLAP_HINT}`);
     }
-    if (keys.has(record.definition.storeKey)) fail("ORM_OWNED_STORE_OWNERSHIP_CONFLICT");
+    if (keys.has(record.definition.storeKey)) fail("ORM_OWNED_STORE_OWNERSHIP_CONFLICT", `Owned store key "${record.definition.storeKey}" is declared by more than one ormBazis entry`);
     keys.add(record.definition.storeKey);
-    for (const other of records) if (other !== record && (overlaps(record.definition.ownedScope, other.definition.ownedScope) || (other.definition.rejectIfPresent ?? []).some((scope) => overlaps(record.definition.ownedScope, scope)))) fail("ORM_OWNED_STORE_OWNERSHIP_CONFLICT");
+    for (const other of records) {
+      if (other === record) continue;
+      if (overlaps(record.definition.ownedScope, other.definition.ownedScope)) fail("ORM_OWNED_STORE_OWNERSHIP_CONFLICT", `${storeName(record.definition)} overlaps the scope of owned store "${other.definition.storeKey}" (${scopeName(other.definition.ownedScope)}); ${OVERLAP_HINT}`);
+      const rejected = (other.definition.rejectIfPresent ?? []).find((scope) => overlaps(record.definition.ownedScope, scope));
+      if (rejected) fail("ORM_OWNED_STORE_OWNERSHIP_CONFLICT", `${storeName(record.definition)} lies in a scope that owned store "${other.definition.storeKey}" rejects (${scopeName(rejected)})`);
+    }
     for (const table of record.expected.tables) {
       const key = `${table.schema}.${table.table}`;
-      if (tables.has(key) || table.schema !== record.definition.ownedScope.schema || !table.table.startsWith(record.definition.ownedScope.tablePrefix)) fail("ORM_OWNED_STORE_OWNERSHIP_CONFLICT");
+      if (tables.has(key)) fail("ORM_OWNED_STORE_OWNERSHIP_CONFLICT", `Table "${table.schema}"."${table.table}" is mapped by more than one owned store entity`);
+      if (table.schema !== record.definition.ownedScope.schema || !table.table.startsWith(record.definition.ownedScope.tablePrefix)) fail("ORM_OWNED_STORE_OWNERSHIP_CONFLICT", `${storeName(record.definition)}: entity table "${table.schema}"."${table.table}" lies outside the store scope; name its tables with the prefix, for example "${record.definition.ownedScope.tablePrefix}${table.table}"`);
       tables.add(key);
-      for (const foreignKey of table.foreignKeys) if (foreignKey.target.schema !== record.definition.ownedScope.schema || !foreignKey.target.table.startsWith(record.definition.ownedScope.tablePrefix)) fail("ORM_OWNED_STORE_OWNERSHIP_CONFLICT");
+      for (const foreignKey of table.foreignKeys) if (foreignKey.target.schema !== record.definition.ownedScope.schema || !foreignKey.target.table.startsWith(record.definition.ownedScope.tablePrefix)) fail("ORM_OWNED_STORE_OWNERSHIP_CONFLICT", `${storeName(record.definition)}: table "${table.table}" has a foreign key to "${foreignKey.target.schema}"."${foreignKey.target.table}" outside the store; an owned store references only its own tables`);
     }
   }
   // The complete ORM graph is compiled only when an owned store is present. This
@@ -156,7 +167,8 @@ export function ownedStoreRegistrations(snapshot: ModuleOwnedContributionSnapsho
     for (const table of expected.tables) {
       const owner = records.find((record) => table.schema === record.definition.ownedScope.schema && table.table.startsWith(record.definition.ownedScope.tablePrefix));
       const rejected = records.some((record) => (record.definition.rejectIfPresent ?? []).some((scope) => table.schema === scope.schema && table.table.startsWith(scope.tablePrefix)));
-      if ((owner && owner !== entry.owned) || rejected) fail("ORM_OWNED_STORE_OWNERSHIP_CONFLICT");
+      if (owner && owner !== entry.owned) fail("ORM_OWNED_STORE_OWNERSHIP_CONFLICT", `${entry.context.name} maps table "${table.schema}"."${table.table}", which belongs to owned store "${owner.definition.storeKey}"; only the store's own context may map it`);
+      if (rejected) fail("ORM_OWNED_STORE_OWNERSHIP_CONFLICT", `${entry.context.name} maps table "${table.schema}"."${table.table}" in a scope an owned store rejects (rejectIfPresent)`);
     }
   }
   const result = Object.freeze(records);

package/library/orm/Repository/README.md

@@ -82,6 +82,9 @@ const DataModule = ormModule({
 ```
 
 `ormModule` exports the `IRepository` family token so importing modules can inject `repositoryFor(User)`.
+A feature module that declares `ormBazis` passes repositories on with its own
+`exports`: `exports: [IRepository]` opens the repositories of all its entities,
+`exports: [repositoryFor(User)]` (since 0.98.22) only that one.
 
 Turning repositories off:
 

package/library/orm/Schema/OrmOwnedStore.ts

@@ -28,14 +28,16 @@ const canonicalDefinitions = new WeakSet<object>();
 export function defineOrmOwnedStoreV1(definition: OrmOwnedStoreDefinitionV1): Readonly<OrmOwnedStoreDefinitionV1> {
   try {
     rejectProxy(definition);
-    const root = closedRecord(definition, ["contract", "storeKey", "formatVersion", "ownedScope", "rejectIfPresent"], ["contract", "storeKey", "formatVersion", "ownedScope"]);
+    const root = closedRecord(definition, ["contract", "storeKey", "formatVersion", "ownedScope", "rejectIfPresent"], ["contract", "storeKey", "formatVersion", "ownedScope"], "the definition");
     const contract = root.contract;
     const storeKey = root.storeKey;
     const formatVersion = root.formatVersion;
-    if (contract !== CONTRACT || !validString(storeKey, 128) || typeof formatVersion !== "number" || !Number.isSafeInteger(formatVersion) || formatVersion <= 0) throw identity();
-    const ownedScope = readScope(root.ownedScope);
+    if (contract !== CONTRACT) throw identity(`contract must be "${CONTRACT}"`);
+    if (!validString(storeKey, 128)) throw identity("storeKey must be a string of 1 to 128 bytes without control characters");
+    if (typeof formatVersion !== "number" || !Number.isSafeInteger(formatVersion) || formatVersion <= 0) throw identity("formatVersion must be a positive integer");
+    const ownedScope = readScope(root.ownedScope, "ownedScope");
     const rejectIfPresent = root.rejectIfPresent === undefined ? [] : readScopes(root.rejectIfPresent);
-    if (rejectIfPresent.some((scope) => sameScope(scope, ownedScope))) throw ownership();
+    if (rejectIfPresent.some((scope) => sameScope(scope, ownedScope))) throw ownership(`rejectIfPresent of "${storeKey}" lists its own ownedScope`);
     const canonicalRejects = uniqueSortedScopes(rejectIfPresent);
     const result: OrmOwnedStoreDefinitionV1 = canonicalRejects.length === 0
       ? { contract: CONTRACT, storeKey, formatVersion, ownedScope }
@@ -56,40 +58,41 @@ export function isDefinedOrmOwnedStoreV1(value: unknown): value is Readonly<OrmO
 
 function readScopes(value: unknown): readonly OrmCatalogScopeV1[] {
   rejectProxy(value);
-  if (!Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype) throw identity();
+  if (!Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype) throw identity("rejectIfPresent must be an array of { schema, tablePrefix }");
   const descriptors = Object.getOwnPropertyDescriptors(value);
   if (Object.getOwnPropertySymbols(value).length !== 0) throw identity();
-  if (value.length > maxRejectScopes) throw identity();
+  if (value.length > maxRejectScopes) throw identity(`rejectIfPresent may list at most ${maxRejectScopes} scopes`);
   const expected = new Set(["length", ...Array.from({ length: value.length }, (_, index) => String(index))]);
   if (Object.keys(descriptors).some((key) => !expected.has(key))) throw identity();
   const scopes: OrmCatalogScopeV1[] = [];
   for (let index = 0; index < value.length; index++) {
     const descriptor = descriptors[String(index)];
     if (!descriptor || !("value" in descriptor)) throw identity();
-    scopes.push(readScope(descriptor.value));
+    scopes.push(readScope(descriptor.value, `rejectIfPresent[${index}]`));
   }
   return scopes;
 }
 
-function readScope(value: unknown): OrmCatalogScopeV1 {
-  const record = closedRecord(value, ["schema", "tablePrefix"], ["schema", "tablePrefix"]);
-  if (!validString(record.schema, 63) || !validString(record.tablePrefix, 63)) throw identity();
+function readScope(value: unknown, path: string): OrmCatalogScopeV1 {
+  const record = closedRecord(value, ["schema", "tablePrefix"], ["schema", "tablePrefix"], path);
+  if (!validString(record.schema, 63) || !validString(record.tablePrefix, 63)) throw identity(`${path}.schema and ${path}.tablePrefix must be strings of 1 to 63 bytes without control characters`);
   return { schema: record.schema, tablePrefix: record.tablePrefix };
 }
 
-function closedRecord(value: unknown, allowed: readonly string[], required: readonly string[]): Record<string, unknown> {
+function closedRecord(value: unknown, allowed: readonly string[], required: readonly string[], path: string): Record<string, unknown> {
   rejectProxy(value);
-  if (value === null || typeof value !== "object") throw identity();
+  if (value === null || typeof value !== "object") throw identity(`${path} must be a plain object`);
   const prototype = Object.getPrototypeOf(value);
-  if (prototype !== Object.prototype && prototype !== null) throw identity();
+  if (prototype !== Object.prototype && prototype !== null) throw identity(`${path} must be a plain object`);
   if (Object.getOwnPropertySymbols(value).length !== 0) throw identity();
   const descriptors = Object.getOwnPropertyDescriptors(value);
   for (const key of Object.keys(descriptors)) {
-    if (!allowed.includes(key)) throw identity();
+    // JSON.stringify escapes control characters of a caller-chosen key.
+    if (!allowed.includes(key)) throw identity(`${path} has an unknown field ${JSON.stringify(key.slice(0, 64))}; allowed: ${allowed.join(", ")}`);
     const descriptor = descriptors[key]!;
-    if (!("value" in descriptor) || descriptor.value === undefined) throw identity();
+    if (!("value" in descriptor) || descriptor.value === undefined) throw identity(`${path}.${key} must be a plain value`);
   }
-  for (const key of required) if (!Object.hasOwn(descriptors, key)) throw identity();
+  for (const key of required) if (!Object.hasOwn(descriptors, key)) throw identity(`${path} is missing the field ${key}`);
   return Object.fromEntries(Object.entries(descriptors).map(([key, descriptor]) => [key, (descriptor as PropertyDescriptor & { value: unknown }).value]));
 }
 
@@ -118,6 +121,7 @@ function compareScope(left: OrmCatalogScopeV1, right: OrmCatalogScopeV1): number
 }
 function sameScope(left: OrmCatalogScopeV1, right: OrmCatalogScopeV1): boolean { return left.schema === right.schema && left.tablePrefix === right.tablePrefix; }
 function rejectProxy(value: unknown): void { if (value !== null && (typeof value === "object" || typeof value === "function") && types.isProxy(value)) throw identity(); }
-function identity(): OrmOwnedStoreAdmissionError { return new OrmOwnedStoreAdmissionError(IDENTITY_MISMATCH, IDENTITY_MISMATCH); }
-function ownership(): OrmOwnedStoreAdmissionError { return new OrmOwnedStoreAdmissionError(OWNERSHIP_CONFLICT, OWNERSHIP_CONFLICT); }
+/** Proxies and symbols keep the bare code: describing them could run caller traps. */
+function identity(reason?: string): OrmOwnedStoreAdmissionError { return new OrmOwnedStoreAdmissionError(IDENTITY_MISMATCH, reason === undefined ? IDENTITY_MISMATCH : `${IDENTITY_MISMATCH}: owned store definition is invalid: ${reason}.`); }
+function ownership(reason: string): OrmOwnedStoreAdmissionError { return new OrmOwnedStoreAdmissionError(OWNERSHIP_CONFLICT, `${OWNERSHIP_CONFLICT}: owned store definition is invalid: ${reason}.`); }
 function deepFreeze<T>(value: T): T { if (value && typeof value === "object") { for (const child of Object.values(value)) deepFreeze(child); Object.freeze(value); } return value; }

package/library/orm/Schema/OwnedStoreAdmission.ts

@@ -11,6 +11,7 @@ import type { OrmCatalogScopeV1, OrmOwnedStoreDefinitionV1 } from "./OrmOwnedSto
 import { isDefinedOrmOwnedStoreV1 } from "./OrmOwnedStore";
 import { failure, postgresOwnedStoreCapability, type OwnedStoreCreateOperationV1, type OwnedStoreIdentityInsertV1, type OwnedStoreSecondaryLockEntryV1 } from "../Providers/ormOwnedStoreRuntime";
 import { OrmOwnedStoreAdmissionError } from "../errors";
+import { explainOwnedStoreFailureV1, type OwnedStoreObservationV1 } from "./OwnedStoreExplain";
 import { types } from "node:util";
 export interface PreparedOwnedStoreV1 {
   readonly definition: Readonly<OrmOwnedStoreDefinitionV1>;
@@ -44,9 +45,25 @@ type LeaseState = {
 const leaseStates = new WeakMap<object, LeaseState>();
 const leaseCounts = new WeakMap<DatabaseProvider, WeakMap<object, number>>();
 const preimages = new Map<string, Buffer>();
+/**
+ * Admits the declared stores. The checks below fail closed with bare codes;
+ * on failure the code is explained from the snapshots read so far (see
+ * OwnedStoreExplain), outside every provider callback.
+ */
 export async function admitOwnedStoresV1(provider: DatabaseProvider, request: OwnedStoreAdmissionRequestV1): Promise<CommittedOwnedStoreAdmissionV1> {
+  const observed: OwnedStoreObservationV1 = {};
+  try {
+    return await admitOwnedStoresCoreV1(provider, request, observed);
+  } catch (error) {
+    if (!(error instanceof OrmOwnedStoreAdmissionError) || Object.getPrototypeOf(error) !== OrmOwnedStoreAdmissionError.prototype) throw error;
+    throw explainOwnedStoreFailureV1(error.code, observed);
+  }
+}
+
+async function admitOwnedStoresCoreV1(provider: DatabaseProvider, request: OwnedStoreAdmissionRequestV1, observed: OwnedStoreObservationV1): Promise<CommittedOwnedStoreAdmissionV1> {
   const admitted = prepare(request);
   const prepared = admitted.prepared;
+  observed.stores = prepared;
   const signal = admitted.signal;
   if (aborted(signal))
     throw failure("ORM_OWNED_STORE_LOCK_UNAVAILABLE");
@@ -76,6 +93,7 @@ export async function admitOwnedStoresV1(provider: DatabaseProvider, request: Ow
         throw failure("ORM_OWNED_STORE_PROVIDER_UNSUPPORTED");
       const definitions = prepared.map(item => item.definition);
       const registry = await operational(() => session.inspectRegistry()).then(snapshot => parseOwnedStoreRegistrySnapshotV1(snapshot, definitions, context));
+      observed.registry = registry;
       if (registry.state.kind === "present")
         validateFixedRegistryShapeV1(registry.state.shape);
       assertCurrent(registry, prepared);
@@ -84,6 +102,7 @@ export async function admitOwnedStoresV1(provider: DatabaseProvider, request: Ow
       const plan = lockPlan(prepared, rows);
       const locked = await session.lockSecondary(plan);
       const catalogue = await operational(() => locked.inspectCatalog(catalogueScopes)).then(snapshot => parseOwnedStoreCatalogSnapshotV1(snapshot, context));
+      observed.catalogue = catalogue;
       const semantic: OwnedStoreCatalogSemanticContextV1 = Object.freeze({
         stores: Object.freeze(prepared.map(item => Object.freeze({ definition: item.definition, expectedSchema: item.expected }))), requestedScopes: catalogueScopes
       });

package/library/orm/Schema/OwnedStoreExplain.ts

@@ -0,0 +1,103 @@
+import { OrmOwnedStoreAdmissionError, type OrmOwnedStoreAdmissionErrorCode } from "../errors";
+import type { OrmCatalogScopeV1, OrmOwnedStoreDefinitionV1 } from "./OrmOwnedStore";
+import type { OwnedStoreCatalogSnapshotV1, OwnedStoreRegistrySnapshotV1 } from "./OwnedStoreCatalog";
+
+/** What admission had already read when it failed; filled only with parsed, validated snapshots. */
+export interface OwnedStoreObservationV1 {
+  stores?: readonly { readonly definition: Readonly<OrmOwnedStoreDefinitionV1>; readonly modelHash: string; readonly ownedScopeHash: string }[];
+  registry?: OwnedStoreRegistrySnapshotV1;
+  catalogue?: OwnedStoreCatalogSnapshotV1;
+}
+
+const REGISTRY = "__bazis_orm_owned_stores_v1";
+
+/**
+ * Turns a bare admission code into a readable message. The checks themselves
+ * stay code-only; this runs after admission failed and recomputes the likely
+ * reason from the same trusted inputs. Names from the code (store keys,
+ * prefixes) are validated by `defineOrmOwnedStoreV1`; names read from the
+ * database are escaped and bounded. Row values and driver text never appear.
+ */
+export function explainOwnedStoreFailureV1(code: OrmOwnedStoreAdmissionErrorCode, observed: OwnedStoreObservationV1): OrmOwnedStoreAdmissionError {
+  const stores = observed.stores ?? [];
+  if (stores.length === 0) return new OrmOwnedStoreAdmissionError(code, code);
+  const rows = observed.registry?.state.kind === "present" ? observed.registry.state.rows : [];
+  const relations = (observed.catalogue?.relations ?? []).filter((relation) => relation.kind === "ordinaryTable");
+  const tablesIn = (scope: OrmCatalogScopeV1) => relations.filter((relation) => relation.schema === scope.schema && relation.name.startsWith(scope.tablePrefix)).map((relation) => relation.name);
+  const all = stores.map((store) => storeName(store.definition)).join(", ");
+  const reason = (() => {
+    switch (code) {
+      case "ORM_OWNED_STORE_IDENTITY_MISMATCH": {
+        for (const store of stores) {
+          const row = rows.find((item) => item.storeKey === store.definition.storeKey);
+          if (!row) continue;
+          if (Number(row.formatVersion) !== store.definition.formatVersion) return `${storeName(store.definition)} is registered with format version ${dbNumber(row.formatVersion)}, the code declares ${store.definition.formatVersion}. ${FROZEN}`;
+          if (row.ownedSchema !== store.definition.ownedScope.schema || row.tablePrefix !== store.definition.ownedScope.tablePrefix) return `${storeName(store.definition)} is registered with schema ${dbName(row.ownedSchema)}, prefix ${dbName(row.tablePrefix)}. ${FROZEN}`;
+          if (row.modelHash !== store.modelHash) return `${storeName(store.definition)}: its model changed since the store was created (tables, columns, keys, indexes or their names). ${FROZEN}`;
+        }
+        return `${all}: the registered identity does not match the code. ${FROZEN}`;
+      }
+      case "ORM_OWNED_STORE_IDENTITY_MISSING": {
+        for (const store of stores) {
+          if (rows.some((row) => row.storeKey === store.definition.storeKey)) continue;
+          const occupied = tablesIn(store.definition.ownedScope);
+          if (occupied.length > 0) return `${storeName(store.definition)} is not registered yet, but its scope already contains tables that no owned store registered: ${names(occupied)}. Remove them, or choose another tablePrefix.`;
+        }
+        return `${all}: the store scope contains tables that are not registered in ${REGISTRY}. Remove them, or choose another tablePrefix.`;
+      }
+      case "ORM_OWNED_STORE_OWNERSHIP_CONFLICT": {
+        for (const store of stores) {
+          for (const row of rows) {
+            if (row.storeKey === store.definition.storeKey) continue;
+            if (overlap(store.definition.ownedScope, { schema: row.ownedSchema, tablePrefix: row.tablePrefix })) return `${storeName(store.definition)} overlaps the registered owned store ${dbName(row.storeKey)} (schema ${dbName(row.ownedSchema)}, prefix ${dbName(row.tablePrefix)}); two prefixes overlap when one starts with the other, so "notes_" and "notes_v2_" overlap while "notes_" and "notesv2_" do not.`;
+          }
+          for (const rejected of store.definition.rejectIfPresent ?? []) {
+            const left = tablesIn(rejected);
+            if (left.length > 0) return `${storeName(store.definition)} does not start while tables of the rejected scope (schema "${rejected.schema}", prefix "${rejected.tablePrefix}") exist: ${names(left)}. Move their data and drop them, together with their row in ${REGISTRY}.`;
+          }
+        }
+        return `${all}: the store scope conflicts with another owned store or with a foreign key between different stores.`;
+      }
+      case "ORM_OWNED_STORE_DRIFT": {
+        // Only claim what the snapshots show: an unreadable catalogue is not a changed model.
+        if (observed.registry !== undefined && observed.catalogue === undefined) return `${all}: the store scope contains an object bazis does not expect there (for example a table with an unusual name or definition, or one created by another tool), so it was not read. Remove such objects from the scope.`;
+        const touched = stores.flatMap((store) => tablesIn(store.definition.ownedScope));
+        return `${all}: the tables in the store scope${touched.length > 0 ? ` (${names(touched)})` : ""} differ from the store model; they were changed outside the store. Restore them, or move the data to a new store.`;
+      }
+      case "ORM_OWNED_STORE_CREATE_FAILED":
+        return `${all}: creating the store tables or their ${REGISTRY} rows failed. Check that the database user may create tables in the store schema, then start again.`;
+      case "ORM_OWNED_STORE_LOCK_UNAVAILABLE":
+        return `${all}: admission did not complete: the database connection failed, the start was cancelled, or another instance held the admission lock. Start again.`;
+      case "ORM_OWNED_STORE_PROVIDER_UNSUPPORTED":
+        return `${all}: owned stores need PostgreSQL through the shared @Infra connection (ormBazisConnect).`;
+    }
+  })();
+  // The code stays first: callers and tests match it in the message text.
+  return new OrmOwnedStoreAdmissionError(code, `${code}: ${reason}`);
+}
+
+const FROZEN = "An owned store does not change in place: declare a new storeKey with a tablePrefix that does not overlap the old one, move the data, then drop the old tables and their row in __bazis_orm_owned_stores_v1 (rejectIfPresent can guard against leftovers).";
+
+/** Code-side names were validated by defineOrmOwnedStoreV1: bounded, no control characters. */
+function storeName(definition: Readonly<OrmOwnedStoreDefinitionV1>): string {
+  return `Owned store "${definition.storeKey}" (schema "${definition.ownedScope.schema}", prefix "${definition.ownedScope.tablePrefix}")`;
+}
+
+/** A database-side identifier: JSON escapes quotes and control characters, so it cannot forge a log line. */
+function dbName(value: string): string {
+  const characters = [...value];
+  return `${JSON.stringify(characters.slice(0, 63).join(""))}${characters.length > 63 ? "…" : ""}`;
+}
+
+function dbNumber(value: string): string {
+  return /^\d{1,16}$/.test(value) ? value : dbName(value);
+}
+
+function names(values: readonly string[]): string {
+  const shown = values.slice(0, 5).map(dbName).join(", ");
+  return values.length > 5 ? `${shown} and ${values.length - 5} more` : shown;
+}
+
+function overlap(a: OrmCatalogScopeV1, b: OrmCatalogScopeV1): boolean {
+  return a.schema === b.schema && (a.tablePrefix.startsWith(b.tablePrefix) || b.tablePrefix.startsWith(a.tablePrefix));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.98.21",
+  "version": "0.98.23",
   "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
   "license": "MIT",
   "author": "Alexander Alenin",