fix(kernel): address KERN-1..7 entity-lifecycle and creation-API bugs

Implement and test the seven HIGH/MEDIUM Backlog items in §3.1/§3.3:

- KERN-1: thread `autoDestructionOnParentRemoval` through the change trail
  (ICreateEntitiesChange field, ComponentChanges.create 4th param, parse());
  expose as ViewComponent constructor option, persisted via ComponentMemory.
- KERN-2: rebind the auto-destruction subscription on every parent change so
  re-parented children survive the destruction of their original parent and
  follow their current one.
- KERN-3: destroyEntity now snapshots its children — flagged ones cascade,
  unflagged ones are promoted to root entries instead of leaking inside the
  kernel.
- KERN-4: invalidate the BFS traversal cache from destroyEntity so
  programmatic destruction paths (e.g. auto-destroy listeners) no longer
  return stale UUIDs.
- KERN-5: resolve the new parent UUID before detaching the current one so a
  bad uuid throws without orphaning the entity.
- KERN-6: Registry.clear() now also clears prop-based (`@`-prefix) routes.
- KERN-7: useProperty/useContext/useParentContext warn when a subsequent
  call passes a different `{compare}` than the one captured on cache miss.

Coverage:
- New vitest specs in Kernel.spec.ts, Registry.spec.ts, ViewComponent.spec.ts.
- New Playwright E2E `auto-destruct.spec.ts` exercising the real
  RemoteWorkerEnv: a parent SO programmatically creates a flagged + an
  unflagged child via entity.kernel.createEntity; after destroyEntity on
  their shared root, the flagged child cascades and the unflagged one is
  promoted to root. Runs in Chromium and Firefox.

CHANGELOG.md and Backlog.md are updated accordingly.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: spearwolf

Backlog.md

@@ -36,8 +36,8 @@
 
 **Hauptrisiken:**
 1. **Worker-Fehlerpfade unter-implementiert** — keine `error`/`messageerror`-Handler, keine Reconnect-Logik, ausstehende Promises hängen nach Worker-Tod ewig (oder bis 5–60 s Timeout).
-2. **Neues Feature „auto destruction on parent removal" (Commit 89c59c2) ist im Datenpfad nicht erreichbar** und behandelt Re-Parenting nicht.
-3. **`destroyEntity` rekursiert nicht über Kinder** — bei Eltern-Destruktion bleiben Nicht-Auto-Kinder als verwaiste Einträge im Kernel.
+2. ~~**Neues Feature „auto destruction on parent removal" (Commit 89c59c2) ist im Datenpfad nicht erreichbar** und behandelt Re-Parenting nicht.~~ **Behoben (KERN-1, KERN-2)** — Flag fließt jetzt durch `ICreateEntitiesChange` → `ComponentChanges.create()` → `parse()`; Subscription wird bei Re-Parent neu verdrahtet.
+3. ~~**`destroyEntity` rekursiert nicht über Kinder** — bei Eltern-Destruktion bleiben Nicht-Auto-Kinder als verwaiste Einträge im Kernel.~~ **Behoben (KERN-3)** — Variante C: Flagged-Kinder kaskadieren, ungeflaggte werden zu Roots befördert.
 4. **DOM-In-Place-Re-Parenting wird nicht beobachtet** (`<shae-prop>` und `<shae-ent>` resolvieren ihren Eltern-Knoten nur in `connectedCallback`).
 5. **CI lässt das gesamte E2E-Paket aus** — der Worker-Roundtrip wird damit faktisch nicht von CI verifiziert.
 6. **`MessageRouter` schluckt Fehler** durch doppeltes `AppliedChangeTrail` im Catch-Pfad — Konsumenten sehen Erfolg trotz interner Exception.
@@ -112,23 +112,13 @@ ComponentContext│  ─ Destroy
 
 ### 3.1 HIGH — Kern (in-the-dark)
 
