@happyvertical/smrt-core 0.51.32 → 0.51.33

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.32",
+  "packageVersion": "0.51.33",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "f9e723deaba5c04c0d53aafb9d5b421a85f5aa63a1887d0b0a1c18db46bc65de",
-    "packageJson": "560664073fbfefcc74a2914f6036c9250394cffc57cdf2fe37e27408a6ff2fd3",
+    "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";

package/dist/system/retention.d.ts

@@ -1,4 +1,49 @@
-import { DatabaseInterface } from '@happyvertical/sql';
+/**
+ * System-table retention — bounded growth for framework-owned tables (#2375).
+ *
+ * Several `_smrt_*` tables are append-only by construction and were, until
+ * this module, unbounded by default: `_smrt_changes` grew one row per
+ * framework save/delete, `_smrt_ai_usage` one row per AI call (persistence is
+ * on by default, see `config.ts`), `_smrt_contexts` accumulated rows whose
+ * `expires_at` nothing ever enforced, `_smrt_dispatch` retained completed
+ * work until an operator remembered to run `smrt dispatch:cleanup`, and
+ * `_smrt_run_once_claims` (#3080) gains one row per `runOnce()` submission
+ * with nothing pruning completed ones.
+ *
+ * This module supplies the missing half:
+ *
+ * - {@link pruneAiUsage} — the retention API `_smrt_ai_usage` never had.
+ * - {@link pruneExpiredContexts} — enforcement for `_smrt_contexts.expires_at`.
+ * - {@link runRetentionSweep} — one entry point that applies a documented,
+ *   opt-out {@link RetentionPolicy} across every framework-owned table, plus
+ *   any task other packages contribute via {@link registerRetentionTask}
+ *   (`@happyvertical/smrt-jobs` registers job/job-event cleanup;
+ *   `@happyvertical/smrt-users` registers session and token expiry).
+ *
+ * Scheduling is the caller's: `smrt db:prune` is the cron entry point, and a
+ * running `TaskRunner` sweeps on an interval unless configured otherwise.
+ *
+ * ## Failure policy
+ *
+ * A sweep is maintenance, not a transaction. One failing task never aborts the
+ * rest — the failure is captured on that task's {@link RetentionTaskResult}
+ * and the sweep continues. Callers decide what a partial sweep means; the CLI
+ * exits non-zero when any task failed.
+ *
+ * ## Predicate indexes
+ *
+ * Every predicate below is indexed by the system DDL in `system/schema.ts`
+ * (`_smrt_contexts(expires_at)`, `_smrt_ai_usage(tenant_id, created_at)`,
+ * `_smrt_dispatch(status, processed_at)` / `(status, updated_at)`,
+ * `_smrt_run_once_claims(status, completed_at)`) or by the jobs compatibility
+ * path in `system/compatibility.ts` (`_smrt_jobs(status, completed_at)`,
+ * `_smrt_job_events(created_at)`). A new retention predicate must ship with
+ * its index.
+ *
+ * @see https://github.com/happyvertical/smrt/issues/2375
+ * @packageDocumentation
+ */
+import type { DatabaseInterface } from '@happyvertical/sql';
 /** Retention for the append-only change feed (`_smrt_changes`). */
 export interface ChangeFeedRetentionPolicy {
     /** Run this task (default `true`). */

package/dist/system/schema.d.ts

@@ -1,4 +1,10 @@
-import { DatabaseEngine } from '../schema/ddl/types.js';
+/**
+ * SMRT System Tables Schema
+ *
+ * System tables use _smrt_ prefix to avoid conflicts with user tables.
+ * All system tables are created in the same database as user data.
+ */
+import type { DatabaseEngine } from '../schema/ddl/types.js';
 /**
  * Context memory storage
  * Stores remembered context (learned strategies, patterns, selectors) for reuse

package/dist/system-fields.d.ts

@@ -1,4 +1,12 @@
-import { FieldDefinition } from './scanner/types.js';
+/**
+ * Canonical SMRT system fields inherited from `SmrtObject`.
+ *
+ * These fields exist on every persistent object at runtime even when they are
+ * not declared in a child class manifest. Keep this definition lightweight:
+ * presence matters for metadata consumers, while schema generation still owns
+ * the exact SQL defaults and constraints for these columns.
+ */
+import type { FieldDefinition } from './scanner/types.js';
 export declare const SMRT_SYSTEM_FIELDS: Readonly<Record<string, FieldDefinition>>;
 export declare function isInjectedSmrtSystemField(field: unknown): boolean;
 export declare function cloneSmrtSystemFields(): Record<string, FieldDefinition>;

package/dist/test-utils.d.ts

@@ -1,4 +1,10 @@
-import { Mock } from 'vitest';
+/**
+ * Comprehensive test utilities for SMRT framework testing
+ *
+ * Provides unified mocking for collections, objects, and database operations
+ * to support both CLI and API generator testing scenarios.
+ */
+import { type Mock } from 'vitest';
 /**
  * Snapshot ObjectRegistry state and return a restore function for manifest-heavy
  * tests that mutate registry internals at runtime.

package/dist/testing/database.d.ts

@@ -1,4 +1,21 @@
-import { DatabaseInterface } from '@happyvertical/sql';
+/**
+ * Test database utilities for SMRT framework
+ *
+ * Provides `getTestDatabase()` which creates an in-memory database with all
+ * registered SMRT object schemas. Uses the same schema generation logic as
+ * the migration system to ensure consistency between test and production.
+ *
+ * @example
+ * ```typescript
+ * import { getTestDatabase } from '@happyvertical/smrt-core/testing';
+ *
+ * beforeEach(async () => {
+ *   const db = await getTestDatabase();
+ *   collection = await MyCollection.create({ db });
+ * });
+ * ```
+ */
+import type { DatabaseInterface } from '@happyvertical/sql';
 /**
  * Options for creating a test database
  */

package/dist/testing/notifications-stub.d.ts

@@ -1,4 +1,18 @@
-import { DatabaseInterface } from '@happyvertical/sql';
+/**
+ * In-process test double for the sql package's optional notification
+ * capability (`db.notifications`, e.g. Postgres LISTEN/NOTIFY).
+ *
+ * Attaches a push-driven `notify`/`listen` pair to a database handle so tests
+ * can exercise the cross-process / cross-replica paths of the collection cache
+ * (#1498) and the change-signal bus (#1763) against a real in-memory SQLite
+ * database that has no native notification support. `notify` records every
+ * broadcast; `listen` exposes an async iterable that yields whatever `push`
+ * delivers.
+ *
+ * Extracted from `__tests__/issue-1498-collection-cache.test.ts` so the same
+ * double backs the change-signal bus tests without duplicating the stub.
+ */
+import type { DatabaseInterface } from '@happyvertical/sql';
 /** One notification as delivered over the stubbed channel. */
 export interface StubNotification {
     channel: string;

package/dist/tools/tool-executor.d.ts

@@ -1,4 +1,9 @@
-import { SignalBus } from '../signals/bus.js';
+/**
+ * Tool Call Execution for AI Function Calling
+ *
+ * This module handles runtime execution of AI tool calls on SMRT object instances.
+ */
+import type { SignalBus } from '../signals/bus.js';
 /**
  * A dynamically-dispatched tool target (typically a SmrtObject instance, but
  * typed structurally so any object whose method names are resolved at runtime

package/dist/tools/tool-generator.d.ts

@@ -1,5 +1,11 @@
-import { AITool } from '@happyvertical/ai';
-import { MethodDefinition } from '../scanner/types.js';
+/**
+ * Tool Manifest Generation for AI Function Calling
+ *
+ * This module converts TypeScript method definitions from the AST scanner
+ * into AI tool format at build time for use with LLM function calling.
+ */
+import type { AITool } from '@happyvertical/ai';
+import type { MethodDefinition } from '../scanner/types.js';
 /**
  * A JSON Schema fragment. The shape is open-ended (different keywords appear
  * for primitives, arrays, unions, etc.), so values are `unknown`; callers

package/dist/utils/json.d.ts

@@ -1,4 +1,12 @@
-import { JSONAdapter, ParseError, Result, StringifyError } from '@happyvertical/json';
+/**
+ * JSON utilities with optional SIMD acceleration
+ *
+ * Uses @happyvertical/json for faster parsing when available,
+ * with automatic fallback to native JSON.
+ *
+ * Performance: 2-3x faster parsing on large JSON files (680KB manifests)
+ */
+import { type JSONAdapter, type ParseError, type Result, type StringifyError } from '@happyvertical/json';
 /**
  * Parse JSON string with optional SIMD acceleration
  *

package/dist/utils/qualified-names.d.ts

@@ -1,4 +1,13 @@
-import { QualifiedClassName } from '../scanner/types.js';
+/**
+ * Utilities for working with qualified class names in the SMRT framework.
+ *
+ * Qualified names follow the format: "@package/name:ClassName"
+ * Example: "@happyvertical/smrt-core:Product"
+ *
+ * This format uniquely identifies classes across packages, eliminating
+ * name collisions when multiple packages define classes with the same name.
+ */
+import type { QualifiedClassName } from '../scanner/types.js';
 /**
  * Creates a qualified class name from package name and class name.
  *

package/dist/utils/scanner-module.d.ts

@@ -1,5 +1,5 @@
-import { CapabilityClassification, DomainKnowledgePlaybookStep } from '@happyvertical/smrt-types';
-import { SmartObjectManifest } from '../scanner/types.js';
+import type { CapabilityClassification, DomainKnowledgePlaybookStep } from '@happyvertical/smrt-types';
+import type { SmartObjectManifest } from '../scanner/types.js';
 /**
  * The scanner's declared agent surface (#2591), mirrored structurally like the
  * rest of this module.

package/dist/utils.d.ts

@@ -1,4 +1,4 @@
-import { SmrtObject } from './object';
+import type { SmrtObject } from './object';
 import { classnameToTablename, pluralize, toSnakeCase } from './utils/naming.js';
 import { toSafeBooleanInteger, toSafeInteger } from './utils/safe-integer.js';
 export { classnameToTablename, pluralize, toSafeBooleanInteger, toSafeInteger, toSnakeCase, };

package/dist/vite-plugin/api-client-entries.d.ts

@@ -1,4 +1,12 @@
-import { SmartObjectDefinition, SmartObjectManifest } from '../scanner/types.js';
+/**
+ * Manifest -> generated API-client entry selection.
+ *
+ * Runtime client values, Vite ambient declarations, and physical prebuild
+ * declarations must agree on which manifest object owns a collection's
+ * canonical endpoint. Collection classes describe access methods, not row
+ * payloads, so a populated model always wins the shared collection key.
+ */
+import type { SmartObjectDefinition, SmartObjectManifest } from '../scanner/types.js';
 export type ApiClientCrudMethod = 'list' | 'get' | 'create' | 'update' | 'delete' | 'search';
 export interface ApiClientEntry {
     /** Original key in manifest.objects. */

package/dist/vite-plugin/changes-route.d.ts

@@ -1,5 +1,36 @@
-import { SmartObjectManifest } from '../scanner/types';
-import { SvelteKitOptions } from './sveltekit-generator.js';
+/**
+ * SvelteKit `_changes` route generation for the change feed (issue #1758).
+ *
+ * Emits `{routesDir}/_changes/+server.ts` — an auth-guarded, tenant-scoped
+ * GET endpoint over the `_smrt_changes` log, part of the client/mobile sync
+ * contract (PRD #1755). Kept in its own module so `sveltekit-generator.ts`
+ * only carries a one-line registration.
+ *
+ * Design notes:
+ * - **Fail-closed auth** (#1540 posture): the handler requires an
+ *   authenticated principal on `locals`. The feed spans every table, so
+ *   per-model `api: { public }` opt-outs deliberately do not apply.
+ * - **Tenant scoping**: when the project has tenant-scoped objects, the
+ *   route establishes tenant context from `locals` exactly like generated
+ *   collection routes, then reads through
+ *   `getAuthorizedTenantScopedChangesSince()` — a tenant only ever sees its
+ *   own changes plus global rows.
+ * - **Table/row authorization** (#3020): the same call additionally applies
+ *   the consumer-supplied `authorizeChangeFeed`/`isChangeFeedEntryVisible`
+ *   hooks (`@happyvertical/smrt-core`'s `change-feed-authz.ts`), if
+ *   registered — a table-level and row-level seam beyond tenant scope (e.g. a
+ *   station principal reading only its own rows of a table the office can
+ *   read in full). Unregistered, behavior is unchanged from pre-#3020.
+ * - **Database resolution**: the route anchors on the project's first
+ *   generated collection (alphabetical) via the consumer's existing
+ *   `getCollection()` helper, inheriting its configuration, request-scoped
+ *   database support and system-table bootstrap. Multi-database projects
+ *   (per-object `db` overrides) see the anchor collection's feed.
+ * - Cleanup rides the existing generated-route sweep: the emitted file
+ *   starts with {@link AUTO_GENERATED_ROUTE_HEADER}.
+ */
+import type { SmartObjectManifest } from '../scanner/types';
+import type { SvelteKitOptions } from './sveltekit-generator.js';
 /**
  * Pick the class the route resolves its database through: the first
  * non-collection object by sorted manifest key, for determinism across

package/dist/vite-plugin/dev-plane-route.d.ts

@@ -1,4 +1,15 @@
-import { SvelteKitOptions } from './sveltekit-generator.js';
+/**
+ * Generated `_dev/[...tool]/+server.ts` route: the in-app runtime dev-plane
+ * (#2782). Opt-in via `svelteKit: { devPlaneRoute: { enabled: true } }`.
+ *
+ * The route is dev-only twice over: it 404s unless SvelteKit's `dev` flag is
+ * set, and it refuses to start without `SMRT_DEV_MCP_TOKEN`. Everything else
+ * — loopback checks, bearer auth, the positive read-only catalog, the MCP
+ * endpoint — lives in `@happyvertical/smrt-dev-mcp/dev-plane`, which the
+ * generated file imports at consumer runtime. Like `_resources`, the route is
+ * only emitted when that subpath resolves from the consumer.
+ */
+import type { SvelteKitOptions } from './sveltekit-generator.js';
 /** Whether `@happyvertical/smrt-dev-mcp/dev-plane` resolves from the consumer. */
 export declare function consumerHasSmrtDevMcp(projectRoot: string): boolean;
 /** Whether this invocation will own the `_dev/[...tool]` output file. */

package/dist/vite-plugin/events-route.d.ts

@@ -1,5 +1,40 @@
-import { SmartObjectManifest } from '../scanner/types';
-import { SvelteKitOptions } from './sveltekit-generator.js';
+/**
+ * SvelteKit `_events` route generation — live change signals (issue #1763,
+ * SERVER half; parent PRD #1755).
+ *
+ * Emits `{routesDir}/_events/+server.ts` — an auth-guarded, tenant-scoped
+ * Server-Sent-Events endpoint that streams coarse change signals (no row
+ * payloads). It is the push companion to the generated `_changes` route
+ * (#1758). Kept in its own module so `sveltekit-generator.ts` only carries a
+ * one-line registration.
+ *
+ * The stream lifecycle (subscribe, catch-up, heartbeat, teardown) lives in
+ * core's `buildChangeEventStream`, imported by the generated file — so the
+ * emitted route stays THIN and the stream logic is written and tested once.
+ *
+ * Design notes (mirror `changes-route.ts`):
+ * - **Fail-closed auth** (#1540 posture): the handler requires an authenticated
+ *   principal on `locals`. The signal stream spans every table, so per-model
+ *   `api: { public }` opt-outs deliberately do not apply.
+ * - **Tenant scoping**: when the project has tenant-scoped objects, the route
+ *   establishes tenant context from `locals` exactly like the `_changes` route,
+ *   then captures the resolved scope ONCE at connection open and passes it to
+ *   the stream (delivery filters against that fixed value — it cannot
+ *   re-resolve per signal outside the request's ALS context).
+ * - **Table/row authorization** (#3020): `locals` is forwarded to
+ *   `buildChangeEventStream`, which — if the consumer registered
+ *   `authorizeChangeFeed`/`isChangeFeedEntryVisible`
+ *   (`@happyvertical/smrt-core`'s `change-feed-authz.ts`) — resolves the
+ *   allowed tables ONCE at connection open (same reasoning as tenant scope)
+ *   and applies both hooks to catch-up replay AND every live signal before it
+ *   is enqueued. Unregistered, behavior is unchanged from pre-#3020.
+ * - **Database resolution**: anchors on the project's first generated
+ *   collection (alphabetical) via `getCollection()`, exactly as `_changes`.
+ * - Cleanup rides the generated-route sweep: the file starts with
+ *   {@link AUTO_GENERATED_ROUTE_HEADER}.
+ */
+import type { SmartObjectManifest } from '../scanner/types';
+import type { SvelteKitOptions } from './sveltekit-generator.js';
 /**
  * Generate the `_events/+server.ts` route. Returns true when a route was
  * written. Disabled with `sveltekit: { eventsRoute: { enabled: false } }`;

package/dist/vite-plugin/generated-client.d.ts

@@ -1,4 +1,12 @@
-import { SmartObjectManifest } from '../scanner/types.js';
+/**
+ * Shared runtime generator for producer and consumer `@smrt/client` modules.
+ *
+ * Keep runtime values on the same manifest-derived contract as physical and
+ * virtual declarations. In particular, disabled objects, partial CRUD
+ * allowlists, stable collection keys, and custom route signatures must not
+ * diverge between the two plugin entry points.
+ */
+import type { SmartObjectManifest } from '../scanner/types.js';
 export declare const GENERATED_CLIENT_CRUD_METHODS: Set<string>;
 export declare const GENERATED_CLIENT_BASE_METHODS: Set<string>;
 export declare function generateClientModule(manifest: SmartObjectManifest, options?: {