@stacksjs/database 0.70.45 → 0.70.54

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2023 Open Web Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/auth-tables.d.ts

@@ -1,4 +1,60 @@
+import { sqlHelpers } from './sql-helpers';
+/**
+ * Defensive ALTER guaranteeing `users.email_verified_at` — the column
+ * `verifyEmail()` writes and the `verified` middleware reads, but which
+ * no generated users migration ever creates (stacksjs/stacks#1948).
+ * Pure builder so tests can assert per-dialect DDL without a live DB.
+ */
+export declare function usersEmailVerifiedAtSql(sql: SqlHelpers): string;
+/**
+ * Defensive ALTER guaranteeing `users.password_changed_at` — the column
+ * `resetPassword()` stamps and the token-validation paths read to bind a
+ * token's validity to the user's credential state (stacksjs/stacks#1957,
+ * a #1947 follow-up). No generated users migration creates it, so the
+ * same pure-builder + try/catch-swallow pattern as
+ * {@link usersEmailVerifiedAtSql} guarantees it from both schema paths.
+ */
+export declare function usersPasswordChangedAtSql(sql: SqlHelpers): string;
+/**
+ * Defensive ALTER guaranteeing `users.two_factor_secret` and
+ * `users.two_factor_enabled` — storage/framework/core/auth/src/
+ * authenticator.ts's TOTP helpers (generateTwoFactorSecret,
+ * verifyTwoFactorCode) have existed since early in the framework's
+ * history, but nothing ever created the columns a caller would persist
+ * them to, or the `passkeys`/`webauthn_challenges` tables
+ * storage/framework/core/auth/src/passkey.ts's WebAuthn helpers
+ * unconditionally query against — every passkey/2FA call site was
+ * dead code pointed at tables that never existed on any install,
+ * `buddy new` included. Same defensive ALTER + swallow pattern as
+ * {@link usersEmailVerifiedAtSql}.
+ */
+export declare function usersTwoFactorColumnsSql(sql: SqlHelpers): string[];
+/**
+ * Defensive ALTER guaranteeing `users.stripe_id` — the `billable`
+ * model trait's methods (createStripeCustomer/createOrGetStripeUser,
+ * used by `user.checkout(...)`) read and write this column
+ * unconditionally, but it's runtime-mixin-only (createBillableMethods
+ * in orm/define-model.ts, gated behind `traits.billable`): nothing in
+ * migration codegen ever creates the column itself, on any model, with
+ * or without the trait enabled. Every Stripe checkout call site was
+ * dead code pointed at a column that never existed, `buddy new`
+ * included — same shape as the passkeys/two_factor gap above (see
+ * stacksjs/status#1 Phase 9).
+ */
+export declare function usersStripeIdSql(): string;
+/**
+ * Runs every `users` guarantee-column ALTER (email_verified_at,
+ * password_changed_at, two_factor_secret, two_factor_enabled,
+ * stripe_id), each independently try/catch-swallowed so one
+ * already-existing column (or a not-yet-existing `users` table) never
+ * skips the others. Exported so `buddy migrate`/`migrate:fresh` can
+ * call it a second time after the numbered model migrations run — see
+ * the call site in {@link migrateAuthTables} for why a single call
+ * isn't enough.
+ */
+export declare function ensureUsersAuthColumns(sql: SqlHelpers, options?: { verbose?: boolean }): Promise<void>;
 /**
  * Create all authentication tables
  */
 export declare function migrateAuthTables(options?: { verbose?: boolean }): Promise<{ success: boolean, error?: string }>;
+declare type SqlHelpers = ReturnType<typeof sqlHelpers>;

package/dist/class-seeder.d.ts