-**[KERN-1]** `autoDestructionOnParentRemoval` ist im Change-Trail-Datenpfad nicht erreichbar.
-*Ort:* `Kernel.ts:218–249`, `types.ts:24–30`.
-`createEntity` akzeptiert den 6. Parameter, aber `parse()` (Zeile 185) gibt ihn nie weiter, und `ICreateEntitiesChange` enthält das Feld gar nicht. Nur der Unit-Test erreicht den Pfad — in Produktion ist das Feature ein No-Op.
-*Empfehlung:* Feld zu `ICreateEntitiesChange` ergänzen, in `ComponentChanges.create()` einreihen, `parse()` weiterreichen, E2E-Test mit echtem Worker ergänzen.
+**[KERN-1]** ~~`autoDestructionOnParentRemoval` ist im Change-Trail-Datenpfad nicht erreichbar.~~ **✅ Behoben** — Feld in `ICreateEntitiesChange` ergänzt, durch `ComponentChanges.create()` (4. Parameter) und `Kernel.parse()` an `createEntity()` weitergereicht. `ViewComponent` bekommt eine neue Konstruktoroption `autoDestructionOnParentRemoval`. Abgedeckt von vitest-Specs (Kernel + ViewComponent) sowie Playwright-E2E-Test `auto-destruct.spec.ts` mit echtem `RemoteWorkerEnv` (Chromium + Firefox).
 
-**[KERN-2]** Re-Parenting bricht die Auto-Destruktions-Subscription.
-*Ort:* `Entity.ts:209–227, 235–246`, `Kernel.ts:265–289`.
-`removeFromParent()` löscht `#parent`, lässt aber `#autoDestructionSubscription` auf den alten Eltern-Knoten zeigen. Wird der alte Vater später zerstört, stirbt das längst woanders einsortierte Kind mit. Umgekehrt wird der neue Vater nicht „verheiratet".
+**[KERN-2]** ~~Re-Parenting bricht die Auto-Destruktions-Subscription.~~ **✅ Behoben** — `Entity` trennt jetzt User-Intent (`#autoDestructionEnabled`) von der konkreten Subscription. `set parentUuid` und `removeFromParent()` rufen `#updateAutoDestructionSubscription()`, das die Subscription gegen den jeweils aktuellen Vater neu herstellt.
 
-**[KERN-3]** `destroyEntity` rekursiert nicht über Kinder.
-*Ort:* `Kernel.ts:251–263`, `Entity.ts:142–169, 167–168`.
-Eltern-`destroyEntity` löscht nur die explizite UUID. Kinder ohne `autoDestructionOnParentRemoval` bleiben als verwaiste Einträge in `kernel.#entities`/`#rootEntities` zurück → echter Leak. Die `#children`-Liste des Vaters wird via `length = 0` geleert, aber die Kinder selbst nicht abgeräumt.
-*Empfehlung:* `destroyEntity` muss Kinder rekursiv abräumen (oder `removeFromParent` sie zu Root befördern), ggf. Policy einbauen.
+**[KERN-3]** ~~`destroyEntity` rekursiert nicht über Kinder.~~ **✅ Behoben (Variante C)** — `Kernel.destroyEntity()` snapshottet die Kinderliste; flagged Kinder werden rekursiv abgeräumt, ungeflaggte via `removeFromParent()` zu Root befördert (und in `#rootEntities` aufgenommen). Damit ist der Leak in `kernel.#entities` geschlossen.
 
-**[KERN-4]** Cache-Invalidierung in `traverseLevelOrderBFS` greift bei programmatischer Destruktion nicht.
-*Ort:* `Kernel.ts:84, 191/197/202`, sowie der Auto-Destroy-Pfad `Entity.ts:239`.
-`#allEntitiesNeedUpdate` wird nur in `parse()` gesetzt, nicht wenn Kinder direkt via Auto-Destroy-Listener `kernel.destroyEntity` aufrufen. Folge: nachfolgende Traversal-Aufrufe können stale UUIDs zurückgeben.
+**[KERN-4]** ~~Cache-Invalidierung in `traverseLevelOrderBFS` greift bei programmatischer Destruktion nicht.~~ **✅ Behoben** — `#allEntitiesNeedUpdate` wird jetzt direkt in `destroyEntity()` gesetzt, sodass auch Auto-Destroy-Listener-Pfade den BFS-Cache invalidieren.
 
 ### 3.2 HIGH — View / Worker
 
@@ -160,9 +150,9 @@ Wenn ein `<shae-ent>`-Vater aus dem DOM entfernt wird, das Kind aber selbst noch
 | **VIEW-9** | `removeTransferables` mutiert die Caller-Trail-Einträge per `delete`. | `RemoteWorkerEnv.ts:23–40` |
 | **VIEW-10** | `LocalShadowObjectEnv` ignoriert `waitForConfirmation`; `MessageToView` läuft via `queueMicrotask`, sodass der `AfterSync`-Event vor den Worker-Nachrichten feuert. **Verhaltensasymmetrie zu `RemoteWorkerEnv`.** | `LocalShadowObjectEnv.ts:40`, `Kernel.ts:316–319` |
 | **VIEW-11** | `ShaePropElement.isShaeEntElement = true` ist offenbar Copy-Paste — nutzt aber `findEntNode` zur Eltern-Suche, was potenziell falsche Treffer ergibt. | `ShaePropElement.ts:68` |
-| **KERN-5** | `Entity.parentUuid`-Setter ruft `removeFromParent()` *vor* dem Resolven des neuen Vaters; wirft `getEntity` einen Fehler, ist die Entity verwaist. | `Entity.ts:97–108` |
-| **KERN-6** | `Registry.clear()` löscht `#truthyPropRoutes` nicht — Test-Pollution + Akkumulation in langlebigen Registries. | `Registry.ts:139–142` |
-| **KERN-7** | `useContext`/`useParentContext`/`useProperty` ignorieren `options` bei Cache-Hit (z. B. `compare`). Der erste Aufrufer „gewinnt", was leise zu falschen Equality-Vergleichen führen kann. | `Kernel.ts:387–396, 495–504, 517–525` |
+| ~~**KERN-5**~~ | ~~`Entity.parentUuid`-Setter ruft `removeFromParent()` *vor* dem Resolven des neuen Vaters; wirft `getEntity` einen Fehler, ist die Entity verwaist.~~ **✅ Behoben** — `getEntity` wird *vor* dem Detach aufgerufen; `Kernel.setParent` validiert die neue UUID vorab. | `Entity.ts`, `Kernel.ts` |
+| ~~**KERN-6**~~ | ~~`Registry.clear()` löscht `#truthyPropRoutes` nicht — Test-Pollution + Akkumulation in langlebigen Registries.~~ **✅ Behoben** — `clear()` räumt auch die Prop-basierten Routen ab. | `Registry.ts` |
+| ~~**KERN-7**~~ | ~~`useContext`/`useParentContext`/`useProperty` ignorieren `options` bei Cache-Hit (z. B. `compare`). Der erste Aufrufer „gewinnt", was leise zu falschen Equality-Vergleichen führen kann.~~ **✅ Behoben** — bei Cache-Hit mit abweichender `compare`-Funktion wird ein `console.warn` emittiert; das alte Reader-Objekt bleibt aus Kompatibilitätsgründen erhalten. | `Kernel.ts` |
 | **VIEW-12** | `ShaePropElement` parst numerische Attribute ohne Warnung — `Number("foo")` → `NaN` propagiert. | `ShaePropElement.ts:177–205` |
 | **VIEW-13** | `ShaeEntElement.#dispatchRequestParent`-Microtask prüft `isConnected` nicht; nach Disconnect bubbelt ein Streu-Event. | `ShaeEntElement.ts:343–346` |
 
@@ -321,12 +311,12 @@ Ein reines JS-Paket (kein TS), `src/` wird ohne Bundle-Schritt veröffentlicht.
 
 ### 7.1 Muss vor 1.0
 
