fix(lint): judge a schema-bound metadata form at its own binding layer (#7815) (#8041)

The runtime publish gate calls `validateVisibilityPredicates(stack)` with no
options, so every view was judged at the `'runtime'` layer default — including
schema-bound metadata forms, which bind the row under edit as `data`. Correct
metadata therefore drew a `visibility-root-mislayered` advisory telling its
author to write `record.`, and `visibility-bare-identifier`'s hint prescribed
`record.<word>`, on a surface that binds no `record` at all.

The layer is now read off the metadata where the metadata states it: a form view
declaring `data: { provider: 'schema', schemaId }` is judged at `metadata`, and
every other site — a plain runtime view, every page component — still takes
`opts.layer`. Derived from the same `schemaIdOf` call that decides the #7696
right-hand-literal-slot stand-down, so the two cannot disagree about which
surface they are on.

The rule itself is unchanged; this is layer plumbing at the invocation side.
`visibility-root-mislayered` is `warning` in both directions, so acceptance is
untouched — measured as identical error sets across the 19-row controls corpus,
and pinned as a property in `runtime-gate.test.ts`.


Claude-Session: https://claude.ai/code/session_01WocN37om5bw81JDoEEMA2e

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

Author: os-zhuang

.changeset/visibility-layer-schema-bound-form.md

@@ -0,0 +1,36 @@
+---
+"@objectstack/lint": patch
+---
+
+fix(lint): judge a schema-bound metadata form at its own binding layer (#7815)
+
+At the runtime publish gate, `validateVisibilityPredicates` ran at its
+`'runtime'` layer default for **every** view, including schema-bound metadata
+forms (`data: { provider: 'schema', schemaId }`). Those forms bind the row under
+edit as `data`, so correct metadata drew a `visibility-root-mislayered` advisory
+telling its author to write `record.` — a root that surface binds nothing under —
+and `visibility-bare-identifier`'s hint prescribed `record.<word>` for the same
+reason. Nothing went red, which is how it survived: the gate was green, the
+advisory was simply wrong, and the only symptom was authors and AI authors being
+steered to the wrong root at the publish door.
+
+The layer is now read off the metadata where the metadata states it. A form view
+declaring `data: { provider: 'schema', schemaId }` is judged at `metadata`; every
+other site — a plain runtime view, every page component — still takes the
+caller's `opts.layer` (default `'runtime'`), so `os validate` / `compile` and any
+file-aware caller are unchanged. It is derived from the same `schemaIdOf` call
+that already decides the right-hand-literal-slot stand-down (#7696), so the two
+verdicts cannot disagree about which surface they are on.
+
+Three consequences on a schema-bound form, all advisory:
+
+- a correctly `data.`-rooted predicate no longer draws the mis-layer advisory;
+- a `record.`-rooted one now does, in ADR-0089 D3's other direction — that
+  predicate can never match, and this door was silent about it;
+- `visibility-bare-identifier` prescribes `data.<word>`, the root the surface
+  actually binds.
+
+`visibility-root-mislayered` is `warning` in both directions and no other rule's
+severity or firing condition moves, so **acceptance is untouched**: the same
+inputs are refused, with the same ids, at the same paths. That boundary is pinned
+as a property in `runtime-gate.test.ts` rather than left as a claim.

packages/lint/src/runtime-gate.test.ts

@@ -491,3 +491,95 @@ describe('the views[] visibility-predicate family at the runtime publish gate (#
     expect(sawAdvisory, 'the corpus must contain an advisory').toBe(true);
   });
 });
