feat(seed): per-organization seed replay for multi-tenant SaaS

hotlong · Copilot · hotlong · commit 4b45c54fd686 · 2026-05-18T12:38:29.000+08:00
Every newly created sys_organization now gets its own private copy of
the artifact's demo data (Salesforce-sandbox style) — independent of
other tenants, populated automatically on org creation regardless of
whether the org was auto-created by signup or manually via the
better-auth createOrganization API.

Pipeline:
- SeedLoaderConfig gains optional 'organizationId' — when set, each
  record is stamped with that org and existing-record lookups
  (loadExistingRecords / resolveFromDatabase) are scoped to that org
  so upsert produces an independent per-tenant copy.
- AppPlugin registers two kernel services at start: 'seed-datasets'
  (the parsed array) and 'seed-replayer' (a (orgId) =&gt; summary
  closure that wraps SeedLoaderService). In multi-tenant mode it
  also SKIPS the inline AppPlugin seed-insert — replay happens
  per-org instead, eliminating NULL-org rows that previously needed
  the orphan-claim hack.
- SecurityPlugin's sys_organization insert middleware now calls the
  'seed-replayer' service for every new org (first or Nth). When the
  replayer is unavailable it falls back to the legacy
  claimOrphanTenantRows (first org) or cloneTenantSeedData (Nth org)
  paths for backwards compatibility.

Fixes the reported issue where signing up a second user on
crm.objectos.app produced an empty CRM dashboard — the demo
accounts/contacts/leads/etc. were claimed by the first org and
invisible to all subsequent tenants.

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/packages/plugins/plugin-security/src/security-plugin.ts b/packages/plugins/plugin-security/src/security-plugin.ts
@@ -402,13 +402,30 @@ export class SecurityPlugin implements Plugin {
       }
     });
 
