@happyvertical/smrt-core 0.51.32 → 0.51.34

package/dist/registry.d.ts

@@ -1,14 +1,43 @@
-import { SmrtCollection, SmrtCollectionOptions } from './collection';
-import { CollectionCacheConfig } from './collection-cache';
-import { FieldOptions, MethodOptions } from './decorators/index.js';
-import { ClassEmbeddingConfig, ProjectEmbeddingConfig, ResolvedEmbeddingConfig } from './embeddings/types';
-import { ValidationError } from './errors';
-import { SmrtObject } from './object';
-import { RegistryDiagnostic } from './registry/diagnostics';
-import { RegisteredClass, RegisteredField, RelationshipMetadata, SmartObjectConfig, SmrtObjectConstructor, ValidatorFunction } from './registry/types';
-import { MethodDefinition, QualifiedClassName, SmartObjectDefinition, SmartObjectManifest, SmrtVisibility, ValidationRule } from './scanner/types.js';
-import { DatabaseEngine } from './schema/ddl/types.js';
-import { SchemaDefinition } from './schema/types.js';
+/**
+ * Global object registry for SMRT classes
+ *
+ * Maintains a central registry of all @smrt decorated classes, enabling
+ * module awareness, automatic API generation, and runtime introspection.
+ * The registry tracks class definitions, field metadata, and configuration
+ * options for code generation and runtime operations.
+ *
+ * @example Registering a class manually
+ * ```typescript
+ * import { ObjectRegistry } from '@happyvertical/smrt-core';
+ *
+ * ObjectRegistry.register(MyClass, {
+ *   api: { exclude: ['delete'] },
+ *   cli: true
+ * });
+ * ```
+ *
+ * @example Using the decorator (recommended)
+ * ```typescript
+ * import { smrt, field } from '@happyvertical/smrt-core';
+ *
+ * @smrt({ api: { exclude: ['delete'] } })
+ * class Product extends SmrtObject {
+ *   @field({ required: true })
+ *   name: string = '';
+ * }
+ * ```
+ */
+import { SmrtCollection, type SmrtCollectionOptions } from './collection';
+import type { CollectionCacheConfig } from './collection-cache';
+import type { FieldOptions, MethodOptions } from './decorators/index.js';
+import type { ClassEmbeddingConfig, ProjectEmbeddingConfig, ResolvedEmbeddingConfig } from './embeddings/types';
+import type { ValidationError } from './errors';
+import type { SmrtObject } from './object';
+import { type RegistryDiagnostic } from './registry/diagnostics';
+import type { RegisteredClass, RegisteredField, RelationshipMetadata, SmartObjectConfig, SmrtObjectConstructor, ValidatorFunction } from './registry/types';
+import type { MethodDefinition, QualifiedClassName, SmartObjectDefinition, SmartObjectManifest, SmrtVisibility, ValidationRule } from './scanner/types.js';
+import type { DatabaseEngine } from './schema/ddl/types.js';
+import type { SchemaDefinition } from './schema/types.js';
 export { isSmrtCollectionExtendsName, SMRT_COLLECTION_BASE_NAMES, } from './registry/collection-resolution';
 export { isFrameworkBaseClass } from './registry/framework-base-classes';
 export type { RelationshipMetadata, RelationshipType, SmartObjectConfig, } from './registry/types';

package/dist/relationship-loader.d.ts

@@ -1,4 +1,4 @@
-import { RelationshipMetadata } from './registry';
+import { type RelationshipMetadata } from './registry';
 /** Resolve the identity used for I/O, never the public display-name alias. */
 export declare function resolveRelationshipTargetName(relationship: RelationshipMetadata): Promise<string>;
 /** One inverse selection contract for lazy, eager and joined readers. */

package/dist/run-once.d.ts

