@happyvertical/smrt-core

ORM, code generation, AI integration, and the DispatchBus. Everything else in the s-m-r-t framework builds on this.

Use smrt-core when you are defining domain objects, querying collections, generating interfaces, or extending the framework runtime. If you want a full application scaffold with users and tenancy already wired, start with smrt-template-sveltekit.

Installation

pnpm add @happyvertical/smrt-core
pnpm add -D @happyvertical/smrt-cli @happyvertical/smrt-vitest

Requires Node.js 24.18.0 or newer. s-m-r-t projects use the Vite plugin to generate manifests and the CLI to apply schema migrations before runtime.

Usage

Define a class with `@smrt()`

import {
  foreignKey,
  smrt,
  SmrtCollection,
  SmrtObject,
} from '@happyvertical/smrt-core';

@smrt()
class Category extends SmrtObject {
  name = '';
}

@smrt({ api: true, cli: true, mcp: true })
class Product extends SmrtObject {
  name = '';
  price: number = 0.0;          // DECIMAL (has decimal point)
  quantity: number = 0;          // INTEGER (no decimal point)
  isPublished = false;

  @foreignKey(Category)
  categoryId = '';
}

class ProductCollection extends SmrtCollection<Product> {
  static readonly _itemClass = Product;
}

Basic CRUD

const products = await ProductCollection.create({ db: 'products.db' });

// Create
const product = await products.create({ name: 'Widget', price: 9.99 });

// Query
const results = await products.list({
  where: { isPublished: true, price: { op: '>', value: 5 } },
  orderBy: 'price DESC',
  limit: 20,
});

Bounded multi-collection reads

When one request needs several independent collections, use a keyed read plan instead of an unbounded Promise.all. Every entry still uses the normal collection list() path, but only the requested number of operations run at once:

import {
  executeCollectionReadPlan,
  type SmrtCollectionReadPlanEntry,
} from '@happyvertical/smrt-core';

const categories: SmrtCollectionReadPlanEntry<Category> = {
  className: 'Category',
  options: { orderBy: 'name ASC' },
};
const products: SmrtCollectionReadPlanEntry<Product> = {
  className: 'Product',
  options: { where: { isPublished: true }, orderBy: 'name ASC' },
};
const records = await executeCollectionReadPlan(
  {
    categories,
    products,
  },
  {
    collectionOptions: { db: 'file:products.db' },
    maxConcurrency: 2,
  },
);

maxConcurrency is required and must be a positive integer. If an entry fails, the executor starts no further queued entries, waits for already-running entries to settle, and rethrows the first error. Read plans do not compose SQL, cache whole-plan results, or change database pool defaults.

Generate metadata and migrate

Configure Vite 8's Oxc decorator transform and point smrtPlugin() at the directory containing your objects:

// vite.config.ts
import { smrtPlugin } from '@happyvertical/smrt-core/vite-plugin';
import { defineConfig } from 'vite';

export default defineConfig({
  oxc: {
    decorator: { legacy: true, emitDecoratorMetadata: true },
  },
  plugins: [
    smrtPlugin({
      include: ['src/objects/**/*.ts'],
      exclude: ['**/*.test.ts'],
    }),
  ],
});

pnpm vite build
pnpm smrt db:migrate

Runtime verifies application tables but does not create them. Rebuild the manifest and rerun the migration after changing persisted object fields.

Reuse a verified generation snapshot in CI

Independent Vite invocations can reuse one generation snapshot prepared by an earlier job without rescanning or rewriting it. First run one normal generation invocation with smrtPlugin() and smrtConsumer() enabled. After both plugins finish, .smrt/manifest.json contains the project and dependency views. Wrap that aggregate once:

import { readFileSync, writeFileSync } from 'node:fs';
import {
  serializeSmrtGenerationSnapshot,
  sha256SmrtGenerationSnapshot,
} from '@happyvertical/smrt-core/vite-plugin';

const provenance = process.env.GITHUB_SHA!;
const sourceRoot = process.env.GITHUB_WORKSPACE ?? process.cwd();
const manifest = JSON.parse(readFileSync('.smrt/manifest.json', 'utf8'));
const bytes = serializeSmrtGenerationSnapshot(manifest, provenance, {
  sourceRoot,
});
writeFileSync('.ci/smrt-generation-snapshot.json', bytes);
console.log(sha256SmrtGenerationSnapshot(bytes));

Transport the exact bytes and digest together, then configure the consumers with caller-trusted provenance (normally the checked-out commit or tree). Both plugins use the same snapshot; each selects its own manifest view. sourceRoot is the current checkout root, so normalized source paths remain portable across workers:

import { smrtConsumer } from '@happyvertical/smrt-core/consumer-plugin';
import { smrtPlugin } from '@happyvertical/smrt-core/vite-plugin';

const provenance = process.env.GITHUB_SHA!;

const generationSnapshot = {
  path: '.ci/smrt-generation-snapshot.json',
  sha256: process.env.SMRT_GENERATION_SNAPSHOT_SHA256!,
  provenance,
  sourceRoot: process.env.GITHUB_WORKSPACE ?? process.cwd(),
};

smrtPlugin({ generationSnapshot });
smrtConsumer({ generationSnapshot });

Both plugins fail closed when the snapshot is missing, malformed, has different bytes, declares different provenance, cannot resolve its portable paths, or the current source-file digests differ from the prepared inputs. Reuse mode still generates routes, types, registration, and virtual modules, but it disables source/package scans, watch rescans, and manifest writes. Omit generationSnapshot for normal local development.

Where consumer manifests are resolved

smrtConsumer() resolves each consumed package's manifest through that package's own package.json#exports map first — the ./manifest.json entry (or its ./manifest alias), which every s-m-r-t model package is required to publish — and only then falls back to the conventional dist/manifest/static-manifest.js, dist/manifest.json, and manifest.json paths. A package whose build emits elsewhere (for example a triple-purpose package that maps "./manifest.json": "./dist/lib/manifest.json") therefore loads normally.

Every declared target is a candidate, not a single choice: an export array is a fallback list and each recognized condition contributes its own target, so a missing first entry does not hide a valid later one. Candidates are probed in order and the first one that loads wins, so a candidate that exists but cannot be read, parsed, or imported is reported and skipped rather than ending the search — the conventional paths stay reachable behind a stale or malformed export target. Targets that resolve outside the package directory are dropped, both lexically and after following symlinks; the package root is itself resolved through symlinks first, so pnpm and workspace installs are unaffected.

A package that yields no usable manifest is never skipped silently. An entry in an explicit packages list is an assertion, so it fails the build by name; a package found by dependency-name discovery only warns by name and contributes no objects.

Consumer web collection definitions

smrtConsumer() also resolves @smrt/web for browser collection consumers:

import { collectionDefinitions, getCollectionDefinition } from '@smrt/web';

The module projects the consumer's aggregated dependency manifest through the same web-definition generator as smrtPlugin(). Each definition retains its provider-qualified objectRef (for example, @acme/widgets:Widget) and its manifest-derived fields, actions, relationships, WebMCP descriptors, and manifestHash. Consumer snapshots select the dependency view, so local project objects are not included. During declaration generation the matching smrt-web.d.ts module is written alongside the other consumer virtual modules.

For SvelteKit projects, default consumer declaration generation runs during the Vite configuration lifecycle as well as the normal build lifecycle. With SvelteKit 2.69.3 or later, svelte-kit sync && svelte-check loads that Vite configuration, so a clean checkout receives the physical @smrt/manifest, @smrt/client, and @smrt/web declarations before type checking. Set generateTypes: false only when another generation step owns those files.

Generated SvelteKit routes

Enable SvelteKit route generation with svelteKit: { enabled: true }. Its default output directory is src/routes/api; set svelteKit.routesDir when your application uses a different route root.

A consumer can host selected dependency models with the same generator. This is an explicit HTTP boundary that is separate from the broader packages registration inventory. Name exact provider-qualified object references; a simple class name, an unknown object, or an empty list fails the build before any generated route is replaced:

smrtConsumer({
  packages: runtimeProviderPackages,
  svelteKit: {
    objects: ['@acme/widgets:Widget'],
    routesDir: 'src/routes/api',
  },
});

projectRoot selects one artifact root for consumer route generation, registration, manifests, and types; it defaults to the current working directory. It remains the consumer artifact root when a Vite config declares a different root; pass projectRoot explicitly when consumer artifacts should share that Vite root or belong elsewhere.

Only the listed objects are passed to route generation, so another API model in the same provider remains absent until it is named. api: false and an empty api.include still suppress handlers, and generated auth, writable-field, and tenant safeguards are unchanged. svelteKit: true remains a legacy consumer integration flag and does not host dependency CRUD routes. Consumer-hosted _changes, _events, and _resources routes are disabled unless their existing option is explicitly enabled; sync/apply is generated when a selected model exposes a mutating API action.