-    // After a sys_organization insert, if this is the FIRST organization
-    // in the system, back-fill `organization_id` on every seed-loaded
-    // user-defined row that landed with `organization_id IS NULL`. Seeds
-    // run as `isSystem` (no auto-fill), so without this hook, demo data
-    // shipped with `defineDataset()` would be invisible to anyone with
-    // an active organization. Idempotent: only fires when row count
-    // before this insert was zero, then never again.
+    // After a sys_organization insert, give the new org its own private
+    // copy of the artifact's demo data (Salesforce-sandbox style):
+    //
+    //   1. PRIMARY PATH — replay the seed datasets registered on the
+    //      kernel's `seed-datasets` service (populated by AppPlugin at
+    //      start) with `organizationId: <newOrgId>`. SeedLoader scopes
+    //      both existing-record lookups and reference resolution to
+    //      that org, so upsert mode produces an independent copy per
+    //      tenant. This works for the FIRST org and EVERY subsequent
+    //      org, whether the org was auto-created by signup
+    //      (`ensureUserHasOrganization`) or manually via the
+    //      better-auth `createOrganization` API.
+    //
+    //   2. FALLBACK A — when no `seed-datasets` service is registered
+    //      (e.g. a plugin-shaped deployment with no AppPlugin), and
+    //      this is the FIRST org, fall back to the legacy
+    //      `claimOrphanTenantRows` path that adopts any NULL-org rows
+    //      a previous AppPlugin inline-seed may have inserted.
+    //
+    //   3. FALLBACK B — when no `seed-datasets` service is registered
+    //      and this is NOT the first org, fall back to
+    //      `cloneTenantSeedData` (donor-based row copy from the very
+    //      first org). Useful for upgrade paths where the new
+    //      service-based flow hasn't been wired yet.
     if (this.multiTenant) {
       ql.registerMiddleware(async (opCtx: any, next: () => Promise<void>) => {
         await next();
@@ -420,6 +437,20 @@ export class SecurityPlugin implements Plugin {
         }
         const newOrgId = opCtx?.result?.id ?? opCtx?.data?.id;
         if (!newOrgId) return;
+
+        // Locate the kernel via ctx — most kernel impls expose either
+        // `getService` on PluginContext directly or attach the kernel
+        // ref. Anything we can't resolve becomes `undefined` and we
+        // gracefully fall back.
+        const kernel: any = (ctx as any).kernel ?? ctx;
+        let datasets: any[] | undefined;
+        try {
+          const raw = kernel?.getService?.('seed-datasets');
+          if (Array.isArray(raw) && raw.length > 0) datasets = raw;
+        } catch { /* service not registered */ }
+
+        // Count existing orgs to pick the right fallback path.
+        let orgCount = 0;
         try {
           const allOrgs = await ql.find(
             'sys_organization',
@@ -431,20 +462,82 @@ export class SecurityPlugin implements Plugin {
             : Array.isArray(allOrgs?.records)
               ? allOrgs.records
               : [];
-          if (list.length !== 1) return;
-          const claims = await claimOrphanTenantRows(ql, newOrgId, { logger: ctx.logger });
-          if (claims.length > 0) {
-            const total = claims.reduce((s, c) => s + c.count, 0);
+          orgCount = list.length;
+        } catch (e) {
+          ctx.logger.warn('[security] failed to count organizations', {
+            error: (e as Error).message,
+          });
+        }
+
+        // ── Primary path: SeedLoader replay scoped to newOrgId ─────
+        // Uses the `seed-replayer` callable that AppPlugin registers
+        // on the kernel (keeps plugin-security free of @objectstack/runtime
+        // import — runtime already depends on us, so the reverse would
+        // be circular).
+        let replayed = false;
+        try {
+          const replayer: any = kernel?.getService?.('seed-replayer');
+          if (typeof replayer === 'function') {
+            const summary = await replayer(newOrgId);
+            const total = (summary?.inserted ?? 0) + (summary?.updated ?? 0);
             ctx.logger.info(
-              `[security] claimed ${total} orphan seed row(s) for first organization ${newOrgId}`,
-              { breakdown: claims },
+              `[security] per-org seed replay for ${newOrgId}: +${summary?.inserted ?? 0} inserted, ${summary?.updated ?? 0} updated, ${summary?.errors?.length ?? 0} error(s)`,
+              {
+                organizationId: newOrgId,
+                errors: summary?.errors?.slice?.(0, 5),
+              },
             );
+            if (total > 0) replayed = true;
+          } else if (datasets) {
+            ctx.logger.warn('[security] per-org seed: datasets present but no replayer registered', {
+              organizationId: newOrgId,
+            });
           }
         } catch (e) {
-          ctx.logger.warn('[security] claim-orphan-tenant-rows failed', {
+          ctx.logger.warn('[security] per-org seed replay failed, falling back', {
+            organizationId: newOrgId,
             error: (e as Error).message,
           });
         }
+        if (replayed) return;
+
+        // ── Fallback A: legacy claim for first org ─────────────────
+        if (orgCount === 1) {
+          try {
+            const claims = await claimOrphanTenantRows(ql, newOrgId, { logger: ctx.logger });
+            if (claims.length > 0) {
+              const total = claims.reduce((s, c) => s + c.count, 0);
+              ctx.logger.info(
+                `[security] claimed ${total} orphan seed row(s) for first organization ${newOrgId}`,
+                { breakdown: claims },
+              );
+              return;
+            }
+          } catch (e) {
+            ctx.logger.warn('[security] claim-orphan-tenant-rows failed', {
+              error: (e as Error).message,
+            });
+          }
+        }
+
+        // ── Fallback B: clone from donor org for subsequent orgs ───
+        if (orgCount > 1) {
+          try {
+            const summary = await cloneTenantSeedData(ql, newOrgId, { logger: ctx.logger });
+            if (summary.length > 0) {
+              const total = summary.reduce((s, c) => s + c.count, 0);
+              ctx.logger.info(
+                `[security] cloned ${total} seed row(s) for new organization ${newOrgId}`,
+                { breakdown: summary },
+              );
+            }
+          } catch (e) {
+            ctx.logger.warn('[security] clone-tenant-seed-data failed', {
+              organizationId: newOrgId,
+              error: (e as Error).message,
+            });
+          }
+        }
       });
     }
   }
diff --git a/packages/runtime/src/app-plugin.ts b/packages/runtime/src/app-plugin.ts
@@ -276,6 +276,80 @@ export class AppPlugin implements Plugin {
                      object: d.object,
                  }));
 
+             // Stash datasets on a kernel service so SecurityPlugin's
+             // sys_organization insert hook can replay them per-tenant
+             // (Salesforce-sandbox style: every new org gets its own
+             // private copy of the artifact's demo data).
+             //
+             // We also register a `seed-replayer` callable so the
+             // SecurityPlugin doesn't need to import @objectstack/runtime
+             // (would create a circular workspace dep). The replayer
+             // captures the SeedLoaderService closure and exposes a
+             // narrow `(orgId) => Promise<summary>` surface.
+             try {
+                 const kernel: any = (ctx as any).kernel;
+                 const existing = (() => {
+                     try { return kernel?.getService?.('seed-datasets'); } catch { return undefined; }
+                 })();
+                 const merged = Array.isArray(existing)
+                     ? [...existing, ...normalizedDatasets]
+                     : normalizedDatasets;
+                 const registerSvc = (name: string, value: any) => {
+                     if (kernel?.registerService) kernel.registerService(name, value);
+                     else if (typeof (ctx as any).registerService === 'function') (ctx as any).registerService(name, value);
+                 };
+                 registerSvc('seed-datasets', merged);
+
+                 const metadataNow = ctx.getService('metadata') as IMetadataService | undefined;
+                 const loggerRef = ctx.logger;
+                 const replayer = async (organizationId: string) => {
+                     if (!organizationId) return { inserted: 0, updated: 0, errors: [] as any[] };
+                     const md = metadataNow ?? (ctx.getService('metadata') as IMetadataService | undefined);
+                     if (!md) {
+                         loggerRef.warn('[seed-replayer] metadata service unavailable');
+                         return { inserted: 0, updated: 0, errors: [] as any[] };
+                     }
+                     const datasetsNow = (() => {
+                         try { return kernel?.getService?.('seed-datasets'); } catch { return merged; }
+                     })() ?? merged;
+                     if (!Array.isArray(datasetsNow) || datasetsNow.length === 0) {
+                         return { inserted: 0, updated: 0, errors: [] as any[] };
+                     }
+                     const seedLoader = new SeedLoaderService(ql, md, loggerRef);
+                     const { SeedLoaderRequestSchema } = await import('@objectstack/spec/data');
+                     const request = SeedLoaderRequestSchema.parse({
+                         datasets: datasetsNow,
+                         config: {
+                             defaultMode: 'upsert',
+                             multiPass: true,
+                             organizationId,
+                         },
+                     });
+                     const result = await seedLoader.load(request);
+                     return {
+                         inserted: result.summary.totalInserted,
+                         updated: result.summary.totalUpdated,
+                         errors: result.errors,
+                     };
+                 };
+                 registerSvc('seed-replayer', replayer);
+                 ctx.logger.info(`[Seeder] Registered ${normalizedDatasets.length} datasets + replayer on kernel (total datasets: ${merged.length})`);
+             } catch (e: any) {
+                 ctx.logger.warn('[Seeder] Failed to register seed-datasets/seed-replayer service', { error: e?.message });
+             }
+
+             // Decide whether to also run the seed inline at AppPlugin
+             // start. In multi-tenant mode, the per-org replay (driven
+             // by SecurityPlugin's sys_organization middleware) is the
+             // source of truth — running it here too would create NULL-
+             // org rows that pollute reads and need a separate claim
+             // step. So we skip it. Single-tenant deployments keep the
+             // legacy behaviour: seed immediately at boot so there's
+             // always demo data without needing an org insert.
+             const multiTenant = String(process.env.OS_MULTI_TENANT ?? 'true').toLowerCase() !== 'false';
+             if (multiTenant) {
+                 ctx.logger.info('[Seeder] multi-tenant mode — skipping inline seed; per-org replay will run on sys_organization insert');
+             } else {
              // Use SeedLoaderService for metadata-driven loading with reference resolution
              try {
                  const metadata = ctx.getService('metadata') as IMetadataService | undefined;
@@ -321,6 +395,7 @@ export class AppPlugin implements Plugin {
                  }
                  ctx.logger.info('[Seeder] Data seeding complete (fallback).');
              }
+             }
         }
     }
 