@@ -1,4 +1,113 @@
-import { DatabaseInterface } from '@happyvertical/sql';
+/**
+ * Idempotency seam: run an action exactly once per submission (#3080).
+ *
+ * Every consumer with a form, a retried request, or a double-tapped button
+ * needs the same guard: a claim row, insert-only against a UNIQUE column
+ * (`claim_key`) in the SAME transaction as the work it guards, so a retry
+ * either runs the work once or replays the first attempt's stored result.
+ * This module is that primitive. It is DB/transaction-level — it takes a
+ * `DatabaseInterface`, not a `SmrtObject`/`SmrtCollection` — so it works
+ * outside SvelteKit and outside the ORM: any caller with a database handle
+ * and a JSON-serializable work result can use it. The claim insert itself
+ * is raw SQL (`## Concurrent submissions` below explains why), not the
+ * ORM's `SmrtObject`-level `_insertOnly` option.
+ *
+ * ## Key derivation (not the token alone)
+ *
+ * The claim key is the sha256 hex digest of the sorted-key-JSON encoding of
+ * `[tenantId, actor, token, contentDigest]`, where `contentDigest` is itself
+ * the sha256 hex digest of the sorted-key-JSON encoding of `content`
+ * ({@link digestRunOnceContent}). Sorted-key JSON ({@link stableStringify},
+ * `./knowledge-graph.ts`) makes the digest stable regardless of property
+ * insertion order.
+ *
+ * The token alone is NOT the key. A first attempt at this exact problem
+ * (reported against #3080) keyed on the token alone and silently collapsed
+ * two genuinely different submissions that happened to reuse one form's
+ * token. Folding in the content digest means a retry of the SAME submission
+ * (same token, same content) replays; a DIFFERENT submission through the
+ * same token (edited content before a resubmit) runs as its own claim.
+ * Folding in `tenantId` and `actor` means two tenants or two actors can never
+ * collide on the same claim even if a token were somehow shared between them.
+ *
+ * Neither the raw token nor the raw content is ever persisted — only their
+ * digests — so the claims table (`_smrt_run_once_claims`,
+ * `./system/schema.ts`) cannot leak submitted business data.
+ *
+ * ## Atomicity
+ *
+ * `runOnce()` opens its own `db.transaction()` (or nests under the caller's,
+ * per `@happyvertical/sql`'s own SAVEPOINT/`NestedTransactionError` rules —
+ * see that package's `DatabaseInterface.transaction` doc) and, inside it:
+ *
+ * 1. Inserts the claim row (`status: 'in_progress'`).
+ * 2. Runs `work(tx)`, passing the SAME transaction-bound handle, so the
+ *    caller's writes and the claim insert commit or roll back together.
+ * 3. Updates the claim row to `status: 'completed'` with the JSON-serialized
+ *    result, still inside the same transaction.
+ *
+ * If `work()` throws, the callback throws, and `db.transaction()`'s own
+ * "commits on success, rolls back on error" contract undoes the claim insert
+ * along with whatever `work()` partially wrote — a claim is never stranded
+ * `'in_progress'` by a failed attempt, and a retry with the same key can
+ * always run again.
+ *
+ * ## Concurrent submissions
+ *
+ * The claim insert uses `INSERT ... ON CONFLICT (claim_key) DO NOTHING
+ * RETURNING claim_key` (the same portable idiom `_smrt_migrations` already
+ * uses in `system/bootstrap.ts`), not a plain `INSERT` caught for a
+ * classified `unique_violation`. This matters on PostgreSQL specifically: a
+ * statement that raises an error aborts the WHOLE transaction ("current
+ * transaction is aborted, commands ignored until end of transaction block"),
+ * so a plain `INSERT` failing on the claim key would make every subsequent
+ * statement in the same transaction — including the very `SELECT` this
+ * function needs to read the winner's stored result back — fail too.
+ * `DO NOTHING` never raises: it returns zero rows instead, which this
+ * function reads as "lost the race" without ever touching the transaction's
+ * error state. SQLite and DuckDB both support the same `ON CONFLICT ... DO
+ * NOTHING` / `RETURNING` syntax, so one query works on every adapter.
+ *
+ * `@happyvertical/sql`'s single-connection adapters (SQLite, DuckDB, JSON)
+ * serialize `transaction()` calls on one connection: a second, concurrent
+ * `runOnce()` call does not begin its own transaction until the first one
+ * ends. PostgreSQL pools, but this `INSERT`'s arbiter still has to check the
+ * unique index against another transaction's uncommitted row of the same
+ * PRIMARY KEY, and blocks until that transaction resolves, then either
+ * no-ops (committed — the row exists) or inserts (rolled back — no row).
+ * Either way, two concurrent callers with the same key never both run
+ * `work()`: exactly one does, and the loser's `INSERT` returns zero rows —
+ * never an error — at which point it reads the now-committed claim row back
+ * and replays its stored result.
+ *
+ * ## Typed answers for a claim that is not (yet) a definite result
+ *
+ * A `runOnce()` conflict is a *definite* decision — the row exists — but
+ * whether it is safe to hand back a result depends on `status`. This mirrors
+ * the "refused vs unknown outcome" distinction #2990 drew for AssistantDock
+ * actions (`./errors.ts#RunOnceClaimError` carries the two codes):
+ *
+ * - `status: 'completed'` — replay the stored `result`. No error.
+ * - `status` anything else (still `'in_progress'`) — some execution holds
+ *   this key right now. `RunOnceClaimError.inFlight()`. Under this module's
+ *   own transaction semantics this is normally unreachable through
+ *   `runOnce()`-to-`runOnce()` races alone (the losing transaction can only
+ *   ever observe a COMMITTED row, and this module only ever commits a row
+ *   once it is `'completed'`) — it is reachable if a claim row was inserted
+ *   outside this module's own completion discipline, and is kept as a
+ *   defined answer rather than an assumption.
+ * - the row cannot be read back at all after `DO NOTHING` reported zero
+ *   rows inserted — `RunOnceClaimError.outcomeUnknown()`. Also normally
+ *   unreachable (the zero-rows case only happens when a committed row
+ *   already exists); kept for adapters/drivers where that and a subsequent
+ *   read are not guaranteed to observe the same committed state.
+ *
+ * Both errors carry `claimKey` and are safe to retry with the SAME token and
+ * content; `runOnce()` never retries them itself.
+ *
+ * @module
+ */
+import type { DatabaseInterface } from '@happyvertical/sql';
 import { RUN_ONCE_CLAIMS_TABLE } from './system/schema.js';
 export { RUN_ONCE_CLAIMS_TABLE };
 /** Input identifying one submission for {@link runOnce}. */

