fix(plugins,services): guarantee a warn channel on twelve optional-error sinks (#10691)

* fix(plugins,services): guarantee a `warn` channel on twelve optional-`error` sinks

Pays down twelve of the fifteen rows in the shrink-only optional-error sink
ledger (#9754): each sink declaring an optional `error` now declares a
NON-optional `warn`, so a durability report always has somewhere to land.
`error` stays optional everywhere — requiring it was measured and rejected as
#9754 option C. The twelve ledger rows are deleted in this same commit, which
the checker requires (it fails on a stale entry).

Three forwarding seams were tightened with them, each reported by `tsc` rather
than guessed at: `MinimalLogger` in plugin-sharing's `rule-hooks.ts` and
`record-share-cascade.ts` (both forward into bulk-recompute's now-guaranteed
sink), and `AuthManagerConfig['logger']` in plugin-auth (forwards verbatim into
`ReconcileMembershipDeps`).

Two of the twelve turned out NOT to be one-line repairs: `report-service.ts`
and `auto-enqueuer.ts` both defaulted their logger to `?? {}` — the same shape
the ledger fences off as an open design call for plugin-security. Neither
default was decided here. The field is now honestly optional instead of being
given a minted sink that declares it can warn and discards everything; runtime
behaviour is unchanged in both directions.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PnJHU45vPJj5UQrxe946Bx

* fix(metadata-protocol): keep the lying-host backstop pin under the tightened sink

`partial-index-probe.test.ts` passed `{}` as an `IndexMigrationLogger` to pin
that `logProblem` degrades to silence rather than throwing. `{}` stopped being
a legal value of that type when `warn` became non-optional, so the case now
casts deliberately and says why: the type-level guarantee and the runtime
backstop are different promises, and this case asserts the second.

Caught by `check:type-check-debt --re-measure` (DEBT 63 -> 64), not by the
package build: `@objectstack/metadata-protocol` declares no `typecheck` script,
so its test files are hidden from tsc and a `--filter ... typecheck` run would
have reported a silent zero-match pass. Ledger number untouched, back at 63.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PnJHU45vPJj5UQrxe946Bx

* test(plugin-auth): declare `warn` on three reconcile-membership logger doubles

`ReconcileMembershipDeps['logger']` guarantees a `warn` channel (#9754), so the
three `{ error: vi.fn() }` doubles in `reconcile-membership.test.ts` stopped
being legal values of it. A fourth double in the same file already declared
`warn` and was unaffected.

Measured rather than assumed, because these files are HIDDEN from
`pnpm typecheck` (plugin-auth's tsconfig excludes its own tests, TEST_DEBT):
`tsc` over a tsconfig with the test exclusion dropped reports 98 with this
branch's plugin-auth changes reverted and 101 with them, so the +3 was this
branch's. With these three doubles repaired it is 98 again.

⛔ The TEST_DEBT ledger number is untouched at 109 and `--lower` was NOT run.
The 11-error surplus #10615 reports is left exactly as that card describes it —
neither consumed by this branch nor closed by it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PnJHU45vPJj5UQrxe946Bx

* fix(changeset): correct the type name, declare the break, and bump `minor`

Three defects in the changeset text, all found in PM review of #10691:

1. `AuthManagerConfig` does not exist. The type is `AuthManagerOptions`
   (auth-manager.ts:375, public via `export * from './auth-manager.js'`), and
   the tightened `logger` field is :647 inside it. Measured: `AuthManagerConfig`
   has ZERO hits in `packages/**` source and only two in a stale CHANGELOG.md —
   so an embedder who hit the compile error and grepped the name this changeset
   shipped would have found an already-retired spelling and been led away from
   the fix. That is what makes it worse than a typo: a changeset body IS the
   published CHANGELOG.

2. `patch` contradicted the changeset's own text. `check-changeset-no-major.mjs`
   records the convention in its own WHY THIS EXISTS block: "During the launch
   window we ship breaking changes as `minor` (pre-1.0 semantics ...)" — every
   publishable package is in the Changesets `fixed` group and versions in
   lockstep, so the bump level is the only channel that tells the stack a release
   can break a build. A changeset that says "an external embedder ... will now
   see a compile error" cannot also be `patch`. Now `minor`; `major` is banned by
   that same guard.

3. The break is now DECLARED (`**BREAKING**`) and carries its ADR-0087
   disposition, which a declared-breaking changeset must state in writing
   (AGENTS.md, enforced by `check:adr-0087-registration`).

The marker is `runtime-interface-only`, naming the seven exported symbols, and it
was chosen by reading the gate rather than by pattern-matching the common case:
`no-migration-prescription` is REFUSED when the body carries a prescription, and
`runtime-interface-only` inherits that same refusal (#8299) — it is a narrowing,
never an escape. It is claimable here because it is TRUE and mechanically
re-checkable: every tightened type is a plain TS logger interface, no Zod
projection, no metadata surface and unreferenced by one, so `objectstack migrate
meta` provably has nothing to rewrite. Nothing is removed or renamed, so
AGENTS.md's FROM → TO requirement (scoped to removals and renames) is not
triggered; the consumer action is stated plainly instead.

Changeset text only — no source file is touched by this commit.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PnJHU45vPJj5UQrxe946Bx

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-warren

.changeset/optional-error-sink-paydown.md

@@ -0,0 +1,64 @@
+---
+"@objectstack/cloud-connection": minor
+"@objectstack/metadata-protocol": minor
+"@objectstack/plugin-approvals": minor
+"@objectstack/plugin-audit": minor
+"@objectstack/plugin-auth": minor
+"@objectstack/plugin-email": minor
+"@objectstack/plugin-reports": minor
+"@objectstack/plugin-sharing": minor
+"@objectstack/plugin-webhooks": minor
+"@objectstack/service-knowledge": minor
+---
+
+**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. -->

packages/cloud-connection/src/cloud-connection-plugin.ts

@@ -56,7 +56,15 @@ interface PluginContext {
     getService<T = any>(name: string): T;
     logger?: {
         info?: (msg: string) => void;
-        warn?: (msg: string) => void;
+        /**
+         * The GUARANTEED fallback channel (#9754). `error` stays optional — hosts do
+         * inject reduced sinks — so `warn` is where a durability report lands when
+         * `error` is absent, and a fallback that may itself be missing is not a
+         * fallback. Call sites keep the `logger?.warn?.(…)` spelling as the backstop
+         * for hosts the TYPE cannot reach; `SweepLogger` in plugin-email's
+         * `outbox-sweep.ts` carries the full reasoning and the measurement.
+         */
+        warn: (msg: string) => void;
         error?: (msg: string, err?: unknown) => void;
     };
 }

packages/metadata-protocol/src/migrations/partial-index-probe.test.ts

@@ -11,6 +11,7 @@ import {
     probeThenReplaceIndex,
     type IndexExec,
 } from './partial-index-probe.js';
+import type { IndexMigrationLogger } from './partial-index-probe.js';
 
 /**
  * The probe-first order, tested where it lives (#6418).
@@ -382,6 +383,18 @@ describe('probe-first partial index replacement (#6418)', () => {
         expect(warnOnly.warn).toHaveBeenCalledWith('msg', { detail: 'detail' });
 
         expect(() => logProblem(undefined, 'msg', 'detail')).not.toThrow();
-        expect(() => logProblem({}, 'msg', 'detail')).not.toThrow();
+        // `{}` is no longer a legal `IndexMigrationLogger` — #9754 made `warn`
+        // non-optional precisely so a sink with NEITHER channel cannot be
+        // written. The cast is deliberate and is the point of the case: it
+        // forces through the one host the TYPE cannot reach (a plain-JS
+        // embedder, or a cast at the boundary) and pins that `logProblem`'s
+        // `?.` backstop still degrades to silence instead of throwing
+        // `logger.warn is not a function` inside a migration probe. Type-level
+        // guarantee and runtime backstop are different promises; this asserts
+        // the second one, and the compile error that used to be impossible here
+        // is now what proves the first.
+        expect(() =>
+            logProblem({} as unknown as IndexMigrationLogger, 'msg', 'detail'),
+        ).not.toThrow();
     });
 });

packages/metadata-protocol/src/migrations/partial-index-probe.ts

@@ -97,13 +97,24 @@ export function resolveIndexExecForTable(engine: unknown, table: string): IndexE
 
 /**
  * Minimal logger surface, structurally compatible with `@objectstack/spec`'s
- * `Logger` (every method optional so a bare console or a test double fits).
+ * `Logger` (a bare console or a test double fits — but see `warn` below, which
+ * #9754 made non-optional, so a double must now declare it).
  * Signatures mirror that contract exactly — notably `error(msg, Error, meta)`
  * versus `warn(msg, meta)` — so a host `Logger` is assignable as-is.
  */
 export interface IndexMigrationLogger {
     info?(message: string, meta?: Record<string, any>): void;
-    warn?(message: string, meta?: Record<string, any>): void;
+    /**
+     * The GUARANTEED fallback channel (#9754). `error` stays optional — hosts do
+     * inject reduced sinks — so `warn` is where a durability report lands when
+     * `error` is absent, and a fallback that may itself be missing is not a
+     * fallback. `logProblem` below is exactly that degrade, and until this member
+     * was required it could reach for two channels and find neither. Call sites
+     * keep the `logger?.warn?.(…)` spelling as the backstop for hosts the TYPE
+     * cannot reach; `SweepLogger` in plugin-email's `outbox-sweep.ts` carries the
+     * full reasoning and the measurement.
+     */
+    warn(message: string, meta?: Record<string, any>): void;
     error?(message: string, error?: Error, meta?: Record<string, any>): void;
 }
 

packages/plugins/plugin-approvals/src/lifecycle-hooks.ts

@@ -87,7 +87,15 @@ interface MinimalEngine {
 interface MinimalLogger {
   debug?: (msg: any, ...rest: any[]) => void;
   info?: (msg: any, ...rest: any[]) => void;
-  warn?: (msg: any, ...rest: any[]) => void;
+  /**
+   * The GUARANTEED fallback channel (#9754). `error` stays optional — hosts do
+   * inject reduced sinks — so `warn` is where a durability report lands when
+   * `error` is absent, and a fallback that may itself be missing is not a
+   * fallback. Call sites keep the `logger?.warn?.(…)` spelling as the backstop
+   * for hosts the TYPE cannot reach; `SweepLogger` in plugin-email's
+   * `outbox-sweep.ts` carries the full reasoning and the measurement.
+   */
+  warn: (msg: any, ...rest: any[]) => void;
   error?: (msg: any, ...rest: any[]) => void;
 }
 

packages/plugins/plugin-audit/src/auth-event-audit.test.ts

@@ -304,13 +304,20 @@ describe('[#8144] createAuthEventAuditSink writes a login row that names its act
         throw new Error('no such table: sys_audit_log');
       },
     };
-    const logger = { error: vi.fn(), debug: vi.fn() };
+    // `warn` is required by `AuthEventAuditLogger` (#9754/#10556): a sink that
+    // declares an optional `error` must be able to degrade. Present here AND
+    // asserted unused below, which pins the ORDER — `error` first, `warn` only
+    // as the fallback. Before the contract change this double was `{ error,
+    // debug }`, a shape the type accepted and the degrade path could not use.
+    const logger = { error: vi.fn(), warn: vi.fn(), debug: vi.fn() };
     const sink = createAuthEventAuditSink({ getEngine: () => broken, logger });
 
     await expect(sink.recordAuthEvent({ action: 'login', userId: 'usr_1' })).resolves.toBeUndefined();
     await sink.recordAuthEvent({ action: 'logout', userId: 'usr_1' });
 
     expect(logger.error).toHaveBeenCalledTimes(1);
+    // The fallback stays untouched while `error` exists.
+    expect(logger.warn).not.toHaveBeenCalled();
     const [msg] = logger.error.mock.calls[0];
     // The two things a durability `error` owes, in its first line.
     expect(String(msg)).toContain('INCOMPLETE');

packages/plugins/plugin-audit/src/auth-event-audit.ts

@@ -106,13 +106,19 @@ export interface AuthSessionAuditEvent {
 export interface AuthEventAuditLogger {
   error?(msg: string, err?: Error, meta?: Record<string, any>): void;
   /**
-   * The fallback channel for the durability report below. `error` is optional
-   * here, so a sink that has none must still have somewhere to put a lost audit
-   * row — reaching for `error` and finding nothing must degrade to `warn`,
-   * never to silence (#9657). Signature and optionality mirror
-   * `ReadAuditLogger` in `read-audit.ts`, which already declared it.
+   * The GUARANTEED fallback channel for the durability report below. `error` is
+   * optional here, so a sink that has none must still have somewhere to put a
+   * lost audit row — reaching for `error` and finding nothing must degrade to
+   * `warn`, never to silence (#9657).
+   *
+   * This is the sink #9754's body calls the sharpest instance: it declared
+   * `error?` and `debug?` and NO `warn` at all, so the call site below COULD NOT
+   * have been written correctly against the contract it was given. #9750 added
+   * `warn?`, which gave it something to reach for and still no guarantee it was
+   * there; non-optional (#9754) is what makes the silence unrepresentable.
+   * Signature and optionality mirror `ReadAuditLogger` in `read-audit.ts`.
    */
-  warn?(msg: string, meta?: Record<string, any>): void;
+  warn(msg: string, meta?: Record<string, any>): void;
   debug?(msg: string, meta?: Record<string, any>): void;
 }
 

packages/plugins/plugin-audit/src/read-audit.test.ts

@@ -314,10 +314,18 @@ describe('#8992 the write is OFF the request path', () => {
   it('a ledger write failure never reaches the read, and reports once at `error`', async () => {
     const errors: string[] = [];
     const debugs: string[] = [];
+    // Required by `ReadAuditLogger` (#9754/#10556) — and asserted unused below,
+    // so the double pins that `error` is reached for FIRST and `warn` is only
+    // the degrade path.
+    const warns: string[] = [];
     const writer = installReadAuditWriter(engine, {
       objects: ['contact'],
       timers: makeManualTimers(),
-      logger: { error: (m: string) => errors.push(m), debug: (m: string) => debugs.push(m) },
+      logger: {
+        error: (m: string) => errors.push(m),
+        warn: (m: string) => warns.push(m),
+        debug: (m: string) => debugs.push(m),
+      },
     })!;
     // Break the ledger AFTER install, so the probe has already run.
     (engine as any).insert = async () => { throw new Error('no such table: sys_audit_log'); };

packages/plugins/plugin-audit/src/read-audit.ts

@@ -112,7 +112,15 @@ export const READ_AUDIT_ACTION = 'read';
 /** Minimal logger surface — structurally the kernel `ctx.logger` (`ILogger`). */
 export interface ReadAuditLogger {
   error?(msg: string, err?: Error, meta?: Record<string, any>): void;
-  warn?(msg: string, meta?: Record<string, any>): void;
+  /**
+   * The GUARANTEED fallback channel (#9754). `error` stays optional — hosts do
+   * inject reduced sinks — so `warn` is where a durability report lands when
+   * `error` is absent, and a fallback that may itself be missing is not a
+   * fallback. Call sites keep the `logger?.warn?.(…)` spelling as the backstop
+   * for hosts the TYPE cannot reach; `SweepLogger` in plugin-email's
+   * `outbox-sweep.ts` carries the full reasoning and the measurement.
+   */
+  warn(msg: string, meta?: Record<string, any>): void;
   debug?(msg: string, meta?: Record<string, any>): void;
 }
 

packages/plugins/plugin-auth/src/auth-manager.ts

@@ -630,8 +630,20 @@ export interface AuthManagerOptions extends Partial<AuthConfig> {
    * Optional structured logger (the kernel `ctx.logger`) for best-effort
    * bookkeeping surfaces such as the ADR-0093 membership reconciler. Omitted →
    * those surfaces run silently (they already fail closed to no-op).
+   *
+   * The whole field stays OPTIONAL — omitting it is still a supported posture.
+   * What is no longer representable is supplying a logger that cannot carry a
+   * durability report: `warn` is non-optional because this value is FORWARDED
+   * verbatim into `ReconcileMembershipDeps.logger` (reconcile-membership.ts),
+   * whose sink guarantees that channel under #9754. Measured before tightening:
+   * the only non-test construction site in this repo is `auth-plugin.ts`, which
+   * passes `ctx.logger` — the kernel `Logger`, whose `warn` is already
+   * required — so the in-tree cost is zero. An external embedder handing
+   * `AuthManager` a reduced `{ info }` sink is the one caller this asks to
+   * change, and that is the point: it was the caller silently discarding the
+   * reconciler's reports (#10556).
    */
-  logger?: { info?: (msg: string, meta?: any) => void; warn?: (msg: string, meta?: any) => void };
+  logger?: { info?: (msg: string, meta?: any) => void; warn: (msg: string, meta?: any) => void };
 
   /**
    * ADR-0069 D2 — account lockout (anti-brute-force). After this many