diff --git a/‎.changeset/21728-install-local-purge.md‎
Lines changed: 13 additions & 0 deletions b/‎.changeset/21728-install-local-purge.md‎
Lines changed: 13 additions & 0 deletions
diff --git a/‎packages/cloud-connection/package.json‎
Lines changed: 1 addition & 0 deletions b/‎packages/cloud-connection/package.json‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎packages/cloud-connection/src/marketplace-install-local-capability-enumeration.test.ts‎
Lines changed: 31 additions & 7 deletions b/‎packages/cloud-connection/src/marketplace-install-local-capability-enumeration.test.ts‎
Lines changed: 31 additions & 7 deletions
diff --git a/‎packages/cloud-connection/src/marketplace-install-local-heal.test.ts‎
Lines changed: 34 additions & 3 deletions b/‎packages/cloud-connection/src/marketplace-install-local-heal.test.ts‎
Lines changed: 34 additions & 3 deletions
diff --git a/‎packages/cloud-connection/src/marketplace-install-local-plugin.ts‎
Lines changed: 60 additions & 28 deletions b/‎packages/cloud-connection/src/marketplace-install-local-plugin.ts‎
Lines changed: 60 additions & 28 deletions
@@ -0,0 +1,13 @@
+---
+"@objectstack/cloud-connection": patch
+---
+
+`POST /api/v1/marketplace/install-local/:manifestId/purge-sample-data` now deletes an installed package's sample rows. Before, it answered `500 DRIVER_UNAVAILABLE` on every runtime.
+
+Clause-②: no
+
+- **What was wrong.** The purge looked up a bare `driver` service, a name no kernel registers (drivers register as `driver.<name>`), so it refused everywhere. Behind that it matched seed records by `id`, which seed records rarely carry: the CRM example's 28 records key by `name`, `email` and `subject`. It also deleted through the driver, past every engine hook.
+- **What it does now.** It deletes through the ObjectQL engine, so lifecycle hooks and the audit trail run, under the posture the seed was written with (record-change automation suppressed). Rows are matched by each dataset's `externalId`, the key the install and the reseed upsert by. A row whose key no seed record declares is never touched. Children are deleted before parents, in the reverse of the seed loader's own dependency order.
+- **Scope.** Under an organization wall the purge removes only the seed rows of the caller's active organization, the scope the install and the reseed seed into. A session with no active organization is answered `400 RESEED_SKIPPED` (`multi-tenant-no-active-org`), the way reseed answers it. Without a wall the deployment is one tenant, and the match is table-wide, as the install's own match is.
+- **The response keeps its shape**, `{ manifestId, deleted, skipped, errors, withSampleData }`. `skipped` counts seed records no row carries (already deleted). `errors` counts records that could not be purged, each with its reason in the server log: a delete the engine refused (for example, a user's row still requires the seed row as its parent), a key that more than one row carries, or a seed record with no key value.
+- A runtime with no data engine or no metadata service still answers `500 DRIVER_UNAVAILABLE`, now naming what is missing.
@@ -32,6 +32,7 @@
   },
   "devDependencies": {
     "@objectstack/lint": "workspace:*",
+    "@objectstack/metadata-core": "workspace:*",
     "@types/node": "^26.6.3",
     "typescript": "^6.0.3",
     "vitest": "^4.1.11"
 
@@ -21,7 +21,7 @@
  * Three principal shapes driven through the composed plugin to the point the
  * state actually changes — `manifest.register()` (shared registry),
  * `objectql.syncSchemas()` (DDL against the shared database), the ledger file on
- * disk, `SeedLoaderService.load()` (rows written), `driver.delete()` (rows
+ * disk, `SeedLoaderService.load()` (rows written), the row delete (rows
  * removed). All three were INDISTINGUISHABLE:
  *
  *   principal                              install  reseed  purge  uninstall
@@ -73,10 +73,19 @@ vi.mock('@objectstack/runtime', () => ({
             seedCalls.push(request);
             return { summary: { totalInserted: 2, totalUpdated: 0, totalSkipped: 0 }, errors: [] };
         }
+        // The purge's dependency order — one object, nothing referenced.
+        async buildDependencyGraph(objectNames: string[]) {
+            return {
+                nodes: objectNames.map((object) => ({ object, dependsOn: [], references: [] })),
+                insertOrder: objectNames,
+                circularDependencies: [],
+            };
+        }
     },
     recordSeedOutcome: vi.fn(),
 }));
 
+import { assertEngineDeleteDispatch } from '@objectstack/metadata-core';
 import { MarketplaceInstallLocalPlugin } from './marketplace-install-local-plugin.js';
 
 const ROUTE_BASE = '/api/v1/marketplace/install-local';