package/dist/runtime/client.d.ts

@@ -1,4 +1,7 @@
-import { SmrtClientOptions } from './types';
+/**
+ * Runtime client implementation for SMRT auto-generated services
+ */
+import type { SmrtClientOptions } from './types';
 export declare class SmrtClient {
     private options;
     constructor(options?: SmrtClientOptions);

package/dist/runtime/server.d.ts

@@ -1,5 +1,8 @@
-import { default as http } from 'node:http';
-import { SmrtRequest, SmrtServerOptions } from './types';
+/**
+ * Runtime server implementation for SMRT auto-generated services
+ */
+import http from 'node:http';
+import type { SmrtRequest, SmrtServerOptions } from './types';
 /**
  * Express-style response object handed to RouteApp-compatibility handlers
  * (registered via {@link SmrtServer.get}/`post`/`put`/`delete`). It mirrors the

package/dist/scanner/import-scanner.d.ts

@@ -1,4 +1,4 @@
-import { ScannerModule } from '../utils/scanner-module.js';
+import type { ScannerModule } from '../utils/scanner-module.js';
 interface ImportScannerOptions {
     missingBuildInstruction: string;
 }

package/dist/scanner/manifest-generator.d.ts

@@ -1,4 +1,7 @@
-import { ScanResult, SmartObjectManifest, SmrtVisibility } from './types.js';
+/**
+ * Manifest generator for creating service manifests from AST scan results
+ */
+import type { ScanResult, SmartObjectManifest, SmrtVisibility } from './types.js';
 /** Package.json shape consumed for import-path and component discovery. */
 interface PackageJsonLike {
     name?: string;

package/dist/scanner/types.d.ts

@@ -1,4 +1,7 @@
-import { SmartObjectConfig } from '../registry.js';
+/**
+ * Type definitions for AST scanning and manifest generation
+ */
+import type { SmartObjectConfig } from '../registry.js';
 /**
  * Qualified class name in format "@package/name:ClassName"
  * Example: "@happyvertical/smrt-core:Product"

package/dist/schema/code-generator.d.ts

@@ -1,5 +1,9 @@
-import { SmartObjectDefinition } from '../scanner/types.js';
-import { SchemaDefinition } from './types.js';
+/**
+ * Code generator for SMRT schema methods
+ * Generates getSchema() static methods for SMRT objects
+ */
+import type { SmartObjectDefinition } from '../scanner/types.js';
+import type { SchemaDefinition } from './types.js';
 export declare class SchemaCodeGenerator {
     /**
      * Generate getSchema() method source code

package/dist/schema/column-data-probes.d.ts

@@ -1,5 +1,30 @@
-import { DatabaseInterface } from '@happyvertical/sql';
-import { DatabaseEngine } from './ddl/types.js';
+/**
+ * Shared live-data column probes (#2874, consolidated for #2878).
+ *
+ * `detectRenameDataPending()` exists in both `migrations/differ.ts` and
+ * `schema/live-parity.ts` — tracked as its own maintenance hazard by #2878,
+ * since the #2874 regression had to be fixed twice, in lockstep, in #2876
+ * (once per copy). Until now the two batched live-data probes that function
+ * depends on were duplicated right along with it: does a named column hold
+ * any non-empty value, and does every non-empty value in a named column
+ * look UUID-shaped? Both copies used the exact same shape —
+ * uncorrelated scalar subqueries, one per column, each with its own
+ * `LIMIT 1` early exit (#2874 review finding F1: never an aggregate over
+ * the whole table, which would force a full scan per probed column even
+ * when the very first row already answers it), and the same positional
+ * `c<index>` aliasing to sidestep PostgreSQL's 63-byte identifier
+ * truncation (#2874 review finding F2'). Extracted here so the two call
+ * sites can never drift out of lockstep again.
+ *
+ * Both functions fall back to isolated per-column probing when the batched
+ * statement itself fails, so one bad column (dropped concurrently, a `CAST`
+ * the engine rejects) withholds only that column's result rather than the
+ * whole table's (#2874 review finding F2). A column absent from the
+ * returned map means "could not be probed" — callers apply their own
+ * fail-closed default, not this module.
+ */
+import type { DatabaseInterface } from '@happyvertical/sql';
+import type { DatabaseEngine } from './ddl/types.js';
 /**
  * SQL predicate: a quoted column holds a non-null, non-empty value. Shared
  * by every probe below (single-table batch, single-column fallback, and

package/dist/schema/ddl/base-strategy.d.ts

@@ -1,5 +1,11 @@
-import { ColumnDefinition, IndexDefinition, SchemaDefinition, SQLDataType, TriggerDefinition } from '../types.js';
-import { DatabaseEngine, DDLStrategy } from './types.js';
+/**
+ * Base DDL Strategy - Shared logic for all database engines
+ *
+ * Provides common DDL generation logic that engine-specific strategies
+ * can override for their particular requirements.
+ */
+import type { ColumnDefinition, IndexDefinition, SchemaDefinition, SQLDataType, TriggerDefinition } from '../types.js';
+import type { DatabaseEngine, DDLStrategy } from './types.js';
 /**
  * Abstract base class for DDL strategies
  *

package/dist/schema/ddl/duckdb-strategy.d.ts

@@ -1,6 +1,18 @@
-import { SchemaDefinition, SQLDataType } from '../types.js';
+/**
+ * DuckDB DDL Strategy
+ *
+ * DuckDB-specific DDL generation with the following characteristics:
+ * - UNIQUE constraints MUST be inline for UPSERT to work (DuckDB issue #12684)
+ * - Supports CAST in DEFAULT values
+ * - Native BOOLEAN, JSON types
+ * - Does NOT support triggers
+ *
+ * CRITICAL: DuckDB's ON CONFLICT clause only works with inline UNIQUE constraints,
+ * not with separate UNIQUE indexes. This is a known DuckDB limitation.
+ */
+import type { SchemaDefinition, SQLDataType } from '../types.js';
 import { BaseDDLStrategy } from './base-strategy.js';
-import { DatabaseEngine } from './types.js';
+import type { DatabaseEngine } from './types.js';
 export declare class DuckDBStrategy extends BaseDDLStrategy {
     readonly engine: DatabaseEngine;
     generateCreateTable(schema: SchemaDefinition): string;

package/dist/schema/ddl/index.d.ts

@@ -1,5 +1,3 @@
-import { SchemaDefinition } from '../types.js';
-import { DatabaseEngine, DDLStrategy, EngineSpecificDDL, MultiEngineDDL } from './types.js';
 /**
  * DDL Generator Module
  *
@@ -12,6 +10,8 @@ export { JsonDuckDBStrategy } from './json-duckdb-strategy.js';
 export { PostgresStrategy } from './postgres-strategy.js';
 export { SQLiteStrategy } from './sqlite-strategy.js';
 export * from './types.js';
+import type { SchemaDefinition } from '../types.js';
+import type { DatabaseEngine, DDLStrategy, EngineSpecificDDL, MultiEngineDDL } from './types.js';
 /**
  * Get the DDL strategy for a specific database engine
  *

package/dist/schema/ddl/json-duckdb-strategy.d.ts

@@ -1,6 +1,14 @@
-import { SQLDataType } from '../types.js';
+/**
+ * JSON Adapter DDL Strategy
+ *
+ * The JSON adapter is backed by DuckDB, so it needs DuckDB's inline UNIQUE
+ * constraints for UPSERT. However, DuckDB's Node API currently round-trips
+ * native UUID values as their 128-bit numeric representation, so SMRT stores
+ * UUID columns as TEXT for JSON-backed databases.
+ */
+import type { SQLDataType } from '../types.js';
 import { DuckDBStrategy } from './duckdb-strategy.js';
-import { DatabaseEngine } from './types.js';
+import type { DatabaseEngine } from './types.js';
 export declare class JsonDuckDBStrategy extends DuckDBStrategy {
     readonly engine: DatabaseEngine;
     mapType(type: SQLDataType): string;

package/dist/schema/ddl/materialize-manifest.d.ts

@@ -1,4 +1,4 @@
-import { DatabaseEngine } from './types.js';
+import type { DatabaseEngine } from './types.js';
 /** @internal */
 export declare function getSQLDefinitionIdentifier(definition: string): {
     name: string;

package/dist/schema/ddl/null-equal-index.d.ts

@@ -1,4 +1,4 @@
-import { IndexDefinition } from '../types.js';
+import type { IndexDefinition } from '../types.js';
 /** Identifies version-gated, transaction-only framework index DDL to the planner. */
 export declare const NULL_EQUAL_INDEX_MARKER = "-- smrt:null-equal-conflict-index";
 export declare function renderNullEqualConflictIndex(tableName: string, index: IndexDefinition): string;

package/dist/schema/ddl/postgres-strategy.d.ts

@@ -1,6 +1,16 @@
-import { SchemaDefinition, SQLDataType, TriggerDefinition } from '../types.js';
+/**
+ * PostgreSQL DDL Strategy
+ *
+ * PostgreSQL-specific DDL generation with the following characteristics:
+ * - JSONB type for JSON columns (more efficient than JSON)
+ * - Native BOOLEAN type
+ * - Full trigger support with PL/pgSQL functions
+ * - UNIQUE can be inline or separate indexes
+ * - Supports CAST in DEFAULT values
+ */
+import type { SchemaDefinition, SQLDataType, TriggerDefinition } from '../types.js';
 import { BaseDDLStrategy } from './base-strategy.js';
-import { DatabaseEngine } from './types.js';
+import type { DatabaseEngine } from './types.js';
 export declare class PostgresStrategy extends BaseDDLStrategy {
     readonly engine: DatabaseEngine;
     generateIndexes(schema: SchemaDefinition): string[];

package/dist/schema/ddl/sqlite-strategy.d.ts

@@ -1,6 +1,16 @@
-import { SQLDataType } from '../types.js';
+/**
+ * SQLite DDL Strategy
+ *
+ * SQLite-specific DDL generation with the following characteristics:
+ * - No CAST expressions in DEFAULT values
+ * - BOOLEAN stored as INTEGER (0/1)
+ * - JSON stored as TEXT (with JSON1 extension functions)
+ * - Supports triggers with SQLite syntax
+ * - UNIQUE can be inline or separate indexes
+ */
+import type { SQLDataType } from '../types.js';
 import { BaseDDLStrategy } from './base-strategy.js';
-import { DatabaseEngine } from './types.js';
+import type { DatabaseEngine } from './types.js';
 export declare class SQLiteStrategy extends BaseDDLStrategy {
     readonly engine: DatabaseEngine;
     /**

package/dist/schema/ddl/types.d.ts

@@ -1,4 +1,13 @@
-import { SchemaDefinition, SQLDataType } from '../types.js';
+/**
+ * DDL Generator Types for Per-Engine SQL Generation
+ *
+ * SMRT handles ALL database maintenance directly. SDK SQL remains a pure query/CRUD layer.
+ * Each database engine has different DDL requirements:
+ * - SQLite: No CAST in DEFAULT, INTEGER for booleans
+ * - DuckDB: Inline UNIQUE constraints required for UPSERT to work
+ * - PostgreSQL: JSONB type, full trigger support
+ */
+import type { SchemaDefinition, SQLDataType } from '../types.js';
 /**
  * Supported database engines
  * - sqlite: SQLite/LibSQL databases

package/dist/schema/foreign-key-ddl.d.ts

@@ -1,5 +1,5 @@
-import { DatabaseEngine } from './ddl/types.js';
-import { ForeignKeyDefinition, SchemaDefinition } from './types.js';
+import type { DatabaseEngine } from './ddl/types.js';
+import type { ForeignKeyDefinition, SchemaDefinition } from './types.js';
 export type ForeignKeyUuidCastSide = 'child' | 'parent' | 'both' | 'none';
 export declare function foreignKeyConstraintName(tableName: string, foreignKey: ForeignKeyDefinition): string;
 export declare function renderForeignKeyConstraint(tableName: string, foreignKey: ForeignKeyDefinition): string;

package/dist/schema/foreign-key-orphan-report.d.ts

@@ -1,6 +1,28 @@
-import { DatabaseInterface } from '@happyvertical/sql';
-import { DatabaseEngine } from './ddl/types.js';
-import { SchemaDefinition } from './types.js';
+/**
+ * Per-foreign-key orphan count report (#2753)
+ *
+ * `foreign-key-ddl.ts` already builds the orphan probe SQL and the suggested
+ * repair the migration differ uses to gate `ADD CONSTRAINT` — deliberately
+ * refusing to repair anything, since only the relationship's owner knows
+ * whether an orphan should be reassigned, nulled, or deleted. What is
+ * missing is the counting: `renderForeignKeyOrphanDetector({ limitOne: true })`
+ * makes the probe a gate, not a report.
+ *
+ * This module runs the same probe as a `COUNT(*)` aggregate (via
+ * `renderForeignKeyOrphanDetector({ countOnly: true })`, so the exact
+ * FROM/JOIN/WHERE predicate is never duplicated) for every manifest-declared
+ * foreign key, and reports child/parent table and column, the orphan count,
+ * and whether the child column is nullable — so the two dispositions the
+ * repair-SQL builder already distinguishes (manual repair vs. null-out) are
+ * visible up front.
+ *
+ * Strictly read-only and diagnostic: it never repairs, and a relationship
+ * whose child or parent table does not exist live is skipped and reported
+ * separately rather than failing the whole report.
+ */
+import type { DatabaseInterface } from '@happyvertical/sql';
+import type { DatabaseEngine } from './ddl/types.js';
+import type { SchemaDefinition } from './types.js';
 /** One manifest foreign key's live orphan count. */
 export interface ForeignKeyOrphanCount {
     childTable: string;

package/dist/schema/foreign-key-planner.d.ts

@@ -1,5 +1,5 @@
-import { DatabaseEngine } from './ddl/types.js';
-import { ForeignKeyDefinition, SchemaDefinition } from './types.js';
+import type { DatabaseEngine } from './ddl/types.js';
+import type { ForeignKeyDefinition, SchemaDefinition } from './types.js';
 export interface ForeignKeyCreationPlan {
     schemas: SchemaDefinition[];
     deferredStatements: string[];

package/dist/schema/foreign-key-policy.d.ts

@@ -1,4 +1,4 @@
-import { ForeignKeyAction } from './types.js';
+import type { ForeignKeyAction } from './types.js';
 /** Normalize decorator action spelling into the SQL vocabulary. */
 export declare function normalizeForeignKeyAction(value: unknown): ForeignKeyAction | undefined;
 /** Validate an externally supplied action rather than interpolating raw SQL. */

package/dist/schema/generator.d.ts

@@ -1,6 +1,10 @@
-import { FieldDefinition, FieldMeta, ManifestSchema, SmartObjectManifest } from '../scanner/types.js';
-import { DatabaseEngine } from './ddl/types.js';
-import { DeclaredIndexDefinition, SchemaDefinition } from './types.js';
+/**
+ * Schema generator for SMRT objects
+ * Converts AST field definitions to database schema definitions
+ */
+import type { FieldDefinition, FieldMeta, ManifestSchema, SmartObjectManifest } from '../scanner/types.js';
+import type { DatabaseEngine } from './ddl/types.js';
+import type { DeclaredIndexDefinition, SchemaDefinition } from './types.js';
 /**
  * Structural shape of a field as read from either the build-time manifest
  * (`FieldDefinition`) or the runtime ObjectRegistry (`getAllFields()` returns

package/dist/schema/index-utils.d.ts

@@ -1,5 +1,14 @@
-import { DatabaseEngine } from './ddl/types.js';
-import { IndexDefinition } from './types.js';
+/**
+ * Index-rendering helpers shared across DDL strategies, schema aggregator,
+ * and the migration generator/differ.
+ *
+ * IMPORTANT: this module must remain a pure utility with **type-only
+ * imports** to avoid introducing a cycle with `registry.ts` /
+ * `collection.ts`. Don't add runtime imports that pull SmrtClass /
+ * SmrtCollection / ObjectRegistry through here.
+ */
+import type { DatabaseEngine } from './ddl/types.js';
+import type { IndexDefinition } from './types.js';
 /**
  * Render the SQL target of a CREATE INDEX statement.
  *

package/dist/schema/live-parity.d.ts

@@ -1,6 +1,30 @@
-import { DatabaseInterface } from '@happyvertical/sql';
-import { DatabaseEngine } from './ddl/types.js';
-import { SchemaDefinition } from './types.js';
+/**
+ * Live-schema parity check (#2368)
+ *
+ * Compares a **live** database against the shape the model layer assumes.
+ * Three inputs define "expected":
+ *
+ * 1. **Declared table shapes** — the manifest schemas the caller passes in.
+ *    These give tables, columns, types, nullability, and declared indexes.
+ * 2. **Hand-DDL system tables** — `_smrt_*` tables parsed out of
+ *    `src/system/schema.ts` (see `system-table-shapes.ts`). They never enter
+ *    the manifest, so nothing else has ever diffed them.
+ * 3. **An expected-shape index policy that does not consult the manifest** —
+ *    every foreign-key / cross-package-ref / tenant column carries a leading
+ *    index, every declared upsert conflict target is backed by a matching
+ *    UNIQUE index, and every `unique: true` column is actually unique in the
+ *    live database.
+ *
+ * Point 3 is the reason this module exists rather than reusing the migration
+ * differ: the differ compares the live database to the manifest, i.e. to the
+ * artifact that dropped the index in the first place, which is why a database
+ * missing 164 tenant-column indexes reported "in sync" (#2356).
+ *
+ * This module is read-only. It emits findings; it never repairs.
+ */
+import type { DatabaseInterface } from '@happyvertical/sql';
+import type { DatabaseEngine } from './ddl/types.js';
+import type { SchemaDefinition } from './types.js';
 /** How badly a finding breaks the deployment. */
 export type LiveParitySeverity = 'error' | 'warning' | 'info';
 /** The class of drift a finding describes. */

package/dist/schema/manifest-schema.d.ts

@@ -1,5 +1,24 @@
-import { DatabaseEngine, EngineSpecificDDL } from './ddl/types.js';
-import { ColumnDefinition, IndexDefinition, SchemaDefinition } from './types.js';
+/**
+ * Manifest schema → structured `SchemaDefinition` helpers (#2358).
+ *
+ * A manifest's `schema.ddl` string is an engine-neutral CREATE TABLE preview:
+ * it carries no indexes and no per-engine type mapping, so nothing that needs
+ * an executable schema may treat it as authoritative. Every consumer that
+ * reads raw manifest JSON — `SchemaAggregator`, `createIsolatedTestDbFromManifest`
+ * in `@happyvertical/smrt-vitest`, third-party tooling — should collect the
+ * structured `columns` / `indexes` through this module and render them with
+ * `getDDLStrategy(engine)`, exactly as `db:migrate` does.
+ *
+ * The cached `ddl` string is used only when a manifest object exposes no
+ * structured columns at all (hand-authored or pre-structured manifests); that
+ * legacy path keeps working but is not engine-complete.
+ *
+ * Keep this module light — type-only imports plus the DDL strategies and the
+ * logger — so it can be re-exported from lightweight entry points without
+ * pulling the registry/collection module graph in by itself.
+ */
+import type { DatabaseEngine, EngineSpecificDDL } from './ddl/types.js';
+import type { ColumnDefinition, IndexDefinition, SchemaDefinition } from './types.js';
 /**
  * Column shape as it appears in raw manifest JSON. `ManifestColumnDefinition`
  * spells the default `default`; registry-side `ColumnDefinition` spells it

package/dist/schema/schema-aggregator.d.ts

@@ -1,5 +1,38 @@
-import { SmartObjectManifest } from '../scanner/types.js';
-import { CollectedManifestTable, ManifestColumnLike } from './manifest-schema.js';
+/**
+ * Schema Aggregator
+ *
+ * Aggregates database schemas across multiple SMRT package manifests.
+ * Handles STI table deduplication, index merging, and sorting for deterministic output.
+ *
+ * Tables and indexes are rendered from the manifests' structured `columns` /
+ * `indexes` through the dialect's DDL strategy (`getDDLStrategy`), the same
+ * renderer `smrt db:migrate` uses — never from the cached `schema.ddl` string,
+ * which carries no indexes and no per-engine types (#2358). Objects that expose
+ * no structured columns fall back to their cached `ddl` for the CREATE TABLE.
+ *
+ * This replaces the manual generate-schema.ts pattern used by downstream
+ * projects like blindmanpress.com (Issue #1013).
+ *
+ * @example
+ * ```typescript
+ * import { SchemaAggregator } from '@happyvertical/smrt-core/schema';
+ *
+ * // Auto-discover from installed @happyvertical packages in node_modules
+ * const aggregator = new SchemaAggregator();
+ * const result = aggregator.aggregate();
+ *
+ * // Or with explicit packages
+ * const result = aggregator.aggregate({
+ *   packages: ['@happyvertical/smrt-profiles', '@happyvertical/smrt-events'],
+ * });
+ *
+ * console.log(result.sql);        // Combined CREATE TABLE + INDEX SQL
+ * console.log(result.tables);     // Map of table info
+ * console.log(result.manifests);  // Loaded manifests by package
+ * ```
+ */
+import type { SmartObjectManifest } from '../scanner/types.js';
+import { type CollectedManifestTable, type ManifestColumnLike } from './manifest-schema.js';
 /**
  * Aggregated table information including DDL, indexes, and source tracking.
  */

package/dist/schema/schema-manager.d.ts

@@ -1,7 +1,16 @@
-import { DatabaseInterface } from '@happyvertical/sql';
-import { DatabaseEngine, EngineSpecificDDL } from './ddl/index.js';
-import { ForeignKeyUuidCastSide } from './foreign-key-ddl.js';
-import { ForeignKeyDefinition, SchemaDefinition } from './types.js';
+/**
+ * Schema Manager - Direct DDL Execution for SMRT
+ *
+ * SMRT handles ALL database maintenance directly.
+ * SDK SQL remains a pure query/CRUD layer.
+ *
+ * This module replaces the use of SDK's syncSchema() with direct DDL execution
+ * using engine-specific DDL strategies.
+ */
+import type { DatabaseInterface } from '@happyvertical/sql';
+import { type DatabaseEngine, type EngineSpecificDDL } from './ddl/index.js';
+import { type ForeignKeyUuidCastSide } from './foreign-key-ddl.js';
+import type { ForeignKeyDefinition, SchemaDefinition } from './types.js';
 /**
  * Schema Manager Options
  */