@@ -0,0 +1,41 @@
+---
+"@objectstack/lint": patch
+"@objectstack/cli": patch
+---
+
+fix(lint): a hook write-set finding on a handler-authored hook reports `path: hooks[i].handler` — a key the author actually wrote — instead of the lowered `hooks[i].body.source` (#16546)
+
+`hook-api-update-readonly-field` / `hook-api-update-readonly-when-field`
+(`validate-readonly-hook-writes.ts`) and `hook-body-write-unknown-field` /
+`hook-body-write-unprovisioned-anchor` / `hook-body-source-unparseable`
+(`validate-hook-body-writes.ts`) all report their `path` against `hook.body`,
+because that is the shape they parse. For a hook authored as an inline
+`handler: async (ctx) => { … }` (39 of 39 hooks in the reference app),
+`hooks[i].body` is not something the author wrote at all — `lowerCallables`
+mints it from the handler before `os build` / `os lint` hand the stack to
+these rules (#16095). The reported `path` therefore named a key that does not
+exist in the author's own source file; grepping for `body.source` there finds
+nothing.
+
+**What changed.** `lowerCallables` now records, per `lowerCallables()` call,
+which `hooks[*].handler` ref strings got their `body` minted this way (as
+opposed to a `body` the author wrote directly). The CLI's four lowering doors
+(`os build`, `os lint`, `os validate`, `os init`/`dev`'s scaffold validation)
+pass that set through `runAuthoringRules`'s `ctx.loweredHookRefs`, and the two
+hook write-set rules use it to redirect a finding on a lowered hook to
+`path: hooks[i].handler` — the key that replaced the function the author
+wrote — with a message suffix ("judged on the metadata body lowered from the
+inline handler") explaining why. A hook whose `body` the author wrote directly
+is unaffected: `path` stays `hooks[i].body.source`, unchanged.
+
+**No verdict changed.** Which hooks are flagged, at what severity, and why is
+untouched — #13653 and #4271 are unmoved by a word. Only the location a
+finding points at, and the wording explaining it, are different. `os build`
+and `os lint` continue to report the identical `path` and message for the
+same hook (#16095's "one implementation, both commands agree" — now including
+this).
+
+No `--json` field was added or removed: `path` and `message` keep their
+existing shape (string), and this is a within-type value correction for the
+one subclass whose old value could never be resolved against the author's
+source in the first place.
@@ -416,6 +416,10 @@ export default class Compile extends Command {
         normalized: authoringRuleUnionStack(normalized as Record<string, unknown>),
         parsed: authoringRuleUnionStack(result.data as Record<string, unknown>),
         sduiManifest: resolveSduiManifest(),
+        // [#16546] Ref strings, not hook indices — survive the union fold and
+        // the per-package re-slice below unchanged (see `LoweringResult.
+        // loweredHookRefs`'s header for why an index would not).
+        loweredHookRefs: lowering.loweredHookRefs,
       });
       const { errors: ruleErrors, advisories } = splitBySeverity(findings);
       ruleAdvisories = advisories;
@@ -489,6 +493,7 @@ export default class Compile extends Command {
             normalized: asStack,
             parsed: asStack,
             sduiManifest: resolveSduiManifest(),
+            loweredHookRefs: lowering.loweredHookRefs,
           }).filter((f) => !alreadyReported.has(findingKey(f)));
           for (const f of pkgFindings) alreadyReported.add(findingKey(f));
           const split = splitBySeverity(pkgFindings);
 
@@ -511,11 +511,15 @@ export function lintConfig(config: any, opts: LintConfigOptions = {}): LintIssue
   //     the family stays silent on it and `checkHookBodyLowering` is what
   //     reports it, so no verdict is ever given about a body that was not
   //     produced. Nothing here touches what `os build` accepts (#13838).
-  const { lowered } = lowerCallables(config as Record<string, unknown>);
+  const { lowered, loweredHookRefs } = lowerCallables(config as Record<string, unknown>);
   for (const f of runAuthoringRules('lint', {
     normalized: config,
     parsed: lowered,
     sduiManifest: opts.sduiManifest,
+    // [#16546] Same ref set `os build` computes from the same normalized
+    // input — what lets `validateReadonlyHookWrites` / `validateHookBodyWrites`
+    // report `hooks[i].handler` here byte-identically to `os build`.
+    loweredHookRefs,
   })) {
     issues.push({
       severity: f.severity === 'info' ? 'suggestion' : f.severity,
 
@@ -260,8 +260,8 @@ export default class Validate extends Command {
       //     own contract decision (`compile.ts` records why the key is
       //     build's alone). No step line is printed either: the text face is
       //     byte-for-byte what it was, and the docs transcripts stay true.
-      const { lowered } = lowerCallables(normalized as Record<string, unknown>);
-      const result = ObjectStackDefinitionSchema.safeParse(lowered);
+      const lowering = lowerCallables(normalized as Record<string, unknown>);
+      const result = ObjectStackDefinitionSchema.safeParse(lowering.lowered);
 
       if (!result.success) {
         if (flags.json) {
@@ -304,6 +304,9 @@ export default class Validate extends Command {
         normalized: normalized as Record<string, unknown>,
         parsed: result.data as Record<string, unknown>,
         sduiManifest: resolveSduiManifest(),
+        // [#16546] Same ref set `os build` / `os lint` compute — keeps this
+        // door's hook write-set findings at the same `path` as the other two.
+        loweredHookRefs: lowering.loweredHookRefs,
       });
       const { errors: ruleErrors, advisories } = splitBySeverity(findings);
       ruleAdvisories = advisories;
 
@@ -59,6 +59,29 @@ export interface LoweringResult {
   bodyExtracted: number;
   /** Per-extraction failures (still emit handler ref + bundle, but warn). */
   bodyExtractionWarnings: BodyExtractionWarning[];
+  /**
+   * [#16546] The `hooks[*].handler` ref strings whose `body` was minted HERE
+   * — extracted from the author's inline `handler` function — as opposed to a
+   * `body` the author wrote directly. A ref lands here if and only if this
+   * call set `hook.body`, so the set is empty whenever every hook already
+   * carried its own `body`.
+   *
+   * A ref, not a hook index: `register`'s `taken`/`refByFn` maps are shared
+   * across the whole walk (top level AND every ADR-0130 D4 package body, see
+   * `lowerBody`'s header), so a ref is unique for this whole call and
+   * survives unchanged through a Zod parse (`handler` is an ordinary
+   * string field) — an index would not: `authoringRuleUnionStack` folds
+   * package hooks into a new top-level array with its OWN numbering, and a
+   * hook index recorded against this call's `hooks[i]` would silently
+   * address a different hook once folded.
+   *
+   * Consumed by `validateReadonlyHookWrites` / `validateHookBodyWrites`
+   * (`@objectstack/lint`) via `AuthoringRuleContext.loweredHookRefs`, to
+   * report `path: hooks[i].handler` — a key that exists in the author's
+   * source — instead of `hooks[i].body.source`, a key this function minted
+   * and the author never wrote.
+   */
+  loweredHookRefs: ReadonlySet<string>;
 }
 
 type AnyFn = (...args: unknown[]) => unknown;
@@ -83,6 +106,7 @@ export function lowerCallables(input: Record<string, unknown>): LoweringResult {
   const functions: Record<string, AnyFn> = {};
   const taken = new Set<string>();
   const warnings: BodyExtractionWarning[] = [];
+  const loweredHookRefs = new Set<string>();
   let bodyExtracted = 0;
 
   // Try to extract a metadata-only body from a callable. Returns null if the
@@ -170,7 +194,12 @@ export function lowerCallables(input: Record<string, unknown>): LoweringResult {
           // Extract metadata body unless the user already provided one.
           if (!hook.body) {
             const body = tryExtractBody(hook.handler as AnyFn, `hook '${name}'`);
-            if (body) hook.body = body;
+            if (body) {
+              hook.body = body;
+              // [#16546] This ref's `body` was minted here, not authored — the
+              // marker the two hook write-set rules redirect their `path` on.
+              loweredHookRefs.add(ref);
+            }
           }
           hook.handler = ref;
         }
@@ -296,6 +325,7 @@ export function lowerCallables(input: Record<string, unknown>): LoweringResult {
     count: Object.keys(functions).length,
     bodyExtracted,
     bodyExtractionWarnings: warnings,
+    loweredHookRefs,
   };
 }
 
 
@@ -88,6 +88,9 @@ export function runScaffoldAuthoringRules(config: unknown): ScaffoldRuleReport {
     normalized: normalized as Record<string, unknown>,
     parsed: result.data as Record<string, unknown>,
     sduiManifest: resolveSduiManifest(),
+    // [#16546] Same ref set the other three doors compute — keeps this
+    // door's hook write-set findings at the same `path` as they are.
+    loweredHookRefs: lowering.loweredHookRefs,
   });
   const { errors, advisories } = splitBySeverity(findings);
 
 
@@ -78,16 +78,25 @@ describe('#16095 — INTAKE: a handler-authored hook reaches the readonly family
     expect(findings).toHaveLength(1);
     expect(findings[0].severity).toBe('error');
     expect(findings[0].message).toContain('is_escalated');
-    // The finding is reported on the LOWERED body — the same path `os build`
-    // reports it on for the same hook, so the two commands agree word for word.
-    expect(findings[0].path).toBe('hooks[0].body.source');
+    // [#16546] `body.source` is a key this author never wrote — the body was
+    // MINTED here from their inline `handler`, so the finding points at the
+    // key they actually wrote instead, with a suffix saying why. `os build`
+    // reports the identical `path` and message suffix for the same hook (see
+    // the e2e sibling's parity assertion), so the two commands still agree
+    // word for word — just no longer on the wrong word.
+    expect(findings[0].path).toBe('hooks[0].handler');
+    expect(findings[0].message).toContain('judged on the metadata body lowered from the inline handler');
   });
 
-  it('CONTROL — the identical statement as an explicit `body` fires the same finding', () => {
+  it('CONTROL — the identical statement as an explicit `body` fires the same finding, path UNCHANGED', () => {
+    // [#16546] Non-regression control: this hook's `body` is author-written,
+    // not lowered from a `handler` — `hooks[0].body.source` names a key that
+    // is really there, and the fix must never move it.
     const findings = rulesOf(bodyHook('escalate', WRITE_READONLY_SOURCE), READONLY_RULE);
     expect(findings).toHaveLength(1);
     expect(findings[0].severity).toBe('error');
     expect(findings[0].path).toBe('hooks[0].body.source');
+    expect(findings[0].message).not.toContain('judged on the metadata body lowered from the inline handler');
   });
 
   it('RED — `hook-api-update-readonly-when-field` (warning) fires on an inline handler too', () => {
@@ -99,6 +108,8 @@ describe('#16095 — INTAKE: a handler-authored hook reaches the readonly family
     );
     expect(findings).toHaveLength(1);
     expect(findings[0].severity).toBe('warning');
+    // [#16546] Same fix, this rule's other finding id.
+    expect(findings[0].path).toBe('hooks[0].handler');
   });
 
   it('RED — `hook-body-write-unknown-field` fires on an inline handler writing an undeclared field', () => {
@@ -111,6 +122,9 @@ describe('#16095 — INTAKE: a handler-authored hook reaches the readonly family
     expect(findings).toHaveLength(1);
     expect(findings[0].severity).toBe('warning');
     expect(findings[0].message).toContain('is_escalatd');
+    // [#16546] The sibling validator (`validate-hook-body-writes.ts`) gets the
+    // same fix — same `ctx.loweredHookRefs`, same shared `hookBodyFindingLocation`.
+    expect(findings[0].path).toBe('hooks[0].handler');
   });
 });
 
@@ -227,16 +241,21 @@ describe('#16095 — door: `runScaffoldAuthoringRules` (reached, and not one of
   };
 
   it('INTAKE — the handler-authored hook IS judged here (it lowers before it parses)', () => {
-    expect(
-      familyOf(
-        handlerHook('escalate', async (ctx: any) => {
-          await ctx.api.object('crm_case').update({ id: ctx.input.id, is_escalated: true });
-        }),
-      ),
-    ).toHaveLength(1);
+    const findings = familyOf(
+      handlerHook('escalate', async (ctx: any) => {
+        await ctx.api.object('crm_case').update({ id: ctx.input.id, is_escalated: true });
+      }),
+    );
+    expect(findings).toHaveLength(1);
+    // [#16546] This door also gets `ctx.loweredHookRefs` (`scaffold-validate.ts`
+    // hands it through the same as `os build` / `os lint` do), so it must not
+    // be the one door still pointing at the un-authored `body.source` key.
+    expect(findings[0].path).toBe('hooks[0].handler');
   });
 
-  it('CONTROL — the identical statement as an explicit `body` fires the same finding', () => {
-    expect(familyOf(bodyHook('escalate_body', WRITE_READONLY_SOURCE))).toHaveLength(1);
+  it('CONTROL — the identical statement as an explicit `body` fires the same finding, path UNCHANGED', () => {
+    const findings = familyOf(bodyHook('escalate_body', WRITE_READONLY_SOURCE));
+    expect(findings).toHaveLength(1);
+    expect(findings[0].path).toBe('hooks[0].body.source');
   });
 });
@@ -101,6 +101,47 @@ describe('lowerCallables', () => {
     });
     expect(out.bodyExtracted).toBe(1);
     expect((out.lowered.hooks as any[])[0].body).toBeDefined();
+    // [#16546] The ref this hook was minted under (its own name here, no
+    // collision) is recorded as body-from-handler — what the two hook
+    // write-set rules read to redirect their finding's `path`.
+    expect((out.lowered.hooks as any[])[0].handler).toBe('contained_hook');
+    expect(out.loweredHookRefs.has('contained_hook')).toBe(true);
+    expect(out.loweredHookRefs.size).toBe(1);
+  });
+
+  it('[#16546] does NOT mark the ref when body extraction fails — no body was minted to misreport', () => {
+    const handler = (ctx: any) => {
+      ctx.record.slug = moduleHelper(ctx.record.name);
+    };
+    const out = lowerCallables({
+      hooks: [{ name: 'slugify_hook_2', handler, events: ['beforeInsert'], object: 'doc' }],
+    });
+    expect(out.bodyExtracted).toBe(0);
+    expect(out.loweredHookRefs.size).toBe(0);
+  });
+
+  it('[#16546] does NOT mark the ref when the hook already carries an author-written `body`', () => {
+    // `lowerCallables` never extracts over an existing `body` (`if (!hook.body)`)
+    // — the `handler` is still lowered to a ref for bundling, but the body
+    // judged by the write-set rules is the one the author wrote, so its `path`
+    // must stay `body.source`.
+    const handler = (ctx: any) => {
+      ctx.record.id = Math.round(Number(ctx.record.raw));
+    };
+    const out = lowerCallables({
+      hooks: [
+        {
+          name: 'authored_body_hook',
+          handler,
+          events: ['beforeInsert'],
+          object: 'doc',
+          body: { language: 'js', source: 'ctx.record.id = 1;' },
+        },
+      ],
+    });
+    expect((out.lowered.hooks as any[])[0].handler).toBe('authored_body_hook');
+    expect((out.lowered.hooks as any[])[0].body).toEqual({ language: 'js', source: 'ctx.record.id = 1;' });
+    expect(out.loweredHookRefs.size).toBe(0);
   });
 
   it('produces a JSON-serializable lowered shape', () => {
 
@@ -299,6 +299,22 @@ export interface AuthoringRuleContext {
    * argument.
    */
   runtimeWriteType?: string;
+  /**
+   * [#16546] `hooks[*].handler` ref strings whose metadata `body` was minted
+   * by `lowerCallables` from the author's inline `handler` function, rather
+   * than authored directly. Set by the CLI commands that lower before they
+   * run this registry (`os build`, `os lint`, `os validate`, scaffold
+   * validate — `lowerCallables`'s own return value, unchanged); ABSENT on the
+   * runtime publish gate, which never receives a `handler` function to lower.
+   *
+   * Read by `validateReadonlyHookWrites` / `validateHookBodyWrites`
+   * (`@objectstack/lint`) through the reference-integrity suite, to report
+   * `path: hooks[i].handler` — the key the author actually wrote — instead of
+   * `hooks[i].body.source`, a key this stack's `body` did not come from the
+   * author for. Absent or not naming a hook's ref means "this hook's `body`
+   * is author-written", and both validators keep reporting `body.source`.
+   */
+  loweredHookRefs?: ReadonlySet<string>;
 }
 
 export interface AuthoringRule {
@@ -1623,7 +1639,7 @@ export function authoringRulesFor(command: AuthoringCommand): readonly Authoring
  */
 export function runAuthoringRules(command: AuthoringCommand, run: AuthoringRuleRun): AuthoringFinding[] {
   const findings: AuthoringFinding[] = [];
-  const ctx: AuthoringRuleContext = { sduiManifest: run.sduiManifest };
+  const ctx: AuthoringRuleContext = { sduiManifest: run.sduiManifest, loweredHookRefs: run.loweredHookRefs };
   for (const rule of authoringRulesFor(command)) {
     const stack = rule.input === 'normalized' ? run.normalized : (run.parsed ?? run.normalized);
     findings.push(...rule.run(stack, ctx));