-1. **Auto-Destroy-Feature komplett verdrahten** — Feld in `ICreateEntitiesChange`, durchreichen in `parse()`, Re-Parenting-Subscription pflegen, E2E-Test mit Worker. *(KERN-1, KERN-2)*
-2. **`destroyEntity` rekursiv über Kinder** — Politik definieren (kaskadieren oder zu Root befördern). *(KERN-3)*
+1. ~~**Auto-Destroy-Feature komplett verdrahten** — Feld in `ICreateEntitiesChange`, durchreichen in `parse()`, Re-Parenting-Subscription pflegen, E2E-Test mit Worker. *(KERN-1, KERN-2)*~~ ✅ Erledigt (Kernel- und ViewComponent-Specs sowie Playwright-E2E `auto-destruct.spec.ts` mit echtem `RemoteWorkerEnv`).
+2. ~~**`destroyEntity` rekursiv über Kinder** — Politik definieren (kaskadieren oder zu Root befördern). *(KERN-3)*~~ ✅ Erledigt (Variante C).
 3. **`MessageRouter`-Doppel-Confirm im Catch-Pfad fixen.** *(VIEW-3)*
 4. **Worker-Fehlerpfade härten:** `error`/`messageerror`-Handler, ausstehende Promises bei `destroy()` rejecten, expliziter `terminated`-Status. *(VIEW-1, VIEW-2)*
 5. **CI lässt E2E nicht aus** — Playwright-Browser im CI-Image installieren, `test:ci` umstellen oder zweiten Job ergänzen. *(CI-Gap)*
-6. **Cache-Invalidierung von `traverseLevelOrderBFS` bei programmatischer Destruktion.** *(KERN-4)*
+6. ~~**Cache-Invalidierung von `traverseLevelOrderBFS` bei programmatischer Destruktion.** *(KERN-4)*~~ ✅ Erledigt.
 
 ### 7.2 Sollte zeitnah
 

packages/shadow-objects-e2e/pages/auto-destruct.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>auto-destruct (KERN-1)</title>
+  </head>
+  <body>
+    <section id="tests"></section>
+    <script type="module" src="/src/auto-destruct.js"></script>
+  </body>
+</html>

packages/shadow-objects-e2e/public/mod-auto-destruct.js

@@ -0,0 +1,64 @@
+// Module-level lifecycle tracker — children's onDestroy callbacks update this,
+// the parent SO reads it back and reports to the view.
+const lifecycle = {
+  flagged: {created: false, destroyed: false, uuid: null},
+  unflagged: {created: false, destroyed: false, uuid: null},
+};
+
+function flaggedChild({entity, onDestroy}) {
+  lifecycle.flagged.created = true;
+  lifecycle.flagged.uuid = entity.uuid;
+  onDestroy(() => {
+    lifecycle.flagged.destroyed = true;
+  });
+}
+
+function unflaggedChild({entity, onDestroy}) {
+  lifecycle.unflagged.created = true;
+  lifecycle.unflagged.uuid = entity.uuid;
+  onDestroy(() => {
+    lifecycle.unflagged.destroyed = true;
+  });
+}
+
+function parent({entity, dispatchMessageToView}) {
+  const doomedUuid = crypto.randomUUID();
+  const flaggedUuid = crypto.randomUUID();
+  const unflaggedUuid = crypto.randomUUID();
+
+  // Build a doomed subtree under the (live) parent entity:
+  //   parent
+  //   └── doomedRoot
+  //       ├── flagged   (autoDestructionOnParentRemoval=true)
+  //       └── unflagged (autoDestructionOnParentRemoval=false)
+  entity.kernel.createEntity(doomedUuid, '#void', entity.uuid);
+  entity.kernel.createEntity(flaggedUuid, 'flaggedChild', doomedUuid, 0, undefined, true);
+  entity.kernel.createEntity(unflaggedUuid, 'unflaggedChild', doomedUuid, 0, undefined, false);
+
+  const beforeDestroy = {
+    flaggedCreated: lifecycle.flagged.created,
+    unflaggedCreated: lifecycle.unflagged.created,
+    flaggedAlive: entity.kernel.hasEntity(flaggedUuid),
+    unflaggedAlive: entity.kernel.hasEntity(unflaggedUuid),
+  };
+
+  entity.kernel.destroyEntity(doomedUuid);
+
+  const afterDestroy = {
+    flaggedDestroyed: lifecycle.flagged.destroyed,
+    unflaggedDestroyed: lifecycle.unflagged.destroyed,
+    flaggedAlive: entity.kernel.hasEntity(flaggedUuid),
+    unflaggedAlive: entity.kernel.hasEntity(unflaggedUuid),
+    unflaggedHasParent: entity.kernel.hasEntity(unflaggedUuid) ? entity.kernel.getEntity(unflaggedUuid).hasParent : null,
+  };
+
+  dispatchMessageToView('autoDestructResult', {beforeDestroy, afterDestroy});
+}
+
+export const shadowObjects = {
+  define: {
+    parent,
+    flaggedChild,
+    unflaggedChild,
+  },
+};

