test(dev): zero-warning-boot regression guards + registry log-level env seam (#3420)

Follow-ups so the startup log stays at zero warnings and the debug output is
discoverable:

1. Regression guards for all three noise sources:
   - password: examples assert every generic (non-better-auth) `password` field
     affirms `ackPlaintextMasking` (showcase no-startup-warnings.test.ts; crm
     smoke.test.ts — future-proofs an example with none today).
   - better-auth: auth-manager.mcp-oauth.test.ts asserts oauthProvider is wired
     with `silenceWarnings.oauthAuthServerConfig: true`.
   - registry: registry-log-level.test.ts asserts the re-register / package-
     overwrite lines are silent at the default `info` level and only emit via
     console.debug at `debug` (never console.warn).

2. Other examples: verified only showcase declared a generic password field; the
   better-auth and registry fixes are framework-level so crm/todo inherit them.
   crm now carries the same password guard. (todo ships no password fields and
   uses the custom `objectstack test` runner, so no vitest guard is added there.)

3. better-auth double-print root cause: the notice fires in oauth-provider's
   `init(ctx)`, run once per betterAuth() construction; auth is (re)built more
   than once at boot (initial lazy build, then a rebuild after boot-time auth
   settings apply — applyConfigPatch nulls the cached instance). silenceWarnings
   gates the emitter itself, so it is covered on every build path. Corrected the
   inaccurate inline comment accordingly.

4. Registry debug discoverability: add a `logLevel` option to
   SchemaRegistryOptions resolved from `OS_REGISTRY_LOG` (unknown → info), so a
   developer can surface the debug-gated housekeeping with OS_REGISTRY_LOG=debug.

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

Author: claude

examples/app-crm/test/smoke.test.ts

@@ -95,6 +95,23 @@ describe('app-crm minimal metadata bundle', () => {
     expect(rules.some((r) => r.type === 'owner')).toBe(true);
   });
 
+  // #3420 — official examples must boot warning-free. A generic (non-better-auth)
+  // `password` field trips the ADR-0100 author-time warning unless it affirms
+  // intent with `ackPlaintextMasking: true`. crm ships none today; this guard
+  // fails loudly if one is ever added without the acknowledgment.
+  it('has no un-acknowledged generic password fields (#3420)', () => {
+    const offenders: string[] = [];
+    for (const obj of (stack.objects ?? []) as any[]) {
+      if (obj?.managedBy === 'better-auth') continue;
+      for (const [fieldName, def] of Object.entries((obj?.fields ?? {}) as Record<string, any>)) {
+        if (def?.type === 'password' && def?.ackPlaintextMasking !== true) {
+          offenders.push(`${obj.name}.${fieldName}`);
+        }
+      }
+    }
+    expect(offenders, `un-acknowledged generic password field(s): ${offenders.join(', ')}`).toEqual([]);
+  });
+
 });
 
 describe('Pipeline dashboard', () => {

examples/app-showcase/test/no-startup-warnings.test.ts

@@ -0,0 +1,33 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect } from 'vitest';
+import stack from '../objectstack.config.js';
+
+/**
+ * #3420 — the official examples must boot with ZERO warnings so users don't get
+ * trained to ignore them. A generic (non-`better-auth`) `password` field trips a
+ * non-fatal `ObjectSchema.create()` warning at author time (ADR-0100: plaintext
+ * at rest, masked on read); the documented way to affirm intent is
+ * `ackPlaintextMasking: true`. This guard fails if a new or edited object
+ * reintroduces an un-acknowledged generic password field — keeping the showcase
+ * boot log clean without silencing the diagnostic for real authors.
+ *
+ * The other two boot-noise sources from #3420 are framework-level and guarded in
+ * their own packages: the better-auth `oauthAuthServerConfig` false positive
+ * (@objectstack/plugin-auth auth-manager.mcp-oauth.test.ts) and the registry
+ * re-register lines (@objectstack/objectql registry-log-level.test.ts).
+ */
+describe('showcase boots without ADR-0100 password warnings (#3420)', () => {
+  it('every generic password field affirms ackPlaintextMasking', () => {
+    const offenders: string[] = [];
+    for (const obj of (stack.objects ?? []) as any[]) {
+      if (obj?.managedBy === 'better-auth') continue;
+      for (const [fieldName, def] of Object.entries((obj?.fields ?? {}) as Record<string, any>)) {
+        if (def?.type === 'password' && def?.ackPlaintextMasking !== true) {
+          offenders.push(`${obj.name}.${fieldName}`);
+        }
+      }
+    }
+    expect(offenders, `un-acknowledged generic password field(s): ${offenders.join(', ')}`).toEqual([]);
+  });
+});

packages/objectql/src/registry-log-level.test.ts

@@ -0,0 +1,77 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { SchemaRegistry, REGISTRY_LOG_LEVELS } from './registry';
+
+/**
+ * #3420 — the registry's expected-but-noisy housekeeping (re-registering an
+ * owned object, overwriting a package manifest on a rebuild / HMR / multi-project
+ * seed-replay) must NOT reach a stock `os dev` boot log. It used to be emitted
+ * via `console.warn` (always on) and looked like an error, though it is a normal
+ * path. It is now emitted at `debug`, so it stays out of the default `info` level
+ * but `OS_REGISTRY_LOG=debug` (or `{ logLevel: 'debug' }`) makes it discoverable.
+ *
+ * This is the regression guard: if either line ever regresses back to `warn`
+ * (or to the always-on `log`/`console.log`), the "silent at info" assertions
+ * fail — keeping the official examples' boot log clean.
+ */
+describe('SchemaRegistry log-level gating (#3420)', () => {
+  const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  const debug = vi.spyOn(console, 'debug').mockImplementation(() => {});
+  beforeEach(() => { warn.mockClear(); debug.mockClear(); });
+  afterEach(() => { delete process.env.OS_REGISTRY_LOG; });
+
+  const reRegisterSameOwner = (r: SchemaRegistry) => {
+    r.registerObject({ name: 'sys_thing', fields: {} } as any, 'com.acme.app', 'sys', 'own');
+    r.registerObject({ name: 'sys_thing', fields: {} } as any, 'com.acme.app', 'sys', 'own');
+  };
+
+  it('at the default (info) level, re-registering an owned object is silent — no warn, no debug', () => {
+    const r = new SchemaRegistry({ multiTenant: false });
+    reRegisterSameOwner(r);
+    expect(warn).not.toHaveBeenCalledWith(expect.stringContaining('Re-registering owned object'));
+    expect(debug).not.toHaveBeenCalledWith(expect.stringContaining('Re-registering owned object'));
+  });
+
+  it('at debug level, the re-register line is emitted via console.debug (never console.warn)', () => {
+    const r = new SchemaRegistry({ multiTenant: false, logLevel: 'debug' });
+    reRegisterSameOwner(r);
+    expect(debug).toHaveBeenCalledWith(expect.stringContaining('Re-registering owned object: sys_thing'));
+    expect(warn).not.toHaveBeenCalledWith(expect.stringContaining('Re-registering owned object'));
+  });
+
+  it('overwriting a package manifest is debug-gated the same way', () => {
+    const manifest = { id: 'com.test', name: 'Test', namespace: 'test', version: '1.0.0' } as any;
+
+    const info = new SchemaRegistry({ multiTenant: false });
+    info.installPackage(manifest);
+    info.installPackage(manifest); // same-package reload → "Overwriting package"
+    expect(warn).not.toHaveBeenCalledWith(expect.stringContaining('Overwriting package'));
+    expect(debug).not.toHaveBeenCalledWith(expect.stringContaining('Overwriting package'));
+
+    debug.mockClear();
+    const dbg = new SchemaRegistry({ multiTenant: false, logLevel: 'debug' });
+    dbg.installPackage(manifest);
+    dbg.installPackage(manifest);
+    expect(debug).toHaveBeenCalledWith(expect.stringContaining('Overwriting package: com.test'));
+  });
+
+  it('resolves the level from OS_REGISTRY_LOG when no explicit option is given', () => {
+    process.env.OS_REGISTRY_LOG = 'debug';
+    expect(new SchemaRegistry({ multiTenant: false }).logLevel).toBe('debug');
+  });
+
+  it('falls back to info for an unrecognized OS_REGISTRY_LOG value', () => {
+    process.env.OS_REGISTRY_LOG = 'chatty';
+    expect(new SchemaRegistry({ multiTenant: false }).logLevel).toBe('info');
+  });
+
+  it('an explicit logLevel option wins over the env var', () => {
+    process.env.OS_REGISTRY_LOG = 'debug';
+    expect(new SchemaRegistry({ multiTenant: false, logLevel: 'silent' }).logLevel).toBe('silent');
+  });
+
+  it('exposes the full level vocabulary for validation', () => {
+    expect(REGISTRY_LOG_LEVELS).toEqual(['debug', 'info', 'warn', 'error', 'silent']);
+  });
+});

packages/objectql/src/registry.ts

@@ -121,6 +121,11 @@ function mergeObjectDefinitions(base: ServiceObject, extension: Partial<ServiceO
  */
 export type RegistryLogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
 
+/** All valid {@link RegistryLogLevel} values — used to validate `OS_REGISTRY_LOG`. */
+export const REGISTRY_LOG_LEVELS: readonly RegistryLogLevel[] = [
+  'debug', 'info', 'warn', 'error', 'silent',
+];
+
 /**
  * Construction options for {@link SchemaRegistry}.
  */
@@ -172,6 +177,19 @@ export interface SchemaRegistryOptions {
    * package ids are always disambiguable by package-scoped resolution.)
    */
   collisionPolicy?: 'error' | 'warn';
+
+  /**
+   * Verbosity of the registry's own `[Registry] …` log lines. Sourced from the
+   * `OS_REGISTRY_LOG` env var when not set explicitly (default `'info'`).
+   *
+   * The point of the env seam is discoverability (#3420): expected-but-noisy
+   * housekeeping — re-registering an owned object / overwriting a package
+   * manifest on a rebuild/HMR/seed-replay — is emitted at `'debug'`, so it stays
+   * out of a stock `info` boot log but a developer chasing a registration issue
+   * can surface it with `OS_REGISTRY_LOG=debug`. An unrecognized value falls
+   * back to `'info'`.
+   */
+  logLevel?: RegistryLogLevel;
 }
 
 /**
@@ -529,6 +547,16 @@ export class SchemaRegistry {
     this.collisionPolicy =
       options.collisionPolicy ??
       ((process.env.OS_METADATA_COLLISION ?? '').toLowerCase() === 'warn' ? 'warn' : 'error');
+
+    // #3420 — env-driven verbosity so debug-level registry housekeeping
+    // (re-register / package overwrite) is discoverable without a code change.
+    // Unrecognized OS_REGISTRY_LOG values fall back to the 'info' default.
+    const envLevel = (process.env.OS_REGISTRY_LOG ?? '').toLowerCase();
+    this._logLevel =
+      options.logLevel ??
+      (REGISTRY_LOG_LEVELS.includes(envLevel as RegistryLogLevel)
+        ? (envLevel as RegistryLogLevel)
+        : this._logLevel);
   }
 
   get logLevel(): RegistryLogLevel { return this._logLevel; }

packages/plugins/plugin-auth/src/auth-manager.mcp-oauth.test.ts

@@ -302,6 +302,16 @@ describe('oauthProvider plugin wiring (DCR + scopes + audiences)', () => {
     expect(opts.validAudiences).toContain('https://acme.example.com/api/v1/auth');
   });
 
+  it('silences the false-positive oauthAuthServerConfig warning (#3420)', async () => {
+    // registerOidcDiscoveryRoutes mounts /.well-known/oauth-authorization-server
+    // (and the /api/v1/auth path-insertion variant) at the issuer ROOT ourselves,
+    // so better-auth's boot-time "Please ensure … exists" reminder is a false
+    // positive. It must be silenced via the documented option, or the stock
+    // showcase prints it (twice) on every `os dev`. Regression guard for the fix.
+    const opts = await capturePluginOpts({ OS_MCP_SERVER_ENABLED: 'true' });
+    expect(opts.silenceWarnings).toEqual({ oauthAuthServerConfig: true });
+  });
+
   it('OS_OIDC_DCR_ENABLED=false forces DCR off even with MCP on', async () => {
     const opts = await capturePluginOpts({ OS_MCP_SERVER_ENABLED: 'true', OS_OIDC_DCR_ENABLED: 'false' });
     expect(opts.allowDynamicClientRegistration).toBe(false);

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

@@ -1853,11 +1853,18 @@ export class AuthManager {
         // mount ourselves at the issuer ROOT (RFC 8414 §3 requires them there,
         // not under the auth basePath) — registerOidcDiscoveryRoutes serves
         // /.well-known/oauth-authorization-server AND the path-insertion variant
-        // (`…/api/v1/auth`) the notice names. Its boot-time "Please ensure …
-        // exists" reminder is therefore a false positive that fires on every
-        // stock example (twice — jwt+oauthProvider init runs it per instance);
-        // silence the one requirement we've already satisfied so an official
-        // dev boot stays warning-free (#3420).
+        // (`…/api/v1/auth`) the notice names. Its "Please ensure … exists"
+        // reminder is therefore a false positive on every stock example.
+        //
+        // #3420 root cause of the DOUBLE print: the notice fires in the
+        // oauth-provider plugin's `init(ctx)`, which better-auth runs once per
+        // `betterAuth()` construction — and the instance is built more than once
+        // at boot (an initial lazy build, then a rebuild once boot-time auth
+        // *settings* are applied — applyConfigPatch() nulls the cached instance
+        // so the next request rebuilds with the new policy). Gating the emitter
+        // here silences the one requirement we've already satisfied across every
+        // build path, independent of how many times auth is constructed, so an
+        // official dev boot stays warning-free.
         silenceWarnings: { oauthAuthServerConfig: true },
         // ── MCP OAuth track (#2698) ────────────────────────────────
         // Coarse tool-family scopes for the platform's own MCP endpoint,