refactor: address code review feedback — extract constant, improve types, add docs

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

packages/runtime/src/app-plugin.ts

@@ -2,6 +2,7 @@
 
 import { Plugin, PluginContext } from '@objectstack/core';
 import { SeedLoaderService } from './seed-loader.js';
+import type { IMetadataService } from '@objectstack/spec/contracts';
 
 /**
  * AppPlugin
@@ -139,7 +140,7 @@ export class AppPlugin implements Plugin {
 
              // Use SeedLoaderService for metadata-driven loading with reference resolution
              try {
-                 const metadata = ctx.getService('metadata') as any;
+                 const metadata = ctx.getService('metadata') as IMetadataService | undefined;
                  if (metadata) {
                      const seedLoader = new SeedLoaderService(ql, metadata, ctx.logger);
                      const { SeedLoaderRequestSchema } = await import('@objectstack/spec/data');

packages/runtime/src/seed-loader.ts

@@ -21,6 +21,9 @@ interface Logger {
   debug(message: string, meta?: Record<string, any>): void;
 }
 
+/** Default field used for externalId matching on target objects */
+const DEFAULT_EXTERNAL_ID_FIELD = 'name';
+
 /**
  * SeedLoaderService — Runtime implementation of ISeedLoaderService
  *
@@ -132,7 +135,7 @@ export class SeedLoaderService implements ISeedLoaderService {
             references.push({
               field: fieldName,
               targetObject,
-              targetField: 'name', // Default externalId
+              targetField: DEFAULT_EXTERNAL_ID_FIELD,
               fieldType: fieldDef.type as 'lookup' | 'master_detail',
             });
           }
@@ -483,6 +486,8 @@ export class SeedLoaderService implements ISeedLoaderService {
     // Build adjacency list and in-degree counts
     for (const node of nodes) {
       for (const dep of node.dependsOn) {
+        // Exclude self-references from ordering (e.g., employee.manager_id → employee).
+        // Self-referencing fields are still tracked in node.references for resolution.
         if (objectSet.has(dep) && dep !== node.object) {
           adjacency.get(dep)!.push(node.object);
           inDegree.set(node.object, (inDegree.get(node.object) || 0) + 1);
@@ -578,7 +583,7 @@ export class SeedLoaderService implements ISeedLoaderService {
 
   private filterByEnv(datasets: Dataset[], env?: string): Dataset[] {
     if (!env) return datasets;
-    return datasets.filter(d => d.env.includes(env as any));
+    return datasets.filter(d => (d.env as string[]).includes(env));
   }
 
   private orderDatasets(datasets: Dataset[], insertOrder: string[]): Dataset[] {

packages/spec/src/contracts/seed-loader-service.ts

@@ -30,6 +30,12 @@ export interface ISeedLoaderService {
   /**
    * Load one or more datasets with full reference resolution and dependency ordering.
    *
+   * The loader automatically:
+   * 1. Filters datasets by environment if `config.env` is set
+   * 2. Builds a dependency graph from object metadata (lookup/master_detail fields)
+   * 3. Topologically sorts datasets so parent objects are inserted before children
+   * 4. Resolves references via externalId, with multi-pass for circular dependencies
+   *
    * @param request - Parsed SeedLoaderRequest (datasets + config)
    * @returns Structured result with per-object stats, errors, and summary
    */