packages/shadow-objects-e2e/src/auto-destruct.js

@@ -0,0 +1,54 @@
+import {on, onceAsync} from '@spearwolf/eventize';
+import {ComponentContext, RemoteWorkerEnv, ShadowEnv, ViewComponent} from '@spearwolf/shadow-objects';
+import './style.css';
+import {testAsyncAction} from './test-helpers/testAsyncAction.js';
+import {testBooleanAction} from './test-helpers/testBooleanAction.js';
+
+main();
+
+async function main() {
+  const shadowEnv = new ShadowEnv();
+  shadowEnv.view = ComponentContext.get();
+  shadowEnv.envProxy = new RemoteWorkerEnv();
+
+  await testAsyncAction('auto-destruct-env-ready', async () => {
+    await shadowEnv.ready();
+  });
+
+  await testAsyncAction('auto-destruct-import-module', async () => {
+    await shadowEnv.envProxy.importScript('/mod-auto-destruct.js');
+  });
+
+  const parentVC = new ViewComponent('parent');
+
+  let result;
+  on(parentVC, 'autoDestructResult', (payload) => {
+    result = payload;
+  });
+
+  await testAsyncAction('auto-destruct-result-arrived', async () => {
+    await shadowEnv.sync();
+    await onceAsync(parentVC, 'autoDestructResult');
+  });
+
+  testBooleanAction('auto-destruct-children-were-created', () => {
+    return (
+      result?.beforeDestroy?.flaggedCreated === true &&
+      result?.beforeDestroy?.unflaggedCreated === true &&
+      result?.beforeDestroy?.flaggedAlive === true &&
+      result?.beforeDestroy?.unflaggedAlive === true
+    );
+  });
+
+  testBooleanAction('auto-destruct-flagged-child-cascaded', () => {
+    return result?.afterDestroy?.flaggedDestroyed === true && result?.afterDestroy?.flaggedAlive === false;
+  });
+
+  testBooleanAction('auto-destruct-unflagged-child-promoted-to-root', () => {
+    return (
+      result?.afterDestroy?.unflaggedDestroyed === false &&
+      result?.afterDestroy?.unflaggedAlive === true &&
+      result?.afterDestroy?.unflaggedHasParent === false
+    );
+  });
+}

packages/shadow-objects-e2e/tests/auto-destruct.spec.ts

@@ -0,0 +1,24 @@
+import {expect, test} from '@playwright/test';
+
+const lookupTestResult = (testId: string) => {
+  test(testId, async ({page}) => {
+    await expect(page.getByTestId(testId)).toHaveAttribute('data-testresult', 'ok');
+  });
+};
+
+const lookupTests = (testIds: string[]) => testIds.forEach(lookupTestResult);
+
+test.describe('auto-destruct (KERN-1)', () => {
+  test.beforeEach('goto page', async ({page}) => {
+    await page.goto('/pages/auto-destruct.html');
+  });
+
+  lookupTests([
+    'auto-destruct-env-ready',
+    'auto-destruct-import-module',
+    'auto-destruct-result-arrived',
+    'auto-destruct-children-were-created',
+    'auto-destruct-flagged-child-cascaded',
+    'auto-destruct-unflagged-child-promoted-to-root',
+  ]);
+});

