@happyvertical/smrt-core 0.36.8 → 0.37.1

package/dist/object.d.ts

@@ -1,4 +1,4 @@
-import { AITool } from '@happyvertical/ai';
+import { AITextCompletionOptions, AITool } from '@happyvertical/ai';
 import { SmrtClassOptions, SmrtClass } from './class';
 import { GenerateEmbeddingsOptions } from './embeddings/types';
 import { ToolCall, ToolCallResult } from './tools/tool-executor';
@@ -42,7 +42,14 @@ export interface SmrtObjectOptions extends SmrtClassOptions {
      */
     _skipAutoEmbeddings?: boolean;
     /**
-     * Allow arbitrary field values to be passed
+     * Allow arbitrary field values to be passed.
+     *
+     * This index signature is intentionally `any` (not `unknown`): subclass
+     * option interfaces across every package (e.g. `FeatureDefinitionOptions`)
+     * are plain interfaces with no index signature, and TS does not consider
+     * such an interface assignable to `[key: string]: unknown` — only to
+     * `[key: string]: any`. Narrowing it would break `super(options)` in every
+     * downstream model. Documented irreducible leaf (S4 #1579).
      */
     [key: string]: any;
 }
@@ -63,6 +70,26 @@ export interface LoadRelatedOptions {
      */
     allowCrossTenant?: boolean;
 }
+/**
+ * Options accepted by the AI operations {@link SmrtObject.is},
+ * {@link SmrtObject.do}, and {@link SmrtObject.describe}.
+ *
+ * Extends the underlying AI client's {@link AITextCompletionOptions} (model,
+ * temperature, maxTokens, …) with two non-standard control keys that are
+ * consumed by these methods and NOT forwarded to `ai.message()`.
+ */
+export interface AiOperationOptions extends AITextCompletionOptions {
+    /**
+     * Set to `false` to omit the injected object "content body" — for callers
+     * that already curate the relevant fields into the instruction/criteria
+     * string. Any other value (including `undefined`) injects it.
+     */
+    includeData?: boolean;
+    /**
+     * Override the injected object-data truncation budget, in characters.
+     */
+    maxDataLength?: number;
+}
 /**
  * Base class for all persistent SMRT domain objects.
  *
@@ -282,7 +309,7 @@ export declare class SmrtObject extends SmrtClass {
      * @param data - Database row data (with snake_case column names)
      * @throws Error if STI validation fails
      */
-    loadDataFromDb(data: any): Promise<void>;
+    loadDataFromDb(data: Record<string, unknown>): Promise<void>;
     /**
      * Gets the database table name for this object
      */