+
+// ─────────────────────────────────────────────────────────────────────
+// #7815 — the layer the gate judges a schema-bound form at.
+//
+// A separate block, added at the end rather than woven into the family suite
+// above (#7576 serialization): nothing in that suite is touched.
+// ─────────────────────────────────────────────────────────────────────
+
+describe('the publish gate judges a schema-bound form at its own layer (#7815)', () => {
+  it('a correctly `data.`-rooted form is SILENT — no advisory, no refusal', () => {
+    // The finding. `authoring-rules.ts` calls `validateVisibilityPredicates(stack)`
+    // with no options, so every view was judged at the `'runtime'` default and
+    // this exact body — correct metadata — came back with an advisory telling
+    // its author to write `record.`, on a surface that binds no `record` at all.
+    // Nothing went red then and nothing goes red now; the difference is only
+    // what the author is told, which is the whole harm of the class.
+    const result = gateView(schemaBoundForm("data.type == 'text'"));
+    expect(result.errors, JSON.stringify(result.errors)).toEqual([]);
+    expect(result.advisories, JSON.stringify(result.advisories)).toEqual([]);
+    // "clean" and "nothing ran" must stay distinguishable.
+    expect(result.rulesRun).toEqual([
+      'validateVisibilityPredicates',
+      'validatePredicatePathRefs',
+    ]);
+  });
+
+  it('the runtime view one fixture-line away still draws it — the rule is live', () => {
+    // The negative control. Standing an advisory down and going blind look
+    // identical from the inside, so the case above is only worth its ink beside
+    // one that still fires: same predicate root, same gate, opposite verdict,
+    // decided by the `data:` source alone.
+    const f = gateView(runtimeView("data.status == 'open'"))
+      .advisories.find((a) => a.rule === 'visibility-root-mislayered');
+    expect(f, 'a wrong-layer paste on a RUNTIME view is still a wrong-layer paste').toBeDefined();
+    expect(f!.severity).toBe('warning');
+  });
+
+  it('a `record.`-rooted form now draws the advisory the OTHER way', () => {
+    // ADR-0089 D3's second direction, unreachable at this door until now: told
+    // `'runtime'`, the rule forbids `data.` and has nothing to say about
+    // `record.`, so a form predicate that can never match published in silence.
+    // Not new behaviour — the rule's existing metadata arm, finally addressed.
+    const result = gateView(schemaBoundForm("record.type == 'text'"));
+    expect(result.errors, 'still advisory-only: acceptance is untouched').toEqual([]);
+    const f = result.advisories.find((a) => a.rule === 'visibility-root-mislayered');
+    expect(f, 'a predicate that never matches must reach the author').toBeDefined();
+    expect(f!.severity).toBe('warning');
+    expect(f!.hint).toMatch(/data/);
+  });
+
+  it('prescribes the root the surface actually binds when it REFUSES', () => {
+    // The second half of the finding: the layer default also chose the root
+    // quoted inside `visibility-bare-identifier`'s hint, so the loudest finding
+    // on this surface — the one that BLOCKS the publish — told the author to
+    // write `record.status` on a form that binds `data`. Same id, same
+    // severity, same input: only the prescription moved.
+    const f = gateView(schemaBoundForm('status == active'))
+      .errors.find((e) => e.rule === 'visibility-bare-identifier');
+    expect(f, 'a bare word on the LEFT is still refused').toBeDefined();
+    expect(f!.severity).toBe('error');
+    expect(f!.hint).toContain('`data.status`');
+    expect(f!.hint).not.toContain('`record.status`');
+  });
+
+  it('moves NO finding across the error/advisory boundary', () => {
+    // The acceptance guarantee this card is bounded by, as a property over the
+    // schema-bound half of the family corpus: the derivation may only ever
+    // change which ADVISORIES are emitted. Asserted as exact error sets — each
+    // one is what the `'runtime'` reading produced on the same input — so a
+    // later edit to the layer plumbing that promoted or demoted anything goes
+    // red here rather than at a tenant's publish door.
+    const cases: Array<[string, string[]]> = [
+      ["data.type == 'text'", []],
+      ["record.type == 'text'", []],
+      ['data.type == active', []],
+      ['status == active', ['visibility-bare-identifier']],
+      ['data.name == active && active', ['visibility-bare-identifier']],
+      ['active == data.type', ['predicate-rhs-path-shaped', 'visibility-bare-identifier']],
+      ["data.tpye == 'text'", ['predicate-path-unresolved']],
+      ["type == 'text'", ['predicate-path-unrooted']],
+      ['data.type == data.label', ['predicate-rhs-path-shaped']],
+      ["country === 'USA'", ['visibility-predicate-syntax']],
+    ];
+    for (const [predicate, expected] of cases) {
+      expect(
+        gateView(schemaBoundForm(predicate)).errors.map((e) => e.rule).sort(),
+        `the refusal set for \`${predicate}\` changed — the #7815 layer derivation is `
+          + `advisory-only by construction, so anything moving here is a scope breach`,
+      ).toEqual([...expected].sort());
+    }
+  });
+});

packages/lint/src/validate-visibility-predicates.test.ts

