@happyvertical/smrt-core 0.30.0

package/dist/signals/bus.js

@@ -0,0 +1,102 @@
+import { createLogger } from "@happyvertical/logger";
+import { makeId } from "@happyvertical/utils";
+import { SignalSanitizer } from "./sanitizer.js";
+const logger = createLogger({ level: "info" });
+class SignalBus {
+  adapters = [];
+  sanitizer;
+  /**
+   * Create a new SignalBus
+   *
+   * @param options - Configuration options
+   */
+  constructor(options) {
+    if (options && options.sanitization !== false && options.sanitization) {
+      this.sanitizer = new SignalSanitizer(options.sanitization);
+    }
+  }
+  /**
+   * Register a signal adapter
+   *
+   * @param adapter - Adapter to register
+   */
+  register(adapter) {
+    this.adapters.push(adapter);
+  }
+  /**
+   * Unregister a signal adapter
+   *
+   * Removes the adapter from the bus to prevent memory leaks.
+   *
+   * @param adapter - Adapter to unregister
+   * @returns True if adapter was found and removed
+   */
+  unregister(adapter) {
+    const index = this.adapters.indexOf(adapter);
+    if (index !== -1) {
+      this.adapters.splice(index, 1);
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Clear all registered adapters
+   *
+   * Removes all adapters from the bus. Useful for cleanup or testing.
+   */
+  clear() {
+    this.adapters = [];
+  }
+  /**
+   * Emit a signal to all registered adapters
+   *
+   * Signals are sanitized (if configured) before being passed to adapters.
+   * Adapters are called in fire-and-forget mode - errors are logged
+   * but don't interrupt the main execution flow.
+   *
+   * @param signal - Signal to emit
+   */
+  async emit(signal) {
+    const sanitizedSignal = this.sanitizer ? this.sanitizer.sanitize(signal) : signal;
+    const promises = this.adapters.map(async (adapter, index) => {
+      try {
+        await adapter.handle(sanitizedSignal);
+      } catch (error) {
+        const adapterName = adapter.constructor.name !== "Object" ? adapter.constructor.name : `Adapter[${index}]`;
+        logger.error(`SignalBus: ${adapterName} failed to handle signal`, {
+          signalId: signal.id,
+          signalType: signal.type,
+          className: signal.className,
+          method: signal.method,
+          adapterIndex: index,
+          error: error instanceof Error ? {
+            message: error.message,
+            name: error.name,
+            stack: error.stack
+          } : error
+        });
+      }
+    });
+    void Promise.allSettled(promises);
+  }
+  /**
+   * Generate unique execution ID for method invocations
+   *
+   * @returns Unique execution ID (CUID2)
+   */
+  generateExecutionId() {
+    return makeId();
+  }
+  /**
+   * Get count of registered adapters
+   *
+   * @returns Number of registered adapters
+   */
+  get adapterCount() {
+    return this.adapters.length;
+  }
+}
+export {
+  SignalBus
+};
+//# sourceMappingURL=bus.js.map

package/dist/signals/bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bus.js","sources":["../../src/signals/bus.ts"],"sourcesContent":["/**\n * Signal Bus for Universal Event Distribution\n *\n * This module provides the central SignalBus for distributing signals\n * to registered adapters (logging, metrics, pub/sub, etc.).\n */\n\nimport { createLogger } from '@happyvertical/logger';\nimport type { Signal, SignalAdapter } from '@happyvertical/smrt-types';\nimport { makeId } from '@happyvertical/utils';\nimport type { SanitizationConfig } from './sanitizer.js';\nimport { SignalSanitizer } from './sanitizer.js';\n\nconst logger = createLogger({ level: 'info' });\n\n/**\n * Central signal distribution bus\n *\n * SignalBus manages adapter registration and signal distribution\n * with fire-and-forget error handling.\n */\nexport class SignalBus {\n  private adapters: SignalAdapter[] = [];\n  private sanitizer?: SignalSanitizer;\n\n  /**\n   * Create a new SignalBus\n   *\n   * @param options - Configuration options\n   */\n  constructor(options?: { sanitization?: SanitizationConfig | false }) {\n    if (options && options.sanitization !== false && options.sanitization) {\n      this.sanitizer = new SignalSanitizer(options.sanitization);\n    }\n  }\n\n  /**\n   * Register a signal adapter\n   *\n   * @param adapter - Adapter to register\n   */\n  register(adapter: SignalAdapter): void {\n    this.adapters.push(adapter);\n  }\n\n  /**\n   * Unregister a signal adapter\n   *\n   * Removes the adapter from the bus to prevent memory leaks.\n   *\n   * @param adapter - Adapter to unregister\n   * @returns True if adapter was found and removed\n   */\n  unregister(adapter: SignalAdapter): boolean {\n    const index = this.adapters.indexOf(adapter);\n    if (index !== -1) {\n      this.adapters.splice(index, 1);\n      return true;\n    }\n    return false;\n  }\n\n  /**\n   * Clear all registered adapters\n   *\n   * Removes all adapters from the bus. Useful for cleanup or testing.\n   */\n  clear(): void {\n    this.adapters = [];\n  }\n\n  /**\n   * Emit a signal to all registered adapters\n   *\n   * Signals are sanitized (if configured) before being passed to adapters.\n   * Adapters are called in fire-and-forget mode - errors are logged\n   * but don't interrupt the main execution flow.\n   *\n   * @param signal - Signal to emit\n   */\n  async emit(signal: Signal): Promise<void> {\n    // Sanitize signal if configured\n    const sanitizedSignal = this.sanitizer\n      ? this.sanitizer.sanitize(signal)\n      : signal;\n\n    // Fire-and-forget - don't await adapter promises\n    const promises = this.adapters.map(async (adapter, index) => {\n      try {\n        await adapter.handle(sanitizedSignal);\n      } catch (error) {\n        // Log adapter errors with detailed context\n        const adapterName =\n          adapter.constructor.name !== 'Object'\n            ? adapter.constructor.name\n            : `Adapter[${index}]`;\n\n        logger.error(`SignalBus: ${adapterName} failed to handle signal`, {\n          signalId: signal.id,\n          signalType: signal.type,\n          className: signal.className,\n          method: signal.method,\n          adapterIndex: index,\n          error:\n            error instanceof Error\n              ? {\n                  message: error.message,\n                  name: error.name,\n                  stack: error.stack,\n                }\n              : error,\n        });\n      }\n    });\n\n    // Don't wait for adapters to complete\n    // They execute asynchronously without blocking the main flow\n    void Promise.allSettled(promises);\n  }\n\n  /**\n   * Generate unique execution ID for method invocations\n   *\n   * @returns Unique execution ID (CUID2)\n   */\n  generateExecutionId(): string {\n    return makeId();\n  }\n\n  /**\n   * Get count of registered adapters\n   *\n   * @returns Number of registered adapters\n   */\n  get adapterCount(): number {\n    return this.adapters.length;\n  }\n}\n"],"names":[],"mappings":";;;AAaA,MAAM,SAAS,aAAa,EAAE,OAAO,QAAQ;AAQtC,MAAM,UAAU;AAAA,EACb,WAA4B,CAAA;AAAA,EAC5B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOR,YAAY,SAAyD;AACnE,QAAI,WAAW,QAAQ,iBAAiB,SAAS,QAAQ,cAAc;AACrE,WAAK,YAAY,IAAI,gBAAgB,QAAQ,YAAY;AAAA,IAC3D;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,SAAS,SAA8B;AACrC,SAAK,SAAS,KAAK,OAAO;AAAA,EAC5B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,WAAW,SAAiC;AAC1C,UAAM,QAAQ,KAAK,SAAS,QAAQ,OAAO;AAC3C,QAAI,UAAU,IAAI;AAChB,WAAK,SAAS,OAAO,OAAO,CAAC;AAC7B,aAAO;AAAA,IACT;AACA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,QAAc;AACZ,SAAK,WAAW,CAAA;AAAA,EAClB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,MAAM,KAAK,QAA+B;AAExC,UAAM,kBAAkB,KAAK,YACzB,KAAK,UAAU,SAAS,MAAM,IAC9B;AAGJ,UAAM,WAAW,KAAK,SAAS,IAAI,OAAO,SAAS,UAAU;AAC3D,UAAI;AACF,cAAM,QAAQ,OAAO,eAAe;AAAA,MACtC,SAAS,OAAO;AAEd,cAAM,cACJ,QAAQ,YAAY,SAAS,WACzB,QAAQ,YAAY,OACpB,WAAW,KAAK;AAEtB,eAAO,MAAM,cAAc,WAAW,4BAA4B;AAAA,UAChE,UAAU,OAAO;AAAA,UACjB,YAAY,OAAO;AAAA,UACnB,WAAW,OAAO;AAAA,UAClB,QAAQ,OAAO;AAAA,UACf,cAAc;AAAA,UACd,OACE,iBAAiB,QACb;AAAA,YACE,SAAS,MAAM;AAAA,YACf,MAAM,MAAM;AAAA,YACZ,OAAO,MAAM;AAAA,UAAA,IAEf;AAAA,QAAA,CACP;AAAA,MACH;AAAA,IACF,CAAC;AAID,SAAK,QAAQ,WAAW,QAAQ;AAAA,EAClC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,sBAA8B;AAC5B,WAAO,OAAA;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,IAAI,eAAuB;AACzB,WAAO,KAAK,SAAS;AAAA,EACvB;AACF;"}

package/dist/signals/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Signal System - Universal Event Distribution
+ *
+ * Provides automatic method tracking and event distribution
+ * for logging, metrics, pub/sub, and other observability needs.
+ */
+export type { Signal, SignalAdapter, SignalType, } from '@happyvertical/smrt-types';
+export { SignalBus } from './bus.js';
+export type { SanitizationConfig } from './sanitizer.js';
+export { SignalSanitizer } from './sanitizer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/signals/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/signals/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EACV,MAAM,EACN,aAAa,EACb,UAAU,GACX,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/signals/sanitizer.d.ts

@@ -0,0 +1,54 @@
+import { Signal } from '@happyvertical/smrt-types';
+/**
+ * Sanitization configuration
+ */
+export interface SanitizationConfig {
+    /**
+     * Keys to redact from signal payloads
+     * Default: common sensitive fields
+     */
+    redactKeys?: string[];
+    /**
+     * Custom replacer function for sanitization
+     * Return undefined to redact the value entirely
+     */
+    replacer?: (key: string, value: any) => any;
+    /**
+     * Replacement value for redacted fields
+     * Default: '[REDACTED]'
+     */
+    redactedValue?: string;
+    /**
+     * Maximum number of stack trace lines to include in sanitized errors
+     * Default: 10
+     */
+    maxStackLines?: number;
+}
+/**
+ * Signal sanitizer
+ *
+ * Removes or redacts sensitive data from signal payloads before
+ * they are processed by adapters.
+ */
+export declare class SignalSanitizer {
+    private config;
+    constructor(config?: SanitizationConfig);
+    /**
+     * Default replacer function
+     *
+     * Redacts sensitive keys and truncates long strings
+     */
+    private defaultReplacer;
+    /**
+     * Sanitize a value using the configured replacer
+     */
+    private sanitizeValue;
+    /**
+     * Sanitize a signal payload
+     *
+     * @param signal - Signal to sanitize
+     * @returns Sanitized signal (new object, doesn't mutate original)
+     */
+    sanitize(signal: Signal): Signal;
+}
+//# sourceMappingURL=sanitizer.d.ts.map

package/dist/signals/sanitizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitizer.d.ts","sourceRoot":"","sources":["../../src/signals/sanitizer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IAEtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,GAAG,CAAC;IAE5C;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAgCD;;;;;GAKG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAA+B;gBAEjC,MAAM,GAAE,kBAAuB;IAS3C;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAiBvB;;OAEG;IACH,OAAO,CAAC,aAAa;IAgDrB;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;CAgBjC"}

package/dist/signals/sanitizer.js

@@ -0,0 +1,111 @@
+const DEFAULT_REDACT_KEYS = [
+  "password",
+  "passwd",
+  "pwd",
+  "secret",
+  "token",
+  "apiKey",
+  "api_key",
+  "accessToken",
+  "access_token",
+  "refreshToken",
+  "refresh_token",
+  "privateKey",
+  "private_key",
+  "authToken",
+  "auth_token",
+  "bearerToken",
+  "bearer_token",
+  "sessionId",
+  "session_id",
+  "ssn",
+  "creditCard",
+  "credit_card",
+  "cvv",
+  "pin"
+];
+class SignalSanitizer {
+  config;
+  constructor(config = {}) {
+    this.config = {
+      redactKeys: config.redactKeys ?? DEFAULT_REDACT_KEYS,
+      replacer: config.replacer ?? this.defaultReplacer.bind(this),
+      redactedValue: config.redactedValue ?? "[REDACTED]",
+      maxStackLines: config.maxStackLines ?? 10
+    };
+  }
+  /**
+   * Default replacer function
+   *
+   * Redacts sensitive keys and truncates long strings
+   */
+  defaultReplacer(key, value) {
+    const lowerKey = key.toLowerCase();
+    if (this.config.redactKeys.some((k) => lowerKey.includes(k.toLowerCase()))) {
+      return this.config.redactedValue;
+    }
+    if (typeof value === "string" && value.length > 1e3) {
+      return `${value.substring(0, 1e3)}... [TRUNCATED]`;
+    }
+    return value;
+  }
+  /**
+   * Sanitize a value using the configured replacer
+   */
+  sanitizeValue(value, seen = /* @__PURE__ */ new WeakSet()) {
+    if (value == null) {
+      return value;
+    }
+    if (typeof value !== "object") {
+      return value;
+    }
+    if (seen.has(value)) {
+      return "[CIRCULAR]";
+    }
+    seen.add(value);
+    if (Array.isArray(value)) {
+      return value.map((item) => this.sanitizeValue(item, seen));
+    }
+    if (value instanceof Error) {
+      return {
+        message: value.message,
+        name: value.name,
+        stack: value.stack ? value.stack.split("\n").slice(0, this.config.maxStackLines).join("\n") : void 0
+      };
+    }
+    const sanitized = {};
+    for (const [key, val] of Object.entries(value)) {
+      const replacedValue = this.config.replacer(key, val);
+      if (replacedValue !== void 0) {
+        sanitized[key] = this.sanitizeValue(replacedValue, seen);
+      }
+    }
+    return sanitized;
+  }
+  /**
+   * Sanitize a signal payload
+   *
+   * @param signal - Signal to sanitize
+   * @returns Sanitized signal (new object, doesn't mutate original)
+   */
+  sanitize(signal) {
+    return {
+      id: signal.id,
+      objectId: signal.objectId,
+      className: signal.className,
+      method: signal.method,
+      type: signal.type,
+      timestamp: signal.timestamp,
+      ...signal.step && { step: signal.step },
+      ...signal.duration !== void 0 && { duration: signal.duration },
+      ...signal.args && { args: this.sanitizeValue(signal.args) },
+      ...signal.result && { result: this.sanitizeValue(signal.result) },
+      ...signal.error && { error: this.sanitizeValue(signal.error) },
+      ...signal.metadata && { metadata: this.sanitizeValue(signal.metadata) }
+    };
+  }
+}
+export {
+  SignalSanitizer
+};
+//# sourceMappingURL=sanitizer.js.map

package/dist/signals/sanitizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitizer.js","sources":["../../src/signals/sanitizer.ts"],"sourcesContent":["/**\n * Signal payload sanitization for security\n *\n * Prevents sensitive data (passwords, tokens, PII) from being leaked\n * into logs, metrics, or other signal outputs.\n */\n\nimport type { Signal } from '@happyvertical/smrt-types';\n\n/**\n * Sanitization configuration\n */\nexport interface SanitizationConfig {\n  /**\n   * Keys to redact from signal payloads\n   * Default: common sensitive fields\n   */\n  redactKeys?: string[];\n\n  /**\n   * Custom replacer function for sanitization\n   * Return undefined to redact the value entirely\n   */\n  replacer?: (key: string, value: any) => any;\n\n  /**\n   * Replacement value for redacted fields\n   * Default: '[REDACTED]'\n   */\n  redactedValue?: string;\n\n  /**\n   * Maximum number of stack trace lines to include in sanitized errors\n   * Default: 10\n   */\n  maxStackLines?: number;\n}\n\n/**\n * Default sensitive keys to redact\n */\nconst DEFAULT_REDACT_KEYS = [\n  'password',\n  'passwd',\n  'pwd',\n  'secret',\n  'token',\n  'apiKey',\n  'api_key',\n  'accessToken',\n  'access_token',\n  'refreshToken',\n  'refresh_token',\n  'privateKey',\n  'private_key',\n  'authToken',\n  'auth_token',\n  'bearerToken',\n  'bearer_token',\n  'sessionId',\n  'session_id',\n  'ssn',\n  'creditCard',\n  'credit_card',\n  'cvv',\n  'pin',\n];\n\n/**\n * Signal sanitizer\n *\n * Removes or redacts sensitive data from signal payloads before\n * they are processed by adapters.\n */\nexport class SignalSanitizer {\n  private config: Required<SanitizationConfig>;\n\n  constructor(config: SanitizationConfig = {}) {\n    this.config = {\n      redactKeys: config.redactKeys ?? DEFAULT_REDACT_KEYS,\n      replacer: config.replacer ?? this.defaultReplacer.bind(this),\n      redactedValue: config.redactedValue ?? '[REDACTED]',\n      maxStackLines: config.maxStackLines ?? 10,\n    };\n  }\n\n  /**\n   * Default replacer function\n   *\n   * Redacts sensitive keys and truncates long strings\n   */\n  private defaultReplacer(key: string, value: any): any {\n    // Check if key should be redacted\n    const lowerKey = key.toLowerCase();\n    if (\n      this.config.redactKeys.some((k) => lowerKey.includes(k.toLowerCase()))\n    ) {\n      return this.config.redactedValue;\n    }\n\n    // Truncate very long strings (potential data dumps)\n    if (typeof value === 'string' && value.length > 1000) {\n      return `${value.substring(0, 1000)}... [TRUNCATED]`;\n    }\n\n    return value;\n  }\n\n  /**\n   * Sanitize a value using the configured replacer\n   */\n  private sanitizeValue(value: any, seen = new WeakSet()): any {\n    // Handle null/undefined\n    if (value == null) {\n      return value;\n    }\n\n    // Handle primitives\n    if (typeof value !== 'object') {\n      return value;\n    }\n\n    // Prevent circular reference infinite loops\n    if (seen.has(value)) {\n      return '[CIRCULAR]';\n    }\n    seen.add(value);\n\n    // Handle arrays\n    if (Array.isArray(value)) {\n      return value.map((item) => this.sanitizeValue(item, seen));\n    }\n\n    // Handle Error objects specially\n    if (value instanceof Error) {\n      return {\n        message: value.message,\n        name: value.name,\n        stack: value.stack\n          ? value.stack\n              .split('\\n')\n              .slice(0, this.config.maxStackLines)\n              .join('\\n')\n          : undefined,\n      };\n    }\n\n    // Handle regular objects\n    const sanitized: Record<string, any> = {};\n    for (const [key, val] of Object.entries(value)) {\n      const replacedValue = this.config.replacer(key, val);\n      if (replacedValue !== undefined) {\n        sanitized[key] = this.sanitizeValue(replacedValue, seen);\n      }\n    }\n\n    return sanitized;\n  }\n\n  /**\n   * Sanitize a signal payload\n   *\n   * @param signal - Signal to sanitize\n   * @returns Sanitized signal (new object, doesn't mutate original)\n   */\n  sanitize(signal: Signal): Signal {\n    return {\n      id: signal.id,\n      objectId: signal.objectId,\n      className: signal.className,\n      method: signal.method,\n      type: signal.type,\n      timestamp: signal.timestamp,\n      ...(signal.step && { step: signal.step }),\n      ...(signal.duration !== undefined && { duration: signal.duration }),\n      ...(signal.args && { args: this.sanitizeValue(signal.args) }),\n      ...(signal.result && { result: this.sanitizeValue(signal.result) }),\n      ...(signal.error && { error: this.sanitizeValue(signal.error) }),\n      ...(signal.metadata && { metadata: this.sanitizeValue(signal.metadata) }),\n    };\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/smrt-knowledge.json

@@ -0,0 +1,335 @@
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-06-23T01:10:51.821Z",
+  "packageName": "@happyvertical/smrt-core",
+  "packageVersion": "0.30.0",
+  "sourceManifestPath": "dist/manifest.json",
+  "agentDocPath": "AGENTS.md",
+  "sourceHashes": {
+    "manifest": "ba1a2dc48fc394b05975859d7848cc3df11eb453116ed04b2317ac887987f655",
+    "packageJson": "39b69770f93605b93f0560ff5b2ebf0ba14c947c9aa471d123b48d031339aa02",
+    "agents": "0fa157a078aa44a0bc104540bd27f0b1e52e66549b7994cba751438a8d44c827"
+  },
+  "exports": [
+    ".",
+    "./consumer-plugin",
+    "./generators",
+    "./generators/cli",
+    "./generators/mcp",
+    "./generators/rest",
+    "./generators/swagger",
+    "./knowledge",
+    "./manifest",
+    "./manifest.json",
+    "./manifest/discover-base-classes",
+    "./manifest/discover-smrt-packages",
+    "./migrations",
+    "./prebuild",
+    "./prebuild/cli",
+    "./runtime",
+    "./scanner",
+    "./scanner/types",
+    "./schema/utils",
+    "./smrt-knowledge.json",
+    "./table-cache",
+    "./testing",
+    "./utils",
+    "./utils/import-workspace-module",
+    "./vite-plugin"
+  ],
+  "dependencies": {
+    "@happyvertical/ai": "catalog:",
+    "@happyvertical/files": "catalog:",
+    "@happyvertical/json": "catalog:",
+    "@happyvertical/logger": "catalog:",
+    "@happyvertical/smrt-config": "workspace:*",
+    "@happyvertical/smrt-scanner": "workspace:*",
+    "@happyvertical/smrt-types": "workspace:*",
+    "@happyvertical/sql": "catalog:",
+    "@happyvertical/utils": "catalog:",
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "cheerio": "^1.1.2",
+    "fast-glob": "3.3.3",
+    "minimatch": "10.1.1",
+    "pluralize": "^8.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "yaml": "^2.8.2",
+    "@faker-js/faker": "^10.2.0",
+    "@huggingface/transformers": ">=3.0.0 <4.0.0",
+    "@types/node": "25.0.9",
+    "@types/pluralize": "^0.0.33",
+    "@xenova/transformers": "^2.17.0",
+    "vite": "7.3.1",
+    "vite-plugin-dts": "4.5.4",
+    "vitest": "^4.0.17"
+  },
+  "smrtDependencies": [
+    "@happyvertical/smrt-config",
+    "@happyvertical/smrt-scanner",
+    "@happyvertical/smrt-types"
+  ],
+  "sdkDependencies": [
+    "@happyvertical/ai",
+    "@happyvertical/files",
+    "@happyvertical/json",
+    "@happyvertical/logger",
+    "@happyvertical/sql",
+    "@happyvertical/utils"
+  ],
+  "tags": [],
+  "risks": [],
+  "objects": [
+    {
+      "name": "SmrtClass",
+      "qualifiedName": "@happyvertical/smrt-core:SmrtClass",
+      "collection": "smrtclasses",
+      "tableName": "smrt_classes",
+      "packageName": "@happyvertical/smrt-core",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "destroy",
+        "getAiUsageSnapshot",
+        "listAiUsage",
+        "resetAiUsage",
+        "summarizeAiUsage"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "SmrtCollection",
+      "qualifiedName": "@happyvertical/smrt-core:SmrtCollection",
+      "collection": "smrtcollections",
+      "tableName": "smrt_collections",
+      "packageName": "@happyvertical/smrt-core",
+      "extends": "SmrtClass",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "count",
+        "create",
+        "delete",
+        "ensureStorageReady",
+        "findAll",
+        "findById",
+        "findOne",
+        "findSimilar",
+        "findSimilarToEmbedding",
+        "forget",
+        "forgetScope",
+        "generateMissingEmbeddings",
+        "generateSchema",
+        "generateTableName",
+        "get",
+        "getDiff",
+        "getFields",
+        "getFieldsSync",
+        "getOrUpsert",
+        "initialize",
+        "list",
+        "listByIds",
+        "query",
+        "recall",
+        "recallAll",
+        "remember",
+        "semanticSearch",
+        "validate"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "SmrtHierarchical",
+      "qualifiedName": "@happyvertical/smrt-core:SmrtHierarchical",
+      "collection": "smrthierarchicals",
+      "tableName": "smrt_hierarchicals",
+      "packageName": "@happyvertical/smrt-core",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "parentId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [],
+      "methods": [
+        "getAncestors",
+        "getChildren",
+        "getDescendants",
+        "getHierarchy",
+        "getParent",
+        "moveTo"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "SmrtJunction",
+      "qualifiedName": "@happyvertical/smrt-core:SmrtJunction",
+      "collection": "smrtjunctions",
+      "tableName": "smrt_junctions",
+      "packageName": "@happyvertical/smrt-core",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "attach",
+        "byLeft",
+        "byRight",
+        "detach",
+        "setLinks"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "SmrtObject",
+      "qualifiedName": "@happyvertical/smrt-core:SmrtObject",
+      "collection": "smrtobjects",
+      "tableName": "smrt_objects",
+      "packageName": "@happyvertical/smrt-core",
+      "extends": "SmrtClass",
+      "fields": [
+        {
+          "name": "created_at",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "updated_at",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        }
+      ],
+      "relationships": [],
+      "methods": [
+        "classifyConstraintError",
+        "clearEmbeddings",
+        "delete",
+        "describe",
+        "do",
+        "executeToolCall",
+        "forget",
+        "forgetScope",
+        "generateEmbeddings",
+        "getAvailableTools",
+        "getEmbedding",
+        "getFields",
+        "getId",
+        "getRelated",
+        "getSavedId",
+        "getSlug",
+        "hasStaleEmbeddings",
+        "initialize",
+        "is",
+        "isRelatedLoaded",
+        "isSaved",
+        "loadDataFromDb",
+        "loadFromId",
+        "loadFromSlug",
+        "loadRelated",
+        "loadRelatedMany",
+        "markAsPersisted",
+        "recall",
+        "recallAll",
+        "remember",
+        "save",
+        "toJSON",
+        "toPlainObject",
+        "toPublicJSON"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "SmrtPolymorphicAssociation",
+      "qualifiedName": "@happyvertical/smrt-core:SmrtPolymorphicAssociation",
+      "collection": "smrtpolymorphicassociations",
+      "tableName": "smrt_polymorphic_associations",
+      "packageName": "@happyvertical/smrt-core",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "metaType",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "metaId",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "role",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "sortOrder",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER"
+        }
+      ],
+      "relationships": [],
+      "methods": [
+        "hydrate"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "SmrtPolymorphicAssociation",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    }
+  ],
+  "surfaces": [],
+  "prompts": [
+    {
+      "filePath": "src/knowledge.test.ts",
+      "key": "orders.review"
+    },
+    {
+      "filePath": "src/knowledge.ts"
+    }
+  ],
+  "relationshipsV2": {
+    "foreignKeyFields": 0,
+    "crossPackageRefFields": 0,
+    "junctionCollections": 0,
+    "hierarchicalObjects": 0,
+    "polymorphicAssociations": 1,
+    "uuidColumns": 6
+  },
+  "agentDoc": "# @happyvertical/smrt-core\n\nORM, code generation, AI integration, and the DispatchBus. Everything else builds on this.\n\n## Key Classes\n\n| Class | File | Purpose |\n|-------|------|---------|\n| SmrtObject | `src/object.ts` | Base persistent object — save, delete, is(), do(), loadFromId/Slug |\n| SmrtCollection | `src/collection.ts` | CRUD collection — list, get, create, delete, getOrUpsert |\n| ObjectRegistry | `src/registry.ts` | Global singleton (globalThis) — class metadata, fields, STI chains, manifests |\n| DispatchBus | `src/dispatch/bus.ts` | Inter-agent messaging — emit, subscribe (persistent), process |\n| GlobalInterceptors | `src/interceptors.ts` | Plugin system — beforeList/Get/Save/Delete hooks (used by tenancy) |\n\n## SmrtObject Lifecycle\n\n`constructor(options)` → `initialize()` → ready for `save()`/`delete()`/`loadFromId()`\n\n- `initialize()`: loads field initializers, applies option values (options override initializers), loads from DB if id/slug provided\n- `save()`: upsert with STI validation, interceptor execution, auto-embeddings. Persisted objects (`isPersisted` — set by DB hydration and successful saves) upsert on `['id']` so natural-key edits (e.g. slug renames) update in place; new objects upsert on the natural-key conflict columns for ingestion-style dedup (#1472)\n- `is(criteria)` / `do(instructions)` / `describe()`: AI operations via function calling. They inject the object's own `toPublicJSON()` (sensitive fields stripped) as a \"content body\" so the model reasons over the instance. Options: `includeData: false` skips injection (for callers that already curate the relevant fields into the instruction); `maxDataLength` overrides the truncation budget. Neither key is forwarded to `ai.message()`. (#1567)\n- `getSlug()`: auto-generates from name → title → label → id\n- `loadRelated(fieldName)`: lazy-loads relationships (cached in `_loadedRelationships` Map)\n\n## SmrtCollection Query\n\n```typescript\nawait collection.list({\n  where: { status: 'active', price: { op: '>', value: 10 } },\n  limit: 50, offset: 0, orderBy: 'created_at DESC'\n});\n```\n\n**WHERE operators**: `=`, `>`, `<`, `>=`, `<=`, `!=`, `in`, `not in`, `like`, `is null`, `is not null`. Arrays auto-detect `IN`. Dot notation for JSON paths: `metadata.userId`.\n\nSTI child collections auto-filter by `_meta_type`.\n\n## @smrt() Decorator Options\n\nKey options: `tableName`, `tableStrategy` ('cti'|'sti'), `conflictColumns`, `api`/`mcp`/`cli` (generation config), `ai` (callable methods), `hooks` (beforeSave/afterSave/beforeDelete/afterDelete), `embeddings` (auto-generate), `tenantScoped`, `agent`.\n\nRegistration sets `SMRT_TABLE_NAME` static property (survives minification).\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\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## DispatchBus\n\n- `emit(signalType, payload, metadata)` → creates persistent Dispatch record\n- `on(pattern, handler)` → in-memory handler (immediate)\n- `subscribe({ signalType, subscriber })` → persistent subscription (survives restarts)\n- `process(subscriberName, handler)` → process pending dispatches\n- Wildcards: `campaign.*` matches `campaign.completed` (single segment only)\n- Tables: `_smrt_dispatch`, `_smrt_dispatch_subscriptions`\n- Status: `pending → processing → completed` (or `failed`)\n\n## Single Table Inheritance (STI)\n\n- Base: `@smrt({ tableStrategy: 'sti' })` — children inherit, share one table\n- Discriminator: `_meta_type` column with qualified names (`@happyvertical/smrt-content:Article`)\n- Child fields: `@meta()` decorator → stored in `_meta_data` JSONB (not as columns)\n- Polymorphic queries: collection loads `_meta_type`, creates correct subclass dynamically\n- Validation: fail-fast on save if `_meta_type` missing or mismatched\n\n## Code Generators\n\n| Generator | Location | Output |\n|-----------|----------|--------|\n| REST API | `src/generators/rest.ts` | OpenAPI-compliant CRUD endpoints |\n| CLI | `src/generators/cli.ts` | `objectname:action` admin commands — writable allowlist, exhaustive-include, `--from-file`, fail-closed tenant context |\n| MCP Server | `src/generators/mcp.ts` | Model Context Protocol tools |\n\n## Child Accessors (R10)\n\n`src/child-accessors.ts` installs a consistent `get<FieldName>()` instance method for every `@oneToMany` field at `@smrt()` registration time (e.g. `@oneToMany('OrderItem') items` → `order.getItems()`), delegating to `loadRelatedMany`. Two invariants:\n\n- **Additive** — never overwrites a hand-rolled method of the same name (checks the whole prototype chain). `Profile.getMetadata()` (key-value) and `ProfileRelationship.getTerms()` are preserved.\n- **Runtime-only** — attached to the prototype, invisible to the build-time manifest, so it never leaks into the REST/CLI/MCP surface.\n\nWhen the target declares multiple FKs back to the parent, annotate `@oneToMany(Target, { foreignKey: '<inverseField>' })`; `loadRelatedMany` and the eager `include:` loader both honor it (else first-match).\n\n## Vite Plugin\n\n```typescript\n// vite.config.ts — required for @smrt() decorators\nexport default defineConfig({\n  esbuild: {\n    tsconfigRaw: {\n      compilerOptions: { experimentalDecorators: true, emitDecoratorMetadata: true }\n    }\n  }\n});\n```\n\n## Gotchas\n\n- **Never override toJSON()** — handles STI discriminator + meta field extraction. Use `transformJSON()`\n- **Property init order**: TypeScript initializers run first, then `initialize()` applies option values (options win)\n- **No runtime schema creation**: application tables must be prepared explicitly via migrations/tooling; runtime only verifies and fails clearly\n- **Retry logic**: `db.get()` (3 retries, 250ms) and `db.upsert()` (3 retries, 500ms) have built-in retry\n- **Field caching**: `_cachedFields` populated during `Collection.create()` — eliminates async `getFields()` per query\n- **Smart cloning**: arrays/objects shallow-cloned in property init to prevent aliasing (Issue #22)\n- **Table verification cache**: `isTableVerified(dbUrl, tableName)` avoids redundant `tableExists()` calls\n- **Manifest required**: build-time AST scanning creates manifest. Without vitest plugin → \"No field metadata\"\n- **Vite plugin loads scanner from `dist/` first**: `src/vite-plugin/import-build-aware.ts` prefers `dist/` when it exists on disk; it only falls back to `src/` on fresh clones. So if you edit `src/scanner/*.ts` or `src/schema/generator.ts` and want those edits reflected in consumer manifest generation, you must rebuild (`pnpm build` or have `pnpm dev` / `pnpm build:watch` running in core). This is intentional — sniffing `.ts` vs `.js` via `import.meta.url` was non-deterministic under tsx and broke 12–13 publishes (#1139).\n"
+}

package/dist/system/compatibility.d.ts

@@ -0,0 +1,8 @@
+import { DatabaseInterface } from '@happyvertical/sql';
+export declare function tableExists(db: DatabaseInterface, tableName: string, typeHint?: string): Promise<boolean>;
+export declare function ensureDispatchSystemTableCompatibility(db: DatabaseInterface, typeHint?: string): Promise<void>;
+export declare function ensureDispatchSubscriptionsSystemTableCompatibility(db: DatabaseInterface, typeHint?: string): Promise<void>;
+export declare function ensureJobsSystemTableCompatibility(db: DatabaseInterface, typeHint?: string): Promise<void>;
+export declare function ensureJobEventsSystemTableCompatibility(db: DatabaseInterface, typeHint?: string): Promise<void>;
+export declare function ensureLegacySystemTableCompatibility(db: DatabaseInterface, typeHint?: string): Promise<void>;
+//# sourceMappingURL=compatibility.d.ts.map

package/dist/system/compatibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compatibility.d.ts","sourceRoot":"","sources":["../../src/system/compatibility.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AA0B5D,wBAAsB,WAAW,CAC/B,EAAE,EAAE,iBAAiB,EACrB,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAgBlB;AAiXD,wBAAsB,sCAAsC,CAC1D,EAAE,EAAE,iBAAiB,EACrB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CA4Cf;AAED,wBAAsB,mDAAmD,CACvE,EAAE,EAAE,iBAAiB,EACrB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CA+Bf;AAED,wBAAsB,kCAAkC,CACtD,EAAE,EAAE,iBAAiB,EACrB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAaf;AAED,wBAAsB,uCAAuC,CAC3D,EAAE,EAAE,iBAAiB,EACrB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAwCf;AAED,wBAAsB,oCAAoC,CACxD,EAAE,EAAE,iBAAiB,EACrB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAKf"}