fix(cloud-connection): install-local purge deletes seed rows through the engine by their seed key

[objectstack-fleet]

Fixes #21728
Clause-②: no

POST /api/v1/marketplace/install-local/:manifestId/purge-sample-data answered 500 DRIVER_UNAVAILABLE on every runtime. It now deletes an installed package's seed rows through the ObjectQL engine, matched by the seed's own key, in the install's own scope.

What was wrong (three defects, stacked)

1. The handler looked up a bare driver service. No kernel registers that name; drivers register as driver.NAME. So the door always refused.
2. Behind the lookup, it matched seed records by rec.id. The CRM example's 28 records carry no id (they key by name / email / subject), so fixing the lookup alone answers deleted: 0, skipped: 28. Ablation leg 2 below measures exactly that.
3. It called the driver's delete directly, past every engine hook and the audit trail.

The unit suites stayed green because four of them mocked a bare driver service.

What changes

• New packages/cloud-connection/src/marketplace-install-local-purge.ts (purgeSeedRows).
  • Key. Each dataset's externalId is read through the spec's own declaration (SeedSchema.shape.externalId, default name). Rows are keyed the way SeedLoaderService keys them for an upsert. A row whose key no seed record declares is never touched.
  • Composite keys. Reference parts (the showcase's ['team', 'project'] junction) are translated through the parent rows this purge matched, as the loader does for same-load targets.
  • No guessing. A key carried by more than one row in scope, a seed record with no key value, a key part pointing at an object this package does not seed, and an engine refusal each count in errors, with the reason logged. None of them counts as skipped, and none deletes anything.
  • Order. The reverse of the loader's own topological insert order (SeedLoaderService.buildDependencyGraph), so children go before parents. No order is written by hand.
  • Context. engine.delete(object, { where: { id } }) under SEED_WRITE_EXECUTION_CONTEXT, the posture the seed was written with. Record-change automation is suppressed; lifecycle hooks and audit run.
• handlePurge resolves objectql and metadata (500 DRIVER_UNAVAILABLE if either is missing, now naming which). It picks the scope with the install's own two primitives, organizationWallActive and resolveActiveOrgId, and hands both to purgeSeedRows. The docblock's "bypass ACL / lifecycle hooks (same pattern as cloud purge)" sentence is gone. The response shape is unchanged.
• Bare-driver mocks.
  • Rewritten against the engine, with a pinned delete that opens with assertEngineDeleteDispatch: heal and capability-enumeration, the two suites that drive the purge.
  • Removed, with the reason left in place: seed-replayer and tenancy-posture, where the mock was dead fixture.
• Changeset: patch on @objectstack/cloud-connection. This is a bug fix in a released package. It adds no export and changes no schema; the door now does what its documented response says.

Zone 2 measurements

• A1, reach (origin/main 025008a, unchanged code).

  • Setup: a scratch copy of the showcase on os dev --fresh with OS_CLOUD_URL=off, then os package install examples/app-crm/dist/objectstack.json as the admin. Result: 3/3/12/5/5 rows, all carrying the default organization.
  • POST …/purge-sample-data {} answered 500 {"code":"DRIVER_UNAVAILABLE",…}. Afterwards crm_account still held 3 rows and crm_opportunity 12.
  • The reseed answered 422 RESEED_NO_ROWS.
  • The same sequence on the fixed build:
    • The purge answered 200 {"deleted":28,"skipped":0,"errors":0} and the user row User Authored Co survived.
    • sys_audit_log gained 28 delete rows.
    • The reseed answered 200 inserted: 28. A second purge deleted 28, and a third answered skipped: 28.

• A2, scope. The install and the reseed seed under organizationWallActive(ctx).

  • Under a wall: they seed into resolveActiveOrgId's organization, and the loader pins organization_id on both its upsert match and its writes.
  • Without a wall (single, the card's boot): no organization is pinned, and the loader's upsert match is table-wide. Measured at the door: POST /auth/organization/create on that boot answers 403 "Creating additional organizations is disabled on this deployment.", so the table is one tenant.
  • The purge reuses those two primitives exactly. Under a wall, every read is filtered to the active organization and the delete is by primary key. A walled session with no active organization gets the reseed's skip shape: 400 RESEED_SKIPPED, Purge did not run: multi-tenant-no-active-org….
  • Pinned on a real walled boot: a purge in organization A leaves organization B's 28 seed rows untouched, and no delete hook ever saw one of them.

• A3, key. The CRM's five datasets declare externalId name / email / name / email / subject (3+3+12+5+5 = 28), with 0 authored ids. The loader writes the key to that same field (loadDataset: dataset.externalId || 'name'; externalIdKey). The purge matches on exactly that field, in scope.

• A4, through the engine.

  • Context: SEED_WRITE_EXECUTION_CONTEXT (isSystem, skipTriggers, seedReplay). triggerHooks runs every lifecycle hook unless skipAutomations is set.
  • Real boot: beforeDelete and afterDelete each fired once per seed row (28), and the audit plugin wrote 28 delete rows.
  • Order: the loader's graph reversed; the route test proves it against the real SeedLoaderService with a manifest listing the child first.
  • Constraint, measured: with a user opportunity still requiring seed account Acme Corp (crm_opportunity.account is required + set_null), the engine refused that account's delete ("still referenced by 1 Opportunity record(s)… required and cannot be cleared"). The purge answered deleted: 27, errors: 1 with the reason logged, and the user's row was untouched.
  • No CRM hook refuses a delete; its only hook is beforeInsert/beforeUpdate.

• A5, ledger flag. sampleDataPurged / withSampleData stay install-wide; the ledger shape is unchanged here.

  • Measured on a walled boot with a real restart: after a purge in A, GET /install-local read as B answers withSampleData: false while B still holds its 28 rows.
  • After the restart, A has 0 rows and B has 28. The healer returns at its wall check before reading anything, so it neither resurrects A nor touches B.
  • No data harm to B. The listing flag is wrong for B, and that is reported to the seat as an out-of-scope finding.

• A6, reverse verification. Both legs ran through scripts/ablation-replace.mjs on marketplace-install-local-purge.ts, which the dogfood resolves through its source alias, so no build leg was needed.

  leg	anchor → replacement	blob	dogfood pin
  delete no-op	const result = await engine.delete(…SEED_WRITE_EXECUTION_CONTEXT }); → const result = true as boolean | number;	a6856b93 → 2d004c57	5 red / 3 green
  match by rec.id	const ids = rowsByKey.get(keyOf(parts)) ?? []; → const ids: string[] = rec?.id ? [String(rec.id)] : [];	a6856b93 → 7e1e9c83	5 red / 3 green; purge answered deleted: 0, skipped: 28

  • The 3 that stayed green both times are the two preconditions and "organization B's seed rows are untouched".
  • Restore, both legs: blob after restore == HEAD (a6856b93) and git diff HEAD is empty.

Tests (at 2b140e9)

• pnpm --filter @objectstack/cloud-connection exec vitest run: 37 files, 459 tests pass. The new marketplace-install-local-purge.test.ts has 16 cases (match, no-guessing, order/context/scope, reference parts, and the route under the real loader).
• pnpm --filter @objectstack/cloud-connection typecheck: clean (both programs).
• New dogfood install-local-purge-sample-data.dogfood.test.ts on a real boot: 8/8 pass. pnpm --filter @objectstack/dogfood typecheck is clean.
• pnpm lint (full, eslint . --no-inline-config): exit 0.

Gates (at 2b140e9)

• node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 86 families (the claim's 46 grew with the dogfood wiring, the lockfile and the ratchet baseline).
• All 86 ran with exit 0. --ran reconciles 86 derived / 86 run / 0 NOT-MEASURED, every line carrying its exit code.
• check:dual-build-cjs-loads first answered PREREQUISITE NOT MET (eight unrelated packages unbuilt). After building them it read 106 entry points across 66 packages, green.
• check:slot-lookup ratcheted down 16 → 15 for the plugin file (the untyped driver lookup is gone). The baseline is committed.

Deviations

• Two stay-out dogfood files edited: packages/qa/dogfood/package.json (devDependency @objectstack/cloud-connection) and packages/qa/dogfood/vitest.config.ts (one anchored source alias), plus their lockfile importer lines.
  • Measured reason: a relative import of the plugin from the new dogfood file puts the plugin's dynamic @objectstack/runtime import into dogfood's shrink-only check:test-source-alias set (NEW unaliased artifact import(s): @objectstack/runtime).
  • The alias is the route the config already takes for its other subjects. No test file another lane holds was touched.
• The purge door gains a refusal it did not have: 400 RESEED_SKIPPED when a wall is up and the session has no active organization. This was dispatched as "reseed's existing skip shape and code". A dedicated code would need a spec ledger row (domain:spec).
• @objectstack/cloud-connection gains a devDependency on @objectstack/metadata-core, for assertEngineDeleteDispatch in its fake engines, as check:engine-double-contract prescribes. It is aliased to source in its vitest config.
• No merge commit. origin/main stayed at 025008a from dispatch to this PR, so git merge origin/main is a no-op.

Acceptance notes

• Boundaries of the new purge (reported, not filed):
  • A seed dataset keyed by id and replayed into a second organization gets derived ids (perOrganizationSeedRowId, private to the loader), so the purge answers skipped for those rows. No install-local package measured has one.
  • Master-detail children of seed rows go with them by their declared cascade.
  • withSampleData: false is written even when errors is non-zero, which is the pre-existing flip.
• Comment drift for the spec seat: in error-code-ledger.zod.ts, DRIVER_UNAVAILABLE's note says "no driver service", and RESEED_SKIPPED's says "reseed declined", but the purge now emits both.
• Checklist drift: docs/qa/platform-checklist/areas/platform-core.json still describes the purge as id-based.
• [finding] marketplace install-local installs a manifest whose engines.protocol this runtime cannot satisfy (^16 on 17): 200 success, while POST /api/v1/packages refuses it 422 OS_PROTOCOL_INCOMPATIBLE #21762 edits this file's install route. Install and reseed behaviour are untouched here.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/cloud-connection, @objectstack/dogfood, touching 15 documentable anchor(s). ⚠️ 2 changed file(s) yielded no anchor (packages/cloud-connection/vitest.config.ts, packages/qa/dogfood/vitest.config.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

15 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/flows.mdx (via organizationId (symbol, a field of interface SamplePurgeInput))
• content/docs/automation/hooks.mdx (via organizationId (symbol, a field of interface SamplePurgeInput))
• content/docs/data-modeling/field-types.mdx (via externalId (symbol, a field of interface PurgeSeedDataset))
• content/docs/data-modeling/fields.mdx (via externalId (symbol, a field of interface PurgeSeedDataset))
• content/docs/data-modeling/seed-data.mdx (via externalId (symbol, a field of interface PurgeSeedDataset), organizationId (symbol, a field of interface SamplePurgeInput))
• content/docs/data-modeling/validation-rules.mdx (via externalId (symbol, a field of interface PurgeSeedDataset))
• content/docs/deployment/cli.mdx (via MarketplaceInstallLocalPlugin (symbol, a top-level class))
• content/docs/deployment/seed-tenancy-repair.mdx (via organizationId (symbol, a field of interface SamplePurgeInput))
• content/docs/getting-started/examples.mdx (via externalId (symbol, a field of interface PurgeSeedDataset))
• content/docs/kernel/events.mdx (via organizationId (symbol, a field of interface SamplePurgeInput))
• content/docs/kernel/runtime-services/audit-service.mdx (via organizationId (symbol, a field of interface SamplePurgeInput))
• content/docs/kernel/runtime-services/sharing-service.mdx (via organizationId (symbol, a field of interface SamplePurgeInput))
• content/docs/permissions/authentication.mdx (via organizationId (symbol, a field of interface SamplePurgeInput))
• content/docs/permissions/system-context.mdx (via organizationId (symbol, a field of interface SamplePurgeInput))
• content/docs/protocol/kernel/config-resolution.mdx (via organizationId (symbol, a field of interface SamplePurgeInput))

⛔ 3 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/index.mdx (via organizationId (symbol, a field of interface SamplePurgeInput))
• content/docs/releases/v16.mdx (via organizationId (symbol, a field of interface SamplePurgeInput))
• content/docs/releases/v17/17-5.mdx (via organizationId (symbol, a field of interface SamplePurgeInput))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 2 changed file(s) yielded no anchor (packages/cloud-connection/vitest.config.ts, packages/qa/dogfood/vitest.config.ts) — pages documenting those are invisible to this run
• 1 cross-cutting symbol(s) contributed no route anchor: organizationId (5 routes)
• 7 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 5 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 025008ae954311ab91ef264d1b750a00ed193b32 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 1f251d7607ecf42d5844d1f44c9ac6cd598ec50f — the merge of head 2b140e985e2d428adf89db3b464eeb652f08af01 into base 025008ae954311ab91ef264d1b750a00ed193b32, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 1f251d7607ecf42d5844d1f44c9ac6cd598ec50f && git checkout 1f251d7607ecf42d5844d1f44c9ac6cd598ec50f
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 025008ae954311ab91ef264d1b750a00ed193b32 2b140e985e2d428adf89db3b464eeb652f08af01 && git checkout -B drift-repro 025008ae954311ab91ef264d1b750a00ed193b32 && git merge --no-ff 2b140e985e2d428adf89db3b464eeb652f08af01

node scripts/docs-audit/affected-docs.mjs --json 025008ae954311ab91ef264d1b750a00ed193b32

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 025008ae954311ab91ef264d1b750a00ed193b32 → pass the list as
args.docs, on the commit named under Which tree this was computed on.