diff --git a/packages/runtime/src/seed-loader.ts b/packages/runtime/src/seed-loader.ts
@@ -102,7 +102,7 @@ export class SeedLoaderService implements ISeedLoaderService {
       this.logger.info('[SeedLoader] Pass 2: resolving deferred references', {
         count: deferredUpdates.length,
       });
-      await this.resolveDeferredUpdates(deferredUpdates, insertedRecords, allResults, allErrors);
+      await this.resolveDeferredUpdates(deferredUpdates, insertedRecords, allResults, allErrors, config.organizationId);
     }
 
     // 7. Build final result
@@ -187,10 +187,17 @@ export class SeedLoaderService implements ISeedLoaderService {
       insertedRecords.set(objectName, new Map());
     }
 
-    // Pre-load existing records for upsert matching
+    // Pre-load existing records for upsert matching. When a target
+    // organization is set, scope the lookup so each tenant gets its
+    // own copy (otherwise upsert would clobber other tenants' rows
+    // that share the same natural key — e.g. `name: 'Acme Corp'`).
     let existingRecords: Map<string, any> | undefined;
     if ((mode === 'upsert' || mode === 'update' || mode === 'ignore') && !config.dryRun) {
-      existingRecords = await this.loadExistingRecords(objectName, externalId);
+      existingRecords = await this.loadExistingRecords(
+        objectName,
+        externalId,
+        config.organizationId,
+      );
     }
 
     // Get reference resolutions for this object
@@ -216,6 +223,15 @@ export class SeedLoaderService implements ISeedLoaderService {
         );
       }
 