@@ -255,6 +255,148 @@ describe('validateVisibilityPredicates (ADR-0089 D3b)', () => {
   });
 });
 
+// ─────────────────────────────────────────────────────────────────────
+// #7815 — WHICH LAYER a site is on, when the caller does not say.
+//
+// The rule above is correct for the layer it is told. What it was told at the
+// runtime publish gate was the `'runtime'` default for EVERY view, including
+// schema-bound metadata forms — so a correctly `data.`-rooted form drew the
+// advisory telling its author to write `record.`. These cases pin the
+// derivation itself; `runtime-gate.test.ts` pins it at the door it was wrong at.
+// ─────────────────────────────────────────────────────────────────────
+
+describe('the layer a site declares for itself (#7815)', () => {
+  /**
+   * A schema-bound metadata form, with the data source on the CONTAINER (the
+   * `self` rung of the `formViewSites` ladder).
+   */
+  const metaForm = (predicate: string) => ({
+    views: [{
+      name: 'field_editor',
+      data: { provider: 'schema', schemaId: 'field' },
+      sections: [{ fields: [{ field: 'notes', visibleWhen: predicate }] }],
+    }],
+  });
+
+  /** The same predicate on a plain runtime view — the negative control. */
+  const runtimeForm = (predicate: string) => ({
+    views: [{ name: 'task_form', sections: [{ fields: [{ field: 'notes', visibleWhen: predicate }] }] }],
+  });
+
+  it('a `data.`-rooted predicate on a schema-bound form is CORRECT — no advisory', () => {
+    // The finding this card is about. `data` IS the root that surface binds.
+    expect(validateVisibilityPredicates(metaForm("data.type == 'grid'"))).toEqual([]);
+  });
+
+  it('the same predicate on a plain runtime view still draws it — the rule is live', () => {
+    // The negative control that keeps the case above from being a walk that
+    // simply went blind: one character of difference in the fixture (the
+    // `data:` source), opposite verdicts.
+    const findings = validateVisibilityPredicates(runtimeForm("data.type == 'grid'"));
+    expect(findings.map((f) => f.rule)).toEqual([VISIBILITY_ROOT_MISLAYERED]);
+    expect(findings[0].severity).toBe('warning');
+  });
+
+  it('a `record.`-rooted predicate on a schema-bound form draws it the OTHER way', () => {
+    // ADR-0089 D3 is bidirectional and this direction was unreachable at the
+    // runtime gate: told `'runtime'`, the rule forbids `data.` and says nothing
+    // about `record.`, so a form predicate that never matches published silent.
+    // No new behaviour — this is the metadata-layer arm the rule already had.
+    const findings = validateVisibilityPredicates(metaForm("record.type == 'grid'"));
+    expect(findings.map((f) => f.rule)).toEqual([VISIBILITY_ROOT_MISLAYERED]);
+    expect(findings[0].severity).toBe('warning');
+    expect(findings[0].message).toContain('record.');
+    expect(findings[0].hint).toContain('data');
+  });
+
+  it('derives per SITE, not per stack — one entry can carry both kinds', () => {
+    // `formViews.<key>` sub-containers each declare their own `data`, so a
+    // stack-level layer would be wrong for one of these two no matter which
+    // value it took.
+    const stack = {
+      views: [{
+        name: 'mixed',
+        object: 'account',
+        formViews: {
+          meta: {
+            data: { provider: 'schema', schemaId: 'field' },
+            sections: [{ fields: [{ field: 'a', visibleWhen: "data.type == 'grid'" }] }],
+          },
+          live: {
+            sections: [{ fields: [{ field: 'b', visibleWhen: "data.type == 'grid'" }] }],
+          },
+        },
+      }],
+    };
+    const findings = validateVisibilityPredicates(stack);
+    expect(findings.map((f) => f.rule)).toEqual([VISIBILITY_ROOT_MISLAYERED]);
+    expect(findings[0].path).toBe('views[0].formViews.live.sections[0].fields[0]');
+  });
+
+  it('`opts.layer` still governs every site that declares no data source', () => {
+    // The file-aware caller's contract is unchanged: a `*.form.ts` whose form
+    // carries no `data: { provider: 'schema' }` is still only reachable through
+    // the option, and a page component always is.
+    expect(validateVisibilityPredicates(runtimeForm("data.type == 'grid'"), { layer: 'metadata' }))
+      .toEqual([]);
+    expect(
+      validateVisibilityPredicates(runtimeForm("record.type == 'grid'"), { layer: 'metadata' })
+        .map((f) => f.rule),
+    ).toEqual([VISIBILITY_ROOT_MISLAYERED]);
+
+    const page = (predicate: string) => ({
+      pages: [{ name: 'p', regions: [{ components: [{ type: 'element:text', visibleWhen: predicate }] }] }],
+    });
+    expect(validateVisibilityPredicates(page("data.x == 'y'")).map((f) => f.rule))
+      .toEqual([VISIBILITY_ROOT_MISLAYERED]);
+    expect(validateVisibilityPredicates(page("data.x == 'y'"), { layer: 'metadata' })).toEqual([]);
+  });
+
+  it('an unresolvable `schemaId` is still a schema-bound SURFACE', () => {
+    // The layer follows the data SOURCE, not whether the id resolves — the same
+    // boundary `literalRhs` draws off the same `schemaIdOf` call, so the two
+    // cannot disagree about which surface they are on.
+    expect(validateVisibilityPredicates({
+      views: [{
+        name: 'f',
+        data: { provider: 'schema', schemaId: 'no_such_schema' },
+        sections: [{ fields: [{ field: 'x', visibleWhen: "data.a == 'b'" }] }],
+      }],
+    })).toEqual([]);
+  });
+
+  it('a non-schema provider is NOT a metadata form', () => {
+    // `schemaIdOf` reads `provider === 'schema'` only; an ObjectQL-backed data
+    // source is a runtime surface and keeps the runtime direction.
+    const findings = validateVisibilityPredicates({
+      views: [{
+        name: 'f',
+        data: { provider: 'object', object: 'account' },
+        sections: [{ fields: [{ field: 'x', visibleWhen: "data.a == 'b'" }] }],
+      }],
+    });
+    expect(findings.map((f) => f.rule)).toEqual([VISIBILITY_ROOT_MISLAYERED]);
+  });
+
+  it('moves NO finding across the error/advisory boundary', () => {
+    // The acceptance guarantee, asserted rather than argued: the derivation may
+    // only ever change which ADVISORIES an author hears. Every fixture here is
+    // schema-bound — the set the derivation moves — and every `error` on it is
+    // the same id, at the same path, that the `'runtime'` reading produced.
+    const errorsOf = (predicate: string) =>
+      validateVisibilityPredicates(metaForm(predicate))
+        .filter((f) => f.severity === 'error')
+        .map((f) => f.rule)
+        .sort();
+
+    expect(errorsOf("data.type == 'grid'")).toEqual([]);
+    expect(errorsOf("record.type == 'grid'")).toEqual([]);
+    expect(errorsOf('status == active')).toEqual([VISIBILITY_BARE_IDENTIFIER]);
+    expect(errorsOf('active == data.type')).toEqual([VISIBILITY_BARE_IDENTIFIER]);
+    expect(errorsOf("country === 'USA'")).toEqual([VISIBILITY_PREDICATE_SYNTAX]);
+  });
+});
+
 // ─────────────────────────────────────────────────────────────────────
 // `visibility-bare-identifier` — #6128 (the build-time half of #5149's
 // 2026-08-06 ruling; the runtime warn-once half landed as objectui#3541).
@@ -475,8 +617,15 @@ describe('visibility-bare-identifier (#6128 / #5149 requirement 3)', () => {
     it('proves the scanner still sees — the stand-down is per IDENTIFIER', () => {
       // Every one of these is the same schema-bound form, so a walk that had
       // gone blind would report nothing here either.
+      //
+      // #7815: this pin used to read `record.status`, which is what the rule
+      // said here while the caller's `'runtime'` default decided the layer for a
+      // form that binds no `record` at all. The refusal is unchanged — same id,
+      // same `error`, same one finding; only the ROOT it prescribes moved to the
+      // one this surface actually binds. (That the pin had to change is the
+      // measurement: an assertion was holding the wrong prescription in place.)
       expect(bareFindings(metaForm('status == active')).map((f) => f.hint))
-        .toEqual([expect.stringContaining('`record.status`')]);
+        .toEqual([expect.stringContaining('`data.status`')]);
       expect(bareFindings(metaForm('active == data.type'))).toHaveLength(1);
       expect(bareFindings(metaForm('data.type == active && active'))).toHaveLength(1);
       // A macro body produces no replacement finding, so nothing stands down.