@happyvertical/smrt-core 0.51.31 → 0.51.33

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
  */

package/dist/schema/system-table-shapes.d.ts

@@ -1,4 +1,23 @@
-import { DatabaseEngine } from './ddl/types.js';
+/**
+ * System-table shape parsing (#2368)
+ *
+ * `_smrt_*` tables are created from hand-written DDL in `src/system/schema.ts`
+ * rather than from decorated classes, so they never enter the manifest and the
+ * manifest-driven differ has never compared them against a live database.
+ *
+ * This module parses that DDL back into a structural description — columns,
+ * declared indexes, and inline `UNIQUE (...)` constraints — so the live-schema
+ * parity check can hold system tables to the same standard as application
+ * tables. The DDL is the source of truth for these tables; parsing it (rather
+ * than duplicating a hand-maintained expectation table) keeps the two from
+ * drifting apart.
+ *
+ * The parser is deliberately narrow: it understands the portable subset SMRT
+ * actually writes (`CREATE TABLE IF NOT EXISTS`, `CREATE [UNIQUE] INDEX IF NOT
+ * EXISTS`, simple column definitions, inline `UNIQUE`/`PRIMARY KEY` table
+ * constraints) and ignores anything else rather than guessing.
+ */
+import type { DatabaseEngine } from './ddl/types.js';
 /** One column as declared by hand-written system-table DDL. */
 export interface SystemTableColumnShape {
     name: string;

package/dist/schema/table-verifier.d.ts

@@ -1,4 +1,4 @@
-import { DatabaseInterface } from '@happyvertical/sql';
+import type { DatabaseInterface } from '@happyvertical/sql';
 /**
  * Verify that a model table already exists.
  *

package/dist/schema/text-cast-probe.d.ts

@@ -1,4 +1,27 @@
-import { DatabaseInterface } from '@happyvertical/sql';
+/**
+ * Shared "probe, then cast" helpers for text-column type convergence (#2771,
+ * #2772).
+ *
+ * Two drift shapes on a table SMRT itself creates share one problem: a live
+ * `text` column holds values that would parse losslessly into the manifest's
+ * declared PostgreSQL type (`timestamptz` or `jsonb`), but the differ cannot
+ * know that without looking at the data. `probeCastSafety()` answers that with
+ * a genuine, exception-safe cast attempt — not a shape heuristic — over every
+ * non-null value, and returns one sample so a fail-closed diagnostic can name
+ * the offending value without dumping the whole column into JS.
+ *
+ * PostgreSQL has no `TRY_CAST`/safe-cast builtin before 17 (`pg_input_is_valid`),
+ * and this fleet targets 16 (see `.github/workflows/postgres-tests.yml`), so a
+ * real per-row safe cast needs PL/pgSQL's exception handling. That handler is
+ * created as a session-scoped (`pg_temp`) function, which is why the create
+ * statement and the probe query run inside one `db.transaction()` — the two
+ * must land on the same physical connection, and a pooled adapter only
+ * guarantees that within one transaction. `target_type` is never derived from
+ * column data (always the literal `'jsonb'`/`'timestamptz'` this module
+ * passes), so the dynamic `EXECUTE format(...)` it builds cannot be steered by
+ * a row value; `%L` quotes the probed value as a literal.
+ */
+import type { DatabaseInterface } from '@happyvertical/sql';
 /** Outcome of a server-side cast-safety probe over one column's non-null values. */
 export type ShapeProbeResult = {
     status: 'clean';

package/dist/schema/utils.d.ts

@@ -1,7 +1,16 @@
-import { DatabaseInterface } from '@happyvertical/sql';
-import { SmrtObject } from '../object.js';
-import { FieldDefinition } from '../scanner/types.js';
-import { DatabaseEngine } from './ddl/index.js';
+/**
+ * Schema generation utilities - Node.js only
+ *
+ * These functions use SchemaGenerator which depends on node:crypto.
+ * Separated from main utils.ts to prevent bundling in browser builds.
+ *
+ * SMRT handles ALL database maintenance directly.
+ * SDK SQL remains a pure query/CRUD layer.
+ */
+import type { DatabaseInterface } from '@happyvertical/sql';
+import type { SmrtObject } from '../object.js';
+import type { FieldDefinition } from '../scanner/types.js';
+import { type DatabaseEngine } from './ddl/index.js';
 export { materializeManifestDDLForEngine, tokenizeSQLDDLBody, } from './ddl/materialize-manifest.js';
 export { assertIdentifierFits, identifierByteLength, isJsonPathIndex, isStiSubtypeUniqueIndex, MAX_IDENTIFIER_BYTES, renderIndexTarget, shortenIdentifier, } from './index-utils.js';
 export { type CollectedManifestTable, collectManifestTables, type ManifestColumnLike, type ManifestIndexLike, type ManifestSchemaLike, manifestColumnsToDefinitions, manifestIndexesToDefinitions, manifestSchemaToDefinition, mergeSchemaDefinitionInto, renderCollectedManifestTable, } from './manifest-schema.js';

package/dist/schema/uuid-convergence.d.ts

@@ -1,4 +1,35 @@
-import { SchemaDefinition } from './types.js';
+/**
+ * UUID convergence for pre-R11 PostgreSQL databases (#2608).
+ *
+ * R11 made SMRT identifiers and references native `uuid` on PostgreSQL.
+ * Databases created before that change still carry `text` id columns, while
+ * every column added afterwards materializes as `uuid`. PostgreSQL cannot
+ * implement a `FOREIGN KEY` across those two physical types — there is no
+ * cast inside FK DDL — so `ALTER TABLE … ADD CONSTRAINT … NOT VALID` fails
+ * with SQLSTATE 42804 and takes the rest of the migration batch with it.
+ *
+ * This module owns the deterministic half of the repair:
+ *
+ * - {@link renderUuidColumnConversion} renders the one-time
+ *   `ALTER COLUMN … TYPE uuid USING …::uuid` (plus the `DROP DEFAULT` a live
+ *   text default would otherwise block), and
+ * - {@link planUuidConvergence} decides *which* columns must convert, by
+ *   grouping every manifest-declared UUID relationship into connected
+ *   components and converging a component only when the live database already
+ *   proves the target shape (at least one side is native `uuid`).
+ *
+ * The planner never coerces data: a component converges only when a caller
+ * supplied probe confirms every non-null value is uuid-shaped, no live
+ * foreign key depends on a column being rewritten, and no member carries some
+ * third physical type. Anything else is returned as a *block* with an
+ * operator-facing reason, so `db:status` can report "blocked" instead of
+ * "pending" and `db:migrate` never attempts DDL PostgreSQL will reject.
+ *
+ * A database whose relationship is `text` on *both* sides is left alone: that
+ * is the tolerated pre-R11 shape (see the R11 uuid/text equivalence in
+ * `migrations/differ.ts`), and its foreign keys apply fine.
+ */
+import type { SchemaDefinition } from './types.js';
 /** One physical column participating in a manifest UUID relationship. */
 export interface UuidConvergenceNode {
     table: string;

package/dist/signals/bus.d.ts

@@ -1,5 +1,11 @@
-import { Signal, SignalAdapter } from '@happyvertical/smrt-types';
-import { SanitizationConfig } from './sanitizer.js';
+/**
+ * Signal Bus for Universal Event Distribution
+ *
+ * This module provides the central SignalBus for distributing signals
+ * to registered adapters (logging, metrics, pub/sub, etc.).
+ */
+import type { Signal, SignalAdapter } from '@happyvertical/smrt-types';
+import type { SanitizationConfig } from './sanitizer.js';
 /**
  * Central signal distribution bus
  *

package/dist/signals/sanitizer.d.ts

@@ -1,4 +1,10 @@
-import { Signal } from '@happyvertical/smrt-types';
+/**
+ * Signal payload sanitization for security
+ *
+ * Prevents sensitive data (passwords, tokens, PII) from being leaked
+ * into logs, metrics, or other signal outputs.
+ */
+import type { Signal } from '@happyvertical/smrt-types';
 /**
  * Sanitization configuration
  */

package/dist/smrt-knowledge.json

@@ -3,12 +3,12 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-core",
-  "packageVersion": "0.51.31",
+  "packageVersion": "0.51.33",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "5c79de7448bc9a0920520f4729c77416f58193d3d7ffe47be4ca2893f071c191",
-    "packageJson": "b3b5daddf573c054322c86d4230796753962ee0d252b8deaa7e59643190bdbd3",
+    "manifest": "0e598c41a70d94e0f311ca2c6c717499d7d360bfde2a10c982e722bd8cc6e928",
+    "packageJson": "624a187e41615d1b71afb40c725502618367487547cf4fe00127265c02c2c2cc",
     "agents": "79356014d92fdf656f648e5c765374913104445a5542243f4819ef362c77a8e5",
     "moduleDoc:agents/object-runtime.md": "34a4e740c109467cd5486c4af0e3bf4b63915697721ab584df0e5506ea9290ca",
     "moduleDoc:agents/revision-guard.md": "aa6b1ddb5b6b49fa27ebbe575ec7fcd6d5ceb35ee25acc702f877a226eb9a99a",
@@ -19,7 +19,7 @@
     "moduleDoc:agents/change-feed.md": "2151843f5d059cff54d7f6a32a6d57c43b9551fc4673edce13209764a09a9ae1",
     "moduleDoc:agents/change-signals.md": "a2dbe7077483b5a19bd5ea9589b5a08fe847377c8e05d01d57f813c6d9cbc28b",
     "moduleDoc:agents/generators.md": "4bc7787947fbcb5c084ce3e7849eff7a240580226e6b64271de7493870683cdf",
-    "moduleDoc:agents/build-knowledge.md": "6705af33224b60521be741144a08f7a0db311a2d63e2b93b0e875280c7f72951",
+    "moduleDoc:agents/build-knowledge.md": "41eff6b3603f00e59eb91820c5ad9e50fb103d25bb5b9947f5b09b59d54a79ea",
     "moduleDoc:agents/memory.md": "a86bdf370403d08ecad3be86e341eb322dfe6e6b7a4e8806a6f8be9bf3421da5",
     "moduleDoc:agents/system-diagnostics.md": "b7ccae18ee312bf788d5470f95fa78d3535f1789247d5372e40ca86538290772",
     "moduleDoc:agents/registry-snapshot.md": "6234aa540427396d1dda1825a4641b1072e247187d5ddf413ae46c691344ee30",
@@ -71,6 +71,7 @@
     "oxc-transform": "0.150.0",
     "pluralize": "^8.0.0",
     "tsx": "^4.23.13",
+    "vite": "8.1.4",
     "yaml": "^2.9.1",
     "@faker-js/faker": "^10.6.0",
     "@huggingface/transformers": ">=3.0.0 <5.0.0",
@@ -80,10 +81,8 @@
     "@types/pluralize": "^0.0.33",
     "@xenova/transformers": "^2.17.2",
     "svelte": "^5.57.1",
-    "svelte-check": "4.7.6",
-    "typescript": "5.9.3",
-    "vite": "8.1.4",
-    "vite-plugin-dts": "5.1.0",
+    "svelte-check": "^4.7.6",
+    "typescript": "6.0.3",
     "vitest": "4.1.10"
   },
   "smrtDependencies": [
@@ -1108,7 +1107,7 @@
     {
       "path": "agents/build-knowledge.md",
       "module": "build-knowledge",
-      "content": "# Decorators, build integration, and knowledge\n\nKey options: `tableName`, `tableStrategy` ('cti'|'sti'), `conflictColumns`, `indexes` (declared multi-column indexes; see [schema-paths.md](schema-paths.md)), `api`/`mcp`/`cli` (generation config), `ai` (callable methods), `hooks` (beforeSave/afterSave/beforeDelete/afterDelete), `embeddings` (auto-generate), `tenantScoped`, `agent`, `ui` (`{ icon, label, description }` — nav/help hints round-tripped through the manifest as plain data; `description` is the object-level seed for form-level help, #2046).\n\nRegistration sets `SMRT_TABLE_NAME` static property (survives minification).\n\n## @field() UI hints (#2046)\n\n`@field({ ui: { basic, group, order, locked } })` — a static, presentation-only\nseed for the field-policy rail (epic #2045). Carried in the manifest under the\nfield's `_meta.ui` (never a top-level `FieldDefinition` key), readable at\nruntime via `getAllFields()` at `field._meta.ui`, and emitted (sanitized) with\n`description` into generated web-collection definitions and browser MCP tool\nschemas. No schema/persistence/security effect — `sensitive`/`readPermission`\nstay the security rail, and `sensitive`/`transient` fields never emit to the\nclient at all.\n\n## Worker registration artifact (#3117)\n\nWith `svelteKit.enabled`, a production `vite build` compiles the generated\n`smrt-register.ts` into `.smrt/runtime/register.js` after the server build\n(`src/vite-plugin/worker-registration.ts`, called once from `closeBundle`).\nadapter-node re-bundles the server from its own entries, so the web bundle is\nnever importable by a separate Node process; this artifact is how a deployed\ntask/schedule worker registers the app's local objects (and, through the\n`.smrt/register.js` it imports, consumed packages' objects) with the same\nqualified identities and isolated manifests as the web server. It is a nested\nSSR build with no consumer plugins: only aliases pointing into the project\nsources (e.g. `$lib`) apply, and every other bare import stays external so the\nworker shares the installed `@happyvertical/smrt-core` registry. SvelteKit\nvirtual modules (`$env/*`, `$app/*`) are not available to a worker; an object\nimporting one fails at worker startup. A failure fails the build.\n\n## Lightweight discovery\n\n`src/knowledge-discovery.ts`, exported through `smrt-core/knowledge`, enumerates\ninstalled scope directories and reads canonical AGENTS/legacy CLAUDE docs without\nloading package code, artifacts, or scanning objects. CLI snapshots and MCP share\nthese primitives. Callers retain selection policy: snapshots resolve links and\nfall back to `packages/*` only when no installed SMRT package loads; MCP preserves\nnode_modules paths, deduplicates realpaths, excludes authored workspace links,\nand then enriches the selected packages. Workspace-root/glob discovery remains\nowned by each consumer.\n\n## Domain Knowledge Artifacts\n\n`smrtPlugin()` writes runtime manifests and agent/developer knowledge artifacts:\n\n- local dev/build: `.smrt/manifest.json` and `.smrt/smrt-knowledge.json`\n- package build: `dist/manifest.json` and `dist/smrt-knowledge.json`\n\nKeep `manifest.json` runtime-focused. `smrt-knowledge.json` is the deterministic\nagent contract for downstream review and architecture tools.\n\nThe CLI's schema-command gate reads that same merged file: a pure-consumer\nproject (0 local objects) qualifies on the consumed packages its manifest\nrecords, so a clobbered `objects` map is what made `smrt db:migrate` report\n`missing_local_manifest` (#2925).\n\n`.smrt/manifest.json` has two writers and neither owns all of it: `smrtPlugin()`\ncontributes the project's scanned objects and `smrtConsumer()` the consumed\npackages' entries. Both writes are merge-preserving, keyed on each entry's\nrecorded `packageName` — a plain overwrite in either direction silently drops\nthe other's objects, and the last pass of a multi-environment build is not\nreliably the aggregating one (#1760, #2925). `dist/manifest.json` stays\nlocal-only: a published package must not carry its dependencies' objects.\n\nThe schema-version-1 object projection is additive and high-signal: it retains\nnormalized tenant mode/field, explicit `cti`/`sti` strategy, conflict columns,\nmethod signatures, and field defaults/constraints/readonly/transient flags.\nSensitive fields are removed before both `fields` and `relationships` are\nderived, including legacy flags stored under `_meta`; matching field and\nsnake-case column names are also removed from projected conflict columns, and a\nsensitive custom tenant field is omitted while retaining scope and mode.\nGenerated artifacts assert this boundary with `sensitiveFieldsExcluded: true`;\nthe optional marker keeps schema version 1 additive while letting readers\nidentify older artifacts that require raw-manifest corroboration.\n\nConfig precedence for knowledge is defaults → top-level `knowledge` in\n`smrt.config.ts` → `packages[packageName].knowledge` → plugin option →\nobject-level `@smrt({ knowledge })`.\n\nObject-level `knowledge: false` excludes an object from authored context only;\nit must not change runtime manifest registration. Use\n`knowledge: { tags, summary, risks }` for review-sensitive domain objects.\n\nHTTP knowledge routes are disabled by default. If `knowledge.api.enabled` is\ntrue, generated SvelteKit routes must stay GET-only and guarded by dev mode or\nadmin auth.\n\n\n## Vite Plugin\n\n```typescript\n// vite.config.ts — required for @smrt() decorators (Vite 8+, oxc transform)\nexport default defineConfig({\n  oxc: {\n    decorator: {\n      legacy: true,\n      emitDecoratorMetadata: true,\n    },\n  },\n});\n```\n\nUnder Vite 8 the oxc transform does not honor the pre-Vite-8 `esbuild.tsconfigRaw`\nrecipe (or tsconfig `experimentalDecorators` reached through SvelteKit's\n`extends \"./.svelte-kit/tsconfig.json\"` chain), so that recipe throws\n`SyntaxError: Invalid or unexpected token` on the first SSR request. Configure\ndecorators through `oxc.decorator` instead. Consumers still pinned on vite<8 need\nthe legacy `esbuild.tsconfigRaw` form with `experimentalDecorators: true,\nemitDecoratorMetadata: true`.\n\nFor independent CI invocations, both `smrtPlugin()` and `smrtConsumer()` accept\nthe same `generationSnapshot: { path, sha256, provenance, sourceRoot }`. The\nschema-v1 snapshot produced by `serializeSmrtGenerationSnapshot()` contains the\nmerged project/dependency manifest, portable source paths, and source-file\ndigests; each plugin selects its own view. Reuse mode fails closed on\nbyte/provenance/path/content drift, skips scans and manifest writes, and still\ngenerates routes, types, registration, and virtual modules. Omit it for normal\nlocal development and watch mode.\n"
+      "content": "# Decorators, build integration, and knowledge\n\nKey options: `tableName`, `tableStrategy` ('cti'|'sti'), `conflictColumns`, `indexes` (declared multi-column indexes; see [schema-paths.md](schema-paths.md)), `api`/`mcp`/`cli` (generation config), `ai` (callable methods), `hooks` (beforeSave/afterSave/beforeDelete/afterDelete), `embeddings` (auto-generate), `tenantScoped`, `agent`, `ui` (`{ icon, label, description }` — nav/help hints round-tripped through the manifest as plain data; `description` is the object-level seed for form-level help, #2046).\n\nRegistration sets `SMRT_TABLE_NAME` static property (survives minification).\n\n## @field() UI hints (#2046)\n\n`@field({ ui: { basic, group, order, locked } })` — a static, presentation-only\nseed for the field-policy rail (epic #2045). Carried in the manifest under the\nfield's `_meta.ui` (never a top-level `FieldDefinition` key), readable at\nruntime via `getAllFields()` at `field._meta.ui`, and emitted (sanitized) with\n`description` into generated web-collection definitions and browser MCP tool\nschemas. No schema/persistence/security effect — `sensitive`/`readPermission`\nstay the security rail, and `sensitive`/`transient` fields never emit to the\nclient at all.\n\n## Worker registration artifact (#3117)\n\nWith `svelteKit.enabled`, a production `vite build` compiles the generated\n`smrt-register.ts` into `.smrt/runtime/register.js` after the server build\n(`src/vite-plugin/worker-registration.ts`, called once from `closeBundle`).\nadapter-node re-bundles the server from its own entries, so the web bundle is\nnever importable by a separate Node process; this artifact is how a deployed\ntask/schedule worker registers the app's local objects (and, through the\n`.smrt/register.js` it imports, consumed packages' objects) with the same\nqualified identities and isolated manifests as the web server. It is a nested\nSSR build with no consumer plugins: only aliases pointing into the project\nsources (e.g. `$lib`) apply, and every other bare import stays external so the\nworker shares the installed `@happyvertical/smrt-core` registry. SvelteKit\nvirtual modules (`$env/*`, `$app/*`) are not available to a worker; an object\nimporting one fails at worker startup. A failure fails the build.\n\n## Lightweight discovery\n\nFilesystem-only discovery, module-doc parsing, and graph freshness are owned by\n`@happyvertical/smrt-scanner/knowledge`. Core's knowledge exports remain compatible\nreexports. Runtime manifest projection and custom-action semantics stay in core.\n\n`src/knowledge-discovery.ts`, exported through `smrt-core/knowledge`, enumerates\ninstalled scope directories and reads canonical AGENTS/legacy CLAUDE docs without\nloading package code, artifacts, or scanning objects. CLI snapshots and MCP share\nthese primitives. Callers retain selection policy: snapshots resolve links and\nfall back to `packages/*` only when no installed SMRT package loads; MCP preserves\nnode_modules paths, deduplicates realpaths, excludes authored workspace links,\nand then enriches the selected packages. Workspace-root/glob discovery remains\nowned by each consumer.\n\n## Domain Knowledge Artifacts\n\n`smrtPlugin()` writes runtime manifests and agent/developer knowledge artifacts:\n\n- local dev/build: `.smrt/manifest.json` and `.smrt/smrt-knowledge.json`\n- package build: `dist/manifest.json` and `dist/smrt-knowledge.json`\n\nKeep `manifest.json` runtime-focused. `smrt-knowledge.json` is the deterministic\nagent contract for downstream review and architecture tools.\n\nThe CLI's schema-command gate reads that same merged file: a pure-consumer\nproject (0 local objects) qualifies on the consumed packages its manifest\nrecords, so a clobbered `objects` map is what made `smrt db:migrate` report\n`missing_local_manifest` (#2925).\n\n`.smrt/manifest.json` has two writers and neither owns all of it: `smrtPlugin()`\ncontributes the project's scanned objects and `smrtConsumer()` the consumed\npackages' entries. Both writes are merge-preserving, keyed on each entry's\nrecorded `packageName` — a plain overwrite in either direction silently drops\nthe other's objects, and the last pass of a multi-environment build is not\nreliably the aggregating one (#1760, #2925). `dist/manifest.json` stays\nlocal-only: a published package must not carry its dependencies' objects.\n\nThe schema-version-1 object projection is additive and high-signal: it retains\nnormalized tenant mode/field, explicit `cti`/`sti` strategy, conflict columns,\nmethod signatures, and field defaults/constraints/readonly/transient flags.\nSensitive fields are removed before both `fields` and `relationships` are\nderived, including legacy flags stored under `_meta`; matching field and\nsnake-case column names are also removed from projected conflict columns, and a\nsensitive custom tenant field is omitted while retaining scope and mode.\nGenerated artifacts assert this boundary with `sensitiveFieldsExcluded: true`;\nthe optional marker keeps schema version 1 additive while letting readers\nidentify older artifacts that require raw-manifest corroboration.\n\nConfig precedence for knowledge is defaults → top-level `knowledge` in\n`smrt.config.ts` → `packages[packageName].knowledge` → plugin option →\nobject-level `@smrt({ knowledge })`.\n\nObject-level `knowledge: false` excludes an object from authored context only;\nit must not change runtime manifest registration. Use\n`knowledge: { tags, summary, risks }` for review-sensitive domain objects.\n\nHTTP knowledge routes are disabled by default. If `knowledge.api.enabled` is\ntrue, generated SvelteKit routes must stay GET-only and guarded by dev mode or\nadmin auth.\n\n\n## Vite Plugin\n\n```typescript\n// vite.config.ts — required for @smrt() decorators (Vite 8+, oxc transform)\nexport default defineConfig({\n  oxc: {\n    decorator: {\n      legacy: true,\n      emitDecoratorMetadata: true,\n    },\n  },\n});\n```\n\nUnder Vite 8 the oxc transform does not honor the pre-Vite-8 `esbuild.tsconfigRaw`\nrecipe (or tsconfig `experimentalDecorators` reached through SvelteKit's\n`extends \"./.svelte-kit/tsconfig.json\"` chain), so that recipe throws\n`SyntaxError: Invalid or unexpected token` on the first SSR request. Configure\ndecorators through `oxc.decorator` instead. Consumers still pinned on vite<8 need\nthe legacy `esbuild.tsconfigRaw` form with `experimentalDecorators: true,\nemitDecoratorMetadata: true`.\n\nFor independent CI invocations, both `smrtPlugin()` and `smrtConsumer()` accept\nthe same `generationSnapshot: { path, sha256, provenance, sourceRoot }`. The\nschema-v1 snapshot produced by `serializeSmrtGenerationSnapshot()` contains the\nmerged project/dependency manifest, portable source paths, and source-file\ndigests; each plugin selects its own view. Reuse mode fails closed on\nbyte/provenance/path/content drift, skips scans and manifest writes, and still\ngenerates routes, types, registration, and virtual modules. Omit it for normal\nlocal development and watch mode.\n\n## Clean consumer type checks (TypeScript 6)\n\nThe consumer config hook writes `.smrt/register.js` alongside generated types\nafter route preflight succeeds. Generated SvelteKit registration imports that\nmodule, so it must exist during `svelte-kit sync`, before Vite's `buildStart`.\nBoth hosted routes and the legacy `svelteKit: true` mode follow this order.\nThe clean-consumer regression fixture ships real provider declarations and\nchecks the generated imports with `svelte-check`.\n"
     },
     {
       "path": "agents/memory.md",

package/dist/system/bootstrap.d.ts

@@ -1,4 +1,5 @@
-import { DatabaseInterface } from '@happyvertical/sql';
+/** Canonical, idempotent SMRT system-table provisioning. */
+import type { DatabaseInterface } from '@happyvertical/sql';
 /**
  * Run `work` serialized against concurrent SMRT system-table bootstrap.
  *

package/dist/system/compatibility.d.ts

@@ -1,4 +1,4 @@
-import { DatabaseInterface } from '@happyvertical/sql';
+import type { DatabaseInterface } from '@happyvertical/sql';
 import { detectEngine } from '../schema/ddl/index.js';
 export declare function tableExists(db: DatabaseInterface, tableName: string, typeHint?: string): Promise<boolean>;
 export declare function getDatabaseEngine(db: DatabaseInterface, typeHint?: string): ReturnType<typeof detectEngine>;

package/dist/system/diagnostics.d.ts

@@ -1,5 +1,20 @@
-import { DatabaseInterface } from '@happyvertical/sql';
-import { ChangeFeedEntry } from '../change-feed.js';
+/**
+ * SMRT system-diagnostics reader.
+ *
+ * A typed, SELECT-only view over the framework-owned `_smrt_*` system tables
+ * for development tooling (smrt-dev-mcp runtime diagnostics). Every read is a
+ * bounded SELECT against explicitly projected safe columns; sensitive columns
+ * are never selected and no statement here writes.
+ *
+ * The reader takes a `DatabaseInterface` (connection resolution lives with the
+ * caller) and degrades per category to a `CategoryUnavailable` result when its
+ * table is missing or a read fails — it never throws for missing tables and
+ * never fabricates data. `_smrt_registry` is a retired system table
+ * ({@link RETIRED_SYSTEM_TABLES}) and is reported as retired rather than
+ * queried.
+ */
+import type { DatabaseInterface } from '@happyvertical/sql';
+import { type ChangeFeedEntry } from '../change-feed.js';
 /** Physical `_smrt_*` tables the diagnostics reader knows about. */
 export declare const SYSTEM_DIAGNOSTICS_TABLES: {
     readonly migrations: "_smrt_schema_migrations";