When smrtPlugin() and smrtConsumer() generate routes in one SvelteKit application, they may use the same canonical routesDir and share one generated surface, or use disjoint directories. Nested directories are rejected before files are changed because a parent generated-root cleanup would otherwise own and remove the child surface. Canonical ownership resolves symlink aliases through the nearest existing directory, so paths that name the same generated directory share one surface. When separate artifact roots resolve to that same route directory, their resolved object and config outputs must also agree; incompatible settings fail before generated handlers or managed ownership records change.

The consumer keeps a private managed-root inventory under .smrt after a successful explicit hosting plan is validated. Changing its routesDir, setting svelteKit: false, returning to legacy svelteKit: true, or omitting the option reconciles only consumer-managed generated handlers before SvelteKit inventories routes. Handwritten handlers and current producer-owned routes are preserved.

The plugin records only the concrete +server.ts files it generated in a bounded .gitignore block. Handwritten handlers below routesDir remain visible to Git, including routes that live beside generated resource handlers. Generation refreshes that block, so stale generated paths stop being ignored when the generator no longer owns them.

Migration note: generation replaces the legacy block below with the bounded exact-path block:

# SMRT auto-generated routes (from Vite plugin)
src/routes/api/**/+server.ts
!src/routes/api/v1/**/+server.ts

Migration takes the recognized # SMRT auto-generated routes (from Vite plugin) header — matched as a whole line — plus the contiguous run of recursive +server.ts wildcards directly beneath it, negations included. The run is matched by shape rather than against your current routesDir, so a project that moved routesDir after adopting the plugin still migrates, and migration still runs once the bounded block exists — leaving a stale negation in place would silently re-include whatever the bounded block stops listing.

The first line that is not a recursive +server.ts wildcard ends the run. A broad rule you added or moved yourself is left unchanged, including an identical pattern elsewhere in the file; remove or narrow it manually if it hides a handwritten route.

Generated routes are build output and are not meant to be committed: they are regenerated on every dev-server start and are not formatted to your Biome or Prettier configuration, so tracking them makes a lint job fail on output no one edits. Track the handwritten handlers beside them — the bounded block lists only generator-owned paths, so they stay visible to Git.

AI operations

With an AI provider configured, every object can use the inherited is() and do() operations:

const isExpensive = await product.is('costs more than the average product');
const description = await product.do('Write a short marketing description');

Opt-In Read Cache

SSR apps that re-query read-heavy / write-rare collections on every request can memoize list() and get() results with an opt-in TTL. Defaults are off — nothing is cached unless a call or model opts in.

// Per call
const published = await resumes.list({
  where: { status: 'published' },
  cache: { ttl: 60_000 },
});

// Per model — list()/get() on this collection cache by default
@smrt({ cache: { ttl: 60_000 } })
class Resume extends SmrtObject {}

// Force a fresh read on hot paths that must read through
const latest = await resumes.list({ cache: false });

Because s-m-r-t owns every mutation path (save(), delete(), collection.create(), getOrUpsert(), junction attach/detach), any write automatically invalidates the affected table's cached entries in-process — including STI siblings sharing the table. Cached values are raw rows: hydration and read interceptors (tenancy, audit) still run on every call. Concurrent identical misses coalesce only on the same concrete database interface. Distinct connection or transaction interfaces never share pending reads or completed rows, even with the same URL; invalidation still clears all interfaces for that URL and table.

Caches are per-process. For multi-replica deployments, add crossProcess: true to broadcast invalidations over the database adapter's notification capability (e.g. Postgres LISTEN/NOTIFY) so peers drop their entries immediately instead of waiting out the TTL:

@smrt({ cache: { ttl: 60_000, crossProcess: true } })
class Resume extends SmrtObject {}

Model-level config is the reliable cross-process opt-in: every process writing the model knows to broadcast, and STI children writing the shared table broadcast even if they opted out of caching their own reads. As a per-call option (list({ cache: { ttl, crossProcess: true } })), writes broadcast only from processes that have already performed such a read — typical for homogeneous replicas running the same routes, but a write-only process never learns about a call-site opt-in.

Writes that bypass s-m-r-t (raw SQL, external processes without crossProcess) are only bounded by the TTL — pick one that matches how stale the data may be.

Bundled Runtimes And External Manifests

Long-lived bundled runtimes such as SvelteKit servers, background workers, and CLI entrypoints should ship two things together:

The generated smrt-register runtime entrypoint for local class registration.
The manifest.json exports for any installed external @happyvertical/smrt-* packages the runtime needs to hydrate at query time.

