feat(spec): warnGenericPasswordFields reads its exemption from the masked-on-read declaration

ObjectSchema.create()'s author-time password warning no longer hard-codes
managedBy 'better-auth'; it warns exactly where isMaskedOnReadFieldType
('password', managedBy) says the read mask applies. Behaviour unchanged
(same warn/no-warn per managedBy x field-shape row). A pin in object.test.ts
ties the warning to the declaration. Comments no longer say objectui derives
from the declaration today: it keeps its interim copy until its re-bind card.

Claude-Session: https://claude.ai/code/session_01CiCTczDo7tGhafXjf61dUJ
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.changeset/20141-masked-on-read-field-types-declared.md

@@ -27,6 +27,8 @@ carrying their own `type === 'secret'` / `'password'` arms. No behaviour
 change: the masked-on-read answer is identical for every `FieldType` ×
 `managedBy` cell, pinned by a table test.
 
+`@objectstack/spec`: `ObjectSchema.create()`'s author-time warning for a `password` field on a non-auth object now reads its `managedBy` exemption from `isMaskedOnReadFieldType` instead of hard-coding `'better-auth'`, so it follows the declaration; which objects and fields warn is unchanged.
+
 A client that renders credential fields (show the mask, offer no copy) should
 derive its set from `isMaskedOnReadFieldType` rather than keep its own list,
 so the server's mask and the client's cannot drift apart.

packages/objectql/src/secret-fields.test.ts