+      // Per-tenant tagging: when a target org is set, stamp every
+      // seeded row with it (unless the record itself already supplies
+      // an explicit organization_id — respect dataset author overrides).
+      // Skipped objects that don't declare `organization_id` will have
+      // the extra key silently ignored by the engine.
+      if (config.organizationId && record['organization_id'] == null) {
+        record['organization_id'] = config.organizationId;
+      }
+
       // Resolve references
       for (const ref of objectRefs) {
         const fieldValue = record[ref.field];
@@ -233,7 +249,7 @@ export class SeedLoaderService implements ISeedLoaderService {
           referencesResolved++;
         } else if (!config.dryRun) {
           // Try to resolve from existing data in the database
-          const dbId = await this.resolveFromDatabase(ref.targetObject, ref.targetField, fieldValue);
+          const dbId = await this.resolveFromDatabase(ref.targetObject, ref.targetField, fieldValue, config.organizationId);
           if (dbId) {
             record[ref.field] = dbId;
             referencesResolved++;
@@ -339,10 +355,17 @@ export class SeedLoaderService implements ISeedLoaderService {
     targetObject: string,
     targetField: string,
     value: unknown,
+    organizationId?: string,
   ): Promise<string | null> {
     try {
+      const where: Record<string, unknown> = { [targetField]: value };
+      // Per-tenant replay: when scoping is requested, only consider
+      // rows that belong to the target tenant so cross-tenant rows
+      // never get borrowed as a "resolved" reference (would silently
+      // create a cross-org FK).
+      if (organizationId) where.organization_id = organizationId;
       const records = await this.engine.find(targetObject, {
-        where: { [targetField]: value },
+        where,
         fields: ['id'],
         limit: 1,
         context: { isSystem: true },
@@ -361,6 +384,7 @@ export class SeedLoaderService implements ISeedLoaderService {
     insertedRecords: Map<string, Map<string, string>>,
     allResults: DatasetLoadResult[],
     allErrors: ReferenceResolutionError[],
+    organizationId?: string,
   ): Promise<void> {
     for (const deferred of deferredUpdates) {
       // Try to resolve from inserted records
@@ -370,7 +394,7 @@ export class SeedLoaderService implements ISeedLoaderService {
       // Try database fallback
       if (!resolvedId) {
         resolvedId = (await this.resolveFromDatabase(
-          deferred.targetObject, deferred.targetField, deferred.attemptedValue
+          deferred.targetObject, deferred.targetField, deferred.attemptedValue, organizationId
         )) ?? undefined;
       }
 
@@ -637,13 +661,19 @@ export class SeedLoaderService implements ISeedLoaderService {
   private async loadExistingRecords(
     objectName: string,
     externalId: string,
+    organizationId?: string,
   ): Promise<Map<string, any>> {
     const map = new Map<string, any>();
     try {
-      const records = await this.engine.find(objectName, {
+      const findArgs: Record<string, unknown> = {
         fields: ['id', externalId],
         context: { isSystem: true },
-      } as any);
+      };
+      // Per-tenant replay: restrict to the target tenant's own rows
+      // so upsert key matching never returns another tenant's record
+      // (would silently steal/overwrite rows across orgs).
+      if (organizationId) findArgs.where = { organization_id: organizationId };
+      const records = await this.engine.find(objectName, findArgs as any);
       for (const record of records || []) {
         const key = String(record[externalId] ?? '');
         if (key) {
diff --git a/packages/spec/src/data/seed-loader.zod.ts b/packages/spec/src/data/seed-loader.zod.ts
@@ -212,6 +212,25 @@ export const SeedLoaderConfigSchema = lazySchema(() => z.object({
    */
   env: z.enum(['prod', 'dev', 'test']).optional()
     .describe('Only load datasets matching this environment'),
+
+  /**
+   * Target organization for per-tenant seed loading.
+   *
+   * When set, the loader:
+   *   - Injects `organization_id: <id>` into every record before write
+   *     (unless the record already supplies one).
+   *   - Scopes existing-record lookups (`loadExistingRecords`,
+   *     `resolveFromDatabase`) to `organization_id = <id>`, so `upsert`
+   *     mode finds the per-org copy rather than another tenant's row.
+   *
+   * Use this from a `sys_organization` insert hook to give every new
+   * tenant a private copy of the artifact-shipped demo data (Salesforce
+   * sandbox style). Omit for cross-tenant / platform-wide seeds (e.g.
+   * `sys_permission_set`) — those rows should have `organization_id`
+   * NULL and are not filtered by the default tenant RLS.
+   */
+  organizationId: z.string().min(1).optional()
+    .describe('Target organization id for per-tenant seed replay'),
 }).describe('Seed data loader configuration'));
 
 export type SeedLoaderConfig = z.infer<typeof SeedLoaderConfigSchema>;