ObjectRegistry.ensureManifestLoaded() can now auto-load installed external classes by either simple name ('EventType') or qualified name ('@happyvertical/smrt-events:EventType'). SmrtCollection.list() and SmrtCollection.get() use that path when they encounter STI discriminators from external packages, so bundled runtimes do not need to import every child class eagerly just to hydrate rows correctly.

If you want to avoid on-demand manifest discovery in a long-lived process, call ObjectRegistry.loadAllManifests() during startup after your local registration file has run.

API

Entry points

Import	Purpose
`@happyvertical/smrt-core`	Objects, collections, decorators, registry, configuration
`@happyvertical/smrt-core/vite-plugin`	Manifest, route, client, and knowledge generation
`@happyvertical/smrt-core/consumer-plugin`	Consume manifests from installed s-m-r-t packages
`@happyvertical/smrt-core/generators`	REST, OpenAPI, CLI, and MCP generator APIs
`@happyvertical/smrt-core/manifest`	Runtime manifest loading and inspection
`@happyvertical/smrt-core/testing`	Database and registry test helpers

Core Classes

Export	Description
`SmrtClass`	Base class with DB, AI, and filesystem access
`SmrtObject`	Persistent object — save, delete, is(), do()
`SmrtCollection`	CRUD collection — list, get, create, upsert
`ObjectRegistry`	Global singleton for class/field metadata
`smrt` (decorator)	Registers a class for code generation and AI

Field Decorators

Export	Description
`field`	General-purpose field decorator
`foreignKey`	Foreign key relationship
`oneToMany`	One-to-many relationship
`manyToMany`	Many-to-many relationship
`meta`	STI child field stored in `_meta_data` JSONB

Dispatch (Inter-Agent Messaging)

Export	Description
`DispatchBus`	Persistent message bus with wildcard subscriptions
`createDispatchBus`	Factory function for DispatchBus
`Dispatch`	Dispatch record model
`DispatchSubscription`	Persistent subscription model

Code Generators

Export	Description
`APIGenerator`	Generates OpenAPI-compliant REST endpoints
`MCPGenerator`	Generates Model Context Protocol tool servers
`createRestServer`	Creates an Express REST server from config
`generateOpenAPISpec`	Generates OpenAPI/Swagger spec

Embeddings (Semantic Search)

Export	Description
`EmbeddingProvider`	Generates embeddings via AI provider
`EmbeddingStorage`	Persists/queries embedding vectors
`CosineSimilarity`	Ranks results by vector similarity
`ContentHasher`	Content hashing for change detection

Context Memory

Every SmrtObject/SmrtCollection can persist learned knowledge via remember() / recall() / recallAll() / forget() (system table _smrt_contexts) — confidence-scored and versioned, with opt-in hierarchical scope fallback (recall({ includeAncestors: true })) and a stored expiresAt the caller filters on (recall() does not auto-drop expired entries). Pairs with semantic search (above) for retrieval; contributor-level behavior and invariants live in AGENTS.md.

Signals (Observability)

Export	Description
`SignalBus`	Universal method-tracking event bus
`SignalSanitizer`	Sanitizes sensitive data in signals
`MetricsAdapter`	Prometheus-compatible metrics adapter
`PubSubAdapter`	Broadcast signals to subscribers

Manifest (Build-Time Metadata)

Export	Description
`ManifestManager`	Reads, writes, and generates manifests
`ManifestBuilder`	Orchestrates scanning to manifest
`ManifestGenerator`	Converts scan results to manifest format
`getManifest`	Async getter for static manifest data

Runtime

Export	Description
`createMCPServer` / `SmrtMCPServer`	MCP server runtime
`createSmrtServer`	REST server runtime
`createSmrtClient`	API client runtime

Schema & Migrations

Export	Description
`SchemaComparer`	Compares current vs. desired schema
`generateSchemaDiff`	Produces a diff between two schemas
`getSQLFromDiff`	Converts schema diff to SQL statements

Interceptors

Export	Description
`GlobalInterceptors`	Plugin hooks for beforeList/Get/Save/Delete
`createInterceptorContext`	Creates context for interceptor execution

Errors

Export	Description
`SmrtError`	Abstract base error class
`DatabaseError`	Database operation failures
`AIError`	AI provider failures
`ValidationError`	Field/object validation failures
`RuntimeError`	General runtime failures
`ErrorUtils`	Retry policy (`withRetry`, `isRetryable`) plus sanitization helpers