@@ -292,7 +319,7 @@ export declare class SmrtObject extends SmrtClass {
      *
      * @returns Object containing field definitions with current values
      */
-    getFields(): Promise<Record<string, any>>;
+    getFields(): Promise<any>;
     /**
      * Override hook for customizing JSON serialization output.
      *
@@ -315,7 +342,9 @@ export declare class SmrtObject extends SmrtClass {
      * class Article extends SmrtObject {
      *   body: string = '';
      *
-     *   protected transformJSON(data: any): any {
+     *   protected transformJSON(
+     *     data: Record<string, unknown>,
+     *   ): Record<string, unknown> {
      *     return {
      *       ...data,
      *       wordCount: this.body.split(/\s+/).length,
@@ -327,7 +356,7 @@ export declare class SmrtObject extends SmrtClass {
      *
      * @see {@link toJSON} for the framework implementation (do not override)
      */
-    protected transformJSON(data: any): any;
+    protected transformJSON(data: Record<string, unknown>): Record<string, unknown>;
     /**
      * Custom JSON serialization
      * Returns a plain object with all field values for proper JSON.stringify() behavior
@@ -345,7 +374,7 @@ export declare class SmrtObject extends SmrtClass {
      * **Customization:** Override `transformJSON()` instead of this method.
      * See transformJSON() documentation for safe customization patterns.
      */
-    toJSON(): any;
+    toJSON(): Record<string, unknown>;
     /**
      * Converts this object to a plain JavaScript object (POJO)
      *
@@ -555,14 +584,14 @@ export declare class SmrtObject extends SmrtClass {
     /**
      * Gets the value of a field on this object
      */
-    protected getFieldValue(fieldName: string): any;
+    protected getFieldValue(fieldName: string): unknown;
     /**
      * Gets the value of a property.
      *
      * @param key - Property name to get value from
      * @returns The property value
      */
-    protected getPropertyValue(key: string): any;
+    protected getPropertyValue(key: string): unknown;
     /**
      * Classifies a raw database driver error message as a unique-constraint or
      * not-null-constraint violation, across SQLite, PostgreSQL and DuckDB.
@@ -694,7 +723,7 @@ export declare class SmrtObject extends SmrtClass {
      *
      * @see {@link do} for open-ended instructions instead of boolean checks
      */
-    is(criteria: string, options?: any): Promise<any>;
+    is(criteria: string, options?: AiOperationOptions): Promise<any>;
     /**
      * Performs a freeform operation on this object using AI instructions.
      *
@@ -727,7 +756,7 @@ export declare class SmrtObject extends SmrtClass {
      *
      * @see {@link is} for boolean criteria checks
      */
-    do(instructions: string, options?: any): Promise<string>;
+    do(instructions: string, options?: AiOperationOptions): Promise<string>;
     /**
      * Generates a description of this object using AI (Issue #52)
      *
@@ -756,7 +785,7 @@ export declare class SmrtObject extends SmrtClass {
      * // "Premium widget, steel construction"
      * ```
      */
-    describe(options?: any): Promise<string>;
+    describe(options?: AiOperationOptions): Promise<string>;
     /**
      * Runs a lifecycle hook if it's defined in the object's configuration
      *
@@ -823,6 +852,24 @@ export declare class SmrtObject extends SmrtClass {
      * ```
      */
     isRelatedLoaded(fieldName: string): boolean;
+    /**
+     * Internal: seed the lazy-load relationship cache from an external batch
+     * loader.
+     *
+     * `SmrtCollection`'s eager `include:` and `getOrUpsert` paths resolve
+     * relationships in bulk and need to prime each instance's cache so a later
+     * {@link loadRelated}/{@link loadRelatedMany} call returns the already-fetched
+     * value instead of re-querying. This method is the sanctioned write path into
+     * the otherwise-private `_loadedRelationships` map, so collaborators never have
+     * to structurally cast into the private field (which the no-private-reach-ins
+     * convention forbids). The leading underscore keeps it out of the generated
+     * REST/CLI/MCP surface, like other framework-internal members.
+     *
+     * @param fieldName - Relationship field whose value is being cached
+     * @param value - The loaded relationship (a `SmrtObject`, an array of them, or
+     *   `null`), stored verbatim
+     */
+    _setLoadedRelationship(fieldName: string, value: unknown): void;
     /**
      * Lazy-loads a `foreignKey` or `crossPackageRef` relationship and caches the
      * result.
@@ -917,7 +964,7 @@ export declare class SmrtObject extends SmrtClass {
     protected resolveManyToManyJoin(fieldName: string, relationship: {
         sourceClass: string;
         targetClass: string;
-        options?: any;
+        options?: Record<string, unknown>;
     }): Promise<{
         through: string;
         sourceColumn: string;
@@ -1024,8 +1071,8 @@ export declare class SmrtObject extends SmrtClass {
         id?: string;
         scope: string;
         key: string;
-        value: any;
-        metadata?: any;
+        value: unknown;
+        metadata?: unknown;
         confidence?: number;
         version?: number;
         expiresAt?: Date;
@@ -1066,7 +1113,7 @@ export declare class SmrtObject extends SmrtClass {
         key: string;
         includeAncestors?: boolean;
         minConfidence?: number;
-    }): Promise<any | null>;
+    }): Promise<unknown>;
     /**
      * Retrieves all remembered context entries for this object in a scope.
      *
@@ -1098,7 +1145,7 @@ export declare class SmrtObject extends SmrtClass {
         scope?: string;
         includeDescendants?: boolean;
         minConfidence?: number;
-    }): Promise<Map<string, any>>;
+    }): Promise<Map<string, unknown>>;
     /**
      * Deletes a specific remembered context entry for this object.
      *

package/dist/object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"object.d.ts","sourceRoot":"","sources":["../src/object.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"object.d.ts","sourceRoot":"","sources":["../src/object.ts"],"names":[],"mappings":"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"}

package/dist/object.js

@@ -289,12 +289,13 @@ class SmrtObject extends SmrtClass {
     const options = this.options;
     if (options.created_at !== void 0) this.created_at = options.created_at;
     if (options.updated_at !== void 0) this.updated_at = options.updated_at;
-    if (options._meta_type !== void 0) {
+    if (typeof options._meta_type === "string") {
       this.setMetaType(options._meta_type);
     }
     const fields = await fieldsFromClass(
       this.constructor
     );
+    const writable = this;
     for (const [key, field] of Object.entries(fields)) {
       if (options[key] !== void 0) {
         const clonedValue = this.cloneValue(options[key]);
@@ -307,7 +308,7 @@ class SmrtObject extends SmrtClass {
           }
         }
         if (!descriptor || descriptor.set || descriptor.writable === true) {
-          this[key] = clonedValue;
+          writable[key] = clonedValue;
         }
       }
     }
@@ -463,17 +464,18 @@ class SmrtObject extends SmrtClass {
       });
     }
     if (isSTI) {
-      if (!formattedData._meta_type) {
+      const metaType = formattedData._meta_type;
+      if (!metaType) {
         throw new Error(
           `STI validation failed: Missing _meta_type discriminator in database row for ${className}. Ensure the row was saved with STI support enabled.`
         );
       }
-      if (!isValidMetaType(formattedData._meta_type, className)) {
+      if (!isValidMetaType(metaType, className)) {
         throw new Error(
-          `STI validation failed: Type mismatch when loading ${className}. Database row has _meta_type='${formattedData._meta_type}' but expected '${getExpectedMetaType(className)}'. This usually means you're trying to load a row with the wrong class.`
+          `STI validation failed: Type mismatch when loading ${className}. Database row has _meta_type='${metaType}' but expected '${getExpectedMetaType(className)}'. This usually means you're trying to load a row with the wrong class.`
         );
       }
-      this.setMetaType(formattedData._meta_type);
+      this.setMetaType(metaType);
     }
     if (process.env.DEBUG_STI) {
       logger.debug("[loadDataFromDb] Starting field hydration", {
@@ -483,6 +485,7 @@ class SmrtObject extends SmrtClass {
     }
     let hydratedCount = 0;
     let skippedCount = 0;
+    const writable = this;
     for (const field in fields) {
       if (Object.hasOwn(fields, field)) {
         let descriptor = Object.getOwnPropertyDescriptor(this, field);
@@ -501,7 +504,7 @@ class SmrtObject extends SmrtClass {
               valueType: typeof value
             });
           }
-          this[field] = value;
+          writable[field] = value;
           hydratedCount++;
         } else {
           skippedCount++;
@@ -555,6 +558,11 @@ class SmrtObject extends SmrtClass {
    *
    * @returns Object containing field definitions with current values
    */
+  // Explicit `any` return (documented S4 #1579 leaf): subclasses legitimately
+  // OVERRIDE getFields() with domain-specific shapes (e.g. projects'
+  // `Project.getFields(): Promise<ProjectField[]>`), which a precise field-map
+  // return type would reject. The body below stays internally typed.
+  // biome-ignore lint/suspicious/noExplicitAny: subclasses OVERRIDE getFields() with domain shapes (e.g. `Project.getFields(): Promise<ProjectField[]>`); a precise base return type would reject those overrides. S4 #1579.
   async getFields() {
     const className = this.getResolvedClassName();
     const cachedFields = await ObjectRegistry.getAllFields(className);
@@ -595,7 +603,9 @@ class SmrtObject extends SmrtClass {
    * class Article extends SmrtObject {
    *   body: string = '';
    *
-   *   protected transformJSON(data: any): any {
+   *   protected transformJSON(
+   *     data: Record<string, unknown>,
+   *   ): Record<string, unknown> {
    *     return {
    *       ...data,
    *       wordCount: this.body.split(/\s+/).length,
@@ -636,13 +646,15 @@ class SmrtObject extends SmrtClass {
       created_at: this.created_at,
       updated_at: this.updated_at
     };
+    const self = this;
     const tableStrategy = ObjectRegistry.getTableStrategy(
       this.getResolvedQualifiedName()
     );
     const isSTI = tableStrategy === "sti";
+    const metaData = {};
     if (isSTI) {
       data._meta_type = this.getResolvedQualifiedName();
-      data._meta_data = {};
+      data._meta_data = metaData;
     }
     const registered = ObjectRegistry.getClass(className);
     let registeredFields = registered?.inheritedFields || ObjectRegistry.getFields(className);
@@ -665,7 +677,7 @@ class SmrtObject extends SmrtClass {
     }
     for (const key of registeredFields.keys()) {
       if (key.startsWith("_") || key === "id" || key === "slug" || key === "context" || key === "created_at" || key === "updated_at" || key === "options" || // Skip options object (not a database column)
-      typeof this[key] === "function") {
+      typeof self[key] === "function") {
         continue;
       }
       const fieldDef = registeredFields.get(key);
@@ -675,21 +687,22 @@ class SmrtObject extends SmrtClass {
       if (fieldDef && (fieldDef.type === "oneToMany" || fieldDef.type === "manyToMany")) {
         continue;
       }
-      const prop = this[key];
+      const prop = self[key];
       const value = this.getPropertyValue(key);
       if (value === void 0) {
         const fieldType = prop && typeof prop === "object" && "type" in prop && prop.type || fieldDef?.type;
         if (fieldType === "text") {
-          const hasTenancyMarker = prop && typeof prop === "object" && "__tenancy" in prop && prop.__tenancy?.isTenantIdField || fieldDef?.__tenancy?.isTenantIdField || fieldDef?._meta?.__tenancy?.isTenantIdField;
+          const propTenancy = prop && typeof prop === "object" && "__tenancy" in prop ? prop.__tenancy : void 0;
+          const hasTenancyMarker = propTenancy?.isTenantIdField || fieldDef?.__tenancy?.isTenantIdField || fieldDef?._meta?.__tenancy?.isTenantIdField;
           if (hasTenancyMarker) {
             if (isSTI && fieldDef?.type === "meta") {
-              data._meta_data[key] = null;
+              metaData[key] = null;
             } else {
               data[key] = null;
             }
           } else {
             if (isSTI && fieldDef?.type === "meta") {
-              data._meta_data[key] = "";
+              metaData[key] = "";
             } else {
               data[key] = "";
             }
@@ -697,7 +710,7 @@ class SmrtObject extends SmrtClass {
         } else if (fieldType === "json") {
           const defaultValue = fieldDef?.default ?? null;
           if (isSTI && fieldDef?.type === "meta") {
-            data._meta_data[key] = defaultValue;
+            metaData[key] = defaultValue;
           } else {
             data[key] = defaultValue;
           }
@@ -705,7 +718,7 @@ class SmrtObject extends SmrtClass {
         continue;
       }
       if (isSTI && fieldDef && fieldDef.type === "meta") {
-        data._meta_data[key] = value;
+        metaData[key] = value;
       } else {
         data[key] = value;
       }
@@ -899,13 +912,14 @@ class SmrtObject extends SmrtClass {
    */
   async getSlug() {
     if (!this.slug) {
+      const self = this;
       let sourceField = null;
-      if (this.name) {
-        sourceField = String(this.name);
-      } else if (this.title) {
-        sourceField = String(this.title);
-      } else if (this.label) {
-        sourceField = String(this.label);
+      if (self.name) {
+        sourceField = String(self.name);
+      } else if (self.title) {
+        sourceField = String(self.title);
+      } else if (self.label) {
+        sourceField = String(self.label);
       } else if (this.id) {
         sourceField = String(this.id);
       }
@@ -1263,9 +1277,12 @@ See issue #377: https://github.com/happyvertical/smrt/issues/377`
       }
       return;
     }
-    const fields = await fieldsFromClass(this.constructor);
+    const fields = await fieldsFromClass(
+      this.constructor
+    );
     for (const [fieldName, field] of Object.entries(fields)) {
-      if (field.options?.required) {
+      const options = field?.options;
+      if (options?.required) {
         const value = this.getFieldValue(fieldName);
         if (value === null || value === void 0 || value === "") {
           throw ValidationError.requiredField(fieldName, className);
@@ -1822,6 +1839,26 @@ Based on the content body, please follow the instructions and provide a response
   isRelatedLoaded(fieldName) {
     return this._loadedRelationships.has(fieldName);
   }
+  /**
+   * Internal: seed the lazy-load relationship cache from an external batch
+   * loader.
+   *
+   * `SmrtCollection`'s eager `include:` and `getOrUpsert` paths resolve
+   * relationships in bulk and need to prime each instance's cache so a later
+   * {@link loadRelated}/{@link loadRelatedMany} call returns the already-fetched
+   * value instead of re-querying. This method is the sanctioned write path into
+   * the otherwise-private `_loadedRelationships` map, so collaborators never have
+   * to structurally cast into the private field (which the no-private-reach-ins
+   * convention forbids). The leading underscore keeps it out of the generated
+   * REST/CLI/MCP surface, like other framework-internal members.
+   *
+   * @param fieldName - Relationship field whose value is being cached
+   * @param value - The loaded relationship (a `SmrtObject`, an array of them, or
+   *   `null`), stored verbatim
+   */
+  _setLoadedRelationship(fieldName, value) {
+    this._loadedRelationships.set(fieldName, value);
+  }
   /**
    * Lazy-loads a `foreignKey` or `crossPackageRef` relationship and caches the
    * result.
@@ -1859,6 +1896,10 @@ Based on the content body, please follow the instructions and provide a response
    *
    * @see {@link getRelated} for a convenience wrapper that auto-detects relationship type
    */
+  // Returns a polymorphic related object whose concrete subclass type only the
+  // CALLER knows (e.g. `metafield.validateValue(...)`). Typed `any` so callers
+  // can use the concrete API without a cast at every site; a generic with a
+  // `SmrtObject` default wouldn't help untyped callers. Documented S4 #1579 leaf.
   async loadRelated(fieldName, opts) {
     if (this._loadedRelationships.has(fieldName)) {
       const cached = this._loadedRelationships.get(fieldName);
@@ -1995,6 +2036,8 @@ Based on the content body, please follow the instructions and provide a response
    * console.log(`${orders.length} orders found`);
    * ```
    */
+  // Polymorphic related objects; concrete type is caller-known (see loadRelated).
+  // Documented S4 #1579 leaf.
   async loadRelatedMany(fieldName, opts) {
     if (this._loadedRelationships.has(fieldName)) {
       const cached = this._loadedRelationships.get(fieldName);
@@ -2104,7 +2147,8 @@ Based on the content body, please follow the instructions and provide a response
       fieldName
     );
     const opts = relationship.options || {};
-    const through = decorator?.through ?? opts.through ?? opts._meta?.through;
+    const optsMeta = opts._meta && typeof opts._meta === "object" ? opts._meta : void 0;
+    const through = decorator?.through ?? opts.through ?? optsMeta?.through;
     if (!through) {
       throw RuntimeError.invalidState(
         `manyToMany field ${fieldName} on ${relationship.sourceClass} is missing the 'through' join table name`,
@@ -2113,12 +2157,12 @@ Based on the content body, please follow the instructions and provide a response
     }
     const targetSimpleName = relationship.targetClass.includes(":") ? relationship.targetClass.split(":").pop() : relationship.targetClass;
     const sourceSimpleName = relationship.sourceClass.includes(":") ? relationship.sourceClass.split(":").pop() : relationship.sourceClass;
-    const sourceColumn = decorator?.sourceKey ?? opts.sourceKey ?? opts._meta?.sourceKey ?? `${toSnakeCase(sourceSimpleName)}_id`;
-    const targetColumn = decorator?.targetKey ?? opts.targetKey ?? opts._meta?.targetKey ?? `${toSnakeCase(targetSimpleName)}_id`;
+    const sourceColumn = decorator?.sourceKey ?? opts.sourceKey ?? optsMeta?.sourceKey ?? `${toSnakeCase(sourceSimpleName)}_id`;
+    const targetColumn = decorator?.targetKey ?? opts.targetKey ?? optsMeta?.targetKey ?? `${toSnakeCase(targetSimpleName)}_id`;
     return {
       through: String(through),
-      sourceColumn,
-      targetColumn,
+      sourceColumn: String(sourceColumn),
+      targetColumn: String(targetColumn),
       targetClassName: relationship.targetClass
     };
   }
@@ -2145,6 +2189,8 @@ Based on the content body, please follow the instructions and provide a response
    * const orders = await customer.getRelated('orders');
    * ```
    */
+  // Polymorphic related object(s); concrete type is caller-known (see
+  // loadRelated). Documented S4 #1579 leaf.
   async getRelated(fieldName, opts) {
     if (this._loadedRelationships.has(fieldName)) {
       const cached = this._loadedRelationships.get(fieldName);
@@ -2337,7 +2383,7 @@ Based on the content body, please follow the instructions and provide a response
     }
     if (result) {
       try {
-        return JSON.parse(result.value);
+        return JSON.parse(String(result.value));
       } catch (error) {
         logger.warn("Skipping corrupted _smrt_contexts value in recall()", {
           ownerClass: this._className,