@atscript/db 0.1.115 → 0.1.117

package/dist/consts-BzRfCcH2.cjs

@@ -0,0 +1,14 @@
+//#region src/shared/consts.ts
+/**
+* Space name used when a model has no `@db.space` annotation. The same
+* default is used by the ambient space registry in `@atscript/moost-db`
+* (which re-exports this constant).
+*/
+const DEFAULT_DB_SPACE = "default";
+//#endregion
+Object.defineProperty(exports, "DEFAULT_DB_SPACE", {
+	enumerable: true,
+	get: function() {
+		return DEFAULT_DB_SPACE;
+	}
+});

package/dist/consts-C_-5_pFq.mjs

@@ -0,0 +1,9 @@
+//#region src/shared/consts.ts
+/**
+* Space name used when a model has no `@db.space` annotation. The same
+* default is used by the ambient space registry in `@atscript/moost-db`
+* (which re-exports this constant).
+*/
+const DEFAULT_DB_SPACE = "default";
+//#endregion
+export { DEFAULT_DB_SPACE as t };

package/dist/{db-view-UfGVUAol.cjs → db-view-DnWm-ddS.cjs}

@@ -2063,7 +2063,7 @@ var AtscriptDbReadable = class {
 	* Public entry point for relation loading. Used by adapters for nested $with delegation.
 	*/
 	async loadRelations(rows, withRelations) {
-		const { loadRelationsImpl } = await Promise.resolve().then(() => require("./relation-loader-Desvk9Ql.cjs")).then((n) => n.relation_loader_exports);
+		const { loadRelationsImpl } = await Promise.resolve().then(() => require("./relation-loader-BnUgJsUG.cjs")).then((n) => n.relation_loader_exports);
 		return loadRelationsImpl(rows, withRelations, this);
 	}
 	/**

package/dist/index.cjs

@@ -1,6 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_db_error = require("./db-error-DXwEzmYJ.cjs");
-const require_db_view = require("./db-view-UfGVUAol.cjs");
+const require_db_view = require("./db-view-DnWm-ddS.cjs");
+const require_consts = require("./consts-BzRfCcH2.cjs");
 const require_ops = require("./ops.cjs");
 const require_validator = require("./validator-BSk8lPH1.cjs");
 let node_crypto = require("node:crypto");
@@ -355,6 +356,7 @@ exports.AtscriptDbTable = require_db_view.AtscriptDbTable;
 exports.AtscriptDbView = require_db_view.AtscriptDbView;
 exports.BaseDbAdapter = require_db_view.BaseDbAdapter;
 exports.CasExhaustedError = require_db_error.CasExhaustedError;
+exports.DEFAULT_DB_SPACE = require_consts.DEFAULT_DB_SPACE;
 exports.DbEncryption = DbEncryption;
 exports.DbError = require_db_error.DbError;
 exports.DbSpace = DbSpace;

package/dist/index.d.cts

@@ -5,6 +5,14 @@ import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-val
 import { c as TArrayPatch, i as buildValidationContext, l as TDbPatch, n as ValidatorMode, o as forceNavNonOptional, r as buildDbValidator, s as isNavRelation, t as ValidationContext, u as getKeyProps } from "./validator-Crqe6vRW.cjs";
 import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, Uniquery as Uniquery$1, computeInsights, isPrimitive, walkFilter } from "@uniqu/core";
 
+//#region src/shared/consts.d.ts
+/**
+ * Space name used when a model has no `@db.space` annotation. The same
+ * default is used by the ambient space registry in `@atscript/moost-db`
+ * (which re-exports this constant).
+ */
+declare const DEFAULT_DB_SPACE = "default";
+//#endregion
 //#region src/strategies/relational-field-mapper.d.ts
 /**
  * Field mapper for relational adapters (e.g. SQLite, MySQL).
@@ -229,4 +237,4 @@ declare function createFailureCollector(what: string): {
   throwIfAny: () => void;
 };
 //#endregion
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, CasExhaustedError, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbQuery, type DbResponse, DbSpace, type DbValidationContext, DocumentFieldMapper, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type OwnPropsOf, type PrimaryKeyOf, RelationalFieldMapper, type TAdapterFactory, type TArrayPatch, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateResult, type TExistingColumn, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TIdDescriptor, type TIdentification, type TMetaResponse, type TMetadataOverrides, type TRelationInfo, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WithOptimisticRetryOptions, type WithRelation, assertGeoPoint, assertNoVersionWrites, buildDbValidator, buildValidationContext, computeInsights, createDbValidatorPlugin, createFailureCollector, decomposePatch, forceNavNonOptional, getDbFieldOp, getKeyProps, guardAggregate, guardFilter, guardQuery, isDbFieldOp, isGeoIndexableType, isGeoPointType, isNavRelation, isPrimitive, resolveDesignType, separateCas, separateFieldOps, translateQueryTree, walkFilter, withOptimisticRetry };
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, CasExhaustedError, DEFAULT_DB_SPACE, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbQuery, type DbResponse, DbSpace, type DbValidationContext, DocumentFieldMapper, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type OwnPropsOf, type PrimaryKeyOf, RelationalFieldMapper, type TAdapterFactory, type TArrayPatch, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateResult, type TExistingColumn, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TIdDescriptor, type TIdentification, type TMetaResponse, type TMetadataOverrides, type TRelationInfo, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WithOptimisticRetryOptions, type WithRelation, assertGeoPoint, assertNoVersionWrites, buildDbValidator, buildValidationContext, computeInsights, createDbValidatorPlugin, createFailureCollector, decomposePatch, forceNavNonOptional, getDbFieldOp, getKeyProps, guardAggregate, guardFilter, guardQuery, isDbFieldOp, isGeoIndexableType, isGeoPointType, isNavRelation, isPrimitive, resolveDesignType, separateCas, separateFieldOps, translateQueryTree, walkFilter, withOptimisticRetry };

package/dist/index.d.mts

@@ -5,6 +5,14 @@ import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-val
 import { c as TArrayPatch, i as buildValidationContext, l as TDbPatch, n as ValidatorMode, o as forceNavNonOptional, r as buildDbValidator, s as isNavRelation, t as ValidationContext, u as getKeyProps } from "./validator-Crqe6vRW.mjs";
 import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, Uniquery as Uniquery$1, computeInsights, isPrimitive, walkFilter } from "@uniqu/core";
 
+//#region src/shared/consts.d.ts
+/**
+ * Space name used when a model has no `@db.space` annotation. The same
+ * default is used by the ambient space registry in `@atscript/moost-db`
+ * (which re-exports this constant).
+ */
+declare const DEFAULT_DB_SPACE = "default";
+//#endregion
 //#region src/strategies/relational-field-mapper.d.ts
 /**
  * Field mapper for relational adapters (e.g. SQLite, MySQL).
@@ -229,4 +237,4 @@ declare function createFailureCollector(what: string): {
   throwIfAny: () => void;
 };
 //#endregion
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, CasExhaustedError, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbQuery, type DbResponse, DbSpace, type DbValidationContext, DocumentFieldMapper, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type OwnPropsOf, type PrimaryKeyOf, RelationalFieldMapper, type TAdapterFactory, type TArrayPatch, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateResult, type TExistingColumn, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TIdDescriptor, type TIdentification, type TMetaResponse, type TMetadataOverrides, type TRelationInfo, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WithOptimisticRetryOptions, type WithRelation, assertGeoPoint, assertNoVersionWrites, buildDbValidator, buildValidationContext, computeInsights, createDbValidatorPlugin, createFailureCollector, decomposePatch, forceNavNonOptional, getDbFieldOp, getKeyProps, guardAggregate, guardFilter, guardQuery, isDbFieldOp, isGeoIndexableType, isGeoPointType, isNavRelation, isPrimitive, resolveDesignType, separateCas, separateFieldOps, translateQueryTree, walkFilter, withOptimisticRetry };
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, CasExhaustedError, DEFAULT_DB_SPACE, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbQuery, type DbResponse, DbSpace, type DbValidationContext, DocumentFieldMapper, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type OwnPropsOf, type PrimaryKeyOf, RelationalFieldMapper, type TAdapterFactory, type TArrayPatch, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateResult, type TExistingColumn, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TIdDescriptor, type TIdentification, type TMetaResponse, type TMetadataOverrides, type TRelationInfo, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WithOptimisticRetryOptions, type WithRelation, assertGeoPoint, assertNoVersionWrites, buildDbValidator, buildValidationContext, computeInsights, createDbValidatorPlugin, createFailureCollector, decomposePatch, forceNavNonOptional, getDbFieldOp, getKeyProps, guardAggregate, guardFilter, guardQuery, isDbFieldOp, isGeoIndexableType, isGeoPointType, isNavRelation, isPrimitive, resolveDesignType, separateCas, separateFieldOps, translateQueryTree, walkFilter, withOptimisticRetry };

package/dist/index.mjs

@@ -1,5 +1,6 @@
 import { n as DbError, t as CasExhaustedError } from "./db-error-BHPXOKzc.mjs";
 import { C as NoopLogger, S as isGeoPointType, _ as DocumentFieldMapper, a as ApplicationIntegrity, b as TableMetadata, c as IntegrityStrategy, d as resolveDesignType, f as assertGeoPoint, g as RelationalFieldMapper, h as guardQuery, i as decomposePatch, l as NativeIntegrity, m as guardFilter, n as AtscriptDbTable, o as BaseDbAdapter, p as guardAggregate, r as assertNoVersionWrites, s as createFailureCollector, t as AtscriptDbView, u as AtscriptDbReadable, v as FieldMappingStrategy, x as isGeoIndexableType, y as UniquSelect } from "./db-view-BllUecjK.mjs";
+import { t as DEFAULT_DB_SPACE } from "./consts-C_-5_pFq.mjs";
 import { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, getDbFieldOp, isDbFieldOp, separateCas, separateFieldOps } from "./ops.mjs";
 import { a as isNavRelation, i as forceNavNonOptional, n as buildValidationContext, o as createDbValidatorPlugin, s as getKeyProps, t as buildDbValidator } from "./validator-C7plt6Kf.mjs";
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
@@ -339,4 +340,4 @@ function translateQueryTree(node, resolveField) {
 	return { [leftField]: { [comp.op]: comp.right } };
 }
 //#endregion
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, BaseDbAdapter, CasExhaustedError, DbEncryption, DbError, DbSpace, DocumentFieldMapper, FieldMappingStrategy, IntegrityStrategy, NativeIntegrity, NoopLogger, RelationalFieldMapper, TableMetadata, UniquSelect, assertGeoPoint, assertNoVersionWrites, buildDbValidator, buildValidationContext, computeInsights, createDbValidatorPlugin, createFailureCollector, decomposePatch, forceNavNonOptional, getDbFieldOp, getKeyProps, guardAggregate, guardFilter, guardQuery, isDbFieldOp, isGeoIndexableType, isGeoPointType, isNavRelation, isPrimitive, resolveDesignType, separateCas, separateFieldOps, translateQueryTree, walkFilter, withOptimisticRetry };
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, BaseDbAdapter, CasExhaustedError, DEFAULT_DB_SPACE, DbEncryption, DbError, DbSpace, DocumentFieldMapper, FieldMappingStrategy, IntegrityStrategy, NativeIntegrity, NoopLogger, RelationalFieldMapper, TableMetadata, UniquSelect, assertGeoPoint, assertNoVersionWrites, buildDbValidator, buildValidationContext, computeInsights, createDbValidatorPlugin, createFailureCollector, decomposePatch, forceNavNonOptional, getDbFieldOp, getKeyProps, guardAggregate, guardFilter, guardQuery, isDbFieldOp, isGeoIndexableType, isGeoPointType, isNavRelation, isPrimitive, resolveDesignType, separateCas, separateFieldOps, translateQueryTree, walkFilter, withOptimisticRetry };

package/dist/plugin.cjs

@@ -2,8 +2,132 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+require("./consts-BzRfCcH2.cjs");
 const require_validation_utils = require("./validation-utils-B7SXPkm7.cjs");
+let node_path = require("node:path");
+node_path = __toESM(node_path, 1);
+let node_url = require("node:url");
 let _atscript_core = require("@atscript/core");
+//#region src/plugin/manifest.ts
+const DB_ENTITY_ANNOTATIONS = [
+	"db.table",
+	"db.view",
+	"db.view.for"
+];
+function isDbEntity(node) {
+	return DB_ENTITY_ANNOTATIONS.some((name) => node.countAnnotations(name) > 0);
+}
+/**
+* Renders the model-manifest module: an inventory of every exported
+* `@db.table` / `@db.view` entity in the project, grouped by `@db.space`.
+*
+* The manifest is an inventory, NOT an action — consumers pass it (filtered,
+* extended with external-package models, split per space) to `syncSchema` /
+* `assertExposed` themselves.
+*
+* Runs on full builds for the `dts` / default formats (the same gate as
+* `atscript.d.ts`), so narrowed special-purpose builds (e.g. the `asc db sync`
+* temp compile) never shrink a committed manifest.
+*/
+async function generateModelManifest(options, output, format, repo) {
+	if (format !== "dts" && format !== _atscript_core.DEFAULT_FORMAT) return;
+	const manifestTarget = node_path.default.isAbsolute(options.path) ? options.path : node_path.default.join(repo.root, options.path);
+	const manifestDir = node_path.default.dirname(manifestTarget);
+	const sources = [...new Set(output.map((o) => o.source).filter(Boolean))].toSorted();
+	const docs = await Promise.all(sources.map((source) => repo.openDocument(source)));
+	const entries = [];
+	const usedAliases = /* @__PURE__ */ new Set();
+	for (const [i, doc] of docs.entries()) {
+		if (!doc) continue;
+		const source = sources[i];
+		const docPath = source.startsWith("file://") ? (0, node_url.fileURLToPath)(source) : source;
+		if (docPath === manifestTarget) continue;
+		let specifier = node_path.default.relative(manifestDir, docPath).split(node_path.default.sep).join("/");
+		if (!specifier.startsWith(".")) specifier = `./${specifier}`;
+		for (const [exportName, node] of [...doc.exports.entries()].toSorted(([a], [b]) => a.localeCompare(b))) {
+			if (!isDbEntity(node)) continue;
+			let alias = exportName;
+			for (let n = 1; usedAliases.has(alias); n++) alias = `${exportName}_${n}`;
+			usedAliases.add(alias);
+			entries.push({
+				alias,
+				exportName,
+				specifier,
+				isView: node.countAnnotations("db.view") > 0 || node.countAnnotations("db.view.for") > 0,
+				space: require_validation_utils.getAnnotationAlias(node, "db.space") || "default"
+			});
+		}
+	}
+	const imports = entries.map((e) => e.alias === e.exportName ? `import { ${e.exportName} } from "${e.specifier}"` : `import { ${e.exportName} as ${e.alias} } from "${e.specifier}"`);
+	const tables = entries.filter((e) => !e.isView).map((e) => e.alias);
+	const views = entries.filter((e) => e.isView).map((e) => e.alias);
+	const spaces = /* @__PURE__ */ new Map();
+	for (const e of entries) {
+		const group = spaces.get(e.space) ?? [];
+		group.push(e.alias);
+		spaces.set(e.space, group);
+	}
+	const spaceKeys = [...spaces.keys()].toSorted((a, b) => a === "default" ? -1 : b === "default" ? 1 : a.localeCompare(b));
+	const list = (items) => items.length ? `[${items.join(", ")}] as const` : "[]";
+	const content = [
+		"/* oxlint-disable */",
+		"/* eslint-disable */",
+		"/**",
+		" * 🪄 This file was generated by Atscript (@atscript/db model manifest)",
+		" * Do not edit this file!",
+		" *",
+		" * Re-generate with `npx asc -f dts`.",
+		" */",
+		...imports,
+		"",
+		`export const dbTables = ${list(tables)}`,
+		`export const dbViews = ${list(views)}`,
+		"/** Every @db.table / @db.view model in this project. */",
+		`export const atscriptModels = ${list(entries.map((e) => e.alias))}`,
+		"/** Models grouped by @db.space (absent annotation → \"default\"). */",
+		"export const modelsBySpace = {",
+		...spaceKeys.map((key) => `  ${JSON.stringify(key)}: ${list(spaces.get(key))},`),
+		"} as const",
+		""
+	].join("\n");
+	output.push({
+		fileName: node_path.default.basename(manifestTarget),
+		content,
+		source: "",
+		target: manifestTarget
+	});
+}
+//#endregion
 //#region src/plugin/annotations/agg.ts
 const dbAggAnnotations = { agg: {
 	sum: new _atscript_core.AnnotationSpec({
@@ -977,6 +1101,15 @@ const dbTableAnnotations = {
 			description: "Schema/namespace name."
 		}
 	}),
+	space: new _atscript_core.AnnotationSpec({
+		description: "Binds the entity to a named database space (a `DbSpace` — one per physical database) for apps running more than one database at once (e.g. MongoDB + PostgreSQL). Absent means the default space.\n\nConsumed by the generated model manifest (grouping in `modelsBySpace`) and by `@TableController(Model)` token binding, which resolves the space registered under this name via `provideDbSpace(space, name)`.\n\n**Example:**\n```atscript\n@db.table \"feed_runs\"\n@db.space \"analytics\"\nexport interface FeedRun { ... }\n```\n",
+		nodeType: ["interface"],
+		argument: {
+			name: "name",
+			type: "string",
+			description: "Space name (matches `provideDbSpace(space, name)`). Default: \"default\"."
+		}
+	}),
 	http: { path: new _atscript_core.AnnotationSpec({
 		description: "HTTP endpoint path where this table is served. Used by the UI for value-help on FK fields. Gets overwritten by the final controller prefix at runtime.\n\n**Example:**\n```atscript\n@db.table \"authors\"\n@db.http.path \"/authors\"\nexport interface Author { ... }\n```\n",
 		nodeType: ["interface"],
@@ -1306,14 +1439,19 @@ const dbViewAnnotations = { view: {
 } };
 //#endregion
 //#region src/plugin/index.ts
-const dbPlugin = () => ({
+const dbPlugin = (options) => ({
 	name: "db",
+	async buildEnd(output, format, repo) {
+		if (!options?.manifest) return;
+		await generateModelManifest(typeof options.manifest === "string" ? { path: options.manifest } : options.manifest, output, format, repo);
+	},
 	config() {
 		return {
 			annotations: { db: {
 				patch: dbColumnAnnotations.patch,
 				table: dbTableAnnotations.table,
 				schema: dbTableAnnotations.schema,
+				space: dbTableAnnotations.space,
 				index: dbIndexAnnotations.index,
 				column: dbColumnAnnotations.column,
 				default: dbColumnAnnotations.default,
@@ -1358,5 +1496,6 @@ const dbPlugin = () => ({
 	}
 });
 //#endregion
+exports.__exportAll = __exportAll;
 exports.dbPlugin = dbPlugin;
 exports.default = dbPlugin;

package/dist/plugin.d.cts

@@ -1,6 +1,25 @@
 import { TAtscriptPlugin } from "@atscript/core";
 
+//#region src/plugin/manifest.d.ts
+/** Options for the generated model manifest (see {@link dbPlugin}). */
+interface TDbManifestOptions {
+  /** Output path for the generated module, relative to the project root. */
+  path: string;
+}
+//#endregion
 //#region src/plugin/index.d.ts
-declare const dbPlugin: () => TAtscriptPlugin;
+/** Options for {@link dbPlugin}. */
+interface TDbPluginOptions {
+  /**
+   * When set, full builds (`asc -f dts`) additionally emit a generated model
+   * manifest module at this path (relative to the project root): an inventory
+   * of every exported `@db.table` / `@db.view` entity —
+   * `dbTables` / `dbViews` / `atscriptModels` / `modelsBySpace` (grouped by
+   * `@db.space`). Feed it to `syncSchema(db, atscriptModels)` so newly added
+   * models can't be silently forgotten.
+   */
+  manifest?: string | TDbManifestOptions;
+}
+declare const dbPlugin: (options?: TDbPluginOptions) => TAtscriptPlugin;
 //#endregion
-export { dbPlugin, dbPlugin as default };
+export { type TDbManifestOptions, type TDbPluginOptions, dbPlugin, dbPlugin as default };

package/dist/plugin.d.mts

@@ -1,6 +1,25 @@
 import { TAtscriptPlugin } from "@atscript/core";
 
+//#region src/plugin/manifest.d.ts
+/** Options for the generated model manifest (see {@link dbPlugin}). */
+interface TDbManifestOptions {
+  /** Output path for the generated module, relative to the project root. */
+  path: string;
+}
+//#endregion
 //#region src/plugin/index.d.ts
-declare const dbPlugin: () => TAtscriptPlugin;
+/** Options for {@link dbPlugin}. */
+interface TDbPluginOptions {
+  /**
+   * When set, full builds (`asc -f dts`) additionally emit a generated model
+   * manifest module at this path (relative to the project root): an inventory
+   * of every exported `@db.table` / `@db.view` entity —
+   * `dbTables` / `dbViews` / `atscriptModels` / `modelsBySpace` (grouped by
+   * `@db.space`). Feed it to `syncSchema(db, atscriptModels)` so newly added
+   * models can't be silently forgotten.
+   */
+  manifest?: string | TDbManifestOptions;
+}
+declare const dbPlugin: (options?: TDbPluginOptions) => TAtscriptPlugin;
 //#endregion
-export { dbPlugin, dbPlugin as default };
+export { type TDbManifestOptions, type TDbPluginOptions, dbPlugin, dbPlugin as default };

package/dist/plugin.mjs

@@ -1,5 +1,98 @@
+import "./consts-C_-5_pFq.mjs";
 import { a as getAnnotationAlias, c as getParentStruct, d as validateExclusiveWith, f as validateFieldBaseType, i as validateRefArgument, l as getParentTypeName, n as hasAnyViewAnnotation, o as getDbTableOwner, p as validateSiblingStringField, r as validateQueryScope, s as getNavTargetTypeName, t as findFKFieldsPointingTo, u as refActionAnnotation } from "./validation-utils-MWOP1Ts4.mjs";
-import { AnnotationSpec, isArray, isInterface, isPrimitive, isRef, isStructure } from "@atscript/core";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { AnnotationSpec, DEFAULT_FORMAT, isArray, isInterface, isPrimitive, isRef, isStructure } from "@atscript/core";
+//#region src/plugin/manifest.ts
+const DB_ENTITY_ANNOTATIONS = [
+	"db.table",
+	"db.view",
+	"db.view.for"
+];
+function isDbEntity(node) {
+	return DB_ENTITY_ANNOTATIONS.some((name) => node.countAnnotations(name) > 0);
+}
+/**
+* Renders the model-manifest module: an inventory of every exported
+* `@db.table` / `@db.view` entity in the project, grouped by `@db.space`.
+*
+* The manifest is an inventory, NOT an action — consumers pass it (filtered,
+* extended with external-package models, split per space) to `syncSchema` /
+* `assertExposed` themselves.
+*
+* Runs on full builds for the `dts` / default formats (the same gate as
+* `atscript.d.ts`), so narrowed special-purpose builds (e.g. the `asc db sync`
+* temp compile) never shrink a committed manifest.
+*/
+async function generateModelManifest(options, output, format, repo) {
+	if (format !== "dts" && format !== DEFAULT_FORMAT) return;
+	const manifestTarget = path.isAbsolute(options.path) ? options.path : path.join(repo.root, options.path);
+	const manifestDir = path.dirname(manifestTarget);
+	const sources = [...new Set(output.map((o) => o.source).filter(Boolean))].toSorted();
+	const docs = await Promise.all(sources.map((source) => repo.openDocument(source)));
+	const entries = [];
+	const usedAliases = /* @__PURE__ */ new Set();
+	for (const [i, doc] of docs.entries()) {
+		if (!doc) continue;
+		const source = sources[i];
+		const docPath = source.startsWith("file://") ? fileURLToPath(source) : source;
+		if (docPath === manifestTarget) continue;
+		let specifier = path.relative(manifestDir, docPath).split(path.sep).join("/");
+		if (!specifier.startsWith(".")) specifier = `./${specifier}`;
+		for (const [exportName, node] of [...doc.exports.entries()].toSorted(([a], [b]) => a.localeCompare(b))) {
+			if (!isDbEntity(node)) continue;
+			let alias = exportName;
+			for (let n = 1; usedAliases.has(alias); n++) alias = `${exportName}_${n}`;
+			usedAliases.add(alias);
+			entries.push({
+				alias,
+				exportName,
+				specifier,
+				isView: node.countAnnotations("db.view") > 0 || node.countAnnotations("db.view.for") > 0,
+				space: getAnnotationAlias(node, "db.space") || "default"
+			});
+		}
+	}
+	const imports = entries.map((e) => e.alias === e.exportName ? `import { ${e.exportName} } from "${e.specifier}"` : `import { ${e.exportName} as ${e.alias} } from "${e.specifier}"`);
+	const tables = entries.filter((e) => !e.isView).map((e) => e.alias);
+	const views = entries.filter((e) => e.isView).map((e) => e.alias);
+	const spaces = /* @__PURE__ */ new Map();
+	for (const e of entries) {
+		const group = spaces.get(e.space) ?? [];
+		group.push(e.alias);
+		spaces.set(e.space, group);
+	}
+	const spaceKeys = [...spaces.keys()].toSorted((a, b) => a === "default" ? -1 : b === "default" ? 1 : a.localeCompare(b));
+	const list = (items) => items.length ? `[${items.join(", ")}] as const` : "[]";
+	const content = [
+		"/* oxlint-disable */",
+		"/* eslint-disable */",
+		"/**",
+		" * 🪄 This file was generated by Atscript (@atscript/db model manifest)",
+		" * Do not edit this file!",
+		" *",
+		" * Re-generate with `npx asc -f dts`.",
+		" */",
+		...imports,
+		"",
+		`export const dbTables = ${list(tables)}`,
+		`export const dbViews = ${list(views)}`,
+		"/** Every @db.table / @db.view model in this project. */",
+		`export const atscriptModels = ${list(entries.map((e) => e.alias))}`,
+		"/** Models grouped by @db.space (absent annotation → \"default\"). */",
+		"export const modelsBySpace = {",
+		...spaceKeys.map((key) => `  ${JSON.stringify(key)}: ${list(spaces.get(key))},`),
+		"} as const",
+		""
+	].join("\n");
+	output.push({
+		fileName: path.basename(manifestTarget),
+		content,
+		source: "",
+		target: manifestTarget
+	});
+}
+//#endregion
 //#region src/plugin/annotations/agg.ts
 const dbAggAnnotations = { agg: {
 	sum: new AnnotationSpec({
@@ -973,6 +1066,15 @@ const dbTableAnnotations = {
 			description: "Schema/namespace name."
 		}
 	}),
+	space: new AnnotationSpec({
+		description: "Binds the entity to a named database space (a `DbSpace` — one per physical database) for apps running more than one database at once (e.g. MongoDB + PostgreSQL). Absent means the default space.\n\nConsumed by the generated model manifest (grouping in `modelsBySpace`) and by `@TableController(Model)` token binding, which resolves the space registered under this name via `provideDbSpace(space, name)`.\n\n**Example:**\n```atscript\n@db.table \"feed_runs\"\n@db.space \"analytics\"\nexport interface FeedRun { ... }\n```\n",
+		nodeType: ["interface"],
+		argument: {
+			name: "name",
+			type: "string",
+			description: "Space name (matches `provideDbSpace(space, name)`). Default: \"default\"."
+		}
+	}),
 	http: { path: new AnnotationSpec({
 		description: "HTTP endpoint path where this table is served. Used by the UI for value-help on FK fields. Gets overwritten by the final controller prefix at runtime.\n\n**Example:**\n```atscript\n@db.table \"authors\"\n@db.http.path \"/authors\"\nexport interface Author { ... }\n```\n",
 		nodeType: ["interface"],
@@ -1302,14 +1404,19 @@ const dbViewAnnotations = { view: {
 } };
 //#endregion
 //#region src/plugin/index.ts
-const dbPlugin = () => ({
+const dbPlugin = (options) => ({
 	name: "db",
+	async buildEnd(output, format, repo) {
+		if (!options?.manifest) return;
+		await generateModelManifest(typeof options.manifest === "string" ? { path: options.manifest } : options.manifest, output, format, repo);
+	},
 	config() {
 		return {
 			annotations: { db: {
 				patch: dbColumnAnnotations.patch,
 				table: dbTableAnnotations.table,
 				schema: dbTableAnnotations.schema,
+				space: dbTableAnnotations.space,
 				index: dbIndexAnnotations.index,
 				column: dbColumnAnnotations.column,
 				default: dbColumnAnnotations.default,

package/dist/rel.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_relation_loader = require("./relation-loader-Desvk9Ql.cjs");
 const require_nested_writer = require("./nested-writer-DoDhl3X3.cjs");
+const require_relation_loader = require("./relation-loader-BnUgJsUG.cjs");
 exports.batchInsertNestedFrom = require_nested_writer.batchInsertNestedFrom;
 exports.batchInsertNestedTo = require_nested_writer.batchInsertNestedTo;
 exports.batchInsertNestedVia = require_nested_writer.batchInsertNestedVia;

package/dist/{relation-loader-Desvk9Ql.cjs → relation-loader-BnUgJsUG.cjs}

@@ -1,18 +1,6 @@
-//#region \0rolldown/runtime.js
-var __defProp = Object.defineProperty;
-var __exportAll = (all, no_symbols) => {
-	let target = {};
-	for (var name in all) __defProp(target, name, {
-		get: all[name],
-		enumerable: true
-	});
-	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
-	return target;
-};
-//#endregion
 const require_nested_writer = require("./nested-writer-DoDhl3X3.cjs");
 //#region src/rel/relation-loader.ts
-var relation_loader_exports = /* @__PURE__ */ __exportAll({
+var relation_loader_exports = /* @__PURE__ */ require("./plugin.cjs").__exportAll({
 	ensureSelectIncludesFields: () => ensureSelectIncludesFields,
 	loadRelationsImpl: () => loadRelationsImpl
 });

package/dist/sync.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_db_view = require("./db-view-UfGVUAol.cjs");
+const require_db_view = require("./db-view-DnWm-ddS.cjs");
 //#region src/schema/schema-hash.ts
 /** Extracts sorted field snapshots from a readable's field descriptors. */
 function extractFieldSnapshots(fields, typeMapper) {
@@ -1018,17 +1018,38 @@ var SchemaSync = class {
 			for (const readable of allReadables) if (readable.renamedFrom) await this.store.deleteTableSnapshot(readable.renamedFrom);
 			await this.store.writeTrackedList(allReadables);
 			if (erroredNames.size === 0) await this.store.writeHash(hash);
-			return {
+			const result = {
 				status: "synced",
 				schemaHash: hash,
 				entries
 			};
+			this.reportOutcome(result, opts?.onError ?? "warn");
+			return result;
 		} finally {
 			heartbeat.stop();
 			await this.store.releaseLock(podId);
 		}
 	}
 	/**
+	* Surfaces the run outcome per the `onError` policy. Reporting must never be
+	* silently lost to the NoopLogger default — when no real logger is
+	* configured, warnings/errors go to `console` (a production consumer lost
+	* months of failed-index errors to the silent default).
+	*/
+	reportOutcome(result, onError) {
+		if (onError === "silent" || result.entries.length === 0) return;
+		const out = this.logger === require_db_view.NoopLogger ? console : this.logger;
+		const counts = /* @__PURE__ */ new Map();
+		for (const entry of result.entries) counts.set(entry.status, (counts.get(entry.status) ?? 0) + 1);
+		const summary = [...counts.entries()].map(([status, n]) => `${n} ${status}`).join(", ");
+		out.log(`[schema-sync] ${result.status}: ${summary}`);
+		const errored = result.entries.filter((e) => e.hasErrors);
+		if (errored.length === 0) return;
+		const lines = errored.map((e) => `[schema-sync] "${e.name}" failed: ${e.errors.join("; ") || e.status}`);
+		for (const line of lines) out.error(line);
+		if (onError === "throw") throw new Error(`[schema-sync] ${errored.length} entr${errored.length === 1 ? "y" : "ies"} failed:\n${lines.join("\n")}`);
+	}
+	/**
 	* Computes a dry-run plan showing what `run()` would do, without executing any DDL.
 	*/
 	async plan(types, opts) {
@@ -1274,6 +1295,30 @@ var SchemaSync = class {
 async function syncSchema(space, types, opts) {
 	return new SchemaSync(space).run(types, opts);
 }
+/**
+* Computes a dry-run plan showing what {@link syncSchema} would do, without
+* executing any DDL. Wraps {@link SchemaSync.plan}.
+*
+* The plan carries structured per-entry diffs (columns to add/rename/drop,
+* type/nullable/default changes, FK changes) plus a human-readable renderer:
+*
+* ```typescript
+* import { planSchema } from '@atscript/db/sync'
+*
+* const plan = await planSchema(db, [UsersType, PostsType])
+* if (plan.status === 'changes-needed') {
+*   for (const entry of plan.entries) {
+*     console.log(entry.print('plan').join('\n'))
+*   }
+* }
+* ```
+*
+* Note: reading the stored baseline still requires a live DB connection (the
+* snapshot lives in the `__atscript_control` table).
+*/
+async function planSchema(space, types, opts) {
+	return new SchemaSync(space).plan(types, opts);
+}
 //#endregion
 exports.SchemaSync = SchemaSync;
 exports.SyncEntry = SyncEntry;
@@ -1286,6 +1331,7 @@ exports.computeTableSnapshot = computeTableSnapshot;
 exports.computeViewSnapshot = computeViewSnapshot;
 exports.fkKey = fkKey;
 exports.hasForeignKeyChanges = hasForeignKeyChanges;
+exports.planSchema = planSchema;
 exports.readStoredSnapshot = readStoredSnapshot;
 exports.snapshotToExistingColumns = snapshotToExistingColumns;
 exports.snapshotToExistingTableOptions = snapshotToExistingTableOptions;

package/dist/sync.d.cts

@@ -240,6 +240,16 @@ interface TSyncOptions {
    * not thrown). Default: NoopLogger — pass `console` to surface them.
    */
   logger?: TGenericLogger;
+  /**
+   * What to do when the run finishes with errored entries (failed index/FK
+   * DDL, external-view checks, …):
+   * - `"warn"` (default) — emit a one-line summary plus per-entry error lines
+   *   via the configured logger, **falling back to `console` when no logger
+   *   is set** (errors are never silently swallowed by the NoopLogger default);
+   * - `"throw"` — same reporting, then throw after snapshots/locks are handled;
+   * - `"silent"` — legacy behavior: outcome is only observable on the result.
+   */
+  onError?: "throw" | "warn" | "silent";
 }
 interface TSyncResult {
   status: "up-to-date" | "synced" | "synced-by-peer";
@@ -278,6 +288,13 @@ declare class SchemaSync {
    * Runs schema synchronization with distributed locking.
    */
   run(types: TAtscriptAnnotatedType[], opts?: TSyncOptions): Promise<TSyncResult>;
+  /**
+   * Surfaces the run outcome per the `onError` policy. Reporting must never be
+   * silently lost to the NoopLogger default — when no real logger is
+   * configured, warnings/errors go to `console` (a production consumer lost
+   * months of failed-index errors to the silent default).
+   */
+  private reportOutcome;
   /**
    * Computes a dry-run plan showing what `run()` would do, without executing any DDL.
    */
@@ -372,5 +389,27 @@ declare function hasForeignKeyChanges(diff: TForeignKeyDiff): boolean;
  * @param opts - Lock TTL, wait timeout, force mode, etc.
  */
 declare function syncSchema(space: DbSpace, types: TAtscriptAnnotatedType[], opts?: TSyncOptions): Promise<TSyncResult>;
+/**
+ * Computes a dry-run plan showing what {@link syncSchema} would do, without
+ * executing any DDL. Wraps {@link SchemaSync.plan}.
+ *
+ * The plan carries structured per-entry diffs (columns to add/rename/drop,
+ * type/nullable/default changes, FK changes) plus a human-readable renderer:
+ *
+ * ```typescript
+ * import { planSchema } from '@atscript/db/sync'
+ *
+ * const plan = await planSchema(db, [UsersType, PostsType])
+ * if (plan.status === 'changes-needed') {
+ *   for (const entry of plan.entries) {
+ *     console.log(entry.print('plan').join('\n'))
+ *   }
+ * }
+ * ```
+ *
+ * Note: reading the stored baseline still requires a live DB connection (the
+ * snapshot lives in the `__atscript_control` table).
+ */
+declare function planSchema(space: DbSpace, types: TAtscriptAnnotatedType[], opts?: Pick<TSyncOptions, "force" | "safe">): Promise<TSyncPlan>;
 //#endregion
-export { SchemaSync, SyncEntry, type TFieldSnapshot, type TForeignKeyDiff, type TForeignKeySnapshot, type TSyncColors, type TSyncEntryStatus, type TSyncOptions, type TSyncPlan, type TSyncResult, type TTableSnapshot, type TViewSnapshot, computeColumnDiff, computeForeignKeyDiff, computeSchemaHash, computeTableHash, computeTableOptionDiff, computeTableSnapshot, computeViewSnapshot, fkKey, hasForeignKeyChanges, readStoredSnapshot, snapshotToExistingColumns, snapshotToExistingTableOptions, syncSchema };
+export { SchemaSync, SyncEntry, type TFieldSnapshot, type TForeignKeyDiff, type TForeignKeySnapshot, type TSyncColors, type TSyncEntryStatus, type TSyncOptions, type TSyncPlan, type TSyncResult, type TTableSnapshot, type TViewSnapshot, computeColumnDiff, computeForeignKeyDiff, computeSchemaHash, computeTableHash, computeTableOptionDiff, computeTableSnapshot, computeViewSnapshot, fkKey, hasForeignKeyChanges, planSchema, readStoredSnapshot, snapshotToExistingColumns, snapshotToExistingTableOptions, syncSchema };

package/dist/sync.d.mts

@@ -240,6 +240,16 @@ interface TSyncOptions {
    * not thrown). Default: NoopLogger — pass `console` to surface them.
    */
   logger?: TGenericLogger;
+  /**
+   * What to do when the run finishes with errored entries (failed index/FK
+   * DDL, external-view checks, …):
+   * - `"warn"` (default) — emit a one-line summary plus per-entry error lines
+   *   via the configured logger, **falling back to `console` when no logger
+   *   is set** (errors are never silently swallowed by the NoopLogger default);
+   * - `"throw"` — same reporting, then throw after snapshots/locks are handled;
+   * - `"silent"` — legacy behavior: outcome is only observable on the result.
+   */
+  onError?: "throw" | "warn" | "silent";
 }
 interface TSyncResult {
   status: "up-to-date" | "synced" | "synced-by-peer";
@@ -278,6 +288,13 @@ declare class SchemaSync {
    * Runs schema synchronization with distributed locking.
    */
   run(types: TAtscriptAnnotatedType[], opts?: TSyncOptions): Promise<TSyncResult>;
+  /**
+   * Surfaces the run outcome per the `onError` policy. Reporting must never be
+   * silently lost to the NoopLogger default — when no real logger is
+   * configured, warnings/errors go to `console` (a production consumer lost
+   * months of failed-index errors to the silent default).
+   */
+  private reportOutcome;
   /**
    * Computes a dry-run plan showing what `run()` would do, without executing any DDL.
    */
@@ -372,5 +389,27 @@ declare function hasForeignKeyChanges(diff: TForeignKeyDiff): boolean;
  * @param opts - Lock TTL, wait timeout, force mode, etc.
  */
 declare function syncSchema(space: DbSpace, types: TAtscriptAnnotatedType[], opts?: TSyncOptions): Promise<TSyncResult>;
+/**
+ * Computes a dry-run plan showing what {@link syncSchema} would do, without
+ * executing any DDL. Wraps {@link SchemaSync.plan}.
+ *
+ * The plan carries structured per-entry diffs (columns to add/rename/drop,
+ * type/nullable/default changes, FK changes) plus a human-readable renderer:
+ *
+ * ```typescript
+ * import { planSchema } from '@atscript/db/sync'
+ *
+ * const plan = await planSchema(db, [UsersType, PostsType])
+ * if (plan.status === 'changes-needed') {
+ *   for (const entry of plan.entries) {
+ *     console.log(entry.print('plan').join('\n'))
+ *   }
+ * }
+ * ```
+ *
+ * Note: reading the stored baseline still requires a live DB connection (the
+ * snapshot lives in the `__atscript_control` table).
+ */
+declare function planSchema(space: DbSpace, types: TAtscriptAnnotatedType[], opts?: Pick<TSyncOptions, "force" | "safe">): Promise<TSyncPlan>;
 //#endregion
-export { SchemaSync, SyncEntry, type TFieldSnapshot, type TForeignKeyDiff, type TForeignKeySnapshot, type TSyncColors, type TSyncEntryStatus, type TSyncOptions, type TSyncPlan, type TSyncResult, type TTableSnapshot, type TViewSnapshot, computeColumnDiff, computeForeignKeyDiff, computeSchemaHash, computeTableHash, computeTableOptionDiff, computeTableSnapshot, computeViewSnapshot, fkKey, hasForeignKeyChanges, readStoredSnapshot, snapshotToExistingColumns, snapshotToExistingTableOptions, syncSchema };
+export { SchemaSync, SyncEntry, type TFieldSnapshot, type TForeignKeyDiff, type TForeignKeySnapshot, type TSyncColors, type TSyncEntryStatus, type TSyncOptions, type TSyncPlan, type TSyncResult, type TTableSnapshot, type TViewSnapshot, computeColumnDiff, computeForeignKeyDiff, computeSchemaHash, computeTableHash, computeTableOptionDiff, computeTableSnapshot, computeViewSnapshot, fkKey, hasForeignKeyChanges, planSchema, readStoredSnapshot, snapshotToExistingColumns, snapshotToExistingTableOptions, syncSchema };

package/dist/sync.mjs

@@ -1017,17 +1017,38 @@ var SchemaSync = class {
 			for (const readable of allReadables) if (readable.renamedFrom) await this.store.deleteTableSnapshot(readable.renamedFrom);
 			await this.store.writeTrackedList(allReadables);
 			if (erroredNames.size === 0) await this.store.writeHash(hash);
-			return {
+			const result = {
 				status: "synced",
 				schemaHash: hash,
 				entries
 			};
+			this.reportOutcome(result, opts?.onError ?? "warn");
+			return result;
 		} finally {
 			heartbeat.stop();
 			await this.store.releaseLock(podId);
 		}
 	}
 	/**
+	* Surfaces the run outcome per the `onError` policy. Reporting must never be
+	* silently lost to the NoopLogger default — when no real logger is
+	* configured, warnings/errors go to `console` (a production consumer lost
+	* months of failed-index errors to the silent default).
+	*/
+	reportOutcome(result, onError) {
+		if (onError === "silent" || result.entries.length === 0) return;
+		const out = this.logger === NoopLogger ? console : this.logger;
+		const counts = /* @__PURE__ */ new Map();
+		for (const entry of result.entries) counts.set(entry.status, (counts.get(entry.status) ?? 0) + 1);
+		const summary = [...counts.entries()].map(([status, n]) => `${n} ${status}`).join(", ");
+		out.log(`[schema-sync] ${result.status}: ${summary}`);
+		const errored = result.entries.filter((e) => e.hasErrors);
+		if (errored.length === 0) return;
+		const lines = errored.map((e) => `[schema-sync] "${e.name}" failed: ${e.errors.join("; ") || e.status}`);
+		for (const line of lines) out.error(line);
+		if (onError === "throw") throw new Error(`[schema-sync] ${errored.length} entr${errored.length === 1 ? "y" : "ies"} failed:\n${lines.join("\n")}`);
+	}
+	/**
 	* Computes a dry-run plan showing what `run()` would do, without executing any DDL.
 	*/
 	async plan(types, opts) {
@@ -1273,5 +1294,29 @@ var SchemaSync = class {
 async function syncSchema(space, types, opts) {
 	return new SchemaSync(space).run(types, opts);
 }
+/**
+* Computes a dry-run plan showing what {@link syncSchema} would do, without
+* executing any DDL. Wraps {@link SchemaSync.plan}.
+*
+* The plan carries structured per-entry diffs (columns to add/rename/drop,
+* type/nullable/default changes, FK changes) plus a human-readable renderer:
+*
+* ```typescript
+* import { planSchema } from '@atscript/db/sync'
+*
+* const plan = await planSchema(db, [UsersType, PostsType])
+* if (plan.status === 'changes-needed') {
+*   for (const entry of plan.entries) {
+*     console.log(entry.print('plan').join('\n'))
+*   }
+* }
+* ```
+*
+* Note: reading the stored baseline still requires a live DB connection (the
+* snapshot lives in the `__atscript_control` table).
+*/
+async function planSchema(space, types, opts) {
+	return new SchemaSync(space).plan(types, opts);
+}
 //#endregion
-export { SchemaSync, SyncEntry, computeColumnDiff, computeForeignKeyDiff, computeSchemaHash, computeTableHash, computeTableOptionDiff, computeTableSnapshot, computeViewSnapshot, fkKey, hasForeignKeyChanges, readStoredSnapshot, snapshotToExistingColumns, snapshotToExistingTableOptions, syncSchema };
+export { SchemaSync, SyncEntry, computeColumnDiff, computeForeignKeyDiff, computeSchemaHash, computeTableHash, computeTableOptionDiff, computeTableSnapshot, computeViewSnapshot, fkKey, hasForeignKeyChanges, planSchema, readStoredSnapshot, snapshotToExistingColumns, snapshotToExistingTableOptions, syncSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db",
-  "version": "0.1.115",
+  "version": "0.1.117",
   "description": "Database adapter utilities for atscript.",
   "keywords": [
     "atscript",
@@ -71,14 +71,14 @@
     "access": "public"
   },
   "devDependencies": {
-    "@atscript/core": "^0.1.82",
-    "@atscript/typescript": "^0.1.82",
+    "@atscript/core": "^0.1.84",
+    "@atscript/typescript": "^0.1.84",
     "@uniqu/core": "^0.1.7",
-    "unplugin-atscript": "^0.1.82"
+    "unplugin-atscript": "^0.1.84"
   },
   "peerDependencies": {
-    "@atscript/core": "^0.1.82",
-    "@atscript/typescript": "^0.1.82",
+    "@atscript/core": "^0.1.84",
+    "@atscript/typescript": "^0.1.84",
     "@uniqu/core": "^0.1.7"
   },
   "scripts": {