packages/shadow-objects/CHANGELOG.md

@@ -9,9 +9,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+- **Bugfix (entity lifecycle, KERN-3):** `kernel.destroyEntity()` now handles its children explicitly instead of leaving them as orphaned entries inside the kernel. Children with `autoDestructionOnParentRemoval` cascade-destroy together with the parent; all other children are promoted to root entities and remain reachable. This fixes a real leak where children without the auto-destruct flag were left in `kernel.#entities` after the parent was destroyed.
+- **Bugfix (entity lifecycle, KERN-2):** `autoDestructionOnParentRemoval` now survives re-parenting. The subscription is rebound to the new parent on every parent change (`Entity.parentUuid` setter / `Kernel.setParent()`), so a re-parented child is no longer destroyed when its *original* parent dies, and is correctly destroyed with its *current* parent.
+- **Bugfix (change trail, KERN-1):** the `autoDestructionOnParentRemoval` flag is now carried end-to-end through the change-trail pipeline. `ICreateEntitiesChange` exposes a new optional `autoDestructionOnParentRemoval?: boolean` field, `ComponentChanges.create()` accepts it as a 4th parameter, and `Kernel.run()`/`parse()` forwards it to `createEntity()`. Previously the kernel parameter existed but the trail-based path (worker and local env) never set it, so the feature was unreachable in production.
+- **New (public API):** `ViewComponent` accepts an `autoDestructionOnParentRemoval?: boolean` constructor option (also exposed as a read-only getter); the value flows through `ComponentContext.addComponent()` into the change trail, and survives `ContextLost` recovery via `ComponentMemory`. Backwards-compatible (defaults to `false`).
+- **Bugfix (entity lifecycle, KERN-5):** `Entity.parentUuid` setter and `Kernel.setParent()` now resolve the new parent UUID *before* detaching from the current parent. A `setParent` call with an unknown UUID throws as before but the entity stays attached to its original parent instead of being orphaned mid-mutation.
+- **Bugfix (registry, KERN-6):** `Registry.clear()` now also clears the prop-based (`@`-prefix) routes. Previously they accumulated across `clear()` calls, polluting tests and long-lived registries.
+- **DX (creation API, KERN-7):** `useProperty()`, `useContext()`, and `useParentContext()` now warn when a subsequent call passes a different `{compare}` function than the first call. The cached signal is created once with the original options; subsequent calls silently returned the cached reader, which could lead to surprising equality semantics. New behavior: still returns the cached reader, but emits a `console.warn` so the mismatch is visible.
+- **Bugfix (BFS cache, KERN-4):** `kernel.destroyEntity()` now invalidates the BFS traversal cache. Previously, programmatic destruction (e.g. through an auto-destroy listener) could leave `traverseLevelOrderBFS()` returning stale UUIDs.
 - **Bugfix (`./bundle.js` export):** the published `dist/bundle.js` now actually contains the inlined worker and the shae-element registrations. Previous releases shipped a 790-byte stub that only set `globalThis.SHADOW_ENTS_BUNDLE_LOADED = true` because the source-side `package.json#sideEffects` array referenced the (no-longer-emitted) intermediate `build/src/*` paths and the bundle entry was tree-shaken. Consumers using `import '@spearwolf/shadow-objects/bundle.js'` now get the full bundle (~130 KB).
 - **Cleanup:** the published `dist/` no longer contains the leftover `tsconfig.lib.tsbuildinfo` build artifact.
-- No source, runtime-API, or runtime-dependency changes. `@spearwolf/eventize@^4.3.1` and `@spearwolf/signalize@^0.28.0` unchanged.
+- Runtime dependencies updated: `@spearwolf/eventize@^4.3.1`, `@spearwolf/signalize@^0.28.0`.
 
 ## [0.30.2] - 2026-02-26