Database error classification

Driver errors reach the model layer wrapped by @happyvertical/sql, which stringifies the driver text into context.originalError — so the constraint wording never appears on error.message. Classify through the cause chain instead of matching messages.

Export	Description
`classifyDatabaseError`	Walks the cause chain and returns the kind plus `deterministic` / `retryable`
`classifyDialectMessage`	Matches a single raw dialect message (the DuckDB fallback)
`isUniqueViolationError`	Unique or primary-key violation anywhere in the chain
`isNotNullViolationError`	NOT NULL violation anywhere in the chain
`isAbortedTransactionError`	Statement issued inside an aborted PostgreSQL transaction (`25P02`)
`isDeterministicDatabaseError`	A retry cannot change the outcome
`isTransientDatabaseError`	Contention or availability; a retry may succeed
`DatabaseErrorKind`	Union of classification kinds
`DatabaseErrorClassification`	Structured result of `classifyDatabaseError`

Tools (AI Function Calling)

Export	Description
`generateToolManifest`	Generates AI tool definitions from methods
`executeToolCall` / `executeToolCalls`	Executes AI tool calls

Utilities

Export	Description
`config`	Global s-m-r-t configuration function
`resolveDatabase`	Resolves DB config to a DatabaseInterface
`smrtPlugin`	Vite plugin for auto-service generation
`generateSvelteKitRoutes`	SvelteKit route generator
`resetVerifiedTables`	Resets table verification cache (testing)
`getTestDatabase`	Creates isolated test databases
`parse` / `stringify` / `clone`	JSON utilities with optional SIMD
`createQualifiedName` / `parseQualifiedName`	STI qualified name helpers

Code Generation

The @smrt() decorator controls what gets generated. Set api, cli, or mcp to true or { include: [...] }:

@smrt({
  api: { include: ['list', 'get', 'create'] },
  mcp: true,
  cli: true,
})
class Product extends SmrtObject { /* ... */ }

Generators produce OpenAPI REST endpoints, Commander CLI commands, and MCP server tools respectively. The Vite plugin (smrtPlugin) generates virtual modules at dev time for routes, clients, and manifests.

Durable MCP tasks

Long-running item actions may opt into the experimental io.modelcontextprotocol/tasks extension. Tasks are disabled by default; list the action names explicitly, and — if the class restricts what the job runner may dispatch — include the action in that allowlist:

import { backgroundEligible } from '@happyvertical/smrt-jobs';

@smrt({
  mcp: { include: ['generateReport'], tasks: ['generateReport'] },
})
class Report extends SmrtObject {
  @backgroundEligible()
  async generateReport(): Promise<ReportResult> { /* ... */ }
}

@backgroundEligible() is owned and enforced by @happyvertical/smrt-jobs, not by this package. It is restrictive: a class with no marked methods lets TaskRunner dispatch any of its methods, and the first marked method turns the set into an exhaustive allowlist that excludes every other method on the class. Use it to narrow the reachable surface, and mark every method you dispatch.

The generated MCP server advertises the extension only when at least one task action is enabled. A task-aware client can request the action as a durable job, then use tasks/get, tasks/update, and tasks/cancel to observe or control it. Generated stdio servers run an mcp-tasks worker automatically.

Dependencies

@happyvertical/ai -- AI client (is/do operations, embeddings)
@happyvertical/sql -- Database interface (SQLite, PostgreSQL)
@happyvertical/files -- Filesystem adapter
@happyvertical/logger -- Structured logging
@happyvertical/smrt-types -- Shared type definitions

Contributor guide

See AGENTS.md for package architecture, invariants, validation, and contributor guidance.

Installation​

Usage​

Define a class with @smrt()​

Basic CRUD​

Bounded multi-collection reads​

Generate metadata and migrate​

Reuse a verified generation snapshot in CI​

Where consumer manifests are resolved​

Consumer web collection definitions​

Generated SvelteKit routes​

AI operations​

Opt-In Read Cache​

Bundled Runtimes And External Manifests​

API​

Entry points​

Core Classes​

Field Decorators​

Dispatch (Inter-Agent Messaging)​

Code Generators​

Embeddings (Semantic Search)​

Context Memory​

Signals (Observability)​

Manifest (Build-Time Metadata)​

Runtime​

Schema & Migrations​

Interceptors​

Errors​

Database error classification​

Tools (AI Function Calling)​

Utilities​

Code Generation​

Durable MCP tasks​

Dependencies​

Contributor guide​