@objectstack/plugin-reports 17.1.0 → 17.2.0

package/CHANGELOG.md

@@ -1,5 +1,134 @@
 # @objectstack/plugin-reports
 
+## 17.2.0
+
+### Minor Changes
+
+- e222a53: **BREAKING** (compile-time only): twelve logger sink types that declared an
+  optional `error` now declare a **non-optional** `warn`, so a durability report
+  always has somewhere to land (#9754, #10556).
+  
+  `minor`, not `major`: during the launch window this stack ships breaking changes
+  as `minor` — every publishable package versions in lockstep, so a `major` would
+  promote the whole release. `patch` would be wrong in the other direction, because
+  this *can* break a consumer's build.
+  
+  `error` stays optional on every one of these types — hosts legitimately inject
+  reduced sinks, and requiring `error` was measured and rejected as #9754 option C.
+  What changes is that its *absence* now has a declared, guaranteed destination.
+  Call sites keep the `logger?.warn?.(…)` spelling as the backstop for hosts the
+  type cannot reach, so **no runtime behaviour changes**: nothing that printed
+  before stops printing, and nothing silent starts printing.
+  
+  ### Who has to change, and what to do
+  
+  Only a caller that hands one of these sinks an object with **no `warn` method** —
+  for example `{ info }` or `{ error }` alone. Add a `warn` member; there is no
+  rename, no removal, and no stored value or metadata key to rewrite. Every
+  construction site inside this repo already supplied one, so the in-repo cost was
+  zero; the compile error is reserved for the callers that were silently discarding
+  these reports.
+  
+  The affected types, by package:
+  
+  - `@objectstack/cloud-connection` — the internal `PluginContext['logger']`
+  - `@objectstack/metadata-protocol` — `IndexMigrationLogger`
+  - `@objectstack/plugin-approvals` — the internal `MinimalLogger` of `lifecycle-hooks`
+  - `@objectstack/plugin-audit` — `AuthEventAuditLogger`, `ReadAuditLogger`
+  - `@objectstack/plugin-auth` — `ReconcileMembershipDeps['logger']`, the internal
+    `LoggerLike` of `member-role-canonical`, and `AuthManagerOptions['logger']`
+  - `@objectstack/plugin-email` — `ReclaimLogger`, via `ReclaimAttachmentContentOptions`
+  - `@objectstack/plugin-reports` — `ReportServiceOptions['logger']`
+  - `@objectstack/plugin-sharing` — the internal `MinimalLogger` of `bulk-recompute`,
+    `rule-hooks` and `record-share-cascade`
+  - `@objectstack/plugin-webhooks` — `OptionalLogger`, via `AutoEnqueuerOptions`
+  - `@objectstack/service-knowledge` — `KnowledgeLogger`
+  
+  `AuthManagerOptions['logger']` is the one most likely to be reached from outside:
+  `AuthManager` is public surface, its `logger` option stays optional, and a logger
+  that *is* supplied must now carry `warn`. The only non-test construction site in
+  this repo passes the kernel `Logger`, whose `warn` is already required.
+  
+  `ReportService` and `AutoEnqueuer` additionally stopped defaulting their logger
+  field to `{}`. The field is now honestly optional rather than holding an empty
+  object that declared it could report and discarded everything. Behaviour is
+  unchanged in both directions.
+  
+  <!-- adr-0087: not-required (runtime-interface-only packages/plugins/plugin-auth/src/auth-manager.ts#AuthManagerOptions, packages/plugins/plugin-auth/src/reconcile-membership.ts#ReconcileMembershipDeps, packages/metadata-protocol/src/migrations/partial-index-probe.ts#IndexMigrationLogger, packages/plugins/plugin-audit/src/auth-event-audit.ts#AuthEventAuditLogger, packages/plugins/plugin-audit/src/read-audit.ts#ReadAuditLogger, packages/plugins/plugin-reports/src/report-service.ts#ReportServiceOptions, packages/services/service-knowledge/src/knowledge-service.ts#KnowledgeLogger) every tightened type is a plain TypeScript logger interface -- no Zod projection, no metadata surface, and none is referenced by one -- so `objectstack migrate meta` has nothing to rewrite. Nothing is removed or renamed and no stored value moves; the only consumer action is adding a `warn` member at a construction site the compiler names. -->
+
+### Patch Changes
+
+- 6d5c4fa: Release these plugins' resources from `destroy()`, the teardown hook the kernel
+  actually calls (#10371). `Plugin` declares `init()`, `start?(ctx)` and
+  `destroy?()` — and no `stop()` — so `ObjectKernel.performShutdown()` and
+  `LiteKernel.destroy()`, which walk the plugins in reverse calling
+  `plugin.destroy()`, walked straight past every plugin whose teardown was spelled
+  `stop()`. `await kernel.shutdown()` resolved with the reports dispatcher still
+  armed, the REST/OpenAPI/Slack connectors still registered on the automation
+  engine, the approvals SLA escalation job still scheduled, and the knowledge
+  event-sync subscription still open.
+  
+  Each teardown body now lives in `destroy()`. `stop()` is retained as a
+  delegating alias with its parameter made optional, so an embedder that learned
+  to call it directly — precisely because the kernel never did — keeps working
+  unchanged. No export is removed and the `Plugin` interface is untouched.
+  
+  Same defect as #9371 in `@objectstack/service-messaging`, which surfaced as
+  fully green test runs exiting 1 on `EnvironmentTeardownError` and being evicted
+  from the merge queue.
+- Updated dependencies [8f04d9a]
+- Updated dependencies [6936d07]
+- Updated dependencies [59eb04d]
+- Updated dependencies [9f05b7d]
+- Updated dependencies [3b2af5e]
+- Updated dependencies [7d2d112]
+- Updated dependencies [5fa0d72]
+- Updated dependencies [02b3b07]
+- 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 [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 [73d9795]
+- Updated dependencies [8012960]
+- Updated dependencies [266654d]
+- Updated dependencies [f34f56b]
+- Updated dependencies [f399618]
+- Updated dependencies [75e9301]
+- Updated dependencies [2810695]
+  - @objectstack/platform-objects@17.2.0
+  - @objectstack/spec@17.2.0
+  - @objectstack/core@17.2.0
+
 ## 17.1.0
 
 ### Patch Changes

package/dist/index.d.mts

@@ -76,9 +76,16 @@ interface ReportServiceOptions {
     engine: ReportEngine;
     email?: ReportEmail;
     clock?: ReportClock;
+    /**
+     * `warn` is GUARANTEED, `error` is not (#9754). Hosts do inject reduced sinks,
+     * so `error` stays optional — but a durability report that degrades to `warn`
+     * needs `warn` to actually be there, and this service degrades to it in eight
+     * places below. The whole `logger` stays optional; what is no longer
+     * representable is a sink that HAS the field and still prints nothing.
+     */
     logger?: {
         info?: (msg: any, ...rest: any[]) => void;
-        warn?: (msg: any, ...rest: any[]) => void;
+        warn: (msg: any, ...rest: any[]) => void;
         error?: (msg: any, ...rest: any[]) => void;
     };
     /** Cap rows per report to protect both DB and email size. */
@@ -109,7 +116,22 @@ declare class ReportService implements IReportService {
     private readonly engine;
     private readonly email?;
     private readonly clock;
-    private readonly logger;
+    /**
+     * Optional, and deliberately NOT defaulted to `{}` (#10556).
+     *
+     * `ReportServiceOptions['logger']` guarantees a `warn` channel under #9754, so `{}` stopped being a
+     * legal value of the type — which is the gate working: an empty object is a
+     * sink that declares it can report and then discards everything. The repair
+     * is to say what is TRUE — there may be no logger at all — rather than to
+     * mint a sink that lies. Runtime behaviour is unchanged in both directions:
+     * absent logger and `{}` both printed nothing before, and print nothing now.
+     *
+     * ⛔ What this deliberately does NOT decide: whether an absent host sink should
+     * instead default to a `console`-backed one. That is the open design call the
+     * #9754 ledger records against `plugin-security`'s `= {}` field, and it is a
+     * maintainer decision — not something to settle here to make a checker green.
+     */
+    private readonly logger?;
     private readonly maxRows;
     private readonly resolveOwnerContext?;
     private readonly canExportFn?;
@@ -221,10 +243,56 @@ declare class ReportsServicePlugin implements Plugin {
     private intervalHandle?;
     private jobName?;
     private jobService?;
+    /**
+     * Captured in `init()` because `destroy()` — the hook the kernel actually
+     * calls — takes NO `PluginContext` (`Plugin.destroy?(): Promise<void> | void`
+     * in core's `types.ts`). Teardown still needs somewhere to report a failed
+     * job cancellation, so the logger is held rather than resolved late.
+     */
+    private logger?;
     constructor(options?: ReportsPluginOptions);
     init(ctx: PluginContext): Promise<void>;
     start(ctx: PluginContext): Promise<void>;
-    stop(ctx: PluginContext): Promise<void>;
+    /**
+     * The kernel's teardown hook (`Plugin.destroy?()`, core `types.ts`) — the
+     * ONLY teardown entry point `ObjectKernel.performShutdown()` and
+     * `LiteKernel.destroy()` invoke.
+     *
+     * [#10371] IT USED TO BE `stop()`, WHICH NOTHING CALLED. The body below was
+     * correct in every respect except its NAME: `Plugin` declares `init()`,
+     * `start?()` and `destroy?()` and no `stop()`, so the kernel walked straight
+     * past this plugin at shutdown and the dispatcher went on ticking after
+     * `await kernel.shutdown()` had resolved. The asymmetry is what hid it:
+     * `start()` IS on the interface and does fire, so a `start`/`stop` pair reads
+     * as symmetric in review.
+     *
+     * WHY IT STAYED INVISIBLE, AND WHERE THE BILL LANDS. `start()` `unref()`s the
+     * interval, so a long-lived host process still exits and nothing complains in
+     * production. Under vitest the worker is alive throughout teardown, so a tick
+     * fires after the test file is over, reads through a driver the suite already
+     * disconnected, and a console fallback warns; `console.*` inside a worker is
+     * an RPC (`onUserConsoleLog`) and one issued after `rpcDone()` snapshotted the
+     * pending set is rejected as `EnvironmentTeardownError`. Nothing awaits that
+     * promise, so it lands as an unhandled rejection and fails a run in which
+     * every test passed. That is the identical defect #9371 fixed in
+     * `MessagingServicePlugin` — measured there as two green PRs (334/334 and
+     * 337/337) evicted from the merge queue.
+     *
+     * The job-service branch matters as much as the timer: when `service-job` is
+     * installed the dispatcher is a scheduled job rather than a `setInterval`, so
+     * a teardown the kernel never reaches leaks whichever of the two this
+     * deployment happens to use.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Retained alias for {@link destroy}. Kept because it is public API of an
+     * exported class, and removing it would break an embedder who learned to call
+     * it directly precisely BECAUSE the kernel never did. The parameter is now
+     * optional and ignored: `destroy()` takes no context, so teardown reads the
+     * logger captured in `init()`. Prefer kernel shutdown; direct callers keep
+     * working unchanged.
+     */
+    stop(_ctx?: PluginContext): Promise<void>;
 }
 
 export { type ReportClock, type ReportEmail, type ReportEngine, ReportService, type ReportServiceOptions, type ReportsPluginOptions, ReportsServicePlugin, renderReport };

package/dist/index.d.ts

@@ -76,9 +76,16 @@ interface ReportServiceOptions {
     engine: ReportEngine;
     email?: ReportEmail;
     clock?: ReportClock;
+    /**
+     * `warn` is GUARANTEED, `error` is not (#9754). Hosts do inject reduced sinks,
+     * so `error` stays optional — but a durability report that degrades to `warn`
+     * needs `warn` to actually be there, and this service degrades to it in eight
+     * places below. The whole `logger` stays optional; what is no longer
+     * representable is a sink that HAS the field and still prints nothing.
+     */
     logger?: {
         info?: (msg: any, ...rest: any[]) => void;
-        warn?: (msg: any, ...rest: any[]) => void;
+        warn: (msg: any, ...rest: any[]) => void;
         error?: (msg: any, ...rest: any[]) => void;
     };
     /** Cap rows per report to protect both DB and email size. */
@@ -109,7 +116,22 @@ declare class ReportService implements IReportService {
     private readonly engine;
     private readonly email?;
     private readonly clock;
-    private readonly logger;
+    /**
+     * Optional, and deliberately NOT defaulted to `{}` (#10556).
+     *
+     * `ReportServiceOptions['logger']` guarantees a `warn` channel under #9754, so `{}` stopped being a
+     * legal value of the type — which is the gate working: an empty object is a
+     * sink that declares it can report and then discards everything. The repair
+     * is to say what is TRUE — there may be no logger at all — rather than to
+     * mint a sink that lies. Runtime behaviour is unchanged in both directions:
+     * absent logger and `{}` both printed nothing before, and print nothing now.
+     *
+     * ⛔ What this deliberately does NOT decide: whether an absent host sink should
+     * instead default to a `console`-backed one. That is the open design call the
+     * #9754 ledger records against `plugin-security`'s `= {}` field, and it is a
+     * maintainer decision — not something to settle here to make a checker green.
+     */
+    private readonly logger?;
     private readonly maxRows;
     private readonly resolveOwnerContext?;
     private readonly canExportFn?;
@@ -221,10 +243,56 @@ declare class ReportsServicePlugin implements Plugin {
     private intervalHandle?;
     private jobName?;
     private jobService?;
+    /**
+     * Captured in `init()` because `destroy()` — the hook the kernel actually
+     * calls — takes NO `PluginContext` (`Plugin.destroy?(): Promise<void> | void`
+     * in core's `types.ts`). Teardown still needs somewhere to report a failed
+     * job cancellation, so the logger is held rather than resolved late.
+     */
+    private logger?;
     constructor(options?: ReportsPluginOptions);
     init(ctx: PluginContext): Promise<void>;
     start(ctx: PluginContext): Promise<void>;
-    stop(ctx: PluginContext): Promise<void>;
+    /**
+     * The kernel's teardown hook (`Plugin.destroy?()`, core `types.ts`) — the
+     * ONLY teardown entry point `ObjectKernel.performShutdown()` and
+     * `LiteKernel.destroy()` invoke.
+     *
+     * [#10371] IT USED TO BE `stop()`, WHICH NOTHING CALLED. The body below was
+     * correct in every respect except its NAME: `Plugin` declares `init()`,
+     * `start?()` and `destroy?()` and no `stop()`, so the kernel walked straight
+     * past this plugin at shutdown and the dispatcher went on ticking after
+     * `await kernel.shutdown()` had resolved. The asymmetry is what hid it:
+     * `start()` IS on the interface and does fire, so a `start`/`stop` pair reads
+     * as symmetric in review.
+     *
+     * WHY IT STAYED INVISIBLE, AND WHERE THE BILL LANDS. `start()` `unref()`s the
+     * interval, so a long-lived host process still exits and nothing complains in
+     * production. Under vitest the worker is alive throughout teardown, so a tick
+     * fires after the test file is over, reads through a driver the suite already
+     * disconnected, and a console fallback warns; `console.*` inside a worker is
+     * an RPC (`onUserConsoleLog`) and one issued after `rpcDone()` snapshotted the
+     * pending set is rejected as `EnvironmentTeardownError`. Nothing awaits that
+     * promise, so it lands as an unhandled rejection and fails a run in which
+     * every test passed. That is the identical defect #9371 fixed in
+     * `MessagingServicePlugin` — measured there as two green PRs (334/334 and
+     * 337/337) evicted from the merge queue.
+     *
+     * The job-service branch matters as much as the timer: when `service-job` is
+     * installed the dispatcher is a scheduled job rather than a `setInterval`, so
+     * a teardown the kernel never reaches leaks whichever of the two this
+     * deployment happens to use.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Retained alias for {@link destroy}. Kept because it is public API of an
+     * exported class, and removing it would break an embedder who learned to call
+     * it directly precisely BECAUSE the kernel never did. The parameter is now
+     * optional and ignored: `destroy()` takes no context, so teardown reads the
+     * logger captured in `init()`. Prefer kernel shutdown; direct callers keep
+     * working unchanged.
+     */
+    stop(_ctx?: PluginContext): Promise<void>;
 }
 
 export { type ReportClock, type ReportEmail, type ReportEngine, ReportService, type ReportServiceOptions, type ReportsPluginOptions, ReportsServicePlugin, renderReport };

package/dist/index.js

@@ -154,7 +154,7 @@ var ReportService = class {
     this.engine = opts.engine;
     this.email = opts.email;
     this.clock = opts.clock ?? { now: () => /* @__PURE__ */ new Date() };
-    this.logger = opts.logger ?? {};
+    this.logger = opts.logger;
     this.maxRows = Math.max(1, opts.maxRows ?? 5e3);
     this.resolveOwnerContext = opts.resolveOwnerContext;
     this.canExportFn = opts.canExport;
@@ -186,7 +186,7 @@ var ReportService = class {
     try {
       allowed = await this.canExportFn(object, context);
     } catch (err) {
-      this.logger.warn?.("ReportService: canExport check failed \u2014 denying export", err);
+      this.logger?.warn?.("ReportService: canExport check failed \u2014 denying export", err);
       allowed = false;
     }
     if (!allowed) {
@@ -382,7 +382,7 @@ var ReportService = class {
           updated_at: ranAt
         }, { context: SYSTEM_CTX });
       } catch (err) {
-        this.logger.warn?.("ReportService: failed to stamp last_run_at", err);
+        this.logger?.warn?.("ReportService: failed to stamp last_run_at", err);
       }
     }
     return {
@@ -485,7 +485,7 @@ var ReportService = class {
         const report = rowFromSaved(row);
         const ownerId = report.owner_id;
         const runContext = ownerId && this.resolveOwnerContext ? await this.resolveOwnerContext(ownerId).catch((err) => {
-          this.logger.warn?.("ReportService.dispatchDue: owner context resolution failed", err);
+          this.logger?.warn?.("ReportService.dispatchDue: owner context resolution failed", err);
           return null;
         }) : null;
         if (!runContext) {
@@ -531,7 +531,7 @@ var ReportService = class {
             });
           }
         } else if (!this.email) {
-          this.logger.warn?.("ReportService.dispatchDue: no email service \u2014 schedule fired but mail not sent");
+          this.logger?.warn?.("ReportService.dispatchDue: no email service \u2014 schedule fired but mail not sent");
         }
         await this.advanceSchedule(schedule, ts);
         fired++;
@@ -541,7 +541,7 @@ var ReportService = class {
           last_status: "failed",
           last_error: String(err?.message ?? err ?? "unknown").slice(0, 500)
         });
-        this.logger.error?.("ReportService.dispatchDue: schedule failed", err);
+        this.logger?.error?.("ReportService.dispatchDue: schedule failed", err);
       }
     }
     return { fired, failed, skipped };
@@ -562,9 +562,9 @@ var ReportService = class {
       try {
         const next = new import_croner.Cron(cron, { timezone: schedule.timezone || "UTC" }).nextRun(from);
         if (next) return next;
-        this.logger.warn?.(`ReportService: cron '${cron}' has no next occurrence; falling back to interval`);
+        this.logger?.warn?.(`ReportService: cron '${cron}' has no next occurrence; falling back to interval`);
       } catch (err) {
-        this.logger.warn?.(`ReportService: invalid cron '${cron}'; falling back to interval`, err);
+        this.logger?.warn?.(`ReportService: invalid cron '${cron}'; falling back to interval`, err);
       }
     }
     const interval = schedule.interval_minutes ?? DEFAULT_INTERVAL_MIN;
@@ -589,7 +589,7 @@ var ReportService = class {
         updated_at: this.clock.now().toISOString()
       }, { context: SYSTEM_CTX });
     } catch (err) {
-      this.logger.warn?.("ReportService: failed to mark schedule", err);
+      this.logger?.warn?.("ReportService: failed to mark schedule", err);
     }
   }
 };
@@ -605,6 +605,7 @@ var ReportsServicePlugin = class {
     this.options = options;
   }
   async init(ctx) {
+    this.logger = ctx.logger;
     ctx.getService("manifest").register({
       id: "com.objectstack.service.reports",
       name: "Reports Service",
@@ -696,16 +697,59 @@ var ReportsServicePlugin = class {
       ctx.logger.info("ReportsServicePlugin: dispatcher registered (setInterval fallback)", { intervalMs });
     });
   }
-  async stop(ctx) {
+  /**
+   * The kernel's teardown hook (`Plugin.destroy?()`, core `types.ts`) — the
+   * ONLY teardown entry point `ObjectKernel.performShutdown()` and
+   * `LiteKernel.destroy()` invoke.
+   *
+   * [#10371] IT USED TO BE `stop()`, WHICH NOTHING CALLED. The body below was
+   * correct in every respect except its NAME: `Plugin` declares `init()`,
+   * `start?()` and `destroy?()` and no `stop()`, so the kernel walked straight
+   * past this plugin at shutdown and the dispatcher went on ticking after
+   * `await kernel.shutdown()` had resolved. The asymmetry is what hid it:
+   * `start()` IS on the interface and does fire, so a `start`/`stop` pair reads
+   * as symmetric in review.
+   *
+   * WHY IT STAYED INVISIBLE, AND WHERE THE BILL LANDS. `start()` `unref()`s the
+   * interval, so a long-lived host process still exits and nothing complains in
+   * production. Under vitest the worker is alive throughout teardown, so a tick
+   * fires after the test file is over, reads through a driver the suite already
+   * disconnected, and a console fallback warns; `console.*` inside a worker is
+   * an RPC (`onUserConsoleLog`) and one issued after `rpcDone()` snapshotted the
+   * pending set is rejected as `EnvironmentTeardownError`. Nothing awaits that
+   * promise, so it lands as an unhandled rejection and fails a run in which
+   * every test passed. That is the identical defect #9371 fixed in
+   * `MessagingServicePlugin` — measured there as two green PRs (334/334 and
+   * 337/337) evicted from the merge queue.
+   *
+   * The job-service branch matters as much as the timer: when `service-job` is
+   * installed the dispatcher is a scheduled job rather than a `setInterval`, so
+   * a teardown the kernel never reaches leaks whichever of the two this
+   * deployment happens to use.
+   */
+  async destroy() {
     if (this.intervalHandle) clearInterval(this.intervalHandle);
     this.intervalHandle = void 0;
     if (this.jobService && this.jobName && typeof this.jobService.cancel === "function") {
       try {
         await this.jobService.cancel(this.jobName);
       } catch (err) {
-        ctx.logger.warn("ReportsServicePlugin: failed to cancel job", err);
+        this.logger?.warn("ReportsServicePlugin: failed to cancel job", err);
       }
     }
+    this.jobService = void 0;
+    this.jobName = void 0;
+  }
+  /**
+   * Retained alias for {@link destroy}. Kept because it is public API of an
+   * exported class, and removing it would break an embedder who learned to call
+   * it directly precisely BECAUSE the kernel never did. The parameter is now
+   * optional and ignored: `destroy()` takes no context, so teardown reads the
+   * logger captured in `init()`. Prefer kernel shutdown; direct callers keep
+   * working unchanged.
+   */
+  async stop(_ctx) {
+    await this.destroy();
   }
 };
 // Annotate the CommonJS export names for ESM import in node: