bazis 0.98.22 → 0.98.24

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.22" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.24" }, 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/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/DbContext.ts

@@ -59,7 +59,7 @@ export abstract class DbContext {
   setByName(name: string): DbSet<Record<string, unknown>> {
     const model = this.#options.model.tryByName(name);
     if (!model) {
-      throw new EntityNotMappedError(name);
+      throw new EntityNotMappedError(name, "dynamic");
     }
     return new DbSet<Record<string, unknown>>(model, this.#runtime);
   }

package/library/orm/Metadata/DynamicModelBuilder.ts

@@ -184,13 +184,12 @@ function buildDynamicModelWithCtor(
   const keys = properties.filter((property) => property.isKey);
   if (def.primaryKey && keys.length > 0) throw new ModelBuildError(`Dynamic table "${def.name}" cannot combine primaryKey with legacy isKey.`);
   if (keys.length === 0 && !def.primaryKey) {
-    throw new ModelBuildError(`Dynamic table "${def.name}" has no primary key. Mark one field with isKey.`);
+    throw new ModelBuildError(`Dynamic table "${def.name}" has no primary key. Mark one field with isKey, or set primaryKey: { properties: [...] }.`);
   }
   if (keys.length > 1) {
+    const names = keys.map((key) => key.propertyName);
     throw new ModelBuildError(
-      `Dynamic table "${def.name}" declares multiple keys ("${keys
-        .map((key) => key.propertyName)
-        .join('", "')}"). Composite keys are not supported.`,
+      `Dynamic table "${def.name}" declares several isKey fields ("${names.join('", "')}"). Mark one field with isKey, or for a composite key use primaryKey: { properties: ["${names.join('", "')}"] }.`,
     );
   }
   const key = keys[0];

package/library/orm/Metadata/OrmModel.ts

@@ -70,6 +70,9 @@ export class OrmModel {
 
   /** Model for an instance, by its constructor. */
   requireForInstance(entity: object): EntityModel {
+    // Rows of dynamic tables are plain objects; their model is known only to setByName().
+    const prototype = Object.getPrototypeOf(entity);
+    if (prototype === Object.prototype || prototype === null) throw new EntityNotMappedError("Object", "plain");
     return this.requireByCtor(entity.constructor as EntityClass);
   }
 

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/library/orm/errors.ts

@@ -96,9 +96,14 @@ export class EntityNotFoundError extends OrmError {
 
 /** The class is not registered as an entity in this context. */
 export class EntityNotMappedError extends OrmError {
-  constructor(name: string) {
+  /** `dynamic`: looked up by name through `setByName`; `plain`: a plain object, not an entity instance. */
+  constructor(name: string, kind: "class" | "dynamic" | "plain" = "class") {
     super(
-      `Type "${name}" is not mapped in this DbContext. Add it to ormModule({ entities: [...] }) and annotate it with @Entity().`,
+      kind === "dynamic"
+        ? `No entity or dynamic model named "${name}" is registered in this DbContext. Register a dynamic table first: options.model.registerModel(buildDynamicModel({ name: "${name}", fields: [...] })).`
+        : kind === "plain"
+          ? `A plain object is not an entity class. For a dynamic table add the row through its set: db.setByName("Table").add(row).`
+          : `Type "${name}" is not mapped in this DbContext. Add it to ormModule({ entities: [...] }) and annotate it with @Entity().`,
     );
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.98.22",
+  "version": "0.98.24",
   "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",