@objectstack/metadata 17.1.0 → 17.2.0

package/CHANGELOG.md

@@ -1,5 +1,111 @@
 # @objectstack/metadata
 
+## 17.2.0
+
+### Patch Changes
+
+- 047ac86: Five `Plugin` implementations now release their resources from `destroy()`, the
+  only teardown hook the kernel calls (#10772).
+  
+  `Plugin` (`@objectstack/core`'s `types.ts`) declares `init()`, `start?(ctx)` and
+  `destroy?()`. `ObjectKernel.performShutdown()` and `LiteKernel.destroy()` walk
+  the plugins in reverse calling `plugin.destroy()` — and nothing anywhere calls
+  `stop()`, `dispose()`, `close()` or `shutdown()` on a plugin. Each of these five
+  spelled its teardown with one of those names instead, so what it released was
+  still held after `await kernel.shutdown()` had **resolved**:
+  
+  | package | class | was spelled | what outlived shutdown |
+  |:--|:--|:--|:--|
+  | `@objectstack/metadata` | `MetadataPlugin` | `stop` (arrow property) | artifact watcher, `manager.dispose()`, repository handle |
+  | `@objectstack/runtime` | `AppPlugin` | `stop` (arrow property) | the `app:unregistered` catalog event, never emitted |
+  | `@objectstack/runtime` | `ExternalValidationPlugin` | `stop` (arrow property) | every armed drift-check `setInterval` |
+  | `@objectstack/plugin-email` | `EmailServicePlugin` | `dispose` | two metadata subscriptions, the SMTP transport, an engine binding |
+  | `@objectstack/plugin-webhooks` | `WebhookOutboxPlugin` | `dispose` | the auto-enqueuer (2 realtime subscriptions + a refresh interval) and two engine hooks |
+  
+  `ExternalValidationPlugin` is the one with teeth: it is one of only two `Plugin`
+  implementations in the tree that own `setInterval` directly, it is mounted on
+  the real `os serve` path, and its `stop()`'s only caller anywhere was the class
+  itself re-arming. Measured against a real kernel, its drift checker performed
+  five further reads in the five intervals after a resolved shutdown — the #9371
+  mechanism verbatim. `WebhookOutboxPlugin.dispose()` had **zero** callers in the
+  entire repo, so its teardown had never run in any process at all.
+  
+  **Nothing is removed and no signature narrows.** Each old name is retained as a
+  delegating alias, because it is public API of an exported class and an embedder
+  may have learned to call it directly precisely BECAUSE the kernel never did.
+  `stop` stays an arrow property where it was one (so a detached
+  `const { stop } = plugin` keeps working) and stays synchronous on
+  `ExternalValidationPlugin` (so a non-awaiting call site is unaffected). The two
+  `stop(ctx)` aliases widen their parameter to optional.
+  
+  One behavioural note for direct callers, since `destroy()` takes no context:
+  `MetadataPlugin.stop(ctx)` and `AppPlugin.stop(ctx)` now use the context
+  captured in `init()` and ignore the argument. In a real composition these are
+  the same object. The visible difference is confined to a plugin whose `init()`
+  never ran — for `MetadataPlugin` a dropped `warn` line, for `AppPlugin` a
+  catalog event that is no longer emitted for an app that was never registered.
+- Updated dependencies [8f04d9a]
+- Updated dependencies [6936d07]
+- Updated dependencies [59eb04d]
+- Updated dependencies [9f05b7d]
+- Updated dependencies [3b2af5e]
+- Updated dependencies [7d2d112]
+- Updated dependencies [5fa0d72]
+- Updated dependencies [8cc8401]
+- Updated dependencies [02b3b07]
+- Updated dependencies [46644e2]
+- Updated dependencies [46d34ab]
+- Updated dependencies [914c413]
+- Updated dependencies [55809a0]
+- Updated dependencies [ee2ff45]
+- Updated dependencies [47cd3ec]
+- Updated dependencies [52db1d1]
+- Updated dependencies [5649efb]
+- Updated dependencies [9d7d2de]
+- Updated dependencies [c815c50]
+- Updated dependencies [795ea05]
+- Updated dependencies [2306a76]
+- Updated dependencies [e5ea701]
+- Updated dependencies [26f3588]
+- Updated dependencies [a40dcc1]
+- Updated dependencies [def0d3e]
+- Updated dependencies [8d0bb79]
+- Updated dependencies [5acb58d]
+- Updated dependencies [2e3cf95]
+- Updated dependencies [4c93387]
+- Updated dependencies [504c8d5]
+- Updated dependencies [a037f7c]
+- Updated dependencies [3ee8ddf]
+- Updated dependencies [16cef97]
+- Updated dependencies [a79bd35]
+- Updated dependencies [6ceaa4b]
+- Updated dependencies [15ea214]
+- Updated dependencies [de19489]
+- Updated dependencies [c684d00]
+- Updated dependencies [923c424]
+- Updated dependencies [0ab81d1]
+- Updated dependencies [1ec36b7]
+- Updated dependencies [5f2e54c]
+- Updated dependencies [189373b]
+- Updated dependencies [35ad101]
+- Updated dependencies [ceb33a9]
+- Updated dependencies [dccbcec]
+- Updated dependencies [05bc692]
+- Updated dependencies [73d9795]
+- Updated dependencies [8012960]
+- Updated dependencies [266654d]
+- Updated dependencies [f34f56b]
+- Updated dependencies [f399618]
+- Updated dependencies [75e9301]
+- Updated dependencies [f334d66]
+- Updated dependencies [2810695]
+  - @objectstack/platform-objects@17.2.0
+  - @objectstack/spec@17.2.0
+  - @objectstack/core@17.2.0
+  - @objectstack/metadata-core@17.2.0
+  - @objectstack/metadata-fs@17.2.0
+  - @objectstack/types@17.2.0
+
 ## 17.1.0
 
 ### Patch Changes

package/dist/index.cjs

@@ -4536,7 +4536,10 @@ var ARTIFACT_FIELD_TO_TYPE = {
   dashboards: "dashboard",
   reports: "report",
   actions: "action",
-  themes: "theme",
+  // `themes: 'theme'` removed at #10485 (ADR-0049): the carrier key is
+  // retired, so a parsed artifact can no longer carry the field — and the
+  // ingest half of the dead pipeline (items stored, read by nothing) goes
+  // with the authoring half rather than surviving it as drift.
   workflows: "workflow",
   flows: "flow",
   // ADR-0090 D3: stacks declare `positions` (stack.zod.ts); the retired
@@ -4589,6 +4592,7 @@ var MetadataPlugin = class {
      */
     this.optionalDependencies = ["com.objectstack.engine.objectql"];
     this.init = async (ctx) => {
+      this.initCtx = ctx;
       ctx.logger.info("Initializing Metadata Manager", {
         root: this.options.rootDir || process.cwd(),
         watch: this.options.watch,
@@ -4770,7 +4774,22 @@ var MetadataPlugin = class {
         console.warn("[MetadataPlugin] Failed to register HMR endpoint", e?.message);
       }
     };
-    this.stop = async (ctx) => {
+    /**
+     * Teardown — the kernel's ONLY teardown hook.
+     *
+     * [#10772] This body used to be spelled `stop(ctx)`. `Plugin`
+     * (`@objectstack/core`'s `types.ts`) declares `init()`, `start?(ctx)` and
+     * `destroy?()` and no `stop()`, and `ObjectKernel.performShutdown()` /
+     * `LiteKernel.destroy()` walk the plugins in reverse calling
+     * `plugin.destroy()` — so the artifact watcher, the manager and the
+     * repository were all still held after `await kernel.shutdown()` had
+     * RESOLVED. The `start`/`stop` pair read symmetric to a reviewer because
+     * `start()` really is on the interface; only one half was ever called.
+     *
+     * Idempotent: every handle is cleared as it is released, so a second
+     * teardown is a no-op rather than a second close.
+     */
+    this.destroy = async () => {
       if (this.artifactWatcher) {
         try {
           await this.artifactWatcher.close();
@@ -4781,7 +4800,7 @@ var MetadataPlugin = class {
       try {
         await this.manager.dispose();
       } catch (e) {
-        ctx.logger.warn("[MetadataPlugin] manager.dispose() failed", { error: e?.message });
+        this.initCtx?.logger?.warn?.("[MetadataPlugin] manager.dispose() failed", { error: e?.message });
       }
       const repo = this.repository;
       if (repo && typeof repo.close === "function") {
@@ -4792,6 +4811,18 @@ var MetadataPlugin = class {
       }
       this.repository = void 0;
     };
+    /**
+     * Retained alias for {@link destroy}. Kept because it is public API of an
+     * exported class: an embedder may have learned to call it directly
+     * precisely BECAUSE the kernel never did, and deleting it would break them.
+     * Still an arrow property, so a detached `const { stop } = plugin` call
+     * keeps working too. The parameter is now optional and ignored —
+     * `destroy()` takes no context, so teardown logs through the context
+     * captured in `init()`.
+     */
+    this.stop = async (_ctx) => {
+      await this.destroy();
+    };
     this.options = {
       ...options,
       watch: options.watch ?? false