@@ -138,7 +147,7 @@ const APP = {
     namespace: 'gated',
     version: '1.0.0',
     objects: [{ name: 'widget', fields: { code: { type: 'text' } } }],
-    data: [{ object: 'widget', records: [{ id: 'w1', code: 'a' }, { id: 'w2', code: 'b' }] }],
+    data: [{ object: 'widget', externalId: 'code', records: [{ code: 'a' }, { code: 'b' }] }],
 };
 
 const LEDGER_FILE = 'com.acme.gated.json';
@@ -155,7 +164,19 @@ afterEach(() => { rmSync(dir, { recursive: true, force: true }); vi.restoreAllMo
 async function mount(shape: Shape, storageDir: string) {
     const register = vi.fn(async () => undefined);
     const syncSchemas = vi.fn(async () => undefined);
-    const driverDelete = vi.fn(async () => true);
+    // The rows the install seeded. The purge deletes them through the ENGINE
+    // (a bare `driver` service stood here once — no kernel registers one, and
+    // mocking it is how a purge that always answered 500 stayed green), so the
+    // engine's `delete` is the observer, opened with the real dispatch contract.
+    const widgets = [{ id: 'w1', code: 'a' }, { id: 'w2', code: 'b' }];
+    const engineDelete = vi.fn(async (object: string, options?: any) => {
+        const dispatch = assertEngineDeleteDispatch(options);
+        if (object !== 'widget' || dispatch.kind !== 'by-id') return false;
+        const at = widgets.findIndex((w) => w.id === dispatch.id);
+        if (at < 0) return false;
+        widgets.splice(at, 1);
+        return true;
+    });
     const rawApp = makeRawApp();
     const hooks = new Map<string, any>();
 
@@ -167,9 +188,12 @@ async function mount(shape: Shape, storageDir: string) {
     const services: Record<string, any> = {
         manifest: { register },
         auth: { api: { getSession: async () => (sessionUser ? { user: sessionUser, session: {} } : null) } },
-        objectql: { syncSchemas, find: async (object: string) => rows[object] ?? [] },
+        objectql: {
+            syncSchemas,
+            find: async (object: string) => (object === 'widget' ? widgets.map((w) => ({ ...w })) : rows[object] ?? []),
+            delete: engineDelete,
+        },
         metadata: { getObject: async () => ({ name: 'widget', fields: {} }) },
-        driver: { delete: driverDelete },
     };
     const ctx: any = {
         hook: (e: string, h: any) => hooks.set(e, h),
@@ -189,7 +213,7 @@ async function mount(shape: Shape, storageDir: string) {
     // counters must start from AFTER that so a refusal case cannot be fooled by
     // boot-time activity it never caused.
     register.mockClear();
-    return { rawApp, register, syncSchemas, driverDelete };
+    return { rawApp, register, syncSchemas, engineDelete };
 }
 
 function makeC(body: unknown, headers: Record<string, string>, manifestId?: string) {
@@ -254,7 +278,7 @@ const DOORS: readonly Door[] = [
         route: `POST ${ROUTE_BASE}/:manifestId/purge-sample-data`,
         body: {},
         needsInstalled: true,
-        effectsFired: (o) => o.driverDelete.mock.calls.length,
+        effectsFired: (o) => o.engineDelete.mock.calls.length,
     },
 ];
 
 
@@ -30,6 +30,15 @@ let loadCalls: any[] = [];
 vi.mock('@objectstack/runtime', () => ({
     SeedLoaderService: class {
         async load(request: any) { loadCalls.push(request); return seedResult; }
+        // The purge reads the loader's dependency order; these objects
+        // reference nothing, so the order is the order asked.
+        async buildDependencyGraph(objectNames: string[]) {
+            return {
+                nodes: objectNames.map((object) => ({ object, dependsOn: [], references: [] })),
+                insertOrder: objectNames,
+                circularDependencies: [],
+            };
+        }
     },
     // #3430 — the heal path records a per-source outcome for the boot banner.
     recordSeedOutcome: vi.fn(),
@@ -46,6 +55,7 @@ import { MarketplaceInstallLocalPlugin } from './marketplace-install-local-plugi
 import { installerAuthService, withInstallerGrants } from './install-local-principal.fixtures.js';
 import { LocalManifestSource } from './local-manifest-source.js';
 import { recordSeedOutcome } from '@objectstack/runtime';
+import { assertEngineDeleteDispatch } from '@objectstack/metadata-core';
 
 type Handler = (c: any) => Promise<any>;
 
@@ -101,17 +111,31 @@ const MANIFEST = {
     ],
 };
 
-/** Services with a controllable emptiness probe. */
+/**
+ * Services with a controllable emptiness probe. The purge deletes through the
+ * `objectql` ENGINE, so that is where `delete` lives — opened with the real
+ * dispatch contract. A bare `driver` service used to stand here: no kernel
+ * registers one (drivers register as `driver.<name>`), and mocking it is how a
+ * purge that always answered 500 stayed green.
+ */
 function makeServices(findRows: Record<string, any[]>) {
     return {
         manifest: { register: vi.fn() },
         auth: installerAuthService(),
         objectql: withInstallerGrants({
             syncSchemas: async () => undefined,
             find: vi.fn(async (object: string) => findRows[object] ?? []),
+            delete: vi.fn(async (object: string, options?: any) => {
+                const dispatch = assertEngineDeleteDispatch(options);
+                if (dispatch.kind !== 'by-id') throw new Error('fake engine: the purge deletes by primary key only');
+                const rows = findRows[object] ?? [];
+                const at = rows.findIndex((r) => r.id === dispatch.id);
+                if (at < 0) return false;
+                rows.splice(at, 1);
+                return true;
+            }),
         }),
         metadata: {},
-        driver: { delete: vi.fn(async () => true) },
     };
 }
 
@@ -211,7 +235,8 @@ describe('rehydrate sample-data healing', () => {
         // Install over an empty DB, with rows landing.
         seedResult = { summary: { totalInserted: 3, totalUpdated: 0, totalSkipped: 0 }, errors: [] };
         const rawApp = makeRawApp();
-        const services = makeServices({ crm_x: [], crm_y: [] });
+        const db: Record<string, any[]> = { crm_x: [], crm_y: [] };
+        const services = makeServices(db);
         const { ctx, fire } = makeCtx(rawApp, services);
         const plugin = new MarketplaceInstallLocalPlugin({ controlPlaneUrl: 'off', storageDir: dir });
         await plugin.start(ctx as any);
@@ -220,12 +245,18 @@ describe('rehydrate sample-data healing', () => {
             makeC({ manifest: MANIFEST }),
         );
         expect(installRes.payload?.success).toBe(true);
+        // What the (mocked) loader reported, as rows: keyed by `name`, the
+        // spec's default `externalId` — these datasets declare none.
+        db.crm_x.push({ id: 'row-1', name: 'a' }, { id: 'row-2', name: 'b' });
+        db.crm_y.push({ id: 'row-3', name: 'c' });
 
         // Purge the sample data.
         const purgeRes = await rawApp.routes.get('POST /api/v1/marketplace/install-local/:manifestId/purge-sample-data')!(
             makeC({}, MANIFEST.id),
         );
         expect(purgeRes.payload?.success).toBe(true);
+        expect(purgeRes.payload?.data).toMatchObject({ deleted: 3, skipped: 0, errors: 0 });
+        expect(db).toEqual({ crm_x: [], crm_y: [] });
         expect(new LocalManifestSource(dir).read(MANIFEST.id).entry?.sampleDataPurged).toBe(true);
 
         // Restart (fresh plugin over the same ledger, DB now empty): no reseed.
 
@@ -97,6 +97,7 @@ import {
 } from './local-manifest-source.js';
 import { ConnectionCredentialStore } from './connection-credential-store.js';
 import { MARKETPLACE_INSTALLED_UI_BUNDLE } from './marketplace-ui.js';
+import { purgeSeedRows } from './marketplace-install-local-purge.js';
 import type { IHttpServer, IMetadataService, IObjectQLEngine } from '@objectstack/spec/contracts';
 import type { DeletePackageRequest, UninstallCleanupOutcome } from '@objectstack/metadata-protocol';
 
@@ -1683,11 +1684,28 @@ export class MarketplaceInstallLocalPlugin implements Plugin {
     /**
      * POST /api/v1/marketplace/install-local/:manifestId/purge-sample-data
      *
-     * Deletes every record whose id is declared in the cached manifest's
-     * seed datasets. Uses the `driver` service directly to bypass ACL /
-     * lifecycle hooks (same pattern as cloud purge). User-created records
-     * are never touched — only ids declared in the package's bundled
-     * datasets are removed. Already-deleted rows count as `skipped`.
+     * Deletes the rows the cached manifest's seed datasets put in the
+     * database, THROUGH THE OBJECTQL ENGINE, so the deletes run every
+     * lifecycle hook (audit, sharing, storage, the package's own) — the same
+     * posture the seed was written with (`SEED_WRITE_EXECUTION_CONTEXT`).
+     * {@link purgeSeedRows} carries the rules; this handler supplies the scope.
+     *
+     *   • A seed row is matched by the seed's own key — each dataset's
+     *     `externalId`, the key the install's upsert and the reseed match on.
+     *     A row whose key no seed record declares (user-authored data) is never
+     *     touched; a key carried by more than one row in scope is not guessed.
+     *   • Scope is the install's: under an organization wall, the caller's
+     *     active organization (the same `organizationWallActive` +
+     *     `resolveActiveOrgId` the install and reseed seed under), and a session
+     *     with none is answered the way reseed answers it. Without a wall the
+     *     deployment is one logical tenant and the match is table-wide, as the
+     *     loader's upsert match is.
+     *   • Children are deleted before parents — the reverse of the loader's own
+     *     dependency order.
+     *
+     * `skipped` counts seed records no row in scope carries (already deleted);
+     * `errors` counts records that could not be purged — refused by the engine,
+     * or not identifiable — each reason logged.
      */
     private handlePurge = async (c: any, ctx: PluginContext): Promise<Response> => {
         const admission = await this.requireInstallCapability(c, ctx, 'Purging sample data');
@@ -1718,36 +1736,50 @@ export class MarketplaceInstallLocalPlugin implements Plugin {
             }, 400);
         }
 
-        let driver: any;
-        try { driver = ctx.getService('driver'); } catch { /* none */ }
-        if (!driver || typeof driver.delete !== 'function') {
+        // The data engine the seed was written through, and the metadata its
+        // dependency order is read from — the pair the seed run itself needs.
+        let ql: IObjectQLEngine | undefined;
+        let metadata: IMetadataService | undefined;
+        try { ql = ctx.getService<IObjectQLEngine>('objectql'); } catch { /* no data engine */ }
+        try { metadata = ctx.getService<IMetadataService>('metadata'); } catch { /* no metadata service */ }
+        if (!ql || !metadata) {
             return c.json({
                 success: false,
-                error: { code: 'DRIVER_UNAVAILABLE', message: 'driver service unavailable — cannot purge.' },
+                error: {
+                    code: 'DRIVER_UNAVAILABLE',
+                    message: 'The data engine (objectql) or the metadata service is not available on this runtime — cannot purge sample data.',
+                },
             }, 500);
         }
 
-        let deleted = 0;
-        let skipped = 0;
-        let errors = 0;
-        for (const ds of datasets) {
-            const object = String(ds.object);
-            for (const rec of ds.records as any[]) {
-                const id = rec?.id;
-                if (id === undefined || id === null || id === '') { skipped++; continue; }
-                try {
-                    const r = await driver.delete(object, id);
-                    if (r === false || r === 0 || r?.deleted === 0) skipped++;
-                    else deleted++;
-                } catch (err: any) {
-                    // Treat "not found" as skipped; anything else as error.
-                    const msg = String(err?.message ?? err);
-                    if (/not.?found|no row/i.test(msg)) skipped++;
-                    else { errors++; ctx.logger?.warn?.(`[MarketplaceInstallLocal] purge ${object}#${id}: ${msg}`); }
-                }
+        // Scope: the one the install and the reseed seed under (applySideEffects).
+        let organizationId: string | undefined;
+        if (organizationWallActive(ctx)) {
+            const resolved = await this.resolveActiveOrgId(c, ctx);
+            if (!resolved) {
+                return c.json({
+                    success: false,
+                    error: {
+                        code: 'RESEED_SKIPPED',
+                        message: 'Purge did not run: multi-tenant-no-active-org. A purge removes the sample rows of the '
+                            + "caller's active organization only, and this session has none — set an active organization and retry.",
+                    },
+                }, 400);
             }
+            organizationId = resolved;
         }
 
+        const { SeedLoaderService } = await import('@objectstack/runtime');
+        const loader = new (SeedLoaderService as any)(ql, metadata, ctx.logger);
+        const graph = await loader.buildDependencyGraph([...new Set(datasets.map((d: any) => String(d.object)))]);
+        const { deleted, skipped, errors } = await purgeSeedRows({
+            engine: ql,
+            datasets,
+            graph,
+            organizationId,
+            warn: (message) => ctx.logger?.warn?.(`[MarketplaceInstallLocal] ${manifestId}: ${message}`),
+        });
+
         // Flip flag so UI reflects the empty baseline. `sampleDataPurged`
         // additionally tells the rehydrate-time healer this emptiness is
         // deliberate — demo rows must not come back on the next restart.
@@ -1757,7 +1789,7 @@ export class MarketplaceInstallLocalPlugin implements Plugin {
             this.ledger.write(entry);
         } catch { /* non-fatal */ }
 
-        ctx.logger?.info?.(`[MarketplaceInstallLocal] purged ${manifestId}: deleted=${deleted} skipped=${skipped} errors=${errors}`);
+        ctx.logger?.info?.(`[MarketplaceInstallLocal] purged ${manifestId}${organizationId ? ` (org=${organizationId})` : ''}: deleted=${deleted} skipped=${skipped} errors=${errors}`);
         return c.json({
             success: true,
             data: { manifestId, deleted, skipped, errors, withSampleData: false },