@@ -1,4 +1,34 @@
+/**
+ * Topologically sort seeders by their declared `dependencies`. Ties
+ * (and dependency-free seeders) come out in alphabetical order so the
+ * result is deterministic across filesystems and runs.
+ *
+ * Unknown dependency names are dropped from the graph with a warning —
+ * they may refer to model-factory seeders that ran earlier in the
+ * `buddy seed` pipeline, or be stale references from a rename. The run
+ * doesn't fail because of them.
+ *
+ * Cycles throw with the offending class names in the error message.
+ *
+ * Exported for testing.
+ */
+export declare function topoSortSeeders(seeders: Array<{ name: string, dependencies?: string[] }>): string[];
 /*.ts`; an explicit `--class` filters to one.
+ *
+ * Ordering:
+ *   1. Files matching `*.ts` (excluding `_*.ts`) are imported.
+ *   2. If any seeder declares `dependencies`, the runnable set is
+ *      topologically sorted (alphabetical tie-break).
+ *   3. Otherwise, the alphabetical order from `Array.sort()` wins —
+ *      cheaper than the topo path and predictable across filesystems.
+ *
+ * Class-name filtering via `options.class` short-circuits both paths
+ * and runs only that one seeder. Cross-seeder dependencies are NOT
+ * resolved transitively in that mode — the caller takes responsibility
+ * for whatever prereqs are needed.
+ *
+ * See stacksjs/stacks#1855 for the original report of unsorted FS
+ * iteration producing zero-row seed runs.
  */
 export declare function runClassSeeders(options?: RunOptions): Promise<{ ran: string[], skipped: string[] }>;
 declare interface RunOptions {
@@ -9,8 +39,27 @@ declare interface RunOptions {
  * Base class for class-based seeders. Subclass this and implement
  * `async run()`. Seeders may call `this.call()` to invoke other
  * seeders, mirroring Laravel's nested-seeder pattern.
+ *
+ * Cross-seeder ordering can be declared explicitly via `dependencies`:
+ *
+ *   ```ts
+ *   export default class JudgeSeeder extends Seeder {
+ *     dependencies = ['CourtHouseSeeder']
+ *     async run() { ... }
+ *   }
+ *   ```
+ *
+ * The class name of each dependency is matched against the class names
+ * `runClassSeeders` discovered in the seeders directory. Unknown
+ * dependency names are warned about but don't fail the run (they may
+ * refer to a model-factory seeder run earlier in `buddy seed`).
+ *
+ * When no `dependencies` are declared, seeders run in alphabetical
+ * order — predictable across filesystems and good enough for projects
+ * that name seeders by data flow (CourtHouse → Judge → Review).
  */
 export declare abstract class Seeder {
+  dependencies?: string[];
   abstract run(): Promise<void> | void;
   protected call(other: new () => Seeder): Promise<void>;
 }

package/dist/database.d.ts

@@ -1,4 +1,4 @@
-import type { QueryBuilder, QueryBuilderConfig, SupportedDialect } from 'bun-query-builder';
+import type { QueryBuilder, QueryBuilderConfig, SupportedDialect } from '@stacksjs/query-builder';
 /**
  * Create a database connection with the given options
  */
@@ -74,12 +74,13 @@ export declare class Database {
   get query(): QueryBuilder<any>;
   initialize(): void;
   switchDriver(driver: SupportedDialect, connection: DatabaseConnectionConfig): void;
-  close(): void;
+  close(): Promise<void>;
   static fromConfig(config: {
     default: SupportedDialect
     connections: {
       sqlite?: { database: string }
       mysql?: { name: string, host?: string, port?: number, username?: string, password?: string }
+      singlestore?: { name: string, host?: string, port?: number, username?: string, password?: string }
       postgres?: { name: string, host?: string, port?: number, username?: string, password?: string }
     }
   }, env?: string): Database;

package/dist/driver-config.d.ts

@@ -1,4 +1,4 @@
-import type { SupportedDialect } from 'bun-query-builder';
+import type { SupportedDialect } from '@stacksjs/query-builder';
 /**
  * Get the connection string for a given driver and configuration
  */
@@ -36,6 +36,16 @@ export declare const driverDefaults: {
   prefix: '';
   charset: 'utf8mb4';
   collation: 'utf8mb4_unicode_ci'
+};
+  singlestore: {
+  name: 'stacks';
+  host: '127.0.0.1';
+  port: 3306;
+  username: 'root';
+  password: '';
+  prefix: '';
+  charset: 'utf8mb4';
+  ssl: false
 };
   postgres: {
   name: 'stacks';
@@ -68,6 +78,24 @@ export declare interface MysqlConfig {
   charset?: string
   collation?: string
 }
+/**
+ * SingleStore specific configuration.
+ *
+ * SingleStore (formerly MemSQL) speaks the MySQL wire protocol, so it shares
+ * MySQL's connection shape. It diverges only in DDL (distributed tables with
+ * SHARD KEY / SORT KEY, no foreign keys) — handled by the migration generator,
+ * not by the connection layer.
+ */
+export declare interface SinglestoreConfig {
+  name: string
+  host?: string
+  port?: number
+  username?: string
+  password?: string
+  prefix?: string
+  charset?: string
+  ssl?: boolean
+}
 /**
  * PostgreSQL specific configuration
  */
@@ -106,6 +134,7 @@ export declare interface DynamoDbConfig {
 export declare interface DatabaseConnections {
   sqlite?: SqliteConfig
   mysql?: MysqlConfig
+  singlestore?: SinglestoreConfig
   postgres?: PostgresConfig
   dynamodb?: DynamoDbConfig
 }

package/dist/drivers/dynamodb.d.ts

@@ -2,11 +2,11 @@ import type { Model } from '@stacksjs/types';
 /**
  * Marshall a JS object to DynamoDB format
  */
-declare function marshall(obj: Record<string, any>): Record<string, any>;
+declare function marshall(obj: Record<string, unknown>): DynamoItem;
 /**
  * Unmarshall a DynamoDB object to JS format
  */
-declare function unmarshall(obj: Record<string, any>): Record<string, any>;
+declare function unmarshall(obj: DynamoItem): Record<string, unknown>;
 /**
  * Generate key pattern for an entity
  */
@@ -27,6 +27,32 @@ export declare function createDynamo(): DynamoClient;
  * DynamoDB client singleton
  */
 export declare const dynamo: DynamoClient;
+/**
+ * Minimal AWS-SDK `DynamoDBClient` shape — just the methods this
+ * driver calls. Typed locally so callers wiring their own SDK
+ * client into `setClient()` get a clear compile-time contract
+ * instead of a runtime "function not found" surprise.
+ */
+export declare interface DynamoSdkClient {
+  query: (req: Record<string, unknown>) => Promise<{
+    Items?: DynamoItem[]
+    Count?: number
+    ScannedCount?: number
+    LastEvaluatedKey?: DynamoItem
+  }>
+  scan: (req: Record<string, unknown>) => Promise<{
+    Items?: DynamoItem[]
+    Count?: number
+    ScannedCount?: number
+    LastEvaluatedKey?: DynamoItem
+  }>
+  getItem: (req: Record<string, unknown>) => Promise<{ Item?: DynamoItem }>
+  putItem: (req: Record<string, unknown>) => Promise<unknown>
+  deleteItem: (req: Record<string, unknown>) => Promise<unknown>
+  updateItem: (req: Record<string, unknown>) => Promise<unknown>
+  batchWriteItem: (req: Record<string, unknown>) => Promise<unknown>
+  transactWriteItems: (req: Record<string, unknown>) => Promise<unknown>
+}
 /**
  * DynamoDB connection configuration
  */
@@ -72,46 +98,72 @@ export declare interface SortKeyBuilder {
  * Batch write operation
  */
 export declare interface BatchWriteOperation {
-  put?: { entity: string, item: Record<string, any> }
+  put?: { entity: string, item: Record<string, unknown> }
   delete?: { entity: string, pk: string, sk: string }
 }
 /**
  * Transact write operation
  */
 export declare interface TransactWriteOperation {
-  put?: { entity: string, item: Record<string, any>, condition?: string }
-  update?: { entity: string, pk: string, sk?: string, set?: Record<string, any>, add?: Record<string, number>, remove?: string[] }
+  put?: { entity: string, item: Record<string, unknown>, condition?: string }
+  update?: { entity: string, pk: string, sk?: string, set?: Record<string, unknown>, add?: Record<string, number>, remove?: string[] }
   delete?: { entity: string, pk: string, sk: string, condition?: string }
   conditionCheck?: { entity: string, pk: string, sk: string, condition: string }
 }
 /**
  * Query result
  */
-export declare interface QueryResult<T = any> {
+export declare interface QueryResult<T = unknown> {
   items: T[]
   count: number
   scannedCount?: number
-  lastKey?: Record<string, any>
+  lastKey?: Record<string, unknown>
 }
+/**
+ * DynamoDB AttributeValue discriminated union (stacksjs/stacks#1894 T-8).
+ *
+ * Mirrors the wire format AWS SDK's `DynamoDBClient` produces and
+ * consumes, declared locally so this package doesn't take a hard
+ * dependency on `@aws-sdk/client-dynamodb` just for its types. Each
+ * concrete variant carries its own typed payload; consumers narrow
+ * via `'S' in attr` / etc.
+ *
+ * Why not just import from AWS SDK: the framework's DynamoDB driver
+ * ships as an optional peer integration. Pulling AWS SDK as a type-
+ * level dep would force every Stacks app to install it whether or
+ * not they use the driver.
+ */
+export type DynamoAttributeValue = | { S: string }
+  | { N: string }
+  | { B: Uint8Array | string }
+  | { BOOL: boolean }
+  | { NULL: true }
+  | { L: DynamoAttributeValue[] }
+  | { M: Record<string, DynamoAttributeValue> }
+  | { SS: string[] }
+  | { NS: string[] }
+  | { BS: Array<Uint8Array | string> }
+/** Marshalled item — the on-the-wire representation. */
+export type DynamoItem = Record<string, DynamoAttributeValue>;
 /**
  * Entity-centric query builder for DynamoDB
  */
-export declare class EntityQueryBuilder<T = any> {
-  constructor(client: any, tableName: string, config: { pkAttribute: string, skAttribute: string, entityTypeAttribute: string, keyDelimiter: string });
+export declare class EntityQueryBuilder<T = unknown> {
+  constructor(client: DynamoSdkClient | undefined, tableName: string, config: { pkAttribute: string, skAttribute: string, entityTypeAttribute: string, keyDelimiter: string });
   entity(entityType: string): this;
   pk(value: string): this;
   get sk(): SortKeyBuilder;
   index(indexName: string): this;
   project(...attributes: string[]): this;
-  filter(attribute: string, operator: string, value?: any): this;
-  where(attribute: string, value: any): this;
-  whereIn(attribute: string, values: any[]): this;
+  filter(attribute: string, operator: string, value?: unknown): this;
+  where(attribute: string, value: unknown): this;
+  whereIn(attribute: string, values: unknown[]): this;
   limit(count: number): this;
   asc(): this;
   desc(): this;
   consistent(): this;
-  startFrom(key: Record<string, any>): this;
-  toRequest(): Record<string, any>;
+  startFrom(key: Record<string, unknown>): this;
+  toRequest(): Record<string, unknown>;
   get(): Promise<T[]>;
   first(): Promise<T | undefined>;
   getAll(): Promise<T[]>;
@@ -123,18 +175,18 @@ export declare class EntityQueryBuilder<T = any> {
 declare class DynamoClient {
   connection(config: DynamoConnectionConfig): this;
   isConfigured(): boolean;
-  setClient(client: any): this;
-  getClient(): any;
+  setClient(client: DynamoSdkClient): this;
+  getClient(): DynamoSdkClient | undefined;
   registerEntity(mapping: SingleTableEntityMapping): this;
   registerModel(model: Model): this;
   getEntityMapping(entityType: string): SingleTableEntityMapping | undefined;
   entity<T = any>(entityType: string): EntityQueryBuilder<T>;
   batchWrite(operations: BatchWriteOperation[]): Promise<void>;
   transactWrite(operations: TransactWriteOperation[]): Promise<void>;
-  put(entity: string, item: Record<string, any>): Promise<void>;
+  put(entity: string, item: Record<string, unknown>): Promise<void>;
   get<T = any>(pk: string, sk?: string): Promise<T | undefined>;
   delete(pk: string, sk?: string): Promise<void>;
-  update(pk: string, sk: string | undefined, updates: Record<string, any>): Promise<void>;
+  update(pk: string, sk: string | undefined, updates: Record<string, unknown>): Promise<void>;
   getTableName(): string;
   getConfig(): {
     tableName: string

package/dist/drivers/helpers.d.ts

@@ -18,6 +18,12 @@ export declare function isArrayEqual(arr1: (number | undefined)[], arr2: (number
 export declare function findDifferingKeys(obj1: any, obj2: any): { key: string, max: number, min: number }[];
 export declare function fetchTables(): Promise<string[]>;
 export declare function getUpvoteTableName(model: Model, tableName: string): string | undefined;
+/**
+ * Foreign-key column of the likes pivot. MUST mirror the runtime default in
+ * orm/src/traits/likeable.ts (`${tableName.replace(/s$/, '')}_id`) — a pivot
+ * generated with any other column name is a table `like()` cannot write to.
+ */
+export declare function getLikeableForeignKey(model: Model, tableName: string): string;
 export declare function prepareNumberColumnType(validator: NumberValidatorType, driver?: string): string;
 // Add new function for enum column types
 export declare function prepareEnumColumnType(validator: EnumValidatorType, driver?: string): string;

package/dist/drivers/mysql.d.ts

@@ -3,5 +3,5 @@ export declare function resetMysqlDatabase(): Promise<Ok<string, never>>;
 export declare function dropMysqlTables(): Promise<void>;
 export declare function generateMysqlMigration(modelPath: string): Promise<void>;
 export declare function generateMysqlTraitMigrations(): Promise<void>;
-export declare function createMysqlForeignKeyMigrations(modelPath: string): Promise<void>;
 export declare function createAlterTableMigration(modelPath: string): Promise<void>;
+export declare function generateIndexCreationSQL(tableName: string, index: { name: string, columns: string[], unique?: boolean, where?: string }): string;

package/dist/drivers/postgres.d.ts

@@ -3,5 +3,5 @@ export declare function dropPostgresTables(): Promise<void>;
 export declare function generatePostgresTraitMigrations(): Promise<void>;
 export declare function resetPostgresDatabase(): Promise<Ok<string, never>>;
 export declare function generatePostgresMigration(modelPath: string): Promise<void>;
-export declare function createPostgresForeignKeyMigrations(modelPath: string): Promise<void>;
+export declare function generateIndexCreationSQL(tableName: string, index: { name: string, columns: string[], unique?: boolean, where?: string }): string;
 export declare function fetchPostgresTables(): Promise<string[]>;

package/dist/drivers/sqlite.d.ts

@@ -5,19 +5,16 @@ export declare function resetSqliteDatabase(): Promise<Ok<string, never>>;
  * cheap to re-apply, but each one is a no-op once set so repeated calls
  * during dev hot-reload don't accumulate state.
  *
- * - WAL journaling: lets readers and a single writer proceed in parallel
- *   instead of serializing every transaction. Critical for dev where the
- *   API server, queue worker, and dashboard all hit the same file.
- * - foreign_keys=ON: SQLite ships with FK enforcement OFF by default.
- *   Without this, FK constraint violations are silently ignored — broken
- *   relations land in the DB and fail later, far from the original write.
- * - busy_timeout: backs off when the file is locked by another writer
- *   instead of failing the whole query immediately.
+ * Connection bootstrap now applies SQLITE_BOOTSTRAP_PRAGMAS automatically
+ * inside @stacksjs/query-builder's wrapped `createQueryBuilder`
+ * (stacksjs/stacks#1951); this export remains for explicit re-application.
+ * See the shared list in @stacksjs/query-builder for what each pragma does
+ * and why it must be set per connection.
  */
 export declare function configureSqlitePragmas(): Promise<void>;
 export declare function dropSqliteTables(): Promise<void>;
 export declare function fetchSqliteFile(): string;
 export declare function fetchTestSqliteFile(): string;
 export declare function generateSqliteMigration(modelPath: string): Promise<void>;
-export declare function createSqliteForeignKeyMigrations(_modelPath: string): Promise<void>;
 export declare function copyModelFiles(modelPath: string): Promise<void>;
+export declare function generateIndexCreationSQL(tableName: string, index: { name: string, columns: string[], unique?: boolean, where?: string }): string;

package/dist/factory.d.ts

@@ -0,0 +1,41 @@
+import type { Attribute, Model } from '@stacksjs/types';
+import type { SeedResult } from './seeder';
+/**
+ * Build the internal `SeederModel`-shaped payload that `seedModelDirect`
+ * expects from a public-API call. Pure function — exported separately
+ * so tests can assert the override-precedence rules without touching
+ * the database.
+ *
+ * Precedence (lowest → highest): per-attribute `factory` output →
+ * global `options.with` → per-row `options.rows[i]`. All keys are
+ * snake-cased before insert so callers can use the model's camelCase
+ * attribute names without thinking about column naming.
+ */
+export declare function buildSeederPayload(modelInput: unknown, options?: GenerateOptions): {
+  name: string
+  table: string
+  count: number
+  fixtures: Array<Record<string, unknown>>
+  attributes: Record<string, Attribute>
+  model: Model
+};
+/**
+ * Generate factory rows for a model and insert them. Designed to be
+ * called from a class seeder.
+ *
+ * Honours the model's per-attribute `factory: faker => …` declarations
+ * — exactly the same code path as the legacy auto-walker — but without
+ * the implicit "every model with `useSeeder` fires on every run"
+ * coupling. See stacksjs/stacks#1919 for the rationale.
+ */
+export declare function generate(modelInput: unknown, options?: GenerateOptions): Promise<SeedResult>;
+export declare const factory: {
+  
+};
+export declare interface GenerateOptions {
+  count?: number
+  fresh?: boolean
+  verbose?: boolean
+  with?: Record<string, unknown>
+  rows?: Array<Record<string, unknown>>
+}

package/dist/fk-audit.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Glob, but resilient to "directory doesn't exist yet" (the userland
+ * `app/Models/` directory in particular often doesn't exist when the
+ * audit runs in framework tests or scaffolded apps that haven't
+ * created any models yet). Avoids the Bun Glob ENOENT.
+ */
+export declare function safeGlob(pattern: string): string[];
+/**
+ * Walk every model file (user + framework defaults) and return the
+ * full list of declared `belongsTo` foreign keys.
+ *
+ * Convention: `Comment` with `belongsTo: ['Post']` implies the FK
+ * `comments.post_id → posts.id`. Same shape the migration generator
+ * uses, so we keep it consistent here. Other relationship types
+ * (`hasOne`, `hasMany`, `belongsToMany` through tables) imply FKs in
+ * the *other* direction or in pivot tables — we only check
+ * `belongsTo` here for the simplest, highest-signal audit.
+ */
+export declare function getDeclaredFKs(): Promise<DeclaredFK[]>;
+/**
+ * Query the live database for every foreign key constraint, returning
+ * a normalised shape. Dialect-aware: PRAGMA on SQLite,
+ * information_schema on MySQL / PostgreSQL.
+ */
+export declare function getLiveFKs(): Promise<LiveFK[]>;
+/**
+ * Diff declared FKs against live FKs. Returns the declared FKs that
+ * have no matching row in the live database — these are the silent
+ * "FK should be enforcing referential integrity but isn't" cases that
+ * motivated this audit.
+ *
+ * Match key is `fromTable.fromColumn → toTable.toColumn` (case-
+ * insensitive). Extra live FKs (present in DB but not in any model)
+ * are not reported — those usually come from manual migrations or
+ * external tooling, both legitimate.
+ */
+export declare function auditForeignKeys(): Promise<FkAuditResult>;
+/**
+ * Scan the live database for rows whose foreign key references a
+ * parent row that doesn't exist. SQLite's `PRAGMA foreign_key_check`
+ * does this regardless of the `foreign_keys` pragma state and excludes
+ * NULL-FK rows. The violating column is resolved by joining the
+ * reported `fkid` against `PRAGMA foreign_key_list(table)`.
+ */
+export declare function findFkOrphans(dialect?: 'sqlite' | 'mysql' | 'postgres' | 'other'): Promise<FkOrphanReport>;
+// stacksjs/stacks#1916 — Foreign-key audit. Compares each model's
+// declared `belongsTo` relationships against the FKs that actually
+// exist in the live database. Drives `buddy doctor`'s FK integrity
+// check, surfaces the "you flipped DB_CONNECTION but the FKs didn't
+// follow" failure mode that motivated #1915 and #1916.
+//
+// Two halves:
+//
+//   1. Declared FKs: walk model files, look at `belongsTo`, compute
+//      the implied FK shape `{ fromTable, fromColumn, toTable,
+//      toColumn }`. Convention is `<related>_id` → `<related>.id`,
+//      same as the migration generator.
+//
+//   2. Live FKs: query the live database. SQLite via
+//      `PRAGMA foreign_key_list("…")`, MySQL/Postgres via
+//      `information_schema.key_column_usage`.
+export declare interface DeclaredFK {
+  fromTable: string
+  fromColumn: string
+  toTable: string
+  toColumn: string
+  model: string
+}
+export declare interface LiveFK {
+  fromTable: string
+  fromColumn: string
+  toTable: string
+  toColumn: string
+}
+export declare interface FkAuditResult {
+  declared: DeclaredFK[]
+  live: LiveFK[]
+  missing: DeclaredFK[]
+}
+// stacksjs/stacks#1951 — FK orphan detection. FK enforcement flipped
+// ON (utils.ts bootstrap pragmas) against databases that were written
+// while `foreign_keys = OFF`, so legacy rows can reference parents that
+// no longer exist. Those orphans silently turn previously-working
+// deletes/inserts into runtime FK failures. This READ-ONLY scan finds
+// them so `buddy doctor` can report before they bite.
+//
+// SQLite-specific: MySQL/Postgres enforce FKs natively, so the
+// FK-off-legacy-data failure mode can't arise there — we degrade to
+// `supported: false` rather than run an expensive per-FK anti-join.
+export declare interface FkOrphan {
+  table: string
+  column: string
+  parent: string
+  count: number
+  sampleRowids: number[]
+}
+export declare interface FkOrphanReport {
+  supported: boolean
+  total: number
+  orphans: FkOrphan[]
+}

package/dist/index.d.ts

@@ -10,12 +10,16 @@ export type {
   PostgresConfig,
   SqliteConfig,
 } from './driver-config';
+export type { GenerateOptions } from './factory';
+export type { ScaffoldOptions, ScaffoldResult } from './seed-scaffold';
+export type { DeclaredFK, FkAuditResult, FkOrphan, FkOrphanReport, LiveFK } from './fk-audit';
+export type { DeclaredUnique, LiveUniqueIndex, UniqueAuditResult } from './unique-audit';
 export type {
   QueryBuilder,
   QueryBuilderConfig,
   Seeder as QueryBuilderSeeder,
   SupportedDialect,
-} from 'bun-query-builder';
+} from '@stacksjs/query-builder';
 export type {
   DynamoConnectionConfig,
   SingleTableEntityMapping,
@@ -85,20 +89,53 @@ export { Seeder, runClassSeeders } from './class-seeder';
 export { addColumnSafely, backfillInBatches, renameColumnSafely } from './safe-migrations';
 // Seeding
 export * from './seeder';
+// stacksjs/stacks#1919 — public factory API. The canonical replacement
+// for the legacy `useSeeder` trait + auto-walker. Class seeders call
+// `factory.generate(Model, opts)` explicitly so there's one
+// orchestration layer per table, no double-fire on tables that have
+// both a `useSeeder` trait and a class seeder file.
+export { factory, generate as factoryGenerate } from './factory';
+// `buddy seed:scaffold` codemod — generates class-seeder files for
+// every model with a `useSeeder` trait, easing the migration off the
+// auto-walker.
+export { scaffoldClassSeedersFromModels, renderSeederFile } from './seed-scaffold';
 // Driver utilities
 export * from './drivers/index';
 // Custom migrations (jobs, errors, etc.)
 export * from './custom/index';
 // Auth tables migration
 export * from './auth-tables';
+// uuid column guarantee for `useUuid` models (stacksjs/status#1 Phase 9)
+export * from './uuid-columns';
+// Notification tables migration (stacksjs/stacks#1937)
+export { migrateNotificationTables } from './notification-tables';
+// RBAC tables migration (stacksjs/stacks#1941 Phase A)
+export { migrateRbacTables } from './rbac-tables';
 // SQL dialect helpers & connection defaults
 export * from './sql-helpers';
 export * from './defaults';
+// Foreign-key audit (stacksjs/stacks#1916) — compare declared
+// `belongsTo` relationships against live FKs.
+export { auditForeignKeys, findFkOrphans, getDeclaredFKs, getLiveFKs } from './fk-audit';
+// Unique-index drift audit (stacksjs/stacks#1952) — compare declared
+// `unique: true` attributes / indexes against live UNIQUE indexes.
+export { auditUniqueIndexes, getDeclaredUniques, getLiveUniqueIndexes } from './unique-audit';
+// Transaction context: AsyncLocalStorage-based scope so side-effect
+// emitters (queue dispatch, mailer send) can buffer themselves
+// until the surrounding `db.transaction(...)` commits
+// (stacksjs/stacks#1882).
+export {
+  __flushAfterCommitNow,
+  __pendingAfterCommitCount,
+  enqueueAfterCommit,
+  isInTransaction,
+  runInTransactionScope,
+} from './transaction-context';
 // Re-export bun-query-builder functions and types
 export {
   createQueryBuilder,
   setConfig,
-} from 'bun-query-builder';
+} from '@stacksjs/query-builder';
 // DynamoDB entity-centric API
 export {
   createDynamo,