@@ -679,9 +679,10 @@ describe('objectql aggregate() rejects credential fields (ADR-0100 / #3171)', ()
  *    this red and be read.
  *  - **The agreement.** For every cell, the runtime collectors and the spec
  *    predicate give the same answer. This is what goes red when the runtime
- *    grows its own copy again (a `def.type === …` arm) instead of deriving:
- *    the renderer derives from the spec too, so a runtime-only answer is a
- *    field masked by the server and drawn in clear by the client.
+ *    grows its own copy again (a `def.type === …` arm) instead of deriving.
+ *    objectui keeps an interim copy until its re-bind card points it at the
+ *    same declaration; from then on a runtime-only answer is a field masked
+ *    by the server and drawn in clear by the client.
  */
 describe('[#20141] masked-on-read: every FieldType × managedBy cell, derived from the spec declaration', () => {
   const FIELD_TYPES: readonly string[] = FieldType.options;

packages/objectql/src/secret-fields.ts

@@ -164,10 +164,12 @@ export class EmptyCredentialWriteError extends Error {
  * types are masked, and which `managedBy` buckets exempt which type, is declared
  * once in `@objectstack/spec/data` (`MASKED_ON_READ_FIELD_TYPES`, read through
  * `isMaskedOnReadFieldType`), and this collector asks that predicate per field.
- * objectui's renderer derives from the same declaration, so the server's mask
+ * objectui keeps its interim `MASKED_FIELD_TYPES` copy until its own re-bind
+ * card lands; after that it reads this same declaration, and the server's mask
  * and the client's cannot drift apart. ⛔ Do not add a `def.type === …` arm
- * here: a type masked here and not in the declaration is drawn in clear by the
- * renderer. Change the declaration instead; the table test in
+ * here: a type masked here and not in the declaration is a second copy, and
+ * once the renderer derives it is a field masked by the server and drawn in
+ * clear by the client. Change the declaration instead; the table test in
  * `secret-fields.test.ts` pins every `FieldType × managedBy` answer.
  *
  * The better-auth exemption is deliberate: the auth subsystem reads its identity

packages/spec/src/data/index.ts

@@ -137,9 +137,10 @@ export * from './field.zod';
 // settings REST path.
 export * from './secret-mask';
 // Which field types are masked on read (ADR-0100) — one per-type rule table,
-// `managedBy` exemption included, read through one predicate. objectql's
-// `collectMaskedReadFields` and objectui's renderer derive from it instead of
-// each owning a hand-written copy (#20141).
+// `managedBy` exemption included, read through one predicate (#20141). objectql's
+// `collectMaskedReadFields` and `ObjectSchema.create()`'s password warning derive
+// from it; objectui keeps its interim `MASKED_FIELD_TYPES` copy until its own
+// re-bind card lands, and derives from it after that.
 export * from './masked-field-types';
 // The unknown-authoring-key lint's CORE — comparator, finding shape, curated
 // guidance tables (#3786). Kept frontend-safe: the stack WALKER that imports

packages/spec/src/data/masked-field-types.ts

@@ -28,7 +28,10 @@
  * which must not draw a masked value in clear or offer to copy it). A type
  * added to one copy and not the other is masked by the server and drawn in
  * clear by the client, or the reverse. `spec` is the contract both already
- * depend on, so the fact is declared here and both derive from it.
+ * depend on, so the fact is declared here. objectql's collectors and
+ * `ObjectSchema.create()`'s `password` warning derive from it now; objectui
+ * keeps its interim `MASKED_FIELD_TYPES` until its own re-bind card lands, and
+ * that card points it at {@link isMaskedOnReadFieldType}.
  *
  * # Shape — a per-type rule, read through one predicate
  *

packages/spec/src/data/object.test.ts

@@ -11,6 +11,7 @@ import { resolveInjectedSystemColumns } from './injected-system-columns';
 import { projectPublishedJsonSchema } from '../../scripts/lib/refinement-projection';
 import { collectDroppedRefinements } from '../../scripts/lib/dropped-refinements';
 import { Field } from './field.zod';
+import { isMaskedOnReadFieldType } from './masked-field-types';
 import type { StateMachineValidation } from './validation.zod';
 
 describe('ObjectCapabilities', () => {
@@ -2459,6 +2460,38 @@ describe('ObjectSchema.create() password-field author warning (ADR-0100)', () =>
     const msg = warn.mock.calls[0]?.[0] as string;
     expect(msg).toContain('ackPlaintextMasking');
   });
+
+  // [#20141] The warning's exemption is the masked-on-read declaration's, not a
+  // second copy: for every `managedBy` bucket (and none), an un-acknowledged
+  // `password` field warns exactly when `isMaskedOnReadFieldType('password', …)`
+  // says the read mask applies. If `MASKED_ON_READ_FIELD_TYPES.password
+  // .exemptManagedBy` changes, this stays green only because the warning follows;
+  // a warning that hard-codes its own bucket goes red here.
+  describe('[#20141] the exemption is read from MASKED_ON_READ_FIELD_TYPES', () => {
+    const buckets = (
+      ObjectSchema.shape.managedBy as unknown as { unwrap(): { options: readonly string[] } }
+    ).unwrap().options;
+    const PW_WARNING = "use type 'password' on a non-auth object";
+    const warnsFor = (managedBy: string | undefined): boolean => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      ObjectSchema.create({
+        name: `adr0100_decl_${(managedBy ?? 'absent').replace(/-/g, '_')}`,
+        ...(managedBy === undefined ? {} : { managedBy: managedBy as never }),
+        fields: { pw: { type: 'password' } },
+      });
+      const fired = warn.mock.calls.some((c) => String(c[0]).includes(PW_WARNING));
+      warn.mockRestore();
+      return fired;
+    };
+
+    it('warns on exactly the buckets where the declaration masks password (the agreement)', () => {
+      expect(buckets.length).toBeGreaterThan(1); // the enum really was read
+      for (const managedBy of [undefined, ...buckets]) {
+        expect(warnsFor(managedBy), `managedBy ${managedBy ?? '(absent)'}`)
+          .toBe(isMaskedOnReadFieldType('password', managedBy));
+      }
+    });
+  });
 });
 
 // ---------------------------------------------------------------------------

packages/spec/src/data/object.zod.ts

@@ -18,6 +18,10 @@ import { retiredKey } from '../shared/retired-key';
 import { refuseRecordProtoKey } from '../shared/record-proto-key-guard';
 import { bannedKeys } from '../shared/refinement-projection';
 import { FIELD_GROUP_KEY_PATTERN } from './field-group-layout';
+// The masked-on-read declaration (#20141); `warnGenericPasswordFields` reads its
+// `password` exemption rather than restating it. No runtime cycle: that module's
+// only imports are type-only.
+import { isMaskedOnReadFieldType } from './masked-field-types';
 export const ApiMethod = z.enum([
   'get', 'list',                // Read
   'create', 'update', 'delete', // Write
@@ -2574,17 +2578,26 @@ const warnedPasswordObjects = new Set<string>();
  * A warning, not an error: `password` now has a defined generic-path contract,
  * and the field-zoo example intentionally exercises every field type — a hard
  * error would be self-inflicted breakage. Deduped per object name so a schema
- * imported many times warns once. `managedBy: 'better-auth'` objects are exempt,
- * as are fields that opt in with `ackPlaintextMasking: true` — the author's
- * explicit "this is intended" acknowledgment (#3420), which lets a deliberate
- * demo/design (e.g. the showcase field-zoo) start with zero warnings.
+ * imported many times warns once. Objects whose `managedBy` exempts `password`
+ * from the read mask are exempt (today `better-auth`), as are fields that opt in
+ * with `ackPlaintextMasking: true` — the author's explicit "this is intended"
+ * acknowledgment (#3420), which lets a deliberate demo/design (e.g. the showcase
+ * field-zoo) start with zero warnings.
+ *
+ * [#20141] The exemption is READ from the masked-on-read declaration
+ * (`MASKED_ON_READ_FIELD_TYPES`, via `isMaskedOnReadFieldType`), never restated:
+ * the warning describes a `password` that is masked on read yet plaintext at
+ * rest, so it fires exactly where the read mask applies to `password`. If that
+ * declaration's `exemptManagedBy` changes, this warning follows it. ⛔ Not
+ * widened to `secret` — a `secret` is encrypted at rest, which is the whole
+ * point of steering authors to it.
  */
 function warnGenericPasswordFields(
   objectName: unknown,
   fields: unknown,
   managedBy: unknown,
 ): void {
-  if (managedBy === 'better-auth') return;
+  if (!isMaskedOnReadFieldType('password', managedBy)) return;
   if (!fields || typeof fields !== 'object') return;
   const passwordFields = Object.entries(
     fields as Record<string, { type?: string; ackPlaintextMasking?: boolean }>,