validate-expressions.ts

// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.

/**
 * Build-time expression validation (ADR-0032 §Decision 1a + 1b).
 *
 * Runs at `objectstack compile`, where the whole normalized stack is in hand —
 * so flow conditions can be checked against the *resolved* object schema
 * (field existence) in addition to CEL syntax. Uses the one shared validator
 * from `@objectstack/formula`, so the verdict matches `registerFlow` and the
 * agent `validate_expression` tool exactly.
 *
 * Scope: flow predicates (start/decision `config.condition` + edge `condition`),
 * every **descriptor-declared** expression slot named by
 * `FLOW_NODE_EXPRESSION_PATHS` (#4027 — e.g. a screen field's `visibleWhen`),
 * object validation-rule / formula predicates, and UI action `visible` /
 * `disabled` predicates. Each error is located (flow/object/action +
 * node/edge/field) with a corrective message.
 *
 * Since #4763 it also carries the **null-guard** verdict: an ordering /
 * arithmetic operator applied to a nullable declared field that no `!= null`
 * test dominates is rejected here, so the `has(a) && has(b) && a < b` trap
 * (which reads as a guard and is not one) never reaches a production write.
 * See `validate-null-guards.ts` for the decision procedure and its scope.
 *
 * Since #24677 it also refuses the one declaration the #24316 hop refusal
 * presupposes: a `lookup` / `master_detail` field whose `reference` is a
 * stored-metadata-body table, located at that field's `reference`. It is not a
 * predicate, but it is judged here so that `os validate`, `os build` and the
 * object save door, which all run this rule's object passes, refuse it alike.
 *
 * ## Scope — the keys this rule reads, and the ones it deliberately does not
 *
 * This rule is registered `input: 'parsed'` (`authoring-rules.ts`), so what it
 * sees on the compile path is what `ObjectStackSchema` returned. Every key it
 * reads is one `@objectstack/spec` DECLARES. That is a contract, not a style
 * preference: the strict sub-schemas reject an undeclared key by NAME, so a
 * branch keyed on one is inert for every stack an author can ship (#4984,
 * #5009, #5017).
 *
 * | Read                                   | Declared by                       |
 * |----------------------------------------|-----------------------------------|
 * | `objects[].validations[]`              | `ObjectSchema`                    |
 * | `objects[].attachedOnRead`             | `ObjectSchema`                    |
 * | `validations[].condition` / `.when` / `.then` / `.otherwise` | the six `*ValidationSchema` variants |
 * | `objects[].fields[].reference`         | `FieldSchema`                     |
 * | `objects[].fields[].expression`        | `FieldSchema`                     |
 * | `objects[].fields[].options`           | `FieldSchema`                     |
 * | `options[].value` / `.visibleWhen`     | `SelectOptionSchema`              |
 * | `objects[].fieldGroups`               | `ObjectSchema`                    |
 * | `fieldGroups[].key` / `.visibleWhen`   | `ObjectFieldGroupSchema`          |
 * | `actions[].objectName`                 | the action schema                 |
 * | `sharingRules[].condition` / `.object` | `SharingRuleSchema`               |
 *
 * NOT read, and each for a reason that is a schema fact (all verified against
 * the live `.shape` in `validate-expressions.test.ts`):
 *
 * - `objects[].validationRules` — `ObjectSchema` declares `validations` and is
 *   strict; the alias is refused with "Did you mean `validationRules` →
 *   `validations`?".
 * - `validations[].expression` / `.predicate` / `.formula` / `.rule` — the four
 *   names `validation.zod.ts` lists in `aliases: { … : 'condition' }`, i.e. the
 *   ones it rejects by name. This one was the worst of the family: the chain
 *   read them BEFORE `condition`, so for a rule carrying both spellings the
 *   canonical predicate was short-circuited away and the rejected alias
 *   validated in its place. Producer and consumer gave two different accounts
 *   of the same metadata (#5017).
 * - `sharingRules[].criteria` / `.predicate` — `criteria` is the runtime's own
 *   spelling of the COMPILED predicate (`criteria_json`), mapped back to the
 *   authored `condition` in the schema's rejection (#3896); `predicate` is
 *   refused outright. #4984 removed the same pair from the org-axis rule.
 * - `objects[].fields[].referenceTo` — `field.zod.ts:331` maps it (with
 *   `relatedTo` / `target` / `targetObject` / `lookupObject`) to `reference`.
 * - `actions[].object` — the action schema's own rejection says "Did you mean
 *   `object` → `objectName`?".
 * - `objects[].fields[].formula` / `.calculation` / `.compute` — the three names
 *   `field.zod.ts:333` aliases back to `expression`. The field-formula pass read
 *   `formula` until #5026, so it had never run against a stack that parses;
 *   converging it onto `expression` ACTIVATED the check rather than deleting a
 *   dead branch, which is why it moved on its own PR with a real-metadata sweep
 *   attached rather than riding along with #5017's five removals.
 *
 * Alias tolerance belongs at the schema's refusal, not in a consumer (Prime
 * Directive #12) — in a consumer it also converts a loud, named rejection into
 * a silently-inert (or, above, silently-WRONG) gate.
 *
 * Every read in this file is now a key the spec declares; the meta-guard in
 * `validate-expressions.test.ts` pins that with no tracked exceptions left.
 */

import {
  validateExpression,
  collectCelRootIdentifiers,
  parseCelToAst,
  SCOPE_ROOTS,
  analyzeRelationshipTraversals,
  buildScope,
} from '@objectstack/formula';
import type { RelationshipTraversalAnalysis } from '@objectstack/formula';
import {
  collectFlowGraphs,
  flowNodeConfigRefusals,
  predicateSlotRefusal,
  resolveFlowNodeExpressions,
  flowNodeValueTemplateRefusals,
  flowNodeTextSlotSources,
  textSlotTemplateRefusal,
  structuralConditionRefusal,
  closedScopeTemplateRefusal,
  templateSlotSource,
} from '@objectstack/spec/automation';
// [#24798] A bulk action's `confirmText` is a `template` slot over the closed
// scope the spec declares for it — judged below by the same template judge.
import { bulkConfirmTemplateRoots } from '@objectstack/spec/ui';
// [#24814] An action's copy — `confirmText`, `successMessage`, `errorMessage` —
// is a `template` slot too, judged in its own module by the same judge.
import { actionCopyTemplateIssues } from './validate-action-copy-templates.js';
// [#15137] The `value`-role half. Same two published primitives the engine
// composes at `registerFlow` (`AutomationEngine.valueEnvelopeRefusals`), in the
// same order: the SHAPE rule lives in the spec's `FlowValueSlotSchema` (the
// slot-neutral name since #19938 — it refuses a non-`cel` dialect and the
// source-less `{ dialect: 'cel' }` that `validateExpression` reads as "not
// authored"), the CEL rule in `validateExpression('value', …)`. Neither
// refusal string is spelled here.
import { FlowValueSlotSchema, VALUE_ENVELOPE_REFUSAL } from '@objectstack/spec/automation';
import type { FlowNodeParsed, FlowEdgeParsed } from '@objectstack/spec/automation';
// [#17495] The blank-source half of the structural-condition refusal, imported
// rather than restated: this is the EDGE door's own rule
// (`FlowEdgeSchema.condition` composes it since #15807) and the very schema
// `AutomationEngine.registerFlow` asks since #17322, so the author-time answer
// and the registration answer are one rule with one sentence. ⛔ Never a second
// hand-written notion of "blank" here — that drift is what #15662 built the
// shared refusal to prevent.
import { EvaluatedExpressionInputSchema, EVALUATED_EXPRESSION_SOURCE_REQUIRED } from '@objectstack/spec/shared';
import { referenceCarrierOf, referenceTargetOf, REFERENCE_VALUE_TYPES } from '@objectstack/spec/data';
import { isStoredMetadataBodyObject, STORED_METADATA_BODY_PRESCRIPTION } from '@objectstack/spec/kernel';
// [#22394] The acting user's declared members — the contract half of the option
// verdict's member allowlist for `current_user` and its ADR-0068 aliases. Read
// off the schema at first use, never restated here.
import { EvalUserSchema } from '@objectstack/spec/identity';

import { collectFlowVariableNames, shadowedFieldReads, shadowedFieldMessage } from './flow-variable-scope.js';
import {
  flowCelEntrances,
  flowCelRootScope,
  perWriteSnapshotEntrance,
  unboundFlowCelRoots,
  unboundFlowCelRootMessage,
} from './flow-cel-root-scope.js';
import type { FlowCelEntrance } from './flow-cel-root-scope.js';
import { injectedColumnsFor, unprovisionedInjectedColumnsFor } from './system-fields.js';
import { findUnguardedNullableOperands, nullGuardMessage } from './validate-null-guards.js';
import type { NullGuardOutcome } from './validate-null-guards.js';
import { recordsOf } from './object-graph.js';
export interface ExprIssue {
  where: string;
  message: string;
  source: string;
  /**
   * `error` fails the build (e.g. a bare ref in a record-scoped formula). `warning`
   * is advisory and never fails it (e.g. a possible field typo in a flattened flow
   * condition, which might be a flow variable). Absent ⇒ treat as `error`.
   */
  severity?: 'error' | 'warning';
  /**
   * [#26858] The judged slot's key path in the stack, in the spelling the other
   * rules' findings carry (`flows[0].edges[1].condition`), beside the human
   * `where`. Set only where the slot has one: a top-level flow edge's
   * `condition`, and (#27643) an object validation rule's `condition` / `when`
   * (`objects[0].validations[1].condition`), a nested branch's included
   * (`objects[0].validations[1].then.condition`). Absent, the finding is
   * located by `where` alone.
   */
  path?: string;
}

type AnyRec = Record<string, unknown>;

/**
 * object name → set of its field names, for schema-aware field checks.
 *
 * Authored fields UNION the system columns the platform injects on that object
 * (#5378). Both halves are needed because the runtime resolves both: a predicate
 * saying `has(record.owner_id)` on an object that never declares `owner_id`
 * evaluates fine, because the registry provisioned the column — so rejecting it
 * here was the platform's own linter denying the platform's own contract, and it
 * pushed apps into re-declaring system columns purely to satisfy this pass
 * (hotcrm#548 declared `owner_id` on all 12 business objects for that reason).
 *
 * The injected half is CONDITIONAL, per object, via the spec derivation the
 * registry itself consumes — not a blanket allowance of every system name. That
 * distinction is the whole value: on `ownership: 'none'` the platform injects no
 * `owner_id`, so `record.owner_id` there stays the error it should be. A blanket
 * union would have traded a false positive for a false negative and called it
 * fixed.
 */
function buildFieldIndex(objects: AnyRec[]): Map<string, string[]> {
  const idx = new Map<string, string[]>();
  for (const obj of objects) {
    const name = typeof obj.name === 'string' ? obj.name : undefined;
    if (!name) continue;
    const fields = obj.fields;
    let names: string[] = [];
    // The LIST shape is read through `recordsOf` (#15742). `Array.isArray`
    // proves the list, never its members: an empty item in a YAML `fields:`
    // list deserialises to `null`, and the cast this replaced dereferenced it
    // before the `.filter` two calls later could drop it. The two sibling
    // readers below already guard (`buildFieldTypeIndex` reads `(f)?.name`,
    // `fieldEntries` filters before mapping) and both drop such a member in
    // SILENCE — it carries no author-written name, so there is nothing to
    // report about it — which is what `recordsOf` does for the array shape too.
    // The MAP shape keeps `Object.keys`: there the author's KEY is the field
    // name, which is exactly what this "did you mean?" index needs.
    if (Array.isArray(fields)) names = recordsOf(fields).map(f => f.name).filter((n): n is string => typeof n === 'string');
    else if (fields && typeof fields === 'object') names = Object.keys(fields as AnyRec);
    // Injected columns come second, de-duplicated by insertion order: a DECLARED
    // `owner_id` is the author's field (the registry lets it win), so the
    // authored spelling keeps its position in the "did you mean?" candidates.
    // A declared read attachment is NOT here: it is not a column, so a stored
    // row never carries it, and this index is what every stored-row site
    // reads. The sites that bind a served row add the blocks themselves — see
    // {@link SERVED_ROW_SITES} and {@link withAttachedBlocks}.
    idx.set(name, [...new Set([...names, ...injectedColumnsFor(obj)])]);
  }
  return idx;
}

/**
 * [#22211 ruling A] The object's declared read-attachment blocks —
 * `ObjectSchema.attachedOnRead`, block name → (leaf key → value type) — as
 * block name → its leaf keys, in declaration order. Empty for an object that
 * declares none, which is every object that does not write the key: such an
 * object hands the shared validator no `attachedOnRead` and keeps exactly the
 * verdicts it had.
 *
 * Own keys only, read off the parsed value; the spec's strict record has
 * already refused a malformed block or leaf at parse.
 */
function attachedOnReadOf(obj: AnyRec): Record<string, string[]> {
  const declared = obj.attachedOnRead;
  const out: Record<string, string[]> = {};
  if (!declared || typeof declared !== 'object' || Array.isArray(declared)) return out;
  for (const [block, leaves] of Object.entries(declared as AnyRec)) {
    if (!leaves || typeof leaves !== 'object' || Array.isArray(leaves)) continue;
    out[block] = Object.keys(leaves as AnyRec);
  }
  return out;
}

/**
 * object name → its declared read attachments (block name → leaf keys), for
 * the served-row sites ({@link SERVED_ROW_SITES}): there each block name joins
 * the field-existence set, and the shared validator judges the second segment
 * of `record.<block>.<leaf>` against the block's leaves
 * (`ExprSchemaHint.attachedOnRead`). Only objects that declare at least one
 * block get an entry, so `index.get(name)` is `undefined` — the hint absent —
 * for every other object.
 */
function buildAttachedOnReadIndex(objects: AnyRec[]): Map<string, Record<string, string[]>> {
  const idx = new Map<string, Record<string, string[]>>();
  for (const obj of objects) {
    const name = typeof obj.name === 'string' ? obj.name : undefined;
    if (!name) continue;
    const blocks = attachedOnReadOf(obj);
    if (Object.keys(blocks).length > 0) idx.set(name, blocks);
  }
  return idx;
}

/**
 * The expression sites whose `record` is a row a service SERVES — the only
 * sites where a declared read attachment resolves.
 *
 * `ObjectSchema.attachedOnRead` declares the blocks a service attaches to the
 * rows it serves, computed per caller and never stored. A block is therefore
 * on `record` only where `record` is such a served row, and this list names
 * those sites:
 *
 * - an action's `visible` and `disabled` predicates. The client's action
 *   runtime evaluates them against the row the surface fetched, and a surface
 *   that reads the declaring service's own routes holds the row that service
 *   served — the console reads `sys_approval_request` through the approvals
 *   routes, whose rows carry the `viewer` block. A surface that fetched the
 *   row elsewhere has no block, which is why such a predicate guards the
 *   block with `has()`.
 *
 * Every other site binds the STORED row, and judges field existence against
 * the object's columns alone ({@link buildFieldIndex}):
 *
 * - a flow's node and edge conditions: the record-change trigger seeds
 *   `record` from the write's payload over the stored row, and a flow's
 *   subject load reads the data engine;
 * - validation rules, a field's `requiredWhen` / `readonlyWhen` and an
 *   option's `visibleWhen`: evaluated on the write, against the stored row
 *   merged with the payload (`rule-validator.ts`);
 * - field formulas: computed on the stored row;
 * - sharing-rule and hook conditions: judged against stored rows and the
 *   write's record.
 *
 * A block named at one of those sites is refused as an unknown field, because
 * at run time it is one: the expression faults on the missing key on every
 * row. A field's `visibleWhen` is not on the list either — it renders against
 * whatever row the surface holds, the stored row on an edit form — nor is a
 * field's cell formatting rule (#22228), for the same reason; no field
 * predicate reads a block.
 *
 * `check` adds the blocks only for a call site that names an entry here, so a
 * new site is fields-only until its binding is shown to be a served row and it
 * is listed.
 */
const SERVED_ROW_SITES = ['action visible', 'action disabled'] as const;
type ServedRowSite = (typeof SERVED_ROW_SITES)[number];

/**
 * The field-existence set at a served-row site: the object's columns, then
 * each block it declares — last, so a column keeps its place in the
 * "did you mean?" candidates. `fields` unchanged when the object declares no
 * block.
 */
function withAttachedBlocks(
  fields: string[] | undefined,
  blocks: Record<string, string[]> | undefined,
): string[] | undefined {
  if (!blocks) return fields;
  return [...new Set([...(fields ?? []), ...Object.keys(blocks)])];
}

/**
 * [#8116] The roots this file's unprovisioned-anchor warning resolves against
 * the bound object — the same pair the #4763 null-guard gate resolves, for the
 * same reason: both bind the object's record shape, so a single-segment member
 * read off either names one of the object's columns.
 */
const BOUND_RECORD_ROOTS = ['record', 'previous'] as const;

/** Minimal structural view of a `parseCelToAst` node (`{ op, args }`). */
type CelNodeLike = { op?: string; args?: unknown };

function isCelNode(v: unknown): v is CelNodeLike {
  return !!v && typeof v === 'object' && typeof (v as CelNodeLike).op === 'string';
}

/**
 * [#8116] Every single-segment `record.<f>` / `previous.<f>` member read in
 * the source, as `field → operand-as-written` (first spelling wins). Empty
 * when the source does not parse — the syntax pass owns that defect, and one
 * broken predicate must produce one finding, not two.
 *
 * Deliberately NEVER a bare identifier: in a flattened flow scope a bare name
 * may be a flow variable, and a false finding here is the trust-killer
 * ADR-0072 D1 names. A `has(record.x)` guard is covered for free — `record.x`
 * is an ordinary member-read node inside the call's argument list. Nested
 * traversal (`record.owner_id.name`) contributes its FIRST segment, which is
 * the column the query engine must resolve on this object.
 */
function collectBoundRecordReads(source: string): Map<string, string> {
  const out = new Map<string, string>();
  const ast = parseCelToAst(source);
  if (!ast) return out;
  // NB: local names are chosen to stay out of the #5017 meta-guard's receiver
  // scan (`node` is a METADATA receiver there — flow `nodes[]` — and this walk
  // reads AST internals, not metadata keys).
  const pending: unknown[] = [ast];
  while (pending.length > 0) {
    const celNode = pending.pop();
    if (!isCelNode(celNode)) continue;
    if (
      (celNode.op === '.' || celNode.op === '.?') &&
      Array.isArray(celNode.args) &&
      celNode.args.length >= 2
    ) {
      const [celRecv, seg] = celNode.args as [unknown, unknown];
      if (
        typeof seg === 'string' &&
        isCelNode(celRecv) &&
        celRecv.op === 'id' &&
        typeof celRecv.args === 'string' &&
        (BOUND_RECORD_ROOTS as readonly string[]).includes(celRecv.args)
      ) {
        if (!out.has(seg)) out.set(seg, `${celRecv.args}.${seg}`);
      }
    }
    const celArgs = celNode.args;
    if (isCelNode(celArgs)) pending.push(celArgs);
    else if (Array.isArray(celArgs)) {
      for (const a of celArgs) {
        if (isCelNode(a)) pending.push(a);
        else if (Array.isArray(a)) for (const b of a) if (isCelNode(b)) pending.push(b);
      }
    }
  }
  return out;
}

/**
 * object name → (field name → field type), for the #1928 tier-4 type-soundness
 * check. Handles both `fields` shapes (array of `{name, type}` and name-keyed
 * map). Fields with a non-string `type` are simply omitted (treated as `dyn`).
 *
 * DECLARED fields only — deliberately NOT widened with the injected columns
 * {@link buildFieldIndex} resolves (#5378). Their TYPES are the registry's
 * (`AUDIT_FIELD_DEFS` and its siblings own what each column looks like; the spec
 * derivation owns only which ones exist), so typing them here would be the
 * hand-copied second table this change exists to avoid. Omitted ⇒ `dyn` ⇒ no
 * type-soundness verdict on an injected column, which is the safe direction: the
 * pass gains no false finding, it simply does not cover them yet.
 */
function buildFieldTypeIndex(objects: AnyRec[]): Map<string, Record<string, string>> {
  const idx = new Map<string, Record<string, string>>();
  for (const obj of objects) {
    const name = typeof obj.name === 'string' ? obj.name : undefined;
    if (!name) continue;
    const fields = obj.fields;
    const types: Record<string, string> = {};
    if (Array.isArray(fields)) {
      for (const f of fields as AnyRec[]) {
        const fn = (f as AnyRec)?.name;
        const ft = (f as AnyRec)?.type;
        if (typeof fn === 'string' && typeof ft === 'string') types[fn] = ft;
      }
    } else if (fields && typeof fields === 'object') {
      for (const [fn, def] of Object.entries(fields as AnyRec)) {
        const ft = (def as AnyRec)?.type;
        if (typeof ft === 'string') types[fn] = ft;
      }
    }
    idx.set(name, types);
  }
  return idx;
}

/** The field list of an object, whichever of the two `fields` shapes it uses. */
function fieldEntries(obj: AnyRec): Array<[string, AnyRec]> {
  const fields = obj.fields;
  if (Array.isArray(fields)) {
    return (fields as AnyRec[])
      .filter((f) => f && typeof f === 'object' && typeof f.name === 'string')
      .map((f) => [f.name as string, f] as [string, AnyRec]);
  }
  if (fields && typeof fields === 'object') {
    return Object.entries(fields as AnyRec)
      .filter(([, def]) => !!def && typeof def === 'object')
      .map(([n, def]) => [n, def as AnyRec] as [string, AnyRec]);
  }
  return [];
}

/**
 * Can this declared field hold `null` when a predicate reads it? (#4763)
 *
 * Deliberately conservative — this feeds a **build-breaking** verdict, so every
 * uncertainty resolves to "not nullable" (no finding). A field is treated as
 * always-valued when it is `required`, carries a `defaultValue`, declares a
 * default option (`options: [{ …, default: true }]` — the select idiom), or is
 * an autonumber the platform populates.
 *
 * The select-idiom branch is grounded, not assumed (#7246). It was the only
 * consumer of `SelectOption.default` anywhere in the repo while the insert path
 * ignored the key entirely, so it concluded "always valued" about a column that
 * really did store `null` — a build-breaking verdict resting on a declaration
 * nothing honoured, and a predicate reading such a field could be silenced by
 * it. `ObjectQL.applyFieldDefaults` now falls back to the marked option when
 * the field declares no `defaultValue`, so the premise this branch always
 * stated is true on the write path. The two sides are kept honest BY
 * CONSTRUCTION: the engine reads the canonical `default` spelling, without a
 * `type` test, exactly as this does — so there is no field this calls
 * always-valued that the engine leaves empty.
 */
function isNullableField(def: AnyRec): boolean {
  if (def.required === true) return false;
  if (def.defaultValue !== undefined && def.defaultValue !== null) return false;
  if (def.type === 'autonumber') return false;
  const options = def.options;
  if (Array.isArray(options) && options.some((o) => !!o && typeof o === 'object' && (o as AnyRec).default === true)) {
    return false;
  }
  return true;
}

/**
 * object name → set of field names that may hold `null` (#4763).
 *
 * DECLARED fields only, like {@link buildFieldTypeIndex} and for a sharper
 * reason: this index feeds a BUILD-BREAKING verdict, so adding the injected
 * columns {@link buildFieldIndex} now resolves would turn `record.created_at`
 * comparisons into errors on stacks that ship today. Nullability there is also
 * genuinely per-column and not derivable from the existence plan — the driver
 * always populates `created_at`, while `owner_id` really can be NULL — so it
 * needs the registry's column definitions, not this module's guesses. Leaving
 * them out costs coverage, never a false error.
 */
function buildNullableFieldIndex(objects: AnyRec[]): Map<string, Set<string>> {
  const idx = new Map<string, Set<string>>();
  for (const obj of objects) {
    const name = typeof obj.name === 'string' ? obj.name : undefined;
    if (!name) continue;
    const nullable = new Set<string>();
    for (const [fname, def] of fieldEntries(obj)) {
      if (isNullableField(def)) nullable.add(fname);
    }
    idx.set(name, nullable);
  }
  return idx;
}

/**
 * [#4889] Does this CEL source read the `parent` root — the master-detail
 * header the write path binds for a detail object's field predicates?
 *
 * Decided from the parsed AST (the same `collectCelRootIdentifiers` the runtime
 * gate uses, so build and runtime can never disagree about what "reads
 * `parent`" means), never a substring scan: a field named `parent_id`, or the
 * string literal `'parent'`, is not a reference to the binding. A source that
 * does not parse answers `false` — the ordinary syntax pass already reports it,
 * and this gate must not report the same defect twice under a worse name.
 */
function readsParentRoot(source: string): boolean {
  const roots = collectCelRootIdentifiers(source);
  return roots.ok && roots.roots.includes('parent');
}

/**
 * The number of `master_detail` relationships an object declares — what decides
 * whether `parent` is a fact the metadata states (#4889). Exactly one ⇒ the
 * write path binds that master as `parent`. Zero ⇒ nothing to bind. Two ⇒ no
 * single "the parent", and picking one by declaration order would make a
 * data-integrity lock depend on field ordering.
 */
function masterDetailCount(obj: AnyRec): number {
  let n = 0;
  for (const [, def] of fieldEntries(obj)) {
    if (def.type !== 'master_detail') continue;
    // `reference` is the ONLY spelling `FieldSchema` declares. `referenceTo`
    // (with `relatedTo` / `target` / `targetObject` / `lookupObject`) is a
    // rejected alias — `field.zod.ts:331` maps it to `reference` in the strict
    // error map, so a field spelling it does not parse (#5017). See the
    // `## Scope` table on this module for why a consumer must not re-admit it.
    //
    // [#18550] Read through the ONE arbiter. ABSENCE is unchanged and still
    // uncounted — `undefined` / `null` / `''` answer `undefined`, and the
    // `.trim()` test below still drops a whitespace-only carrier, which names
    // no object either. UNREADABILITY used to be uncounted too, and that is
    // the silence: an object-valued carrier made a declared `master_detail`
    // invisible to this count, so `parent` was judged unbound (or two masters
    // read as one) from metadata that does declare a relationship.
    // ⭐ The literal `.reference` read STAYS here, in the argument, and only
    // the SHAPE judgment moves out — the form `validate-security-posture.ts`
    // and `data-model-rules.ts` already use, and for their stated reason: the
    // #5017 receiver meta-test reads this rule's SOURCE to prove it reads
    // `reference` and never an alias, and a read folded inside a helper call
    // would disarm that scan silently.
    const ref = referenceCarrierOf({ reference: def.reference }, 'validate-expressions masterDetailCount');
    if (ref !== undefined && ref.trim() !== '') n += 1;
  }
  return n;
}

/** The raw CEL source behind a predicate slot (string or `{ dialect, source }`). */
function celSourceOf(raw: unknown): string | undefined {
  if (typeof raw === 'string') return raw;
  if (raw && typeof raw === 'object') {
    const rec = raw as AnyRec;
    // A non-CEL dialect (`js`) has its own null semantics — not ours to judge.
    if (typeof rec.dialect === 'string' && rec.dialect !== 'cel') return undefined;
    if (typeof rec.source === 'string') return rec.source;
  }
  return undefined;
}

/** One predicate a validation rule carries — see {@link rulePredicates}. */
interface RulePredicate {
  label: string;
  raw: unknown;
  /** 0 for the rule itself; 1 inside its `then` / `otherwise`, and so on down. */
  depth: number;
  /** The key the predicate is written under on its own rule. */
  slot: 'condition' | 'when';
  /** The name of the rule that carries it (the nested rule's own, below depth 0). */
  ruleName: string;
  /**
   * [#27643] Its key path inside the top-level rule (`condition`, `when`,
   * `then.condition`, `otherwise.then.when`), for a finding's `path`.
   */
  key: string;
}

/**
 * Every predicate a validation rule carries, including the ones nested inside a
 * `conditional` rule's `then` / `otherwise` — the trap hides there just as
 * happily as at the top level.
 */
function rulePredicates(rule: AnyRec, path: string, depth = 0, keyPrefix = ''): RulePredicate[] {
  const out: RulePredicate[] = [];
  const name = typeof rule.name === 'string' ? rule.name : '?';
  const here = path ? `${path} → '${name}'` : `'${name}'`;
  // `condition` is the declared predicate key on every validation-rule variant
  // that has one (`script`, `cross_field`). `expression` / `predicate` /
  // `formula` / `rule` are the four names `validation.zod.ts` REJECTS by name
  // (`aliases: { formula: 'condition', expression: 'condition', predicate:
  // 'condition', rule: 'condition' }`), so a rule spelling any of them does not
  // parse. Reading them here put the canonical key in THIRD position — an
  // author who wrote both `condition` and a rejected alias had their canonical
  // predicate short-circuited away and the alias validated instead (#5017).
  const main = rule.condition;
  if (main != null) {
    out.push({ label: `validation rule ${here}`, raw: main, depth, slot: 'condition', ruleName: name, key: `${keyPrefix}condition` });
  }
  if (rule.when != null) {
    out.push({
      label: `validation rule ${here} when-predicate`, raw: rule.when, depth, slot: 'when', ruleName: name, key: `${keyPrefix}when`,
    });
  }
  for (const branch of ['then', 'otherwise'] as const) {
    const nested = rule[branch];
    if (nested && typeof nested === 'object' && !Array.isArray(nested)) {
      out.push(...rulePredicates(nested as AnyRec, `${here} ${branch}`, depth + 1, `${keyPrefix}${branch}.`));
    }
  }
  return out;
}

/**
 * A FIELD-level conditional rule (`visibleWhen` / `readonlyWhen` /
 * `requiredWhen`) that reaches for a namespace root the field level does not
 * bind. The field level binds THREE roots and nothing else — `record`,
 * `previous`, and `parent` on a master-detail line item — measured at three
 * independent ends: the server (`rule-validator.ts` binds
 * `{ record, previous, extra: { parent } }` for `readonlyWhen` and
 * `{ record, previous, ...parentScope }` for `requiredWhen`), the client
 * (`evalFieldPredicate` binds `record` + `previous` + a caller `scope` that
 * is only ever `{ parent }` across objectui's five field-level call sites),
 * and the authoring surface (objectui's `FIELD_RULE_ROOTS`, whose comment
 * says "nothing else").
 *
 * ## Why this is a rule of its own rather than a missing root
 *
 * Until commit e9b526597 the same rejection fell out of `@objectstack/formula`'s
 * `SCOPE_ROOTS` not listing `current_user` — a global baseline, doing a
 * per-surface job by accident. Two things were wrong with that:
 *
 *  1. The rest of the package said the opposite. `introspectScope` hands
 *     `current_user` to authors as a legal root and `checkRoleCatalog`'s four
 *     position-membership regexes all lead with it, because ADR-0068 D1 makes
 *     it THE canonical spelling and `buildScope` really does mount it. One
 *     package, two accounts of one root.
 *  2. The diagnostic was the generic bare-field one, so it prescribed
 *     "Write `record.current_user`" — a shape that binds on NO layer. An
 *     author who followed it wrote something strictly worse than what they
 *     started with, and the failure stayed silent.
 *
 * So the baseline now declares the root (a reference through it never faults
 * platform-wide) and the surface that genuinely cannot bind it says so here,
 * in its own words, with the prescriptions that actually exist.
 *
 * ## Why the membership test is an ALLOWLIST (#6713)
 *
 * Until #6713 this rule matched a hand-written DENYLIST — one root in #6584,
 * three after #6585 (`current_user` / `user` / `ctx`). The denylist was never
 * the truth: the three anchors above pin a three-item ALLOWLIST, and
 * everything outside it is equally unbound, faults identically, and — this is
 * the part that made the hole invisible — is equally SILENT. A root in
 * `SCOPE_ROOTS` resolves in the strict env, so the bare-reference check one
 * line up never fires on it either. #6713 measured 21 roots living in that
 * gap (`input`, `output`, `os`, `vars`, `variables`, `automation`, `context`,
 * `args`, `item`, `env`, `step`, `result`, `trigger`, `event`, `payload`,
 * `data`, `params`, `config`, `settings`, `features`, `current`), two of them
 * highly credible author typos rather than theoretical members:
 *
 *  - `os.user.id` — ADR-0068 D1's FOURTH user spelling. #6585 took three and
 *    left this one, so the same semantic error stayed silent under one of the
 *    four names the platform itself mounts the user object under.
 *  - `data.status == 'x'` — `data` is the LEGAL root of this very
 *    `visibleWhen` key on a METADATA form (`view.zod.ts`: "Root: `record` …
 *    in runtime forms, or `data` in metadata forms"). Two form kinds, one key
 *    name, different roots — and the repo's own `*.form.ts` files are full of
 *    the `data` spelling for an author to copy.
 *
 * A denylist cannot track `SCOPE_ROOTS`: every root added there is unreported
 * here until somebody remembers to copy it across (`current_user` itself
 * arrived in commit e9b526597, and needed that same change (#6584) to be noticed). The allowlist inverts the
 * maintenance burden onto the three roots that are pinned by three anchors and
 * change only when the evaluators do.
 *
 * The membership test is {@link FIELD_RULE_JUDGED_ROOTS} minus the allowlist.
 * Its bulk is `SCOPE_ROOTS`, taken from `@objectstack/formula` rather than
 * restated here (#6713 published it for this consumer) — one list, one
 * definition, no drift — plus the nowhere-bound roots #13935 measured outside
 * that baseline; see "Why the judged vocabulary is WIDER than `SCOPE_ROOTS`"
 * below.
 * It deliberately is NOT `firstUndeclaredReference`, the declaredness oracle
 * the sibling visibility rule uses, and the difference is a measured false
 * positive rather than a preference: the strict env also declares CEL's TYPE
 * names, so `type(record.x) == string` reports `string` as a root that
 * "resolves". Judging by declaredness would reject that legitimate predicate;
 * judging by membership does not. Everything the oracle owns and this list
 * does not — bare field references, comprehension-macro variables — keeps
 * falling to the bare-reference check, which has the right prescription for
 * it. The two partitions are disjoint and there is no gap between them.
 *
 * ⚠️ That disjointness used to hold for FREE and no longer does. While every
 * judged root was a `SCOPE_ROOTS` member it was declared in the strict env, so
 * the bare-reference check could not fire on it whatever this rule decided.
 * A NOWHERE-BOUND root is undeclared there, so both checks see it — the walk
 * suppresses the bare-reference verdict for a root this rule has claimed
 * (`claimedRoot` on the `check` closure) to keep the invariant true by
 * construction instead of by coincidence.
 *
 * ## Why it is an error and not a warning
 *
 * Every fault direction available here is either silent or the opposite of
 * what the author declared (see the per-slot table below): a `visibleWhen`
 * written to HIDE leaves the field visible to everyone, a `readonlyWhen`
 * written to unlock-under-a-condition locks the field on every write, and a
 * `requiredWhen` — silent until ADR-0137 D2 — now refuses every write that
 * reaches the root, because that root is never bound there. Only the last
 * produces a runtime error at all, and it produces it on the first write in
 * production; build time is where the author should meet it (#6146).
 *
 * Verdict scope is the field level only. Per-option `visibleWhen` is checked
 * by the loop in the field walk and deliberately NOT passed through here:
 * options resolve against the host's predicate scope, which binds
 * `current_user` (ADR-0068 / objectui#2284) — that surface is where such a
 * predicate belongs, which is why it is also the first prescription below.
 * The option has its own root verdict (`optionVisibleWhenRootIssue`, #22157),
 * over the roots the server's option check binds: the acting user, and never
 * `parent`.
 *
 * ## The user roots, and why `ctx` is judged whole-root (#6585)
 *
 * ADR-0068 D1 makes `user` and `ctx.user` ALIASES of `current_user` — one
 * `EvalUser` object under every spelling (`buildScope` in
 * `formula/stdlib.ts` hangs the same reference on `current_user` / `user` /
 * `ctx.user` / `os.user`). Matching only the canonical spelling meant the
 * identical semantic error got a diagnostic under `current_user` and total
 * silence under the aliases — which spelling the author picked decided
 * whether they got the diagnostic, the exact fork AI authors cannot
 * self-check. All four roots now share one verdict and one prescription;
 * the message names the spelling found, nothing else varies. (`os` joined the
 * set in #6713 — it is the fourth name `buildScope` mounts the same object
 * under, and the allowlist would have rejected it anyway; what the user tier
 * decides is only WHICH prescription it gets, and the user one is right for
 * `os.user`. `os.org` / `os.env` land in the same tier too. The option
 * surface named by the first prescription does NOT bind them: the server's
 * option check fills `os` with its `user` member only, so a predicate moved
 * there meets that surface's member verdict (#22274), which names what is
 * bound instead.)
 *
 * `ctx` is judged as a WHOLE root, not only in `ctx.user` form, because at
 * this surface that is simply what is true: `buildScope` creates the `ctx`
 * root ONLY when the evaluation carries a user (`scope.ctx = { user }`
 * inside `if (ctx.user !== undefined)`), and no field-level site passes one
 * — the server binds `record`+`previous`(+`parent`) (`rule-validator.ts`
 * `readonlyWhenBindings` / the `requiredWhen` block) and the client's
 * `evalFieldPredicate` binds `record`+`previous`+caller `scope` (only ever
 * `{ parent }`). So `ctx.locale` faults exactly like `ctx.user.id` here.
 * `ctx` IS ActionEngine's predicate root elsewhere — the platform's real
 * `ctx.user` predicates all sit on action `visible` (`sys-user.object.ts`,
 * `sys-invitation.object.ts`), a surface this helper never reads — and
 * measured usage of field-level `*When` with ANY user root is zero across
 * examples/, packages/ and objectui (#6585's sweep).
 *
 * The rejected alternative was matching `ctx` only in its `ctx.user` form.
 * `collectCelRootIdentifiers` reports ROOTS and drops member names by
 * design, so that reading needs a source-level spelling match — and a
 * spelling match is precisely the defect this rule exists to remove: it
 * would re-open the same fork one level down (`ctx["user"].id` silent,
 * `ctx.user.id` rejected), while leaving a real fail-open fault (`ctx.locale`)
 * unreported for the sake of a narrower rule NAME.
 *
 * ## The message tiers on TWO orthogonal axes
 *
 * The causal half tiers by SLOT (#6716); the prescription half tiers by ROOT
 * (#6713). They are independent — `data` on a `readonlyWhen` needs the
 * metadata-form prescription AND the locked-field consequence — so one
 * skeleton carries both rather than a message per combination.
 *
 * ### Axis 1 — the consequence, by SLOT (#6716, all three cells measured)
 *
 * Until #6713/#6716 all three slots shared ONE sentence: "the predicate
 * faults and falls back to VISIBLE, leaving the field the test was meant to
 * hide showing for everyone". That is precise for exactly one of them. The
 * measurement, at both ends of each slot:
 *
 *  - **`visibleWhen` — client-only, and since objectui#6010 it fails in TWO
 *    ways rather than one.** The server half is unchanged and still exactly
 *    right: it never evaluates a FIELD-level `visibleWhen` at all —
 *    `rule-validator.ts`'s `ConditionalFieldDef` has no such member, and
 *    `hasFieldRules` gates on `requiredWhen || readonlyWhen ||
 *    fieldHasOptionVisibility` — the `visibleWhen` it does evaluate is the
 *    per-OPTION one. The RENDERER half moved. `plugin-form`'s
 *    `sectionFields.ts` (`fromObjectSchema`) copies an object field's ADR-0036
 *    `visibleWhen` / `readonlyWhen` / `requiredWhen` straight onto the runtime
 *    form field, and the SDUI form renderer resolves those through
 *    `resolveFieldRuleState` **with `predicateScope` bound**. So under a host
 *    that publishes a scope the predicate does not fault: it RESOLVES, the
 *    control is hidden in that one form, and the server still returns the value
 *    to every other reader — a silent enforcement gap. Only where no host
 *    publishes a scope (the public `/f/:slug` route, every non-form reader)
 *    does the old sentence still describe what happens: unbound root, fault,
 *    `fallback: true`, field visible to everyone.
 *
 *    ⛔ This is not a reason to relax {@link FIELD_RULE_BOUND_ROOTS}. The
 *    verdict is MORE justified than when it was written, not less: trading a
 *    loud lint error for a gap nobody can see is the one outcome worse than
 *    the error. Only the causal clause was re-measured.
 *  - **`readonlyWhen` — the two ends fault in OPPOSITE directions, and the
 *    server wins.** Server: `isReadonlyWhenLocked` matches the fault with
 *    `unknownVariableOf` and returns `true` — "the declared lock is not
 *    waived because it could not be evaluated" (#4889's carve-out, whose
 *    trigger is precisely the unbound-ROOT case, not the undeclared-key one)
 *    — and `stripReadonlyWhenFields` then DELETES the field from the incoming
 *    payload and lets the rest of the write through. Client:
 *    `resolveFieldRuleState` passes `fallback: false`, so the form renders the
 *    field editable. The standing "server enforces, client is courtesy" rule
 *    — ADR-0124 D1 — resolves the disagreement: the author edits
 *    the field, the save reports
 *    success, and the value silently never lands. The old sentence told this
 *    author the field would be VISIBLE TO EVERYONE — the opposite failure, and
 *    the opposite troubleshooting direction.
 *  - **`requiredWhen` — the server REFUSES, and never about visibility.**
 *    Server: a `requiredWhen` that cannot be evaluated refuses the write,
 *    naming the field and the rule (ADR-0137 D2). It was fail-OPEN until then
 *    — the block logged `unknownVariableOf`'s name and `continue`d, and a
 *    record saved with the field empty. Client: `fallback: false`, so the form
 *    does not mark the field required, and the save it submits is refused. An
 *    unbound root faults on every write that reaches it. "Falls back to
 *    VISIBLE" was not merely imprecise here, it named the wrong property of
 *    the field.
 *
 * `conditionalRequired` reached this helper until #25767: its `FieldSchema`
 * tombstone was a ≤16.x retirement kit and aged out, so the schema no longer
 * declares the key and the field walk no longer passes it (the strict parse
 * refuses it as an unknown key, naming the upgrade guide).
 *
 * ### Axis 2 — the prescription, by ROOT (#6713)
 *
 * The pre-#6713 prescriptions are user-oriented (move to the option level,
 * declare permission-set FLS) because the pre-#6713 denylist held only user
 * roots. Handed to an author who wrote `data.type == 'select'`, "move it to
 * the option's `visibleWhen`" answers a question nobody asked. Three tiers:
 *
 *  - **user roots** (`current_user` / `user` / `ctx` / `os`) keep the existing
 *    two user-specific prescriptions plus the `record` rewrite. What changed is
 *    the GROUNDING of the first one, not the prescription: it used to read
 *    "per-option is the one `*When` surface that binds `current_user`", and
 *    since objectui#6010 a form VIEW's field predicate binds those roots too —
 *    client-side only, because nothing on the write path evaluates a form-view
 *    field `visibleWhen`. So per-option is recommended for the reason that
 *    survives the change: the rule validator enforces it on write. The message
 *    now says that, and names the view surface only to refuse it as a
 *    destination for a server-enforced object rule (trading a loud lint error
 *    for a silent enforcement gap is the one outcome worse than the error);
 *  - **`data`** gets the metadata-form-vs-runtime-form explanation, because
 *    that is what the mistake IS — the same key name, the other form kind's
 *    root;
 *  - **`app` and the other NOWHERE-BOUND roots** get the bound-nowhere
 *    explanation and an explicit refusal of `record.<root>` (#13935, below);
 *  - **everything else** gets the general rewrite, phrased without claiming
 *    which other surface the author copied it from.
 *
 * ## Why the judged vocabulary is WIDER than `SCOPE_ROOTS` (#13935)
 *
 * `SCOPE_ROOTS` was the membership test until #13935, and it is the wrong
 * question by one word: it answers "is this root declared PLATFORM-WIDE",
 * while the rule needs "does this rule have a measured verdict for this root".
 * The two agreed for 27 roots and then disagreed for `app`. Falling outside the
 * membership test sent it to the bare-reference check, whose prescription is to
 * rewrite the root as a member of the record — and following that earns
 * ``unknown field `app` `` from the field-existence pass one line up. A first
 * diagnostic that is false about the root, and a wasted correction cycle.
 *
 * ⭐ **Decision batch #67 (2026-09-07) moved the grounds and left the verdict
 * standing.** #13935 justified the widening by saying `app` was bound at the
 * renderer; the batch ruled the engine's declared scope to be the contract,
 * ObjectUI aligned to it, and `app` is now bound at no site at all. What that
 * falsifies is the WORD "ambient", not the membership: the two-step wrong
 * correction above is still exactly what an author gets if this root leaves the
 * judged vocabulary, so the constant keeps the root, under
 * {@link FIELD_RULE_NOWHERE_BOUND_ROOTS}'s name and grounds, and the tier's
 * message states what is now true instead of what was true then.
 *
 * `SCOPE_ROOTS`' own docblock made the original widening measurable rather than
 * a matter of taste: its `current_user` entry claims to be "the last one this
 * list was missing" (commit e9b526597 wrote it). `app` is that sentence's second counterexample —
 * the same mechanism (#6713's point: a hand-maintained list doing a per-surface
 * job drifts), a second sighting, not an analogy to the first.
 *
 * ⛔ The repair deliberately does NOT add `app` to `SCOPE_ROOTS`. That list is
 * the published strict-lint accept baseline in `@objectstack/formula`, so
 * adding a root there stops EVERY surface that judges bare identifiers from
 * faulting it — a widened public accept set, to fix one surface's diagnostic.
 * The judged vocabulary is assembled HERE, where the per-surface question is
 * asked, and `SCOPE_ROOTS` is left as the proper subset it already is.
 */
/**
 * The roots a field-level `*When` predicate binds. Everything else in
 * {@link FIELD_RULE_JUDGED_ROOTS} is rejected — see the allowlist section above.
 */
export const FIELD_RULE_BOUND_ROOTS = ['record', 'previous', 'parent'] as const;
/**
 * Author-reachable roots that bind at NO evaluation site and that `SCOPE_ROOTS`
 * does not declare either — judged HERE so this rule owns their verdict instead
 * of dropping them through to the bare-reference check.
 *
 * ## Why this is no longer called AMBIENT (decision batch #67, 2026-09-07)
 *
 * #13935 added `app` under that name on a premise the batch has since ruled
 * away: that objectui's app-shell bound it at the renderer, so the honest
 * verdict was "bound somewhere, just not here". Batch #67 ruled that the
 * engine's `SCOPE_ROOTS` is the contract and ObjectUI aligns to it; ObjectUI
 * shipped that — its scope builder no longer binds `app` — and the
 * producer-side card asking for the opposite was closed as not planned under
 * the same ruling. The membership survives and its GROUNDS do not: `app` binds
 * nowhere at all now, which is what this name asserts and the old one did not.
 *
 * ⛔ The constant is NOT emptied, and that is the whole point of the repair.
 * Membership is what keeps the field-rule verdict reachable; drop the root and
 * it falls through to `@objectstack/formula`'s generic bare-reference check,
 * whose prescription is to rewrite the root as a member of the record — the
 * exact advice #13935 existed to remove, because following it earns an
 * `unknown field` error on that same root one pass later. Both directions were
 * measured before this was written, and the emptied form is strictly worse for
 * the author.
 *
 * ⛔ Nor is the repair to widen `SCOPE_ROOTS`. That list is the published
 * strict-lint accept baseline in `@objectstack/formula`, so a root added there
 * stops EVERY surface that judges bare identifiers from faulting it — a widened
 * public accept set, to fix one surface's wording. The judged vocabulary is
 * assembled HERE, where the per-surface question is asked.
 *
 * ⚠️ Membership says only that this rule has a measured verdict for the root.
 * It is emphatically NOT a claim that anything binds it — that reading is the
 * one that went stale — and not a claim that the FIELD level binds it either,
 * which is {@link FIELD_RULE_BOUND_ROOTS} and is unchanged.
 */
export const FIELD_RULE_NOWHERE_BOUND_ROOTS = ['app'] as const;
/**
 * The vocabulary this rule judges against, of which `SCOPE_ROOTS` is a proper
 * subset (#13935): the platform-wide baseline, plus the roots that bind nowhere
 * at all and still earn a measured verdict here.
 *
 * `SCOPE_ROOTS` comes FIRST so the tie-break in {@link fieldRuleRootIssue} —
 * "anything else falls back to `SCOPE_ROOTS` order" — keeps its exact
 * pre-#13935 precedence: a predicate reading both a baseline root and a
 * nowhere-bound one reports the baseline root, the same root it reported
 * before.
 */
export const FIELD_RULE_JUDGED_ROOTS: readonly string[] = [
  ...SCOPE_ROOTS,
  ...FIELD_RULE_NOWHERE_BOUND_ROOTS,
];
/**
 * ADR-0068 D1's four user spellings, in the order the message's tie-break
 * prefers them (canonical first — the #6585 ordering, with `os` appended so
 * the pre-existing three keep their exact precedence).
 */
const FIELD_RULE_USER_ROOTS = ['current_user', 'user', 'ctx', 'os'] as const;
/**
 * [#26646] The slot name an object's `fieldGroups[].visibleWhen` is judged
 * under: the field `visibleWhen` slot's root verdict, located on the group
 * and worded for it ({@link FIELD_RULE_SLOT_CONSEQUENCE}, {@link fieldRuleRootIssue}).
 */
const FIELD_GROUP_VISIBLE_WHEN_SLOT = 'field group visibleWhen';
/**
 * The slot-agnostic clause — provably true for any slot, specific to none.
 * Used where the honest answer is "not measured for this slot", never as a
 * softening of a cell that WAS measured.
 */
const FIELD_RULE_SLOT_CONSEQUENCE_GENERIC =
  'the predicate faults, and a faulting rule never produces the verdict you declared — each ' +
  'slot resolves the fault to its own fallback, and none of those fallbacks is yours';
/** Axis 1 — see "the consequence, by SLOT" above. Every cell is measured. */
const FIELD_RULE_SLOT_CONSEQUENCE: Record<string, string> = {
  visibleWhen:
    'the predicate no longer merely faults — and BOTH of its outcomes are wrong, in opposite ' +
    'directions. Under a host that publishes a predicate scope the renderer RESOLVES it ' +
    // `sectionFields` is spelled WITHOUT its `.ts` extension for the same
    // reason the `*.form` spelling below is: this is a STRING literal, and
    // #5017's receiver scan strips comments but not strings, so `sectionFields.ts`
    // inside the message registers `sectionFields` as a read receiver of this
    // rule. Measured — it went red on the first run, exactly as the sibling did.
    '(plugin-form\'s `sectionFields` copies this object rule onto the runtime form field and ' +
    '`resolveFieldRuleState` evaluates it with the host scope bound, the `current_user` binding ' +
    'ADR-0089 D1 gives every runtime record surface) — so the ' +
    'control is hidden in that one form while NO server-side gate evaluates a field-level ' +
    '`visibleWhen` at all: the record still carries the value and every other reader still ' +
    'returns it, a SILENT enforcement gap. Where no host publishes a scope (the console public ' +
    '`/f/:slug` route, and every non-form reader) the root is unbound, the predicate faults and ' +
    'the renderer falls back to VISIBLE (`resolveFieldRuleState` evaluates visibility with ' +
    '`fallback: true`), leaving the field the test was meant to hide showing for everyone. ' +
    'The gap is the WORSE of the two — a visible fail-open gets reported, and a ' +
    'silent one does not',
  readonlyWhen:
    'the predicate faults — and the two ends fault in OPPOSITE directions. The server treats ' +
    'the field as LOCKED (`isReadonlyWhenLocked` will not waive a declared lock it could not ' +
    'evaluate) and drops your value from the payload, while the form still renders the ' +
    'field editable (`fallback: false`). The server is the one that decides: ' +
    'the field looks writable, the save reports success, and the value silently never lands',
  requiredWhen:
    'the predicate faults on every write that reaches that root, and the server REFUSES a write ' +
    'whose requirement it cannot evaluate (ADR-0137 D2: the refusal names the field and the ' +
    'rule) — while the form does not mark the field required, so nothing on screen says why the ' +
    'save failed',
  // [#22227] The deadline's settle predicate (objectui#11815 ruling D) joins
  // the family on the `visibleWhen` side: display only, nothing on the write
  // path reads it. Its one consumer — objectui's date cells, the host
  // evaluating it per row — lands after the spec publishes, so there is no
  // runtime here to measure a fault direction against. The generic clause is
  // the honest cell until it does; re-measure and write the slot's own cell
  // then, as #6716 did for the other three.
  settledWhen: FIELD_RULE_SLOT_CONSEQUENCE_GENERIC,
  // [#26646] A field group's section predicate takes the field `visibleWhen`
  // slot's verdict, with its own fault direction: the form renderer's
  // section gate (`sectionGateVisible`) evaluates it with the same engine,
  // record assembly and host scope as a field's own `visibleWhen`, and
  // resolves a fault to HIDDEN, not visible.
  [FIELD_GROUP_VISIBLE_WHEN_SLOT]:
    'the predicate faults wherever no host publishes that root, and a field group\'s gate fails ' +
    'CLOSED: the whole group, header included, is hidden for everyone on that form or record page. ' +
    'Where a host does publish it, the renderer resolves it and the group hides in that one form ' +
    'only, while every other reader still returns the fields in it: a SILENT enforcement gap',
};

/**
 * The decision half of the rule documented above, as ONE exported function so
 * every surface that judges a field-level `*When` stands on the same verdict
 * AND the same message (Prime Directive #12). Two consumers today: the
 * metadata walk in {@link validateStackExpressions} below, and the docs-corpus
 * gate `scripts/check-doc-formula-expressions.mjs`, which judges the same
 * field-rule slots (the three siblings, and since #22227 a deadline's
 * `settledWhen`) where a fenced example's enclosing structure identifies the
 * field layer (#11407). Before that gate existed this lived as a closure inside the walk —
 * fine while there was one caller, and exactly how a second caller comes to own
 * a DIALECT of the rule instead of the rule.
 *
 * `null` = nothing to report: the source does not parse (the syntax pass owns
 * that, and reporting it twice under a worse name is the #4889 mistake), or
 * every root it reads is one the field level binds.
 */
export function fieldRuleRootIssue(
  slot: string,
  source: string,
): { root: string; message: string } | null {
  const roots = collectCelRootIdentifiers(source);
  if (!roots.ok) return null;
  // Filtered through the judged vocabulary, in its order — so a bare field
  // reference (owned by the bare-reference check one line up) and a CEL type
  // name (`type(record.x) == string`) can never land here.
  const kept = FIELD_RULE_JUDGED_ROOTS.filter(
    (r) => !(FIELD_RULE_BOUND_ROOTS as readonly string[]).includes(r) && roots.roots.includes(r),
  );
  if (kept.length === 0) return null;
  // One issue per slot even when a predicate reaches for two rejected roots.
  // User roots win the tie-break (canonical spelling first) so #6585's
  // message stays stable; anything else falls back to SCOPE_ROOTS order,
  // which is stable too — never AST walk order.
  const root = FIELD_RULE_USER_ROOTS.find((r) => kept.includes(r)) ?? kept[0]!;
  // [#26646] A field group has no options and is not a field: its user-root
  // prescription keeps only the two answers that apply to it.
  const userRoot = (FIELD_RULE_USER_ROOTS as readonly string[]).includes(root);
  const prescription = userRoot && slot === FIELD_GROUP_VISIBLE_WHEN_SLOT
    ? `To hide the group's fields by role, declare field-level security on a permission set ` +
      `for each field in the group (\`fields: { 'OBJECT.FIELD': { readable: false } }\`), which ` +
      `the server enforces. To gate the group on record state, rewrite the predicate against ` +
      `\`record\`.`
    : userRoot
    ? `To gate the CHOICES of a select by user, move the predicate to the option's own ` +
      `\`visibleWhen\` (\`options: [{ …, visibleWhen: … }]\`) — the rule validator evaluates ` +
      `that one against \`current_user\` and its ADR-0068 aliases on every write, so the gate ` +
      `holds server-side. To hide the FIELD by role, declare field-level security on a ` +
      `permission set (\`fields: { '<object>.<field>': { readable: false } }\`), which the ` +
      `server enforces. To gate on record state, rewrite the predicate against \`record\`. ` +
      `Note that a form VIEW's own field predicate HAS bound these roots since the form renderer ` +
      `took up the \`current_user\` binding ADR-0089 D1 gives every runtime record surface — ` +
      `but only in the renderer, so moving a server-enforced object rule there swaps a loud ` +
      `error for a silent enforcement gap; it is not a fourth answer.`
    : root === 'data'
      // The `*.form` spelling is deliberately not `*.form.ts`: this is a
      // STRING literal, and #5017's receiver scan strips comments but not
      // strings, so `form.ts` inside the message registers `form` as a read
      // receiver of this rule. Measured — it went red on the first run.
      ? `\`data\` is the root of a METADATA form (a \`*.form\` module — the metadata row ` +
        `being edited); ` +
        `this is an OBJECT field, whose runtime form binds the row as \`record\` — one key name, ` +
        `two form kinds, two roots. Rewrite \`data.<key>\` as \`record.<field>\`.`
      : (FIELD_RULE_NOWHERE_BOUND_ROOTS as readonly string[]).includes(root)
        // #13935, re-founded on decision batch #67. Everything the general
        // clause below says is false about these roots: they are NOT declared
        // platform-wide, and no evaluation site binds them — so "move the
        // decision to a surface that binds it" names no such surface. This tier
        // says the root is unbound EVERYWHERE, which is the one statement that
        // survives the batch.
        //
        // The pre-batch text said the renderer mounted it. That was true when
        // #13935 measured it and the batch ruled it away: the engine's declared
        // scope is the contract, ObjectUI aligned to it, and its scope builder
        // stopped binding this root. Naming the renderer here now would send an
        // author to a surface that no longer binds it either.
        //
        // The `record.<root>` rewrite is still refused IN THE MESSAGE rather
        // than merely omitted, and that refusal is what this tier exists to
        // keep: it is the advice the bare-reference check gives, and the second
        // diagnostic it earns (`unknown field`) names a different problem than
        // the one the author has. Emptying the constant instead of renaming it
        // would hand them exactly that advice again.
        //
        // No spec path is named: this is a STRING literal, and #5017's receiver
        // scan strips comments but not strings, so a module path inside the
        // message registers its first segment as a read receiver of this rule.
        // Measured on the sibling tiers — each went red on the first run.
        //
        // `record.` + the root is assembled with `+` for the same scan: written
        // as one template literal, `record.${'$'}{root}` reads as a member
        // access off a `record` receiver, because `$` is an identifier char.
        ? `\`${root}\` is NOT declared platform-wide, and no evaluation site binds it — not ` +
          `this one, and not any other: it is absent from the engine's declared scope, and ` +
          `decision batch #67 ruled that declared scope to be the contract, so the renderer ` +
          `that once mounted it beside \`current_user\` / \`user\` / \`ctx\` / \`os\` / \`data\` / ` +
          `\`features\` was aligned to the same set and no longer binds it either. The predicate ` +
          `therefore faults wherever it is written, and there is no surface to move it to. ` +
          `⛔ Do NOT write \`` + 'record.' + `${root}\`: \`${root}\` is not a field on this ` +
          `object, so that spelling only trades this diagnostic for an \`unknown field\` error ` +
          `on \`${root}\`. Rewrite the ` +
          `predicate against \`record\` (plus \`previous\`, and \`parent\` on a master-detail line ` +
          `item) — gate on record state, not on this root.`
        : `\`${root}\` is declared platform-wide and bound at OTHER evaluation sites (flow, ` +
        `automation, screen and action predicates), never at the field level. Rewrite the ` +
        `predicate against \`record\` (plus \`previous\`, and \`parent\` on a master-detail line ` +
        `item), or move the decision to a surface that binds \`${root}\`.`;
  return {
    root,
    message:
      (slot === FIELD_GROUP_VISIBLE_WHEN_SLOT
        ? `\`visibleWhen\` reads \`${root}\`, but a field group's section predicate binds only `
        : `\`${slot}\` reads \`${root}\`, but a field-level conditional rule binds only `) +
      `\`record\` (plus \`previous\`, and \`parent\` on a master-detail line item) — ` +
      `\`${root}\` is unbound here, so ` +
      `${FIELD_RULE_SLOT_CONSEQUENCE[slot] ?? FIELD_RULE_SLOT_CONSEQUENCE_GENERIC}. ` +
      prescription,
  };
}

/**
 * [#22228] The roots a field's cell formatting rule binds — the scope of each
 * `FieldSchema.conditionalFormatting[].condition`: `value`, this field's value
 * on the record, and `record`, the row the cell belongs to. Nothing else, by
 * the card's ruling: the host styling a cell has the row and the cell's value
 * in hand, and no write is in flight, so there is no `previous`; no inline
 * grid header, so there is no `parent`; and the field-rule family's user-root
 * refusal holds here for the same reason it holds there.
 *
 * `value` is NOT a platform root (`SCOPE_ROOTS` does not list it) and is not
 * added there: that list is the published strict-lint accept baseline, and a
 * root added to it stops every surface that judges bare identifiers from
 * faulting it. This surface names it to the shared validator instead, through
 * `ExprSchemaHint.roots` ({@link FIELD_FORMATTING_SURFACE_ROOTS}), which only
 * ever turns a refusal into an acceptance for this one call.
 */
export const FIELD_FORMATTING_BOUND_ROOTS = ['value', 'record'] as const;
/**
 * The bound roots this surface mounts BEYOND the platform baseline — what the
 * `check` closure hands `validateExpression` as `roots`. `record` is already a
 * `SCOPE_ROOTS` member, so only `value` is listed.
 */
const FIELD_FORMATTING_SURFACE_ROOTS: readonly string[] = FIELD_FORMATTING_BOUND_ROOTS.filter(
  (r) => !(SCOPE_ROOTS as readonly string[]).includes(r),
);

/**
 * [#22228] The root verdict for a field's cell formatting rule: a condition
 * that reads a root this surface does not bind — anything in
 * {@link FIELD_RULE_JUDGED_ROOTS} other than `record` (`value` is not in that
 * vocabulary at all). The same membership test as {@link fieldRuleRootIssue},
 * for the same reasons (an allowlist, judged by membership rather than by
 * declaredness), over this surface's own allowlist and in its own words: the
 * family's message names `previous` and `parent` as bound, and here neither is.
 *
 * `null` = nothing to report: the source does not parse (the syntax pass owns
 * that), or every root it reads is bound here.
 */
export function fieldFormattingRootIssue(
  location: string,
  source: string,
): { root: string; message: string } | null {
  const roots = collectCelRootIdentifiers(source);
  if (!roots.ok) return null;
  const kept = FIELD_RULE_JUDGED_ROOTS.filter(
    (r) => !(FIELD_FORMATTING_BOUND_ROOTS as readonly string[]).includes(r) && roots.roots.includes(r),
  );
  if (kept.length === 0) return null;
  // One issue per rule, user roots first (the family's tie-break), then the
  // judged vocabulary's own order — stable, never AST walk order.
  const root = FIELD_RULE_USER_ROOTS.find((r) => kept.includes(r)) ?? kept[0]!;
  return {
    root,
    message:
      `\`${location}\` reads \`${root}\`, but a field's conditional formatting rule binds only ` +
      `\`value\` (this field's value on the record) and \`record\` (the row the cell belongs to) — ` +
      `\`${root}\` is unbound where the cell is styled, so the condition faults and the rule never ` +
      `styles the cell. Rewrite the condition against \`value\` or \`record\`.`,
  };
}

/**
 * [#13935] Does this `@objectstack/formula` error carry the bare-reference
 * verdict for one of `roots`?
 *
 * Matched on the diagnostic's opening clause because it carries no code to
 * filter on — `validateExpression` pushes `{ source, message }` and nothing
 * else. The fragility that buys is bounded and made LOUD rather than left
 * silent: a reword upstream makes the suppression miss, a nowhere-bound root
 * then earns two diagnostics instead of one — the second of them carrying the
 * `record`-qualified rewrite this rule refuses by name — and the
 * `toHaveLength(1)` assertions in the residual-root table go red. ⛔ Do not
 * soften those to `toBeGreaterThan(0)` — the length is the pin.
 *
 * The parameter is `diagnostic` rather than `message` so #5017's receiver scan
 * reads the `.startsWith` below as this file's own plumbing instead of as a
 * read off a `message` metadata receiver, which is a real key elsewhere in the
 * spec (`validations[].message`).
 */
function isBareReferenceToAny(diagnostic: string, roots: readonly string[]): boolean {
  return roots.some((root) => diagnostic.startsWith(`bare reference \`${root}\``));
}

/**
 * [#22565] Whether `diagnostic` is the flattened-scope near-miss WARNING
 * `validateExpression` gives a bare non-field identifier on a flow condition
 * ("`X` is not a field of `obj` — did you mean …? If `X` is a flow variable this
 * is safe to ignore") about one of `roots`.
 *
 * The flow walk withdraws that warning at a site where the unbound-root judge
 * refuses the same root: the judge has read the flow's whole bound set, so "if it
 * is a flow variable" is already answered no, and one broken root earns one
 * finding. Matched on the leading sentence for the reason
 * {@link isBareReferenceToAny} gives; a reword upstream makes the withdrawal miss
 * LOUDLY — the root then carries two findings and the `toHaveLength(1)` pin in
 * `validate-expressions.flow-cel-root.test.ts` goes red.
 */
function isFlattenedNearMissFor(diagnostic: string, roots: readonly string[]): boolean {
  return roots.some((root) => diagnostic.startsWith(`\`${root}\` is not a field of`));
}

/**
 * [#20078] The field-level predicate slots a read THROUGH a reference field is
 * refused on: the two field-rule slots the server evaluates on a write, and a
 * select option's own `visibleWhen`.
 */
type FieldTraversalSlot = 'requiredWhen' | 'readonlyWhen' | 'option visibleWhen';

/** [#20078] A root a field-level predicate binds, with the record shape it binds. */
interface FieldTraversalHolder {
  root: 'record' | 'previous' | 'parent';
  /** Field name → declared type, for the object whose record this root binds. */
  types: Readonly<Record<string, string>>;
  /** That object's name — the prescription names it. */
  owner: string;
}

/**
 * [#20078] What the SERVER does with a field-level predicate that faults, per
 * slot. Every cell is the runtime's own behaviour at `rule-validator.ts`, and
 * `engine-field-predicate-fault.test.ts` pins each one end to end.
 */
const FIELD_TRAVERSAL_CONSEQUENCE: Record<FieldTraversalSlot, string> = {
  requiredWhen:
    'The server REFUSES every write that reaches this predicate — a requirement it cannot evaluate ' +
    'refuses the write, naming the field and the rule (ADR-0137 D2)',
  readonlyWhen:
    'The server REFUSES every update that writes this field — a lock it cannot evaluate refuses the ' +
    'write rather than dropping the value (ADR-0137 D2) — so the field can never be changed once the ' +
    'record exists',
  'option visibleWhen':
    'The server REFUSES every write by an acting user that picks this option — an option gate it ' +
    'cannot evaluate refuses the write, naming the option, the field and the fault (ADR-0137 D2)',
};

/**
 * [#20078] The refusal for a field-level predicate that reads THROUGH a
 * reference field — `record.account.tier` on a `lookup` named `account`.
 *
 * ## Why it is refused, and where it is not
 *
 * The field level is evaluated against the record it binds and nothing else:
 * no field-level `requiredWhen` / `readonlyWhen` and no option `visibleWhen` is
 * hydrated (ObjectQL's `rule-validator.ts`: "the field level is not hydrated at
 * all"). A reference field there holds the related record's bare ID, so every
 * read through it faults — on every row, whatever the data — and the runtime
 * can then only refuse the write (ADR-0137 D2: the two field-rule slots, and
 * since #22402 the option gate on the write path). Hydrating the field
 * level would be a capability of its own; until one exists, the predicate
 * cannot mean what it says, and `objectstack validate` is where the author
 * should hear it (NORTH-STAR priority rule 4) rather than from the first
 * refused write in production.
 *
 * The ONE seam that does read one hop through a reference is a `validations[]`
 * rule's `condition` (`checkPredicate`, #18682), which is why that is the
 * prescription for the `record` root — and why the same traversal written
 * there passes this pass untouched. It is NOT the prescription for `previous`
 * (never hydrated at any seam, a validation rule's included) or `parent` (bound
 * only for the field-rule slots, never for a validation rule), so those roots
 * get the repair that is true for them.
 *
 * ## The judgment is the runtime's, not a second copy of it
 *
 * Which fields a source reads through is `@objectstack/formula`'s
 * `analyzeRelationshipTraversals` — the analysis the engine itself runs
 * (`rule-validator.ts` names a field-rule fault's reference with it, and
 * hydrates a validation rule from it). Which fields are references is the
 * spec's `REFERENCE_VALUE_TYPES`, the set `validateExpression`'s own
 * traversal-conflict arm asks. An object-valued field (`record.address.city`)
 * is not a reference and is left alone.
 *
 * Only DECLARED fields are judged: the injected system columns
 * (`owner_id`, `created_by`, …) carry no type in this pass's index, so a read
 * through one is not refused here — the safe direction, a missed finding and
 * never a false one.
 */
function fieldTraversalMessage(
  slot: FieldTraversalSlot,
  root: FieldTraversalHolder['root'],
  field: string,
  fieldType: string,
  related: readonly string[],
  owner: string,
): string {
  const named = Array.from(related, (r) => `\`${r}\``).join(', ');
  // `root` + '.' is assembled with `+` so no template literal here spells a
  // member read off a receiver name the declared-key meta-test would pick up.
  const path = '`' + root + '.' + field + '`';
  const prescription = root === 'record'
    ? `Only a \`validations[]\` rule's \`condition\` reads one hop through a reference — the related ` +
      `record is loaded before it runs. Express the check as a \`validations[]\` \`script\` rule, or ` +
      `read a column this object declares.` +
      (slot === 'option visibleWhen'
        ? ` For a choice, the rule's \`condition\` states the FAILURE — this option picked while the ` +
          `related column disqualifies it; the option is then offered to everyone and refused on save.`
        : '')
    : root === 'previous'
      ? `\`previous\` is the stored row and is never read through a reference — not here, and not in a ` +
        `\`validations[]\` rule either — so there is no surface to move this read to. Compare ${path} ` +
        `itself (it holds the id), or read a column this object declares.`
      : `\`parent\` is the master-detail header as stored, so its references hold bare ids too, and no ` +
        `\`validations[]\` rule binds \`parent\` at all. Read a column '${owner}' declares instead ` +
        `(denormalise the value you need onto '${owner}').`;
  return (
    `\`${slot}\` reads ${named} through ${path}, a \`${fieldType}\` field — but a field-level predicate ` +
    `never reads the related record: there ${path} holds the related record's bare id, so the read ` +
    `faults on every row. ${FIELD_TRAVERSAL_CONSEQUENCE[slot]}. ${prescription}`
  );
}

/**
 * [#22157] The roots a select option's own `visibleWhen` binds, read off the
 * one server site that evaluates it: ObjectQL's `evaluateOptionVisibility`
 * (`rule-validator.ts`). That call hands the expression engine `record` (the
 * merged write), `previous`, the acting user and `permissions`, and nothing
 * else; `@objectstack/formula`'s `buildScope` turns that into these roots:
 *
 *  - `record`, and `previous` (bound on an update);
 *  - the acting user, under ADR-0068 D1's canonical `current_user` and the
 *    three aliases `buildScope` hangs the same object on: `user`, and the
 *    `user` member of `ctx` and of `os`. They are listed at bare-root
 *    granularity because that is what {@link collectCelRootIdentifiers}
 *    reports, the same reading as the runtime's own `USER_SCOPE_ROOTS` beside
 *    the evaluator. All four are bound only when the write carries a user; a
 *    system write takes the evaluator's "no acting user" branch by design,
 *    which is not what this verdict judges.
 *
 * `permissions` mounts NO root: it answers `current_user.can(…)` through the
 * environment (#18783), so it is absent here.
 *
 * `parent` is NOT bound. The write path binds a master-detail header for a
 * field's own `readonlyWhen` / `requiredWhen` only, so the field-rule verdict
 * one level up ({@link FIELD_RULE_BOUND_ROOTS}) accepts it and this one does
 * not.
 *
 * ⛔ A root joins this list in the same change that binds it in
 * `evaluateOptionVisibility`, never before.
 *
 * Two of these roots are accepted WHOLE here but bound only IN PART: `ctx` and
 * `os` carry just their `user` member at the option check. What they carry is
 * {@link OPTION_VISIBLE_WHEN_BOUND_MEMBERS}'s to say (#22274). And the acting
 * user itself — under all four spellings — carries only the members
 * {@link optionVisibleWhenUserMembers} derives (#22394).
 */
const OPTION_VISIBLE_WHEN_BOUND_ROOTS: readonly string[] = ['record', 'previous', 'current_user', 'user', 'ctx', 'os'];

/**
 * [#22274] The MEMBERS the option check binds under the two namespace roots
 * {@link OPTION_VISIBLE_WHEN_BOUND_ROOTS} accepts whole, read off the same
 * call as that list.
 *
 * `evaluateOptionVisibility` (`rule-validator.ts`) hands the evaluator
 * `{ record, previous, user, permissions }`. `@objectstack/formula`'s
 * `buildScope` builds `ctx` and `os` as containers, and from that context it
 * fills each with one member, `user` (ADR-0068 D1's alias of `current_user`,
 * the same `EvalUser` object). `os` gains `org` only from an `org` in the
 * context, and `os.env` only from an `env`. The option check passes neither,
 * and `ctx` has no other source in `buildScope` at all. So `os.org.id`,
 * `os.env` and `ctx.locale` are unbound at the option check, though `os.org`
 * is bound at other sites (a `formula` field, an expression `defaultValue`, a
 * seed value) and `os.env` at the seed loader. Measured through the built
 * `evaluateValidationRules` with an authenticated caller, each faults
 * (`No such key: org` / `env` / `locale`), and the write is refused (ADR-0137
 * D2; until #22402 the value was admitted).
 *
 * Only `ctx` and `os` are listed, and every member listed IS the acting user
 * (`buildScope` hangs the one `EvalUser` object on `current_user`, `user`,
 * `ctx.user` and `os.user`). So this map judges the FIRST member under each
 * namespace, and what the acting user carries one level further down
 * (`ctx.user.positions`, `os.user.roles`) is judged against
 * {@link optionVisibleWhenUserMembers}, exactly as `current_user.positions` is
 * (#22394).
 *
 * The test suite derives this list from the real `buildScope` and evaluator,
 * given the option check's context, so a member `buildScope` starts mounting
 * there, or one this list accepts that it never mounts, turns that test red.
 * ⛔ A member joins this list in the same change that binds it in
 * `evaluateOptionVisibility`, never before.
 */
const OPTION_VISIBLE_WHEN_BOUND_MEMBERS: Readonly<Record<string, readonly string[]>> = {
  ctx: ['user'],
  os: ['user'],
};

/**
 * [#22394] The two ROOTS the option check binds the acting user under. Its
 * other two spellings, `ctx.user` and `os.user`, are the members
 * {@link OPTION_VISIBLE_WHEN_BOUND_MEMBERS} lists. All four are one `EvalUser`
 * object (ADR-0068 D1), so all four are judged against one allowlist.
 */
const OPTION_VISIBLE_WHEN_USER_ROOTS: readonly string[] = ['current_user', 'user'];

/**
 * [#22394] The acting user as the option check's caller hands it over: the
 * return shape of ObjectQL's `buildEvalUser` (`engine.ts`) — the caller's id,
 * its scope-resolved `positions` and its organization id (`null` outside one),
 * and nothing else. The VALUES are irrelevant; only which keys are present
 * decides which members `buildScope` mounts.
 *
 * This is the one fact the allowlist below cannot read from code:
 * `@objectstack/lint` cannot depend on ObjectQL. ⛔ It changes in the same
 * change that changes `buildEvalUser`'s shape, never before — the rule
 * {@link OPTION_VISIBLE_WHEN_BOUND_MEMBERS} states for the call around it.
 */
const OPTION_CHECK_ACTING_USER: { id: string; positions: string[]; organizationId: string | null } = {
  id: '',
  positions: [],
  organizationId: null,
};

let optionVisibleWhenUserMembersMemo: readonly string[] | undefined;

/**
 * [#22394] The members of the acting user an option `visibleWhen` may read:
 * the members that are BOTH declared by the contract and bound by the option
 * check. Derived on first use from two sources, never written out here:
 *
 *  - **declared** — the keys of `EvalUserSchema` (`@objectstack/spec`, ADR-0068
 *    D1): `id`, `name`, `email`, `positions`, `isPlatformAdmin`,
 *    `organizationId`. `roles` is not among them: ADR-0090 D3 renamed it
 *    `positions`, with no alias.
 *  - **bound** — the keys of the object `@objectstack/formula`'s `buildScope`
 *    mounts as `current_user` for {@link OPTION_CHECK_ACTING_USER}, the very
 *    normalisation the evaluator runs (`createEvalUser`, which also derives
 *    `isPlatformAdmin` from `positions`).
 *
 * Where the two differ, either one refuses: a member is accepted only when
 * both name it. Measured before this verdict existed, through the built
 * `evaluateValidationRules` with an authenticated caller: `name` and `email`
 * are declared but never set at the option check (the engine passes neither),
 * so `current_user.email == '…'` faulted (`No such key: email`) and the value
 * was admitted; `roles` is bound nowhere and declared nowhere, and faulted the
 * same way. (Since #22402 such a fault refuses the write instead, ADR-0137 D2;
 * the build verdict still names it first.) Bound-but-undeclared is empty today,
 * and the test suite pins it empty: a member the evaluator mounted without a
 * declaration would be a capability the contract never promised.
 *
 * `current_user.can(object, verb)` is not a member read at all — it is a
 * receiver call the evaluator's environment answers from the permission map
 * (#18783) — so it never reaches this list.
 *
 * Memoised, and computed on first use rather than at module load: resolving a
 * `lazySchema` builds it, and the boot path imports this package.
 */
function optionVisibleWhenUserMembers(): readonly string[] {
  if (optionVisibleWhenUserMembersMemo !== undefined) return optionVisibleWhenUserMembersMemo;
  const declaredUserMembers = Object.keys(EvalUserSchema.shape);
  const actingUser = buildScope({ user: OPTION_CHECK_ACTING_USER })['current_user'];
  const boundUserMembers = actingUser !== null && typeof actingUser === 'object' ? Object.keys(actingUser) : [];
  optionVisibleWhenUserMembersMemo = declaredUserMembers.filter((m) => boundUserMembers.includes(m));
  return optionVisibleWhenUserMembersMemo;
}

/** `` `a`, `b` and `c` `` — names spelled for a message, in the order given. */
function tickedList(listedNames: readonly string[]): string {
  const tickedNames = listedNames.map((n) => '`' + n + '`');
  return tickedNames.length > 1
    ? `${tickedNames.slice(0, -1).join(', ')} and ${tickedNames[tickedNames.length - 1]}`
    : tickedNames.join('');
}

/** The members read under one root, in name order: hop, value and deeper reads alike. */
function membersReadUnder(found: RelationshipTraversalAnalysis): string[] {
  const { traversals, bareFields, multiHopFields } = found;
  return [...new Set([...Array.from(traversals, ([m]) => m), ...bareFields, ...multiHopFields])].sort();
}

/** The members read one hop below `member` of the analysed root, in name order. */
function membersReadThrough(found: RelationshipTraversalAnalysis, member: string): string[] {
  const { traversals } = found;
  for (const [m, reads] of traversals) {
    if (m === member) return [...reads].sort();
  }
  return [];
}

/** A CEL member path, spelled for a message: `` `root.member` ``. */
function celMemberPath(root: string, member: string): string {
  // Assembled with `+`: #5017's receiver scan reads string literals too, so a
  // literal CEL path in a message would register its root as a read receiver.
  return '`' + root + '.' + member + '`';
}

/**
 * [#22157] The root verdict for a select option's own `visibleWhen`: a root
 * the server's option check does not bind ({@link OPTION_VISIBLE_WHEN_BOUND_ROOTS})
 * is refused, located at the option.
 *
 * ## Why it is refused
 *
 * The evaluator faults on an unbound root (`Unknown variable: parent`,
 * measured through the real `evaluateValidationRules` with an authenticated
 * caller), and a faulting option predicate refuses every write by an acting
 * user that picks the option (ADR-0137 D2, since #22402 — it was fail-OPEN
 * until then: the value admitted and the gate never enforced). Either way the
 * declared gate never answers, and a gate the runtime cannot evaluate must not
 * pass a door (ADR-0049): the author hears it here, not from the first refused
 * write in production. Nothing else refused it: every root judged here is in
 * `SCOPE_ROOTS`, which the strict env declares, so the bare-reference check
 * stays silent on it. The case that made
 * the hole credible is `parent`, which the field-rule slots one level up accept
 * on an object with exactly one `master_detail`.
 *
 * ## Why the membership test is `SCOPE_ROOTS`, not the field-rule vocabulary
 *
 * The gap is exactly the roots that pass the strict env. A root outside
 * `SCOPE_ROOTS` (a nowhere-bound root such as `app`) is undeclared there, so
 * the bare-reference check already refuses it at error on this slot; judging
 * it here as well would give one mistake two verdicts. The test is an
 * ALLOWLIST read against that list, for the reason {@link fieldRuleRootIssue}
 * records (#6713): a root added to `SCOPE_ROOTS` is judged here the day it
 * lands, with no second list to copy it into.
 *
 * ## Members of a bound root (#22274)
 *
 * `ctx` and `os` pass the root test, but the option check fills them with
 * their `user` member only ({@link OPTION_VISIBLE_WHEN_BOUND_MEMBERS}). A
 * predicate that reads any other member of either (`os.org.id`, `os.env`,
 * `ctx.locale`) is refused by the same verdict, located at the same option,
 * when it reads no unbound root. The members a source reads are
 * `@objectstack/formula`'s `analyzeRelationshipTraversals` reading of that
 * root, so `os.org`, `os.?org`, `os['org']` and `has(os.org)` are one read. A
 * computed key (`os[k]`) names no member and is not judged.
 *
 * ## Members of the acting user (#22394)
 *
 * The same verdict judges what the acting user carries, under all four of its
 * spellings: the first member of `current_user` / `user`, and the member one
 * hop below `ctx.user` / `os.user`. Each is held to
 * {@link optionVisibleWhenUserMembers} — declared by `EvalUserSchema` AND bound
 * by the option check — so `current_user.roles` (renamed `positions` by
 * ADR-0090 D3) and `current_user.email` (declared, never set there) are
 * refused, read by the same reader and so in every spelling.
 *
 * With #22157 (roots) and #22274 (namespace members) this closes the family:
 * every receiver the option check binds has its members judged against a
 * declared source — `record` / `previous` against the object's fields (the
 * `unknown field` check in `validateExpression`), `ctx` / `os` against
 * {@link OPTION_VISIBLE_WHEN_BOUND_MEMBERS}, and the four spellings of the
 * acting user against {@link optionVisibleWhenUserMembers}. The test suite
 * enumerates the receivers off the real `buildScope` and pins that table.
 *
 * `null` = nothing to report: the source does not parse (the syntax pass owns
 * that), or every root and member it reads is one the option check binds.
 */
function optionVisibleWhenRootIssue(
  objectName: string | undefined,
  field: string,
  option: string,
  source: string,
): { root: string; message: string } | null {
  const roots = collectCelRootIdentifiers(source);
  if (!roots.ok) return null;
  const kept = SCOPE_ROOTS.filter(
    (r) => !OPTION_VISIBLE_WHEN_BOUND_ROOTS.includes(r) && roots.roots.includes(r),
  );
  if (kept.length === 0) return optionVisibleWhenMemberIssue(objectName, field, option, source, roots.roots);
  // One issue per option even when the predicate reads two unbound roots, in
  // `SCOPE_ROOTS` order: stable, never AST walk order. The author fixes one
  // and the next run names the other.
  const root = kept[0]!;
  const owner = objectName ? `'${objectName}'` : 'this object';
  const prescription = root === 'parent'
    ? `An option is judged against the record being written, never against its master-detail ` +
      `header: only a field's own \`readonlyWhen\` and \`requiredWhen\` bind \`parent\`, on an ` +
      `object with exactly one \`master_detail\`. To gate this choice on the header, read a column ` +
      `${owner} declares instead (denormalise the header value you need onto ${owner}).`
    : `\`${root}\` is declared platform-wide and bound at OTHER evaluation sites, never by the ` +
      `option check. Rewrite the predicate against \`record\` (plus \`previous\`), or against the ` +
      `acting user as \`current_user\`.`;
  return {
    root,
    message:
      `\`visibleWhen\` of option ${option} on field '${field}' reads \`${root}\`, but the server's ` +
      `option check binds only \`record\`, \`previous\` and the acting user (\`current_user\`, and ` +
      `its ADR-0068 aliases \`user\`, \`ctx\` and \`os\`), so \`${root}\` is unbound there. ` +
      `${FIELD_TRAVERSAL_CONSEQUENCE['option visibleWhen']}. ${prescription}`,
  };
}

/**
 * The clause every member refusal ends its consequence with: a member the
 * option check never sets is not only a fault, it also defeats the two
 * spellings an author reaches for to guard it.
 */
const OPTION_MEMBER_GUARD_CONSEQUENCE =
  'a `has()` test or an optional read of it never finds it set, so the option is refused on every ' +
  'write instead, or admitted on every write when the test is negated or the read\'s default passes';

/**
 * [#22274] The member half of {@link optionVisibleWhenRootIssue}: a member of
 * `ctx` or `os` the option check does not bind
 * ({@link OPTION_VISIBLE_WHEN_BOUND_MEMBERS}) — and [#22394] a member of the
 * acting user it does not bind ({@link optionVisibleWhenUserMembers}), under
 * `current_user` / `user` or one hop below `ctx.user` / `os.user`. One finding
 * per option, the first unbound member in `SCOPE_ROOTS` order, then (under a
 * namespace) the namespace's own member before the acting user's, then in name
 * order: stable, never AST walk order.
 *
 * The message names the member, says what the option check DOES bind there,
 * and gives the remedy that is true for the member. For `os.org` that is
 * `current_user.organizationId`: the engine builds the acting user with the
 * caller's organization id (`null` outside one), so that one organization fact
 * IS bound at the option check.
 */
function optionVisibleWhenMemberIssue(
  objectName: string | undefined,
  field: string,
  option: string,
  source: string,
  roots: readonly string[],
): { root: string; message: string } | null {
  for (const root of SCOPE_ROOTS) {
    if (!roots.includes(root)) continue;
    const namespaceMembers = OPTION_VISIBLE_WHEN_BOUND_MEMBERS[root];
    const isUserRoot = OPTION_VISIBLE_WHEN_USER_ROOTS.includes(root);
    if (namespaceMembers === undefined && !isUserRoot) continue;
    const found = analyzeRelationshipTraversals(source, root);
    if (found === null) continue;
    const membersRead = membersReadUnder(found);
    if (isUserRoot) {
      const member = membersRead.find((m) => !optionVisibleWhenUserMembers().includes(m));
      if (member !== undefined) return optionVisibleWhenUserMemberIssue(objectName, field, option, root, member);
      continue;
    }
    const member = membersRead.find((m) => !namespaceMembers!.includes(m));
    if (member !== undefined) {
      return optionVisibleWhenNamespaceMemberIssue(objectName, field, option, root, member);
    }
    // [#22394] Every member the namespace binds IS the acting user, so what is
    // read one hop below it is the acting user's member.
    for (const userMember of namespaceMembers!) {
      const below = membersReadThrough(found, userMember).find((m) => !optionVisibleWhenUserMembers().includes(m));
      if (below !== undefined) {
        return optionVisibleWhenUserMemberIssue(objectName, field, option, `${root}.${userMember}`, below);
      }
    }
  }
  return null;
}

/** [#22274] The refusal of a `ctx` / `os` member the option check does not bind. */
function optionVisibleWhenNamespaceMemberIssue(
  objectName: string | undefined,
  field: string,
  option: string,
  root: string,
  member: string,
): { root: string; message: string } {
  const path = celMemberPath(root, member);
  const owner = objectName ? `'${objectName}'` : 'this object';
  const prescription = root === 'os' && member === 'org'
    ? `The option check binds no organization. The one organization fact it carries is the acting ` +
      `user's: ${celMemberPath('current_user', 'organizationId')} holds the caller's organization ` +
      `id (\`null\` outside one), so compare that instead. Any other fact about the organization ` +
      `cannot gate an option; read a column ${owner} declares.`
    : root === 'os' && member === 'env'
      ? `The option check binds no deployment environment (${path} is bound only where an ` +
        `evaluation is given one, such as a seed value), so the choices a record offers cannot ` +
        `depend on it there. Gate on a column ${owner} declares, or on the acting user as ` +
        `\`current_user\`.`
      : `Whatever other evaluation sites bind under \`${root}\`, the option check binds only its ` +
        `\`user\` member. Rewrite the predicate against \`record\` (plus \`previous\`), or against ` +
        `the acting user as \`current_user\`.`;
  return {
    root,
    message:
      `\`visibleWhen\` of option ${option} on field '${field}' reads ${path}, but the server's ` +
      `option check binds only \`record\`, \`previous\` and the acting user (\`current_user\`, and ` +
      `its ADR-0068 aliases \`user\`, \`ctx\` and \`os\`), and under \`${root}\` it binds the ` +
      `\`user\` member and nothing else, so ${path} is unbound there. ` +
      `${FIELD_TRAVERSAL_CONSEQUENCE['option visibleWhen']}; ${OPTION_MEMBER_GUARD_CONSEQUENCE}. ${prescription}`,
  };
}

/**
 * [#22394] The refusal of a member of the acting user the option check does
 * not bind. `receiver` is the spelling the author wrote (`current_user`,
 * `user`, `ctx.user` or `os.user`), so the remedy is written back in it.
 *
 * Three remedies, by what the member is:
 *
 *  - `roles` / `role` — not an `EvalUser` member at all: ADR-0090 D3 renamed
 *    the membership array `positions`, one-step, with no alias. The remedy is
 *    the rename, `'NAME' in RECEIVER.positions`.
 *  - a member `EvalUserSchema` declares but the option check never sets
 *    (`name`, `email`) — real on a surface that is handed a fuller user, never
 *    here: the engine builds the acting user from the caller's id, positions
 *    and organization id only. The remedy is a bound member, or a column.
 *  - anything else — a member nobody declares. The remedy is the bound list.
 */
function optionVisibleWhenUserMemberIssue(
  objectName: string | undefined,
  field: string,
  option: string,
  receiver: string,
  member: string,
): { root: string; message: string } {
  const path = celMemberPath(receiver, member);
  const owner = objectName ? `'${objectName}'` : 'this object';
  const carried = tickedList(optionVisibleWhenUserMembers());
  const declared = Object.keys(EvalUserSchema.shape).includes(member);
  const prescription = member === 'roles' || member === 'role'
    ? `The acting user has no \`${member}\`: ADR-0090 D3 renamed its membership array ` +
      `${celMemberPath(receiver, 'positions')} — the built-in identity and position names the user ` +
      `holds — with no alias. Write \`'NAME' in ${receiver}.positions\` instead.`
    : declared
      ? `\`${member}\` is declared on the acting user (\`EvalUser\`) but the server builds the user ` +
        `for this check from the caller's ${tickedList(Object.keys(OPTION_CHECK_ACTING_USER))} only, ` +
        `so it is never set here, whichever surface sets it elsewhere. Gate on a member the check ` +
        `binds, or on a column ${owner} declares.`
      : `\`${member}\` is not a member of the acting user (\`EvalUser\`). Gate on a member the check ` +
        `binds, or on a column ${owner} declares.`;
  return {
    root: receiver,
    message:
      `\`visibleWhen\` of option ${option} on field '${field}' reads ${path}, but the acting user the ` +
      `server's option check binds (\`current_user\`, and its ADR-0068 aliases \`user\`, ` +
      `${celMemberPath('ctx', 'user')} and ${celMemberPath('os', 'user')}) carries ${carried} and ` +
      `nothing else, so ${path} is unbound there. ` +
      `${FIELD_TRAVERSAL_CONSEQUENCE['option visibleWhen']}; ${OPTION_MEMBER_GUARD_CONSEQUENCE}. ${prescription}`,
  };
}

/**
 * [#24720, #24957] The root verdict for a `validations[]` rule's own predicates — a
 * `script` / `cross_field` rule's `condition`, a `conditional` rule's `when`,
 * and the same two slots on every rule nested in its `then` / `otherwise`: a
 * predicate that reads `parent` is refused, at `error`.
 *
 * ## Why it is reported
 *
 * ObjectQL evaluates every one of those predicates in `ruleScope(record,
 * previous)` (`rule-validator.ts`: `checkPredicate`, `checkConditional`), which
 * binds `record` and `previous` and no master-detail header. The header is
 * bound as `parent` for a field's own `readonlyWhen` / `requiredWhen` only
 * ({@link FIELD_RULE_BOUND_ROOTS}), on an object with exactly one
 * `master_detail`. So the predicate faults (`Unknown variable: parent`) on
 * every write it judges, and an unevaluable rule fails closed: the write is
 * refused, the seed's own rows at boot included. Nothing else named it,
 * because `parent` is in `SCOPE_ROOTS`, which the strict env declares, so the
 * bare-reference check stays silent. The field-rule slots one level up accept
 * the same text, which is what makes it the shape an author copies.
 *
 * ## Why an error
 *
 * A rule the runtime cannot evaluate must not pass a door (ADR-0049), so the
 * verdict is `error`: it fails `os build` and the object save door refuses a
 * publish-mode write that carries it. The rule is judged as written, so a rule
 * marked `active: false`, a rule whose `events` a stack never fires, and a
 * `conditional` branch whose `when` is never true are refused too. No ADR-0087
 * conversion can rewrite a predicate that reads `parent`; the repair is the
 * author's. The refusal ships without a deprecation window under the standing
 * ruling (甲, as amended: a protocol narrowing ships as soon as it can, with no
 * retirement release), which first shipped this verdict at `warning`.
 *
 * ## Why `parent` alone
 *
 * This is the one root the record's own field rules bind and its validation
 * rules do not: the credible copy, the one the runtime's own diagnostics name.
 * Whether the other platform-wide roots the rule evaluator binds no more of
 * (the acting user's among them) earn the same verdict is not decided here,
 * because neither the runtime nor its callers were measured for them.
 *
 * ⛔ This verdict is withdrawn in the same change that binds `parent` for a
 * `validations[]` rule, never before.
 *
 * `null` = nothing to report: the source does not parse (the syntax pass owns
 * that), or it reads no `parent`.
 */
function validationRuleParentIssue(
  objectName: string | undefined,
  ruleName: string,
  slot: 'condition' | 'when',
  source: string,
): string | null {
  if (!readsParentRoot(source)) return null;
  const owner = objectName ? `'${objectName}'` : 'this object';
  return (
    `\`${slot}\` of validation rule '${ruleName}' reads \`parent\`, but the server evaluates a ` +
    `\`validations[]\` rule against \`record\` and \`previous\` only, so \`parent\` is unbound there. ` +
    `The rule can never be evaluated, and the server REFUSES every write it judges — a rule that ` +
    `cannot be evaluated fails closed, seed rows included. The master-detail header is bound as ` +
    `\`parent\` only for a field's own \`readonlyWhen\` and \`requiredWhen\`, on an object with exactly ` +
    `one \`master_detail\`: to lock or require a field on the header's state, write the predicate on ` +
    `that field's \`readonlyWhen\` or \`requiredWhen\` instead. For any other check, read a column ` +
    `${owner} declares (denormalise the header value you need onto ${owner}).`
  );
}

/**
 * [#20078] The master object of an object with exactly ONE `master_detail`
 * relationship — the record the field level binds as `parent` — or `undefined`
 * when there is not exactly one (the #4889 gate above owns that verdict).
 *
 * The literal `.reference` read stays in the argument for the #5017 receiver
 * scan, exactly as in {@link masterDetailCount}.
 */
function singleMasterOf(obj: AnyRec): string | undefined {
  const targets: string[] = [];
  for (const [, def] of fieldEntries(obj)) {
    if (def.type !== 'master_detail') continue;
    const ref = referenceCarrierOf({ reference: def.reference }, 'validate-expressions singleMasterOf');
    if (ref !== undefined && ref.trim() !== '') targets.push(ref.trim());
  }
  return targets.length === 1 ? targets[0] : undefined;
}

/**
 * [#24316] An object's reference fields whose target is a stored-metadata-body
 * table ({@link isStoredMetadataBodyObject}), field → target. A hop through one
 * of them is the read ObjectQL's one-hop loader refuses for both seams that
 * serve a hop, so the lint refuses it where it is written.
 *
 * The literal `.reference` read stays in the argument for the #5017 receiver
 * scan, exactly as in {@link masterDetailCount}. Only the authored carrier is
 * read: a type whose target is implied never implies the family. A `tree`
 * field's authored `reference` cannot name it (the object schema refuses any
 * target but the declaring object); a `user` field's authored `reference` is
 * not refused at parse, so a `user` naming the family is collected too
 * (#24677 measured it).
 */
function storedMetadataBodyReferencesOf(obj: AnyRec): Map<string, string> {
  const out = new Map<string, string>();
  for (const [name, def] of fieldEntries(obj)) {
    if (typeof def.type !== 'string' || !REFERENCE_VALUE_TYPES.has(def.type)) continue;
    const ref = referenceCarrierOf({ reference: def.reference }, 'validate-expressions storedMetadataBodyReferencesOf');
    if (ref !== undefined && isStoredMetadataBodyObject(ref.trim())) out.set(name, ref.trim());
  }
  return out;
}

/**
 * [#24316] The refusal of a one-hop read into a stored-metadata-body table, at
 * one of the two sites that serve a hop. It names the reference, the table and
 * the columns read, and never anything a row holds.
 */
function storedMetadataBodyHopMessage(
  site: 'formula' | 'rule',
  field: string,
  target: string,
  columns: string,
): string {
  const consequence = site === 'formula'
    ? 'so this formula reads null on every row'
    : 'so this rule has no verdict and every write it judges is refused';
  const read = celMemberPath('record', field);
  return `${read} is a reference to '${target}', a stored-metadata table, and this ${site} reads `
    + `${columns} through it. A formula or a validation rule never reads through `
    + `a reference into a stored-metadata table: the hop is not read, ${consequence}. Those rows carry stored `
    + 'metadata bodies, which are served only through the metadata API (`GET /api/v1/meta/:type/:name`), '
    + `where the body is projected. Remove the read through \`${field}\`; ${read} alone is the `
    + 'stored id, if the id is what you need.';
}

/**
 * [#24677] The refusal of the declaration every hop above presupposes: a
 * `lookup` or `master_detail` field (or any other type the collector admits)
 * whose `reference` is a stored-metadata-body table
 * ({@link storedMetadataBodyReferencesOf}). The engine never hydrates
 * such a field — `expand` keeps its stored id, and a master-detail `parent`
 * root over a family header stays unbound — so the field saves and never
 * works. It names the field, its type, the target and the rule, and ends on
 * the family's one prescription, as the hook-body and flow-write refusals do.
 *
 * Worded apart from {@link storedMetadataBodyHopMessage} on purpose ("a table
 * of stored metadata", never that message's "a stored-metadata table"), so
 * the hop refusal's pins, which select its findings by that phrase, read the
 * hop refusal alone.
 */
function storedMetadataBodyReferenceMessage(field: string, type: string, target: string): string {
  const consequence = type === 'master_detail'
    ? 'a formula or a validation rule never reads through the field, and this object\'s `parent` root stays '
      + 'unbound, so every write a `parent` rule judges is refused'
    : 'and a formula or a validation rule never reads through the field';
  return `\`${field}\` is a \`${type}\` whose \`reference\` names '${target}', a table of stored metadata. `
    + 'A relationship field may not target a stored-metadata-body table: the engine never '
    + `hydrates one, so \`$expand\` keeps the stored id and never nests the row, ${consequence}. `
    + 'Those rows carry stored metadata bodies, served only '
    + 'through the metadata API (`GET /api/v1/meta/:type/:name`), where the body is projected; to point a '
    + 'record at a metadata item, store its type and name in `text` fields instead. '
    + STORED_METADATA_BODY_PRESCRIPTION;
}

/**
 * [#24410] The refusal of a formula's one-hop read of a field the reference's
 * target does not declare. It opens in the shared validator's `unknown field`
 * words, so the two first-segment and second-segment verdicts read as one
 * family, and names the read, the target and where the field would have to be
 * declared — never on the object carrying the formula.
 *
 * [#24468] The same refusal for a validation rule's hydrated `condition`; only
 * the consequence differs: the rule has no verdict, so every write it judges
 * is refused.
 */
function undeclaredHopFieldMessage(
  site: 'formula' | 'rule',
  objectName: string,
  field: string,
  target: string,
  column: string,
): string {
  const consequence = site === 'formula'
    ? 'so the formula reads null on every row'
    : 'so the rule has no verdict and every write it judges is refused';
  return `unknown field \`${column}\` on \`${target}\`: this ${site} reads it through the reference `
    + `${celMemberPath('record', field)}, and '${target}' declares no field '${column}', ${consequence}. `
    + `Read a field '${target}' declares, or declare '${column}' on '${target}' — not on `
    + `'${objectName}', the object carrying this ${site}.`;
}

/**
 * [#17495] Why a structural condition whose SHAPE is fine is still not
 * authorable: its source is blank. The author-time twin of the gate #17322 put
 * in `AutomationEngine.registerFlow`, spelled the same way against the same
 * imported schema, so `objectstack validate` and `registerFlow` refuse one set.
 *
 * Applied to the SOURCE rather than to the whole value on purpose — the same
 * decision, for the same reason, as the engine's copy: the union would also
 * refuse an envelope carrying no `dialect` or one outside its enum, and both
 * are admitted at this slot (`structuralConditionRefusal`'s docblock, and
 * #4336's ruling), so handing it the whole value would widen this narrowing
 * past what was ruled.
 *
 * Reached only after `structuralConditionRefusal` has cleared the value, so
 * `raw` is bare text or an envelope carrying a string `source`; the `typeof`
 * guard is what makes that precondition local rather than assumed.
 *
 * @returns the refusal and the source to attribute it to, or `undefined` when
 *   the source is non-blank and this rule has nothing to say.
 */
function evaluatedSourceRefusal(raw: unknown): { message: string; source: string } | undefined {
  const source = typeof raw === 'string' ? raw : (raw as { source?: unknown }).source;
  if (typeof source !== 'string') return undefined;
  const verdict = EvaluatedExpressionInputSchema.safeParse(source);
  if (verdict.success) return undefined;
  return { message: verdict.error.issues[0]?.message ?? EVALUATED_EXPRESSION_SOURCE_REQUIRED, source };
}

/** Options for {@link runStackExpressionPasses}. */
export interface StackExpressionOptions {
  /**
   * [#22019] The singular metadata type of the per-write snapshot the runtime
   * publish gate is judging (`AuthoringRuleContext.runtimeWriteType`, passed
   * through by this rule's registry entry). ABSENT on `os build`, `os lint`
   * and `os validate`, which run every pass below.
   *
   * On an `object` write exactly FIVE passes judge — every pass over the
   * object's own body — each the build's own call at the build's own position
   * in the walk:
   *
   *  - the field-formula pass over `fields[].expression` — the build's
   *    `validateExpression('value', …)` call, with its warnings and the
   *    unprovisioned-anchor warning on the same key. That is the verdict
   *    `formulas.mdx` says backs both `os build` and metadata registration,
   *    and the save door gave none of it: a formula calling an unregistered
   *    function (`sqrt(record.amount)`) saved with a 200 and read `null` on
   *    every row (#22019);
   *  - [#22032, pass 1] the validation-rule pass over `validations[]` — the
   *    `condition` (with the relationship-traversal checks the rule validator
   *    serves) and the `conditional` rule's `when`, plus the #4763 null-guard
   *    gate over every predicate the rule carries, its nested `then` /
   *    `otherwise` branches included. The same sentence of `formulas.mdx`
   *    covers it, and the door gave none of it either: a rule whose
   *    `condition` called `sqrt` or read a bare `amount` saved with a 200 and
   *    then faulted on every write the rule judged;
   *  - [#22032, pass 2] the field-rule-slot pass over `fields[]` — each of
   *    `requiredWhen` / `readonlyWhen` / `visibleWhen` (and, since #22227, a
   *    deadline's `settledWhen`; `conditionalRequired` left with its tombstone, #25767)
   *    as a `record`-scoped predicate with its root verdict, plus the `parent`
   *    gate (a `readonlyWhen` / `requiredWhen` reading `parent` on an object
   *    without exactly one `master_detail`), the #4811 null-guard gate over
   *    `requiredWhen`, and the #20078 refusal of a `requiredWhen` /
   *    `readonlyWhen` read through a reference field. The same sentence of
   *    `formulas.mdx` covers it, and the door gave none of it either: a
   *    `requiredWhen` reading a bare `amount` saved with a 200, and the server
   *    refuses a write whose requirement it cannot evaluate (ADR-0137 D2);
   *  - [#22032, pass 3] the per-option `visibleWhen` pass over
   *    `fields[].options[]` — each option's predicate on the `record` scope,
   *    plus the #20078 refusal of a read through a reference field. The build
   *    accepts `current_user` there (ADR-0068 D1; the option evaluator binds
   *    it) and refuses it one level up on the field-rule slots, and the door
   *    gives both verdicts as the build gives them. The same sentence of
   *    `formulas.mdx` covers it, and the door gave none of it either: an
   *    option whose `visibleWhen` read a bare `amount` saved with a 200, and
   *    the server's option check cannot evaluate it, so every write that picks
   *    the option is refused (ADR-0137 D2; until #22402 it failed open and the
   *    gate it declares was never enforced). Since
   *    #22157 the pass also refuses a root that option check does not bind
   *    (`parent` above all), at both doors through this same call; since
   *    #22274 a member of `ctx` / `os` it does not fill, and since #22394 a
   *    member of the acting user it does not bind (`current_user.roles`);
   *  - [#22032, pass 4] the object's own `actions[]` pass — each action's
   *    `visible`, and its `disabled` unless that is a boolean literal, as a
   *    `record`-scoped predicate (`checkAction` below). The same sentence of
   *    `formulas.mdx` covers it, and the door gave none of it either: an
   *    action whose `visible` read a bare `amount` saved with a 200, and the
   *    action runtime's fail-closed evaluation then hides the action on every
   *    record. One location differs from the build, never the verdict: an
   *    action ALSO declared in the stack's top-level `actions` is located by
   *    the build at `stack · action …` (the de-duplication in `checkAction`),
   *    while an object write carries no top-level actions, so the door locates
   *    the same predicate at `object '…' · action …`.
   *
   * [#24798] A sixth judges an object write too: the bulk `confirmText`
   * pass over the object's own `listViews` (`bulkConfirmTextIssues`), errors
   * since #25205. On a `view` write that pass is the ONLY one, over the
   * written view's `list` and `listViews` — every other pass reads a
   * collection a view write does not carry.
   *
   * [#24814] An action's copy pass (`actionCopyTemplateIssues`, errors since
   * #25680, a holeless `${…}` sentence included since #25709) judges an object
   * write's own `actions[]`; on a `page` write it is the ONLY pass, over the
   * written page's action rows and inline actions.
   *
   * The passes over the stack's OTHER collections — flows, the top-level
   * `actions`, sharing rules and hooks — read an empty list on an object
   * write. None of them is the object's own body, the object write's snapshot
   * does not carry them, and each is judged at its own type's door; the claim
   * holds by construction rather than by the snapshot's shape.
   */
  runtimeWriteType?: string;
}

/**
 * Validate every predicate in the stack. Returns the list of issues (empty =
 * clean). Caller decides how to surface / whether to fail the build.
 */
export function validateStackExpressions(stack: AnyRec): ExprIssue[] {
  return runStackExpressionPasses(stack, {});
}

/**
 * {@link validateStackExpressions} with the runtime publish gate's write type
 * — the one body both run, so the CLI and the door cannot drift apart.
 *
 * [#22019] Kept OFF the package's public entry on purpose: the write type is
 * the gate's private input, read only by this rule's registry entry
 * (`authoring-rules.ts`), and the published `validateStackExpressions(stack)`
 * keeps the signature it always had.
 */
export function runStackExpressionPasses(stack: AnyRec, options: StackExpressionOptions): ExprIssue[] {
  const issues: ExprIssue[] = [];
  // [#22019] See {@link StackExpressionOptions.runtimeWriteType}: on an object
  // write only the passes over the object's own body judge: the field-formula
  // pass and (#22032) the validation-rule, field-rule-slot, per-option
  // `visibleWhen` and object-action passes. Every loop below over another
  // collection — flows, the top-level `actions`, sharing rules, hooks — reads
  // an empty list under it, so the claim holds by construction rather than by
  // the shape of the snapshot the gate happens to build today.
  const objectWrite = options.runtimeWriteType === 'object';
  // [#24798] On a `view` write exactly ONE pass judges — the bulk `confirmText`
  // pass over the written view's own list containers ({@link bulkConfirmTextIssues});
  // every other pass reads a collection a view write does not carry, so it
  // returns before them by construction rather than by snapshot shape.
  if (options.runtimeWriteType === 'view') return bulkConfirmTextIssues(stack, { views: true, objects: false });
  // [#24814] On a `page` write exactly ONE pass judges too — the action copy
  // pass over the written page's action rows and inline actions
  // (`validate-action-copy-templates.ts`), whose findings are errors (#25680).
  if (options.runtimeWriteType === 'page') {
    return actionCopyTemplateIssues(stack, { actions: false, objects: false, pages: true });
  }
  const objects = recordsOf(stack.objects);
  const fieldIndex = buildFieldIndex(objects);
  const attachedOnReadIndex = buildAttachedOnReadIndex(objects);
  const fieldTypeIndex = buildFieldTypeIndex(objects);
  const nullableIndex = buildNullableFieldIndex(objects);
  // [#24316] object name → its references into a stored-metadata-body table,
  // read the first time a site of that object serves a hop, or (#24677) when
  // the walk reaches the object's fields, whichever comes first — never before
  // the walk reaches the object, so a carrier the spec cannot read is refused
  // by the pass that owned that verdict before this one existed.
  const storedMetadataBodyReferenceIndex = new Map<string, Map<string, string>>();
  const storedMetadataBodyReferencesFor = (objectName: string): Map<string, string> => {
    let familyRefs = storedMetadataBodyReferenceIndex.get(objectName);
    if (!familyRefs) {
      familyRefs = new Map();
      for (const obj of objects) if (obj.name === objectName) familyRefs = storedMetadataBodyReferencesOf(obj);
      storedMetadataBodyReferenceIndex.set(objectName, familyRefs);
    }
    return familyRefs;
  };
  /**
   * [#24316] Refuse a one-hop read through a reference into a
   * stored-metadata-body table, at the two sites that serve a hop: a
   * validation rule's hydrated `condition` or `when` ({@link check} with
   * `traversalHydration`) and a formula field's `expression`
   * ({@link judgeFieldFormula}). ObjectQL's one-hop loader never reads that
   * hop, so as written the field reads null or the rule refuses every write;
   * this says so where the expression is written, with the prescription.
   */
  const refuseStoredMetadataBodyHop = (
    where: string,
    raw: unknown,
    objectName: string,
    site: 'formula' | 'rule',
  ): void => {
    const source = celSourceOf(raw);
    if (!source) return;
    const traversals = analyzeRelationshipTraversals(source, 'record')?.traversals;
    if (!traversals || traversals.size === 0) return;
    const familyRefs = storedMetadataBodyReferencesFor(objectName);
    for (const [field, columns] of traversals) {
      const target = familyRefs.get(field);
      if (!target) continue;
      issues.push({
        where,
        message: storedMetadataBodyHopMessage(site, field, target, Array.from(columns, (c) => `'${c}'`).sort().join(', ')),
        source,
        severity: 'error',
      });
    }
  };

  /**
   * [#24410] Refuse a formula's one-hop read of a field the reference's target
   * does not declare (`record.book.name` where the book declares no `name`).
   * ObjectQL's one-hop loader reads only declared columns of the target, so as
   * written the formula reads null on every row; this says so where it is
   * written, at the build and at the object save door alike.
   *
   * [#24468] The two sites that serve a hop share it: a formula field's
   * `expression` ({@link judgeFieldFormula}) and a validation rule's hydrated
   * `condition` or `when` ({@link check} with `traversalHydration`), where the
   * rule has no verdict and refuses every write it judges.
   *
   * Judged against the target's field index — its declared fields and the
   * system columns the platform injects on it, the set the registry carries —
   * and the primary key, which no field map carries and the loader reads. A
   * target outside the stack (or the door's snapshot, which carries the live
   * registry's objects, another package's included) has no index here and is
   * not judged; a hop into the stored-metadata-body family is refused by
   * {@link refuseStoredMetadataBodyHop} and not judged twice.
   */
  const refuseUndeclaredHopField = (
    where: string,
    raw: unknown,
    objectName: string,
    site: 'formula' | 'rule',
  ): void => {
    const source = celSourceOf(raw);
    if (!source) return;
    const analysis = analyzeRelationshipTraversals(source, 'record');
    const traversals = analysis?.traversals;
    if (!traversals || traversals.size === 0) return;
    for (const obj of objects) {
      if (obj.name !== objectName) continue;
      for (const [field, def] of fieldEntries(obj)) {
        // [#24468] A reference read more than one hop deep is refused whole by
        // the traversal checks; its first column is not judged a second time.
        const columns = analysis?.multiHopFields.has(field) ? undefined : traversals.get(field);
        const target = columns ? referenceTargetOf(def)?.trim() : undefined;
        if (!columns || !target || isStoredMetadataBodyObject(target) || !fieldIndex.has(target)) continue;
        for (const column of [...columns].sort()) {
          if (column === 'id' || fieldIndex.get(target)?.includes(column)) continue;
          issues.push({
            where,
            message: undeclaredHopFieldMessage(site, objectName, field, target, column),
            source,
            severity: 'error',
          });
        }
      }
    }
  };

  // [#8116] object name → the injected anchors registered with NO storage
  // behind them (non-empty only for ADR-0015 `external` objects). The other
  // half of {@link buildFieldIndex}'s #5378 widening: the anchors ARE
  // addressable — the field-existence pass rightly resolves them — but on a
  // federated object nothing backs them, so a predicate over one silently
  // matches nothing. Existence stays green; provenance warns.
  const unprovisionedIndex = new Map<string, ReadonlySet<string>>();
  for (const obj of objects) {
    const name = typeof obj.name === 'string' ? obj.name : undefined;
    if (!name) continue;
    const anchors = unprovisionedInjectedColumnsFor(obj);
    if (anchors.size > 0) unprovisionedIndex.set(name, anchors);
  }

  /**
   * [#8116] The unprovisioned-anchor warning — the author-time half of the
   * #7865 provenance marker (runtime halves: #7833 / #7859 / #7858). Fires on
   * a `record.<anchor>` / `previous.<anchor>` read where the anchor is an
   * injected system column the platform registers on this `external` object
   * but provisions no storage for.
   *
   * `warning`, not `error`, on the #7219 family's criterion: an error needs a
   * closed oracle, and this pass cannot see the remote table — it knows the
   * anchor has no PLATFORM storage, not what the deployment's remote schema or
   * a runtime plugin might resolve. The runtime degradation is also non-fatal
   * (silently empty results), the class this package reports advisorily; and
   * the security-critical member of the class is already fenced at runtime by
   * the #7859/#7858 guards. An author-DECLARED column of the same name is the
   * author's (`'author'` provenance — it maps a remote column they vouch for)
   * and never enters the index, so the tenant-wall case #7859 protects stays
   * silent here too.
   */
  const warnUnprovisionedAnchors = (where: string, raw: unknown, objectName?: string): void => {
    if (!objectName) return;
    const anchors = unprovisionedIndex.get(objectName);
    if (!anchors) return;
    const source = celSourceOf(raw);
    if (!source) return;
    for (const [field, operand] of collectBoundRecordReads(source)) {
      if (!anchors.has(field)) continue;
      issues.push({
        where,
        message:
          `\`${operand}\` reads '${field}', an injected system column with NO storage behind it: ` +
          `'${objectName}' is an external object (ADR-0015), so the remote database owns its schema ` +
          `and the platform registers this anchor without provisioning a column. The predicate can ` +
          `never match a real value — on SQLite it silently degrades to constant-false (HTTP 200, ` +
          `zero rows, no error). If the remote table really carries this column, declare '${field}' ` +
          `in the object's own fields (mapped through the external binding's columnMap) so the ` +
          `reference resolves to a column you vouch for; otherwise drop the reference, or opt the ` +
          `object out of the injection (\`ownership: 'none'\` for the ownership anchors, ` +
          `\`systemFields: { audit: false }\` for the audit family).`,
        source,
        severity: 'warning',
      });
    }
  };

  /**
   * The #4763 null-guard gate. Wired to exactly those surfaces whose predicates
   * CEL evaluates over a record made **total** for every declared field
   * (`materializeDeclaredFields`, #1871/#4649) — today: object validation rules
   * (`rule-validator.ts`, fail-closed since #4761), lifecycle hook `condition`s,
   * and field `requiredWhen` (#4811).
   *
   * Totality is the criterion that can DISQUALIFY a surface: on a total binding
   * `has()` is uniformly true and `!= null` is the fix, while on a SPARSE one
   * `has()` is a genuine guard and `!= null` faults with `No such key` — so
   * pointing this gate at a sparse-bound surface would reject correct metadata
   * and prescribe a fix that breaks it. It is not by itself a licence to cover:
   * since #6454 field `readonlyWhen` is total and still excluded, by clause 3 of
   * the #4953 ruling (the gate widens only once BOTH server-side seams are
   * total, and the flow trigger-record half is not wired yet).
   * `validate-null-guards.ts` carries the measured evidence table and the
   * per-surface ledger (action predicates, flow conditions, field
   * `readonlyWhen`, sharing rules and `Field.formula` are each excluded there
   * with a traced reason, and the reasons are no longer all the same one). Read
   * it before extending this call.
   */
  const checkNullGuards = (
    where: string,
    subject: string,
    raw: unknown,
    objectName: string | undefined,
    // What THIS surface's runtime does once the predicate aborts. Passed
    // explicitly rather than inferred, because the two possibilities are
    // opposite failures and the message has to name the right one (#4811).
    outcome: NullGuardOutcome = 'fail-closed',
  ): void => {
    if (!objectName) return;
    const nullableFields = nullableIndex.get(objectName);
    if (!nullableFields || nullableFields.size === 0) return;
    const source = celSourceOf(raw);
    if (!source) return;
    for (const finding of findUnguardedNullableOperands(source, { nullableFields })) {
      issues.push({
        where,
        message: nullGuardMessage(subject, objectName, finding, outcome),
        source,
        severity: 'error',
      });
    }
  };

  const check = (
    where: string,
    raw: unknown,
    objectName?: string,
    scope: 'record' | 'flattened' = 'flattened',
    /**
     * [#13935] Set when the field-rule check has issued a verdict for this
     * site. Bare-reference errors naming a NOWHERE-BOUND root are dropped so
     * the two partitions stay DISJOINT — the invariant this rule's docblock has
     * always asserted, which used to hold for free (every judged root was a
     * `SCOPE_ROOTS` member, and a declared root never trips the bare-reference
     * check) and stops holding for free the moment the judged vocabulary is
     * wider than the baseline. Without it a nowhere-bound root earns BOTH
     * verdicts, one of which is the false `record.<root>` prescription #13935
     * exists to remove.
     *
     * The suppressed set is {@link FIELD_RULE_NOWHERE_BOUND_ROOTS} rather than
     * only the root the verdict NAMED, and the difference shows up when one
     * predicate reaches for two rejected roots. This rule emits one verdict per
     * slot, so with `ctx.locale == 'en' && app.locale == 'en'` the tie-break
     * names `ctx` and `app` would otherwise keep its bare-reference —
     * re-emitting the exact false prescription, on the exact root, that #13935
     * removes. Suppressed, the author fixes `ctx`, re-runs, and `app` earns its
     * own correct verdict: the same one-root-at-a-time iteration this rule
     * already does for two baseline roots. Baseline roots need no entry — being
     * declared in the strict env, they never trip the bare-reference check at
     * all.
     */
    fieldRuleVerdictIssued?: boolean,
    /**
     * [#18682] Opt this ONE site in to the relationship-traversal conflict
     * checks. True only where the traversal is actually SERVED — object
     * validation rules' `condition` and `when`, which ObjectQL's
     * `checkPredicate` and `checkConditional` hydrate (#24512) (a formula
     * `expression`, the other served site, is judged by `judgeFieldFormula`,
     * which does not go through this helper). Everywhere
     * else the checks' prescription ("write `record.<fk>.id`") is false,
     * because nothing hydrates there and the repaired expression would fault;
     * on the fail-open seams that means the rule stops enforcing entirely.
     */
    traversalHydration?: boolean,
    /**
     * Set only where this site's `record` is a row a service serves — an entry
     * of {@link SERVED_ROW_SITES}. There the object's declared read
     * attachments join the field-existence set and their leaves are judged;
     * absent, the site binds the stored row and resolves the object's columns
     * alone, which is every site that does not name one.
     */
    servedRowSite?: ServedRowSite,
    /**
     * [#22228] Roots THIS site binds beyond the platform baseline, handed to
     * the shared validator as `ExprSchemaHint.roots` so a read of one is not
     * refused as a bare field. Only a field's cell formatting rule passes one
     * (`value`, {@link FIELD_FORMATTING_SURFACE_ROOTS}); absent, the call is
     * byte for byte what it was.
     */
    extraRoots?: readonly string[],
  ): void => {
    if (raw == null) return;
    // Absent unless this is a served-row site on an object that declares a
    // read attachment.
    const attachedOnRead = objectName && servedRowSite ? attachedOnReadIndex.get(objectName) : undefined;
    const fields = objectName ? withAttachedBlocks(fieldIndex.get(objectName), attachedOnRead) : undefined;
    // Field types feed the #1928 tier-4 soundness warning; only consulted for
    // `record`-scoped sites, so it is harmless to pass for flattened ones too.
    const fieldTypes = objectName ? fieldTypeIndex.get(objectName) : undefined;
    // Spread only when given, so every other site's hint is unchanged.
    const roots = extraRoots ? { roots: extraRoots } : {};
    const res = validateExpression('predicate', raw as string | { dialect?: string; source?: string },
      objectName ? { objectName, fields, attachedOnRead, fieldTypes, scope, traversalHydration, ...roots } : { scope, ...roots });
    for (const e of res.errors) {
      if (fieldRuleVerdictIssued && isBareReferenceToAny(e.message, FIELD_RULE_NOWHERE_BOUND_ROOTS)) continue;
      issues.push({ where, message: e.message, source: e.source, severity: 'error' });
    }
    for (const w of res.warnings) issues.push({ where, message: w.message, source: w.source, severity: 'warning' });
    if (objectName && traversalHydration) refuseStoredMetadataBodyHop(where, raw, objectName, 'rule');
    if (objectName && traversalHydration) refuseUndeclaredHopField(where, raw, objectName, 'rule');
    // [#8116] Provenance rides every object-bound predicate this helper
    // validates, whichever scope: the `record`/`previous` roots are explicit
    // in the source, so flattened flow conditions are covered without ever
    // judging a bare identifier.
    warnUnprovisionedAnchors(where, raw, objectName);
  };

  /**
   * The metadata-walk half: locate the source, then defer to the shared
   * {@link fieldRuleRootIssue} for the verdict and the message.
   *
   * [#13935] Split into a COMPUTE half and a PUSH half. The compute half runs
   * before {@link check} so the claimed root can be handed to it, while the
   * push half still runs after, keeping the emitted order of the two
   * diagnostics exactly as it was — a slot can carry a field-rule verdict AND
   * an unrelated field-existence error, and tests index into that order.
   */
  const fieldRuleRootVerdict = (
    slot: string,
    raw: unknown,
  ): { root: string; message: string; source: string } | null => {
    const source = celSourceOf(raw);
    if (!source) return null;
    const issue = fieldRuleRootIssue(slot, source);
    return issue ? { ...issue, source } : null;
  };

  /**
   * [#20078] Refuse a field-level predicate that reads THROUGH a reference
   * field, once per reference field per root it binds — see
   * {@link fieldTraversalMessage} for why, and for the prescription per root.
   */
  const refuseFieldTraversal = (
    where: string,
    slot: FieldTraversalSlot,
    raw: unknown,
    holders: readonly FieldTraversalHolder[],
  ): void => {
    const source = celSourceOf(raw);
    if (!source) return;
    for (const { root, types, owner } of holders) {
      // `null` when the source does not parse — the syntax pass owns that.
      const traversals = analyzeRelationshipTraversals(source, root)?.traversals;
      for (const [field, related] of traversals ?? []) {
        // `typeof` rather than an own-key test: an inherited name (`constructor`)
        // answers a function here, never a declared type string.
        const fieldType: unknown = types[field];
        if (typeof fieldType !== 'string' || !REFERENCE_VALUE_TYPES.has(fieldType)) continue;
        issues.push({
          where,
          message: fieldTraversalMessage(slot, root, field, fieldType, [...related].sort(), owner),
          source,
          severity: 'error',
        });
      }
    }
  };

  /**
   * A declared bare-CEL slot (#4027). No object schema is passed: these slots
   * bind the *screen's own* collected values, not the trigger record's fields, so
   * a field-existence pass would report every field name as unknown.
   */
  const checkDeclaredPredicate = (where: string, raw: unknown): { refused: boolean } => {
    // [#19961] No `raw == null` early return: whether an absent value is a
    // finding is the resolver's call, not this pass's. It emits absent / `null`
    // only for a `required` ledger slot (a `decision` branch's `expression`),
    // and there it is a refusal — the one `predicateSlotRefusal` gives the
    // other two doors. An early return here answered "valid" for the very
    // value `FlowSchema.parse` refuses, for any caller of
    // `validateStackExpressions` that did not parse first.
    //
    // [#15572] The slot is declared bare CEL TEXT, so a non-string — the
    // `{ dialect, source }` envelope above all — is refused on SHAPE before
    // anything tries to read a source out of it. The refusal is the spec's,
    // shared with the engine's `registerFlow` pass: `error`, because that pass
    // throws, and a shape build refuses must not pass author time.
    //
    // [#17493] The same call refuses a BLANK string too (the resolver emits it
    // for this role). `objectstack validate` meets that value first at its
    // schema step — `FlowSchema.parse` refuses it — so this is the pass that
    // answers for a stack handed to `validateStackExpressions` directly.
    const shapeRefusal = predicateSlotRefusal(raw);
    if (shapeRefusal) {
      issues.push({ where, message: shapeRefusal.message, source: shapeRefusal.source, severity: 'error' });
      return { refused: true };
    }
    const res = validateExpression('predicate', raw as string | { dialect?: string; source?: string });
    for (const e of res.errors) issues.push({ where, message: e.message, source: e.source, severity: 'error' });
    for (const w of res.warnings) issues.push({ where, message: w.message, source: w.source, severity: 'warning' });
    return { refused: false };
  };

  /**
   * A declared `value` slot (#15137) — the `assignment` node's
   * `assignments.*` and, since #19938, the `create_record` / `update_record`
   * `fields.*`: the slots whose job is to compute a value.
   *
   * The resolver emits ONLY envelope-shaped objects for this role, so anything
   * that arrives is an author declaring an expression. `error`, matching the
   * engine's `registerFlow` throw: build and run time must agree about what
   * registers, and a malformed envelope used to be stored verbatim and rendered
   * by `notify` as JSON with nothing said at any layer.
   *
   * @returns whether the slot was refused on SHAPE, so the caller can skip the
   *   root judgment (#22565) — a value that is not an envelope has no source to
   *   read roots from.
   */
  const checkDeclaredValue = (where: string, raw: unknown): { refused: boolean } => {
    if (raw == null) return { refused: false };
    // `celSourceOf` — not a second read of `.source`: the same helper every
    // other slot in this file locates its finding with.
    const source = celSourceOf(raw) ?? '';
    const shape = FlowValueSlotSchema.safeParse(raw);
    if (!shape.success) {
      // Already prefixed by the spec's own refinement — do not say it twice.
      for (const issue of shape.error.issues) issues.push({ where, message: issue.message, source, severity: 'error' });
      return { refused: true };
    }
    const res = validateExpression('value', raw as { dialect?: string; source?: string });
    for (const e of res.errors) {
      issues.push({ where, message: `${VALUE_ENVELOPE_REFUSAL} ${e.message}`, source: e.source, severity: 'error' });
    }
    for (const w of res.warnings) {
      issues.push({ where, message: w.message, source: w.source, severity: 'warning' });
    }
    return { refused: false };
  };

  // ── Flows ──────────────────────────────────────────────────────────
  // [#22565] Which flows an entrance opens to the root judgment — read once per
  // stack, because an entrance lives outside the flow it feeds (an action,
  // another flow's `subflow` / `map` node). At the runtime publish gate
  // (`runtimeWriteType` set) the per-write snapshot holds the written flow alone,
  // so no entrance is visible there and the judgment stands down
  // (`perWriteSnapshotEntrance`), by design: a judgment that reads other items of
  // the stack is `objectstack validate`'s, and that snapshot is not widened for
  // it (rulings `5791822697` item 3 and `6104584601`; `flow-cel-root-scope.ts`'s
  // module note). Every other verdict this pass gives at that door is unchanged.
  const runtimeGateWrite = options.runtimeWriteType !== undefined;
  const flowEntrances: ReadonlyMap<string, FlowCelEntrance> =
    objectWrite || runtimeGateWrite ? new Map() : flowCelEntrances(stack, fieldIndex);
  for (const flow of objectWrite ? [] : recordsOf(stack.flows)) {
    const flowName = typeof flow.name === 'string' ? flow.name : '(unnamed flow)';
    // [#26858] The flow's index in the authored list, for a finding's key path
    // (`recordsOf` hands an array's own members back). A map-form `flows` has
    // no index to spell, so its findings keep `where` alone.
    const flowIndex = Array.isArray(stack.flows) ? stack.flows.indexOf(flow) : -1;
    // `Array.isArray` proves the LIST, never its MEMBERS — the sentence #15742
    // removed from one reader below in this same file. A YAML `nodes:` item
    // left empty deserialises to `null`, and `nodes.find(n => n.type === …)` on
    // the very next line dereferenced it (#15793).
    const nodes = recordsOf(flow.nodes);
    // `edges` is the SAME reader one list over, and #15793 reached only the node
    // lists (#16910). The edge walk below reads `.id` off each member, so a
    // YAML `edges:` item left empty threw a `TypeError` out of a rule
    // contractually typed `(stack) => Issue[]` — the crash `lintFlowPatterns`
    // was filed for, reached through this rule instead, on the same document.
    const edges = recordsOf(flow.edges);
    // The record-change target object — `record.*` refs resolve against it.
    const startNode = nodes.find(n => n.type === 'start');
    const startCfg = (startNode?.config ?? {}) as AnyRec;
    const objectName = typeof startCfg.objectName === 'string' ? startCfg.objectName : undefined;

    // #4347 — every graph in the flow, not just `flow.nodes`/`flow.edges`. An
    // ADR-0031 container keeps a whole sub-graph in its `config`, so the
    // top-level walk validated PART of the flow while reporting on all of it: a
    // predicate written in the wrong dialect inside a `loop` body passed
    // `objectstack validate` and shipped. This is the author-time half of the
    // same traversal the engine's registration pass now does; `scope` names the
    // region so the located message still points at one edge.
    //
    // Handed the COERCED `nodes`, never `flow` raw (#15793). `collectFlowGraphs`
    // declares its input as `FlowNodeParsed[]` — already-parsed nodes — and is
    // transparent about members: it forwards the caller's array and re-exposes
    // that same object. So it neither admits nor rejects a non-record member;
    // passing raw authored metadata is calling it OUT OF CONTRACT, and it then
    // dereferences `node.config` in its own region walk. Coercing only the
    // local `nodes` above does not fix the crash, it relocates it into
    // `packages/spec` — measured. Contract-first the caller is what changes.
    // `edges` is coerced and handed on for the identical reason, never
    // `flow.edges` raw out of the spread: coercing only the local read
    // relocates the crash instead of removing it — measured on #15793 for
    // `nodes`, measured again on #16910 for `edges`.
    const graphs = collectFlowGraphs({
      ...flow,
      nodes: nodes as unknown as FlowNodeParsed[],
      edges: edges as unknown as FlowEdgeParsed[],
    });

    // [#14089] The flattened-scope shadowing pass needs the flow's COMPLETE
    // variable set before any condition is judged, so it is a separate walk over
    // the (already materialized) graph list rather than an interleaved one.
    // That is forced, not stylistic: `seedRunVariables` builds ONE variable map
    // per run, so a name declared by the LAST node is in scope for a condition
    // on the first — collecting as the checking walk goes would make the verdict
    // depend on traversal order. `collectFlowGraphs` is still called once.
    const declaredVariables = collectFlowVariableNames(flow, graphs);

    /**
     * [#22565] The flow CEL ROOT judgment. A root the run does not bind fails
     * that run with `Unknown variable: X`, and before this pass nothing at build
     * said so: `user.id == "u1"` — the run-user spelling formulas, RLS and the
     * client accept — validated clean and faulted at the first evaluation,
     * because flow CEL binds the run's user as `current_user` only.
     *
     * One bound set per flow, built once like `declaredVariables` above and for
     * the same reason (one variable map serves the whole run): the flow's own
     * bindings, the engine's roots and every object's fields — see
     * `flow-cel-root-scope.ts` for the set, and for the flows it stands down on
     * because their run can bind a name the reader cannot see: a node's, or an
     * entrance's (`flowEntrances` above). `error`: the run faults on the root,
     * every time the expression is evaluated.
     */
    const rootScope = flowCelRootScope(
      flow,
      graphs,
      objectName,
      fieldIndex,
      runtimeGateWrite
        ? perWriteSnapshotEntrance()
        : flowEntrances.get(typeof flow.name === 'string' ? flow.name : '') ?? {},
    );

    /**
     * [#22565] Refuse each root `raw` reads that the flow does not bind.
     *
     * @param from the index in `issues` this site's own findings start at — a
     *   flattened-scope near-miss warning `check()` pushed there about a root
     *   refused here is withdrawn ({@link isFlattenedNearMissFor}).
     * @param role a `value` slot's plain string is a literal, so only its CEL
     *   envelope is read; a predicate slot is CEL as a string too.
     */
    const refuseUnboundRoots = (where: string, raw: unknown, from: number, role: 'predicate' | 'value'): void => {
      if (role === 'value' && !(raw && typeof raw === 'object' && (raw as AnyRec).dialect === 'cel')) return;
      const source = celSourceOf(raw);
      if (!source) return;
      const unbound = unboundFlowCelRoots(source, rootScope);
      if (unbound.length === 0) return;
      const refused = unbound.map((unboundRoot) => unboundRoot.root);
      for (let i = issues.length - 1; i >= from; i--) {
        const issue = issues[i]!;
        if (issue.severity === 'warning' && isFlattenedNearMissFor(issue.message, refused)) issues.splice(i, 1);
      }
      for (const unboundRoot of unbound) {
        issues.push({ where, message: unboundFlowCelRootMessage(unboundRoot, rootScope), source, severity: 'error' });
      }
    };

    /**
     * [#14089] The one bare-identifier case a flattened flow scope may not stay
     * silent about: a name bound as BOTH a declared flow variable and a field on
     * the bound object. The variable wins at runtime and nothing says so, which
     * is why the diagnostic exists; every other bare identifier here is the form
     * the platform's own contract and canon teach, and is deliberately NOT
     * judged. Severity `warning` — see `flow-variable-scope.ts` for the ruling,
     * the measured mechanism, and the oracle's known blind spot.
     */
    const warnShadowedFieldReads = (where: string, raw: unknown): void => {
      if (!objectName) return;
      const celSource = celSourceOf(raw);
      if (!celSource) return;
      for (const shadowed of shadowedFieldReads(celSource, declaredVariables, fieldIndex.get(objectName) ?? [])) {
        issues.push({
          where,
          message: shadowedFieldMessage(shadowed, objectName),
          source: celSource,
          severity: 'warning',
        });
      }
    };

    /**
     * [#15662] A STRUCTURAL condition (`config.condition` on a node,
     * `edge.condition`) refused on SHAPE before anything reads a source out of
     * it. The refusal is the spec's, shared with the engine's `registerFlow`
     * pass: `error`, because that pass throws, and a shape build refuses must
     * not pass author time.
     *
     * ⚠️ Deliberately NOT `predicateSlotRefusal`, which the declared-slot arm
     * above uses. A ledger `predicate` slot is declared `z.string()`; neither
     * structural slot is — `FlowEdgeSchema.condition` is
     * `EvaluatedExpressionInputSchema` (#15807), so an envelope is the shape
     * the parse itself produces, and a node's `config` is an open `z.record`
     * that passes one through verbatim. Both are admitted here; a value that
     * is neither text nor an envelope carrying a string `source` is not,
     * because the evaluator reads it as an EMPTY condition and answers a
     * silent `false` — since #15807 that includes an `ast`-only envelope, which
     * the edge schema refuses one tier earlier and which this pass is the only
     * producer-side gate for on `config.condition`.
     *
     * [#17495] SECOND gate, after the shape one and before the CEL one — the
     * author-time half of the refusal #17322 landed in `registerFlow`. The
     * source must be non-blank. `structuralConditionRefusal` admits every
     * string by design, so a whitespace-only `config.condition` cleared the
     * shape gate and then cleared `validateExpression` too (it trims, and reads
     * a blank source as "not authored") — this pass reported NOTHING for
     * exactly the value `registerFlow` now throws on. The author ran
     * `objectstack validate`, got a clean bill, deployed, and the flow stopped
     * registering behind one `warn` line; on a `start` node that key is the
     * TRIGGER GATE, so the whole flow is gated shut.
     *
     * The rule is the edge door's own `EvaluatedExpressionInputSchema`,
     * IMPORTED — not a second hand-written notion of "blank". That is the drift
     * #15662 built one shared refusal to prevent, and the route `registerFlow`
     * took for the same reason; the sentence comes from the schema too, so the
     * two doors cannot answer differently.
     *
     * @returns whether the slot was refused, so the caller can skip the
     *   value-reading passes that would otherwise re-report it as an empty one.
     */
    const checkStructuralCondition = (where: string, raw: unknown): { refused: boolean } => {
      if (raw == null) return { refused: false };
      const shapeRefusal = structuralConditionRefusal(raw);
      if (shapeRefusal) {
        issues.push({ where, message: shapeRefusal.message, source: shapeRefusal.source, severity: 'error' });
        return { refused: true };
      }
      const blankRefusal = evaluatedSourceRefusal(raw);
      if (blankRefusal) {
        issues.push({ where, message: blankRefusal.message, source: blankRefusal.source, severity: 'error' });
        return { refused: true };
      }
      return { refused: false };
    };

    for (const graph of graphs) {
      const at = graph.scope ? `flow '${flowName}' · ${graph.scope}` : `flow '${flowName}'`;
      // `recordsOf`, not `as unknown as AnyRec[]` (#15793). A NESTED region's
      // node list is only `Array.isArray`-checked by `collectFlowGraphs` before
      // it becomes a graph, so this list carries the producer's word about its
      // members and not a check. The top-level graph is clean by the coercion
      // at the call site above; this is the same decision made once more where
      // that guarantee stops, through the file's one home for it.
      for (const node of recordsOf(graph.nodes)) {
        const cfg = (node.config ?? {}) as AnyRec;
        const nodeCondWhere = `${at} · node '${node.id}' (${node.type}) condition`;
        if (!checkStructuralCondition(nodeCondWhere, cfg.condition).refused) {
          const from = issues.length;
          check(nodeCondWhere, cfg.condition, objectName);
          warnShadowedFieldReads(nodeCondWhere, cfg.condition);
          refuseUnboundRoots(nodeCondWhere, cfg.condition, from, 'predicate');
        }

        // Descriptor-declared expression slots (#4027). Before this, the traversal
        // hardcoded `condition` and assumed every other node string was a `{var}`
        // template — so `screen.fields[].visibleWhen`, declared bare CEL since
        // #3304, was validated by nobody and #3528 shipped a template-dialect
        // predicate through compile, validate and run time in silence.
        // A `predicate` slot is checked as bare CEL, and a `value` slot's
        // envelope by its own rule (`checkDeclaredValue`) — the two roles the
        // ledger has since #19939 retired the single-brace one with the
        // `loop` / `map` `collection` it recorded.
        const nodeType = typeof node.type === 'string' ? node.type : '';
        // [#20316] What the node's executor needs its `config` to carry — a key
        // its contract requires, left out, and a `decision` branch list it
        // cannot read. The spec's one judge, the same call `FlowSchema.parse`
        // makes (and `registerFlow` meets through that parse), so a stack
        // handed to `validateStackExpressions` without a parse in front of it
        // is held to the same bar. `error`: the flow would register and then
        // refuse — or, for a branch with no label, misroute — every run.
        const configRefusals = flowNodeConfigRefusals(nodeType, node.config)
          // A `script`'s `function` stays the callable check's below (#1870,
          // #4343): this pass may be handed a pre-conversion source, and that
          // check reads what such a source spells — the `functionName` alias,
          // the retired dispatch keys — and names each, where the judge would
          // only see `function` absent. Since the judge also refuses a key a
          // `script`'s contract does not declare (#21982), it would name that
          // same `functionName` alias undeclared too, so that one refusal is
          // the callable check's as well: the pass keeps the pre-conversion
          // tolerance it declares. Every other undeclared key stays refused.
          .filter((configRefusal) => !(nodeType === 'script' && (
            configRefusal.path === 'function'
            || (configRefusal.code === 'node-config-refused-by-contract' && configRefusal.path === 'functionName')
          )));
        for (const configRefusal of configRefusals) {
          issues.push({
            where: `${at} · node '${node.id}' (${nodeType}) config.${configRefusal.path}`,
            message: configRefusal.message,
            source: configRefusal.source,
            severity: 'error',
          });
        }
        for (const found of resolveFlowNodeExpressions(nodeType, cfg)) {
          const slotWhere = `${at} · node '${node.id}' (${nodeType}) ${found.entry.label} at config.${found.path}`;
          // [#15137] `value` slots are checkable too, by their own rule — see
          // `checkDeclaredValue`. Not shadowing-checked: the shadow diagnostic is
          // about a bare identifier resolving to a variable instead of a field,
          // and a value envelope is evaluated in the flow-variable scope by
          // design — there is no field reading to displace.
          if (found.entry.role === 'value') {
            const from = issues.length;
            if (!checkDeclaredValue(slotWhere, found.value).refused) {
              refuseUnboundRoots(slotWhere, found.value, from, 'value');
            }
            continue;
          }
          if (found.entry.role !== 'predicate') continue;
          const slotFrom = issues.length;
          // [#15572] A slot refused on SHAPE gets no second diagnostic: the
          // shadowing warning is about which scope a CEL source resolves in,
          // and a value that is not CEL text has no source to resolve.
          if (checkDeclaredPredicate(slotWhere, found.value).refused) continue;
          // [#14288] The shadowing warning is about the SCOPE an expression is
          // evaluated in, not about which key it was authored under — so it
          // belongs on every `predicate` slot the ledger declares, not just the
          // two hardcoded `condition` keys #14089 reached. Measured on the
          // engine before it was extended here, because "same scope" is the
          // whole premise and a narrower per-node scope would have made this
          // call site a false positive:
          //
          //  • `seedRunVariables` builds ONE map per run (`engine.ts`, declared
          //    variables first, then the record's fields only where nothing is
          //    bound yet) and it threads UNCHANGED into every node executor —
          //    `execute()` seeds it, `executeNode` passes it down, and
          //    `executor.execute(node, variables, context)` hands that same Map
          //    object over. No clone, no narrowing, anywhere on the path.
          //  • `decision.conditions[].expression` (`builtin/logic-nodes.ts`)
          //    evaluates against that very parameter — literally the same Map
          //    a node `condition` is judged against.
          //  • `screen.fields[].visibleWhen` (`refuseInvalidScreenInput`)
          //    evaluates against `run.variables` — the persisted snapshot of
          //    the same seeded map — with the SUBMITTED bag overlaid. A
          //    superset, so the shadow still reaches it: the overlay carries
          //    the screen's own collected values, never the bound record's
          //    field, so it can never hand back a field the variable displaced.
          //
          // Same `declaredVariables` set, same severity, no new rule id: this
          // moves no accept set and judges no bare identifier for being bare
          // (the 2026-09-01 option-C ruling's letter).
          warnShadowedFieldReads(slotWhere, found.value);
          // [#22565] The same scope again, judged for roots the run cannot bind.
          refuseUnboundRoots(slotWhere, found.value, slotFrom, 'predicate');
        }
        // [#19939] The `{…}` template dialect is retired from the value slots
        // (the C half of #11182 ruling D, which this replaced: until then a
        // template EXPRESSION here drew a `warning` pointing at the CEL value
        // envelope). A literal that still spells it is refused at `error` —
        // the one judge `registerFlow` calls on the same config
        // (`flowNodeValueTemplateRefusals`), walking the ledger's `value` slots
        // and the two legacy `assignment` shapes, so build and registration
        // give one verdict, and each refusal names the token's CEL spelling.
        for (const templateRefusal of flowNodeValueTemplateRefusals(nodeType, cfg)) {
          issues.push({
            where: `${at} · node '${node.id}' (${nodeType}) ${templateRefusal.label} at config.${templateRefusal.path}`,
            message: templateRefusal.message,
            source: templateRefusal.source,
            severity: 'error',
          });
        }
        // [#22110] The TEXT slots (a notify `title` / `message` and, since
        // #19939, its `actionUrl` and an http `url` and each `headers` value, a
        // screen `title` / `description`, an `end` `message`) render ADR-0032 §3's
        // `{{ }}` holes. The same two checks `registerFlow` runs on the same
        // config, in the same order: a single-brace token left from the 17.x
        // dialect is refused with its hole spelling (the spec's one judge),
        // and a slot carrying none is compiled as the `template` it is — a
        // hole holding logic or an unknown formatter is an `error` here, not a
        // throw at the node mid-run.
        for (const slot of flowNodeTextSlotSources(nodeType, cfg)) {
          const slotWhere = `${at} · node '${node.id}' (${nodeType}) ${slot.label} at config.${slot.path}`;
          const tokenRefusal = textSlotTemplateRefusal(slot.source);
          if (tokenRefusal !== undefined) {
            issues.push({ where: slotWhere, message: tokenRefusal, source: slot.source, severity: 'error' });
            continue;
          }
          for (const e of validateExpression('template', slot.source).errors) {
            issues.push({ where: slotWhere, message: e.message, source: e.source, severity: 'error' });
          }
        }
        // #1870 — a `script` node must name a callable, and since #4343 that is
        // the whole of what the node does: `config.function`. A node without one
        // is a silent no-op that otherwise passes build. (Function *existence*
        // isn't checkable here — functions are code, not serialized into the
        // artifact — so this is a structural check; the runtime verifies the
        // named function is actually registered.)
        if (node.type === 'script') {
          // `function` is canonical; a pre-parse source may still carry the
          // `functionName` alias during the protocol-17 window, until the
          // 'flow-node-script-config-aliases' conversion (#3796) canonicalizes it.
          const fn =
            (typeof cfg.function === 'string' ? cfg.function.trim() : '') ||
            (typeof cfg.functionName === 'string' ? cfg.functionName.trim() : '');
          // A source that predates #4343 may still carry a retired dispatch key.
          // Naming it beats the generic "no callable": these ARE what the author
          // wrote, and each has a different replacement. The schema tombstones
          // carry the full prescription; this is the one-line version at lint.
          const action = typeof cfg.actionType === 'string' ? cfg.actionType.trim() : '';
          const retired = ['actionType', 'template', 'recipients', 'variables', 'script']
            .filter((k) => cfg[k] != null);
          if (retired.length > 0) {
            issues.push({
              where: `${at} · node '${node.id}' (script) callable`,
              message:
                `script node carries \`${retired.map((k) => `config.${k}`).join('`, `')}\` — retired in ` +
                `@objectstack/spec 17, which made \`script\` a call to a registered function and nothing ` +
                `else. The built-in 'email'/'slack' actions were logger-backed ` +
                `stubs that delivered nothing, and inline \`config.script\` was never executed. ` +
                (action && action !== 'invoke_function' && !['email', 'slack'].includes(action)
                  ? `\`actionType: '${action}'\` named a registered function — move it to \`function: '${action}'\`. `
                  : `Use a \`notify\` node for mail, a \`connector_action\` (Slack connector) or \`http\` node ` +
                    `for Slack, and a registered function for logic. `) +
                // #6856 route D (maintainer-ruled), reworded under #9529 and #9591: the
                // house sentence names the TOOL's behaviour, never the retired key's
                // fate — "rewrite it" read two ways over a branch that DELETES the key
                // (template/recipients/variables/script) — and claims no more than the
                // tool does: the default run lists, `--write` writes only the edits it
                // can prove. Plain-quoted (not a template literal)
                // so this site is a member of `retired-key-migrate-sentence.test.ts`'s
                // widened scan (#7030) on the same textual shape as the spec corpus — no
                // interpolation lives in this clause, so nothing is lost switching quote style.
                'This edit left `os migrate meta` with the protocol-16.x conversions: apply it by hand, or run the tool on a release that still carries the conversion — https://objectstack.ai/docs/protocol-upgrade.',
              source: JSON.stringify({ id: node.id, type: node.type, config: cfg }),
            });
          } else if (!fn) {
            issues.push({
              where: `${at} · node '${node.id}' (script) callable`,
              message:
                `script node declares no \`function\` — it would do nothing at runtime. ` +
                `Name a registered function (\`function: 'my_fn'\`, registered via ` +
                `\`defineStack({ functions })\`).`,
              source: JSON.stringify({ id: node.id, type: node.type, config: cfg }),
            });
          }
        }
      }
      // `recordsOf`, not `as unknown as AnyRec[]` (#16910) — the same reason as
      // the `graph.nodes` reader above: a NESTED region's edge list is only
      // `Array.isArray`-checked by `collectFlowGraphs` before it becomes a
      // graph (the node side of that walk is member-filtered since #16752, the
      // edge side is not), so it carries the producer's word about its members
      // and not a check.
      for (const edge of recordsOf(graph.edges)) {
        const edgeCondWhere = `${at} · edge '${edge.id}' (${edge.source}→${edge.target}) condition`;
        const first = issues.length;
        if (!checkStructuralCondition(edgeCondWhere, edge.condition).refused) {
          const from = issues.length;
          check(edgeCondWhere, edge.condition, objectName);
          warnShadowedFieldReads(edgeCondWhere, edge.condition);
          refuseUnboundRoots(edgeCondWhere, edge.condition, from, 'predicate');
        }
        // [#26858] A top-level edge's findings also carry the slot's key path,
        // indexed over the list the author wrote (the coerced one drops `null`
        // members and would renumber). A nested region's edge keeps `where`.
        const edgeIndex = flowIndex >= 0 && graph.path.length === 0 && Array.isArray(flow.edges)
          ? flow.edges.indexOf(edge)
          : -1;
        if (edgeIndex >= 0) {
          const path = `flows[${flowIndex}].edges[${edgeIndex}].condition`;
          for (let k = first; k < issues.length; k++) issues[k] = { ...issues[k]!, path };
        }
      }
      // No `checkNullGuards` on node/edge conditions — and NOT for the reason
      // #4811 first recorded (#4811 re-measured it). The stated blocker was the
      // flattened scope: a bare identifier like `budget > 100000` might be a flow
      // variable rather than a field. That is true of a bare-identifier checker,
      // but this gate never resolves a bare identifier — it matches only
      // `record.<f>` / `previous.<f>`, and the engine binds both roots
      // unconditionally, so it is immune to that ambiguity.
      //
      // The real blocker is totality. `record-change-trigger.ts` seeds the flow's
      // record as `{ ...(inputData ?? {}), ...after }` (spelled `inputDoc` until
      // #5671 dropped that alias read) with no `materializeDeclaredFields`,
      // so a declared column the write never mentioned is an ABSENT key, not a
      // null one — and there `record.x != null` faults (`No such key`) exactly
      // like the comparison it was meant to guard. The gate's prescription is
      // unsound on this surface until the trigger's record is made total the way
      // #4649 made the validation-rule and hook bindings total.
      //
      // (For the record, the flattened-scope ambiguity is separately real and
      // would need its own criterion: flow inputs shadow record fields —
      // `if (!variables.has(k))` in `AutomationEngine.execute` — and a node's
      // `outputVariable` can overwrite either, so a sound bare-identifier pass
      // must subtract flow inputs, every `outputVariable`, screen-collected
      // variable names and node ids.)
    }
  }

  // ── Object validation-rule + formula predicates ────────────────────
  for (const obj of objects) {
    const objectName = typeof obj.name === 'string' ? obj.name : undefined;
    // [#27643] The object's index in the authored list, for a validation-rule
    // finding's key path (`recordsOf` hands an array's own members back). A
    // map-form `objects` has no index to spell, so its findings keep `where`
    // alone, as a map-form `flows` collection's do (#26858).
    const objectIndex = Array.isArray(stack.objects) ? stack.objects.indexOf(obj) : -1;
    // `validations` is the key `ObjectSchema` declares; `validationRules` is a
    // rejected alias of it (#5017) — see the `## Scope` table above.
    const validations = obj.validations;
    // [#22032, pass 1] NOT fenced on an object write: this loop is the
    // validation-rule pass the object save door runs, at the build's own
    // position, so the door's findings and their order are the build's.
    for (const rule of recordsOf(validations)) {
      const where = `object '${objectName}' · validation '${(rule.name as string) ?? '?'}'`;
      // [#27643] Every finding below also carries the judged slot's key path
      // (`objects[0].validations[1].condition`), indexed over the lists the
      // author wrote, in the spelling a flow edge's findings use (#26858), so
      // a draft's `_diagnostics` reports it item-relative
      // (`validations.1.condition`). `where` stays the human locator.
      const ruleIndex = objectIndex >= 0 && Array.isArray(obj.validations) ? obj.validations.indexOf(rule) : -1;
      const rulePath = ruleIndex >= 0 ? `objects[${objectIndex}].validations[${ruleIndex}]` : undefined;
      const atSlot = (key: string, first: number): void => {
        if (!rulePath) return;
        const path = `${rulePath}.${key}`;
        for (let k = first; k < issues.length; k++) issues[k] = { ...issues[k]!, path };
      };
      // The declared predicate key is `condition` (see `rulePredicates`).
      // Validation predicates are `record`-scoped — no field flattening — so
      // bare refs are flagged (#1928).
      // [#18682] The sites where a relationship traversal is SERVED: these are
      // the `script` / `cross_field` conditions ObjectQL's `checkPredicate`
      // hydrates, and (#24512) a `conditional` rule's `when`, which
      // `checkConditional` evaluates on the same hydrated scope.
      // `traversalHydration` is passed on those two slots here and nested below
      // (#22042), and on a formula field's `expression` (`judgeFieldFormula`,
      // #24197), and NOWHERE else.
      let first = issues.length;
      check(where, rule.condition, objectName, 'record', undefined, true);
      atSlot('condition', first);
      first = issues.length;
      check(`${where} when`, (rule as AnyRec).when, objectName, 'record', undefined, true);
      atSlot('when', first);
      const predicates = rulePredicates(rule, '');
      // [#22042] The same verdict one level down, and every level below it: a
      // `conditional` rule's `then` / `otherwise` is a rule the evaluator runs
      // (`checkConditional` hands the branch to `evaluateRule`), so its
      // predicates meet `check()` exactly as the two calls above do — located
      // at the label `rulePredicates` builds, the location the null-guard gate
      // below already gives the same predicate. Depth 0 is skipped: the rule's
      // own `condition` / `when` met `check()` above, under their own location.
      // Hydration follows the evaluator, as at the top level: ObjectQL's
      // `collectPredicateRelationships` reaches a nested `condition` and a
      // nested `when` alike, and both are evaluated hydrated, so both slots
      // meet the traversal checks.
      for (const p of predicates) {
        if (p.depth === 0) continue;
        first = issues.length;
        check(`object '${objectName}' · ${p.label}`, p.raw, objectName, 'record', undefined, true);
        atSlot(p.key, first);
      }
      // [#24720] The rule's root verdict, over every predicate it carries,
      // located where `check()` above located the same predicate. `parent` is
      // a `SCOPE_ROOTS` member, so `check()` never reports a bare reference to
      // it and the two verdicts stay disjoint; see
      // {@link validationRuleParentIssue}.
      for (const p of predicates) {
        const source = celSourceOf(p.raw);
        const message = source ? validationRuleParentIssue(objectName, p.ruleName, p.slot, source) : null;
        if (!message) continue;
        const at = p.depth > 0
          ? `object '${objectName}' · ${p.label}`
          : p.slot === 'when' ? `${where} when` : where;
        // `error`: a rule the runtime cannot evaluate must not pass a door; see the docblock.
        first = issues.length;
        issues.push({ where: at, message, source: source!, severity: 'error' });
        atSlot(p.key, first);
      }
      // #4763 — null-guard gate over every predicate the rule carries, nested
      // `then`/`otherwise` branches included.
      for (const p of predicates) {
        first = issues.length;
        checkNullGuards(`object '${objectName}' · ${p.label}`, p.label, p.raw, objectName);
        atSlot(p.key, first);
      }
    }
    // Field-level formulas (computed fields) reference the same object.
    const fields = obj.fields;
    // Paired with the field's NAME. `fields` has two authored shapes and the
    // name lives in a different place in each: it is `f.name` in the array
    // shape and the KEY in the name-keyed map shape. Walking `Object.values`
    // dropped that key, so every diagnostic on a map-shaped object — the shape
    // `Field.text({…})` authoring produces, i.e. the common one — was located
    // at `field '?'` (#4811). Harmless-looking while the name only appeared in
    // `where`; not harmless once a message has to tell the author which field
    // to edit. Array entries keep their previous fallback so a nameless one is
    // still validated rather than silently skipped.
    const fieldList: Array<[string, AnyRec]> = Array.isArray(fields)
      ? (fields as AnyRec[])
          .filter((f) => !!f && typeof f === 'object')
          .map((f) => [typeof f.name === 'string' ? f.name : '?', f] as [string, AnyRec])
      : (fields && typeof fields === 'object'
          ? Object.entries(fields as AnyRec)
              .filter(([, def]) => !!def && typeof def === 'object')
              .map(([n, def]) => [n, def as AnyRec] as [string, AnyRec])
          : []);

    // (ADR-0062 D7's `field.columnName`-on-external-objects rejection was removed
    // with `field.columnName` itself in #2377: the field no longer exists, so there
    // is no dual-source ambiguity to guard — external column mapping is `external.columnMap`.)

    // [#4889] How many masters this object has, for the `parent`-scope gate
    // below. Computed once per object, not per field.
    const masters = masterDetailCount(obj);

    // [#24677] A `lookup` / `master_detail` whose `reference` is a
    // stored-metadata-body table is refused where it is declared: the engine
    // never hydrates it, so it saves and never works. Read through the hop
    // refusal's own collector and index, so the two verdicts judge one set,
    // and AFTER `masterDetailCount`, so an unreadable `reference` carrier is
    // still refused by the pass that owned that verdict first. NOT fenced on
    // an object write: the field is the object's own body, so the object save
    // door gives the build's verdict, at the build's position in this walk.
    // The type is read from the field-type index, never off the field again:
    // the #5017 receiver meta-test pins the keys this walk reads off `f`. The
    // collector admits only a field whose `type` is a string, and the index
    // records every such field, so each collected field has its type here.
    if (objectName) {
      const familyRefs = storedMetadataBodyReferencesFor(objectName);
      const ownFieldTypes = fieldTypeIndex.get(objectName);
      for (const [fname] of fieldList) {
        const target = familyRefs.get(fname);
        const type = ownFieldTypes?.[fname];
        if (!target || !type) continue;
        issues.push({
          where: `object '${objectName}' · field '${fname}' reference`,
          message: storedMetadataBodyReferenceMessage(fname, type, target),
          source: '',
          severity: 'error',
        });
      }
    }

    // [#20078] The roots a field-level predicate binds, each with the record
    // shape it binds: `record` / `previous` are this object's, `parent` is its
    // single master's — judged only when that master is in the stack, since
    // its field types come from the same index. An option binds `record` /
    // `previous` (and the user), never `parent`.
    const ownTypes = objectName ? fieldTypeIndex.get(objectName) : undefined;
    const master = masters === 1 ? singleMasterOf(obj) : undefined;
    const masterTypes = master ? fieldTypeIndex.get(master) : undefined;
    const optionHolders: FieldTraversalHolder[] = objectName && ownTypes
      ? [
          { root: 'record', types: ownTypes, owner: objectName },
          { root: 'previous', types: ownTypes, owner: objectName },
        ]
      : [];
    const fieldRuleHolders: FieldTraversalHolder[] = master && masterTypes
      ? [...optionHolders, { root: 'parent', types: masterTypes, owner: master }]
      : optionHolders;

    /**
     * The field-formula pass — one computed field's `expression`. A closure
     * since #22019, whose object door ran this pass and no other slot of the
     * field walk; since #22032's pass 2 the door runs the field-rule slots as
     * well, and this is called at one point only — the same point of the field
     * walk it always ran at — so the build's findings and their order are
     * unchanged.
     */
    const judgeFieldFormula = (fname: string, f: AnyRec): void => {
      if (f.expression) {
        // `expression` is the key `FieldSchema` declares for a computed field —
        // what `Field.formula({ expression: … })` writes. This read was spelled
        // `formula` until #5026, one of the names `field.zod.ts:333` REJECTS by
        // aliasing it back to `expression`, so the whole pass had never run
        // against a stack that parses. Converging it ACTIVATED a check rather
        // than deleting a dead branch — the real-metadata sweep that had to
        // accompany that is in #5026's PR body.
        //
        // formulas are `value` role (any return type), still CEL. They are
        // `record`-scoped — `record.<field>`, never bare — so flag bare refs (#1928).
        //
        // No `checkNullGuards` here, and unlike the action / flow surfaces this
        // is NOT a totality verdict (#4811). A formula is `value`-role and
        // natively nullable, and `guard ? value : null` is the blessed shape
        // (#3306 rewrites it through `dyn(...)`). Whether unguarded arithmetic
        // such as `record.budget - record.spent` should be *forbidden* here is a
        // question about what authors are allowed to write — a product decision
        // for the maintainer, not a wiring gap for a lint PR to close on its own.
        // The convention already leans guarded (`showcase_project.budget_remaining`
        // writes `(record.budget == null ? 0 : record.budget) - …`), so the cost of
        // deciding later is low. Raise it as its own issue rather than widening
        // this call. Ledger: `validate-null-guards.ts`.
        //
        // The object's columns alone, never its read attachments: a formula is
        // computed on the stored row, which carries no block (see
        // {@link SERVED_ROW_SITES}).
        //
        // [#24197] `traversalHydration`: a formula `expression` is a site where
        // a relationship traversal is SERVED — ObjectQL's formula read path
        // preloads ONE hop through a reference field (`record.book.title`)
        // before computing the field, page-batched, under the reader's own
        // read. So one hop passes here, and the two shapes that path cannot
        // serve — a second hop, and a reference read both through and as a
        // value — are refused with the formula-worded prescription.
        const res = validateExpression('value', f.expression as string | { dialect?: string; source?: string },
          objectName
            ? {
                objectName,
                fields: fieldIndex.get(objectName),
                fieldTypes: fieldTypeIndex.get(objectName),
                scope: 'record',
                traversalHydration: true,
              }
            : { scope: 'record' });
        // Names the KEY the author edits, not the field type. Saying "formula"
        // here is how the wrong spelling propagates: the next author reads the
        // diagnostic and writes `formula:`, which the schema then rejects.
        const fieldWhere = `object '${objectName}' · field '${fname}' expression`;
        for (const e of res.errors) issues.push({ where: fieldWhere, message: e.message, source: e.source, severity: 'error' });
        for (const w of res.warnings) issues.push({ where: fieldWhere, message: w.message, source: w.source, severity: 'warning' });
        if (objectName) refuseStoredMetadataBodyHop(fieldWhere, f.expression, objectName, 'formula');
        // [#24410] And a hop to a field the target does not declare.
        if (objectName) refuseUndeclaredHopField(fieldWhere, f.expression, objectName, 'formula');
        // [#8116] Formulas read the same record binding the predicates do, so
        // a `record.<anchor>` read inside one degrades identically.
        warnUnprovisionedAnchors(fieldWhere, f.expression, objectName);
      }
    };

    for (const [fname, f] of fieldList) {
      // [#22032, pass 2] NOT fenced on an object write: the field-rule slots
      // below — the four slots' root verdict, the `parent` gate, the
      // `requiredWhen` null guard and the traversal refusal — are the pass the
      // object save door runs, at the build's own position in this walk, so
      // the door's findings and their order are the build's. The per-option
      // `visibleWhen` loop between them joined the door in pass 3; no slot of
      // this walk is fenced any more.
      //
      // Field-level conditional rules are server-enforced (rule-validator) and
      // record-scoped — a bare ref silently fails the rule (required/readonly
      // not enforced = data-integrity hole). #1928 class, same as actions.
      //
      // [#22227] `settledWhen` — a `date` / `datetime` deadline's settle
      // predicate (objectui#11815 ruling D) — is the fifth slot, judged exactly
      // as `visibleWhen` is: the `record`-scoped `check` (it parses, it reads
      // `record.<field>` and never a bare field, the field exists) and the
      // root verdict over FIELD_RULE_BOUND_ROOTS. Like `visibleWhen` it is
      // display only, so the server-side gates further down (the `parent`
      // gate, the null guard, the traversal refusal) do not apply to it.
      for (const key of ['requiredWhen', 'readonlyWhen', 'visibleWhen', 'settledWhen'] as const) {
        const where = `object '${objectName}' · field '${fname}' ${key}`;
        const raw = (f as AnyRec)[key];
        // [#13935] Verdict FIRST, emitted second. `check` needs to know which
        // root this rule has claimed so the two partitions stay disjoint; the
        // push order below is the pre-#13935 one.
        const verdict = fieldRuleRootVerdict(key, raw);
        check(where, raw, objectName, 'record', verdict !== null);
        if (verdict) {
          issues.push({ where, message: verdict.message, source: verdict.source, severity: 'error' });
        }
      }
      // [#22228] The field's cell formatting rules — `conditionalFormatting`,
      // each `{ condition, style }` (the list view's own rule element). Each
      // condition is judged by the `record`-scoped `check` with `value` named
      // as a root this surface binds (it parses, it reads `record.<field>`
      // and never a bare field, the field exists), plus this surface's own
      // root verdict: `value` and `record` only. Display only, like
      // `visibleWhen`, so none of the write-path gates below (the `parent`
      // gate, the null guard, the traversal refusal) applies. Not fenced on an
      // object write: the object save door runs this pass too, at this
      // position.
      //
      // `f.conditionalFormatting` is read LITERALLY so #5017's source scan
      // checks it against `FieldSchema`, and so is each rule's `condition`.
      // The index is the rule's position as authored — the location names it.
      const cellRules: readonly unknown[] = Array.isArray(f.conditionalFormatting) ? f.conditionalFormatting : [];
      for (const [ri, entry] of [...cellRules].entries()) {
        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
        const cellRule = entry as AnyRec;
        const location = `conditionalFormatting[${ri}].condition`;
        const where = `object '${objectName}' · field '${fname}' ${location}`;
        const raw: unknown = cellRule.condition;
        const ruleSource = celSourceOf(raw);
        const verdict = ruleSource ? fieldFormattingRootIssue(location, ruleSource) : null;
        check(where, raw, objectName, 'record', verdict !== null, undefined, undefined, FIELD_FORMATTING_SURFACE_ROOTS);
        if (verdict) {
          issues.push({ where, message: verdict.message, source: ruleSource!, severity: 'error' });
        }
      }
      // [commit e9b526597] Per-OPTION `visibleWhen` — a `select`/`multiselect`/`radio`
      // option's own predicate (`SelectOptionSchema.visibleWhen`,
      // `field.zod.ts:143`). It had no traversal here at all, so the whole
      // option surface reached compile, validate and run time unvalidated:
      // a bare field ref (`country == 'cn'`) or a reference to a field that
      // does not exist produced no build error, and the option then simply
      // never offered itself.
      //
      // Deliberately checked on the SAME `record` scope as the field-level
      // slots, and that is the whole of the difference between the two faces
      // after commit e9b526597: `current_user` is a declared root platform-wide (ADR-0068
      // D1), so it passes here — options resolve through
      // `resolveCascadingOptions` against the host's predicate scope, which
      // binds it (ADR-0068 / objectui#2284), and the showcase's
      // `'org_admin' in current_user.positions` is the pinned legal usage — while
      // `checkFieldRuleRoot` above rejects it one level up, where nothing
      // binds it. Same helper, two verdicts, because the two surfaces have two
      // evaluators; neither verdict is a side effect of a shared root list.
      //
      // [#22157] …and the option has a root verdict of its own, over the roots
      // the SERVER's option check binds (`optionVisibleWhenRootIssue`). The
      // shared root list (`SCOPE_ROOTS`) let every platform-wide root through
      // here, `parent` among them, though `evaluateOptionVisibility` binds only
      // `record`, `previous` and the acting user: such a predicate faulted on
      // every write that picked the option and was admitted unchecked. So the
      // two surfaces now differ by exactly what their evaluators bind: this
      // one accepts the acting user and refuses `parent`, the field-rule slots
      // the other way round. [#22274] The same verdict judges the members of
      // `ctx` and `os`, which the option check fills with `user` only, and
      // [#22394] the acting user's own members under all four of its spellings,
      // held to what `EvalUserSchema` declares AND the option check binds.
      //
      // [#22032, pass 3] NOT fenced on an object write: the option's `check`,
      // its root verdict (#22157) and its traversal refusal are the pass the
      // object save door runs, at the build's own position in this walk, so the
      // door's findings and their order are the build's — the `current_user`
      // acceptance above included. See
      // {@link StackExpressionOptions.runtimeWriteType}.
      for (const [oi, opt] of recordsOf(f.options).entries()) {
        const label = typeof opt.value === 'string' ? `'${opt.value}'` : `#${oi}`;
        const optionWhere = `object '${objectName}' · field '${fname}' option ${label} visibleWhen`;
        check(optionWhere, opt.visibleWhen, objectName, 'record');
        // [#22157] After `check`, before the traversal refusal: every root this
        // verdict judges is declared in the strict env, so `check` never
        // reports a bare reference to it and the two stay disjoint.
        const optionSource = celSourceOf(opt.visibleWhen);
        const verdict = optionSource ? optionVisibleWhenRootIssue(objectName, fname, label, optionSource) : null;
        if (verdict) {
          issues.push({ where: optionWhere, message: verdict.message, source: optionSource!, severity: 'error' });
        }
        // [#20078] An option's predicate is evaluated against the record as
        // stored — a read through a reference faults, and the server refuses
        // the write (ADR-0137 D2). `current_user` (and `current_user.can(…)`) is NOT a
        // record traversal and is not judged here.
        refuseFieldTraversal(optionWhere, 'option visibleWhen', opt.visibleWhen, optionHolders);
      }
      // [#4889] A `parent`-scoped `readonlyWhen` is a SERVER-enforced lock:
      // the write path resolves the object's master-detail header and binds it
      // as `parent`. That binding exists only when the object declares exactly
      // ONE `master_detail` relationship. With none — or with two, where the
      // metadata does not say which one "the parent" is — the predicate can
      // never evaluate, and the runtime then holds the field LOCKED forever (it
      // will not wave a declared lock through just because it could not be
      // checked). The metadata already contains everything needed to see that
      // at build time, so it is decided here rather than discovered as an
      // unwritable field in production — PD #12, declared rather than guessed.
      //
      // [#4977] Extended to `requiredWhen`, which the server enforces from the
      // same declaration site through the same evaluator and which gained its
      // own `parent` binding in the same issue. The two slots ask ONE question —
      // "is `parent` a fact this object's metadata states?" — so they share one
      // gate rather than growing a second copy of `masterDetailCount` +
      // `readsParentRoot`.
      //
      // What they do NOT share is the CONSEQUENCE, and the message has to name
      // the right one or it prescribes the wrong fix (the same reason #4811's
      // null-guard gate passes its outcome in explicitly instead of inferring
      // it). The two runtimes answer an unbindable `parent` differently:
      // `readonlyWhen` fails CLOSED (#4889 — an unbound scope root resolves to
      // LOCKED, so the field becomes unwritable forever), while `requiredWhen`
      // REFUSES the write (ADR-0137 D2 — it was fail-OPEN until then, #4977)
      // wherever the predicate reads `parent`. Either way the declaration is
      // unusable, and this gate is where the author meets it instead of the
      // first write in production.
      //
      // `visibleWhen` (no server-enforced `parent` binding of its own) keeps
      // its verdict untouched.
      // Destructured in the loop head on purpose: both predicate slots stay
      // LITERAL member reads (`f.readonlyWhen` / `f.requiredWhen`) rather than a
      // computed `f[key]`, so the #5017 meta-test's source scan still sees every
      // key this rule reads and can still check it against `FieldSchema`. An
      // indexed read here would have disarmed that scan silently.
      for (const [slot, raw, consequence] of [
        ['readonlyWhen', f.readonlyWhen, `the field would be locked on every write`],
        ['requiredWhen', f.requiredWhen, `writes would be refused — the predicate faults wherever it reads \`parent\`, and the server refuses a write whose requirement it cannot evaluate`],
      ] as const) {
        const source = celSourceOf(raw);
        if (masters === 1 || !source || !readsParentRoot(source)) continue;
        issues.push({
          where: `object '${objectName}' · field '${fname}' ${slot}`,
          message:
            `\`${slot}\` reads \`parent\`, but object '${objectName}' declares ` +
            `${masters === 0 ? 'no' : `${masters}`} \`master_detail\` relationship${masters === 1 ? '' : 's'} — ` +
            `so the server has no header record to bind as \`parent\` and ${consequence}. ` +
            (masters === 0
              ? `Declare the owning relationship as \`Field.masterDetail('<master>')\`, or rewrite the predicate against \`record\`.`
              : `\`parent\` needs exactly one master; name the header explicitly through \`record.<fk>\` state instead, or model the extra relationship as a \`lookup\`.`),
          source,
          severity: 'error',
        });
      }
      // #4811 — `requiredWhen` is the one field-level slot that meets the
      // null-guard gate's totality criterion: `evaluateValidationRules`
      // evaluates it against the SAME `materializeDeclaredFields`-merged
      // record the object's validation rules see. It is also the surface
      // where an unguarded predicate used to hurt most quietly — a faulting
      // `requiredWhen` was fail-OPEN, so the field was simply never required
      // and the write sailed through. Since ADR-0137 D2 it refuses the write
      // (`rule-validator.ts`: "failed to evaluate … — write rejected"), the
      // same outcome as a validation rule's since #4761, so it takes the
      // `'fail-closed'` clause below.
      //
      // `readonlyWhen` is still NOT included even though it sits on the same
      // field — but no longer because its binding is sparse. Since #6454
      // `readonlyWhenBindings` runs both roots through
      // `materializeDeclaredFields`, so `!= null` IS the right prescription
      // there now; what holds the wiring back is clause 3 of the #4953 ruling
      // (both server-side seams first — the flow trigger-record half is
      // outstanding). When it is wired it needs `'fail-closed'`, like
      // `requiredWhen` above: a faulting `readonlyWhen` refuses the write since
      // ADR-0137 D2 too. `visibleWhen` has no record-scoped total binding of
      // its own. See the surface ledger in
      // `validate-null-guards.ts`.
      checkNullGuards(
        `object '${objectName}' · field '${fname}' requiredWhen`,
        `field '${fname}' requiredWhen`,
        f.requiredWhen,
        objectName,
        'fail-closed',
      );
      // [#20078] The two field-rule slots the server evaluates on a write are
      // never hydrated, so a read THROUGH a reference field faults there on
      // every row and, since ADR-0137 D2, refuses the write. Refused here, with
      // the seam that does read one hop (a `validations[]` rule) as the repair.
      // Literal member reads, like the `parent` gate above, for the #5017 scan.
      for (const [slot, raw] of [
        ['requiredWhen', f.requiredWhen],
        ['readonlyWhen', f.readonlyWhen],
      ] as const) {
        refuseFieldTraversal(`object '${objectName}' · field '${fname}' ${slot}`, slot, raw, fieldRuleHolders);
      }
      judgeFieldFormula(fname, f);
    }

    // [#26646] A field group's section predicate — `fieldGroups[].visibleWhen`
    // (ADR-0085 §5). The form renderer evaluates it with the same engine,
    // record assembly and scope as a field's own `visibleWhen` and gates the
    // WHOLE group fail-closed, so a predicate that faults (a bare reference,
    // an unknown field) hides the group, header included, on every form and
    // record page. It takes the field `visibleWhen` slot's verdict exactly:
    // the `record`-scoped `check` and the root verdict over
    // FIELD_RULE_BOUND_ROOTS, worded for the group. Display only, like
    // `visibleWhen`, so none of the write-path gates above (the `parent` gate,
    // the null guard, the traversal refusal) applies. Not fenced on an object
    // write: the object save door runs this pass too, at this position.
    // Located at the group's `key`, the name a field's `group` points back to.
    //
    // `fieldGroup.visibleWhen` is read LITERALLY so #5017's source scan checks
    // it against `ObjectFieldGroupSchema`.
    for (const fieldGroup of recordsOf(obj.fieldGroups)) {
      const groupKey = typeof fieldGroup.key === 'string' ? fieldGroup.key : '?';
      const where = `object '${objectName}' · field group '${groupKey}' visibleWhen`;
      const raw: unknown = fieldGroup.visibleWhen;
      const verdict = fieldRuleRootVerdict(FIELD_GROUP_VISIBLE_WHEN_SLOT, raw);
      check(where, raw, objectName, 'record', verdict !== null);
      if (verdict) {
        issues.push({ where, message: verdict.message, source: verdict.source, severity: 'error' });
      }
    }
  }

  // ── Action `visible` / `disabled` predicates ───────────────────────
  // Record-scoped, same as validation rules: a record-header / row action's
  // `visible` is evaluated by ActionEngine against `{ record, recordId,
  // objectName, user, … }` with fail-closed semantics, so a BARE field ref
  // (`done` instead of `record.done`) throws and the action is silently hidden
  // on every record (the trap behind the #2183 "Mark Done never hides" hunt).
  // Flagging it here turns that into a build error with a corrective message.
  // `disabled` may be a boolean (skip) or a predicate (check).
  const seenActions = new Set<string>();
  const checkAction = (where: string, action: AnyRec, objectName?: string): void => {
    // `objectName` is the declared key on an action; `object` is the rejected
    // alias the strict error map maps back to it ("Did you mean `object` →
    // `objectName`?"), so an action spelling it does not parse (#5017).
    const obj = objectName
      ?? (typeof action.objectName === 'string' ? action.objectName : undefined);
    const name = typeof action.name === 'string' ? action.name : '?';
    const key = `${obj ?? ''}:${name}`;
    if (seenActions.has(key)) return; // de-dup (actions are merged onto objects AND kept top-level)
    seenActions.add(key);
    // The served-row sites: an action's predicates bind the row the surface
    // fetched, so a declared read attachment resolves here and nowhere else.
    check(`${where} · action '${name}' visible`, action.visible, obj, 'record', undefined, undefined, 'action visible');
    if (typeof action.disabled !== 'boolean') {
      check(`${where} · action '${name}' disabled`, action.disabled, obj, 'record', undefined, undefined, 'action disabled');
    }
    // No `checkNullGuards` here, and the reason is measured rather than assumed
    // (#4811). These predicates DO reach real CEL — a bare authored string is
    // normalized to a `{dialect:'cel'}` envelope by `ExpressionInputSchema` and
    // `objectui`'s renderers preserve it — and a fault IS fail-closed, so the
    // `has(a) && has(b) && a < b` trap genuinely bites here too: the action
    // silently disappears on every record. What blocks the gate is the record
    // BINDING: it is whatever the client fetched (a detail read, or a list row
    // holding only the view's projected columns), and no materialization step
    // exists anywhere on that path. On such a sparse binding `!= null` — the fix
    // this gate prescribes — faults with `No such key`, so gating here would
    // reject working metadata and hand the author a correction that breaks it.
    // Covering this surface means first making the binding total, which is a
    // platform contract change, not a lint change. Ledger: `validate-null-guards.ts`.
    //
    // Nor is the INVERSE rule the answer. "Flag `!= null` on a sparse binding"
    // was evaluated and declined (#8881): on a sparse binding the abort is at
    // key resolution, so `record.a == 'pending'` faults exactly as `!= null`
    // does — `!= null` is one spelling of nine, not the fault. Measured yield
    // over authored metadata in both repos is 2 of 34 record-scoped action
    // predicates, and whether any given one faults depends on the VIEW's
    // `$select` projection (and, through `&&` short-circuiting, on row data),
    // neither of which this pass can see. Full reasoning in the ledger.
  };
  // The stack's top-level `actions` are not an object's own body: an object
  // write reads an empty list here (they are judged at the `action` door). See
  // {@link StackExpressionOptions.runtimeWriteType}.
  for (const action of objectWrite ? [] : recordsOf(stack.actions)) {
    checkAction('stack', action);
  }
  // [#22032, pass 4] NOT fenced on an object write: an object's own
  // `actions[]` predicates are the pass the object save door runs, so the
  // door's findings and their order are the build's for an object body. The
  // one difference is a location, never a verdict: an action also declared
  // top-level was claimed by the loop above in the build (`stack · action …`),
  // and is located here on an object write.
  for (const obj of objects) {
    const objectName = typeof obj.name === 'string' ? obj.name : undefined;
    for (const action of recordsOf(obj.actions)) {
      checkAction(`object '${objectName}'`, action, objectName);
    }
  }

  // ── Sharing-rule predicates (security-critical, record-scoped) ─────
  // A criteria sharing rule's `condition` decides which rows a principal sees.
  // It is evaluated against the record, so a bare ref silently changes access.
  // Named `sharingRule` rather than `rule` so the declared-key guard in the
  // test can tell this receiver apart from the VALIDATION rule one — the two
  // are governed by different schemas, and a scan that merged them would let a
  // key declared by either schema pass on both (#5017).
  for (const sharingRule of objectWrite ? [] : recordsOf(stack.sharingRules)) {
    const ruleObj = typeof sharingRule.object === 'string' ? sharingRule.object : undefined;
    const where = `sharingRule '${(sharingRule.name as string) ?? '?'}'${ruleObj ? ` (${ruleObj})` : ''} condition`;
    // `condition` is the authored key `SharingRuleSchema` declares. `criteria`
    // is the RUNTIME spelling of the compiled predicate (`criteria_json`) and
    // `sharing.zod.ts` maps it back to `condition` in its rejection message;
    // `predicate` is refused with no rename at all. #4984 removed exactly this
    // pair one file over; this was the same read left behind (#5017).
    check(where, sharingRule.condition, ruleObj, 'record');
  }

  // ── Hook `condition` predicates (record-scoped gate) ───────────────
  // A lifecycle hook's `condition` skips the handler when false; it is
  // evaluated against the record, so a bare ref silently makes the hook
  // run on every record (or never) instead of the intended subset.
  for (const hook of objectWrite ? [] : recordsOf(stack.hooks)) {
    const hookName = (hook.name as string) ?? '?';
    if (typeof hook.object === 'string') {
      check(`hook '${hookName}' (${hook.object}) condition`, hook.condition, hook.object, 'record');
      // #4763 — the third instance the issue found lived on exactly this path.
      checkNullGuards(
        `hook '${hookName}' (${hook.object}) condition`,
        `hook '${hookName}' condition`,
        hook.condition,
        hook.object,
      );
      continue;
    }

    // A hook may target MANY objects (`object: ['a','b']`). Previously any
    // non-string target dropped to `undefined`, so the condition got NO
    // field-awareness at all — a hook filtering on a field that exists on none
    // of its targets passed clean (issue #3583). The hook body runs against
    // each target in turn, so a ref missing from ANY of them silently
    // misbehaves there; validate per target and de-duplicate the
    // object-independent diagnostics (syntax/shape) that every pass repeats.
    const targets = Array.isArray(hook.object)
      ? (hook.object as unknown[]).filter((o): o is string => typeof o === 'string' && o !== '*')
      : [];
    if (targets.length === 0) {
      // `'*'` (or an unusable shape) — no single field set to judge against;
      // syntax/shape is still validated.
      check(`hook '${hookName}' condition`, hook.condition, undefined, 'record');
      continue;
    }

    const before = issues.length;
    const seen = new Set<string>();
    const kept: ExprIssue[] = [];
    for (const target of targets) {
      const mark = issues.length;
      check(`hook '${hookName}' (${target}) condition`, hook.condition, target, 'record');
      checkNullGuards(
        `hook '${hookName}' (${target}) condition`,
        `hook '${hookName}' condition`,
        hook.condition,
        target,
      );
      for (let i = mark; i < issues.length; i++) {
        const issue = issues[i];
        const key = `${issue.message}\u0000${issue.source ?? ''}`;
        // Keep the first occurrence of each distinct diagnostic. A field-unknown
        // finding differs per target (it names the object), so each survives;
        // a syntax error is identical across targets and collapses to one.
        if (!seen.has(key)) {
          seen.add(key);
          kept.push(issue);
        }
      }
    }
    issues.length = before;
    issues.push(...kept);
  }

  // [#24798] The bulk `confirmText` template slots: an object's own
  // `listViews` on every run (an object write included — they are the
  // object's own body), a view's list containers off an object write.
  issues.push(...bulkConfirmTextIssues(stack, { views: !objectWrite, objects: true }));
  // [#24814] The action copy template slots: an object's own `actions[]` on
  // every run (an object write included), the top-level `actions` and the
  // pages' action rows off an object write. Errors since #25680, a holeless
  // `${…}` sentence included since #25709.
  issues.push(...actionCopyTemplateIssues(stack, { actions: !objectWrite, objects: true, pages: !objectWrite }));

  return issues;
}

/** The slot as {@link closedScopeTemplateRefusal}'s sentences name it. */
const BULK_CONFIRM_TEXT_SLOT = "A bulk action's `confirmText`";

/** A blank sentence — `trim()`'s whitespace set is exactly `\s`. */
const BLANK_TEXT = /^\s*$/;

/** The label segment for a named list view (`listViews.<key>`). */
const LIST_VIEWS_LABEL = 'listViews';

/**
 * [#24798, ruling B] Judge every bulk action def's `confirmText` — the
 * ADR-0032 `template` slot `ui/bulk-action.zod.ts` declares over a CLOSED
 * scope, `bulkConfirmTemplateRoots(def)` (`count` and the def's params by
 * name). The same two steps the flow text slots take above, in the same
 * order, through the same judge: a single-brace token or a hole over an
 * unbound root is named by `closedScopeTemplateRefusal` (the template judge's
 * closed-scope entry), and a text carrying neither is compiled as the
 * `template` it is (`validateExpression('template', …)`), which names a hole
 * holding logic or an unknown formatter. A blank sentence is named too.
 *
 * [#25205] Every finding is an `error`, as the flow text slots' are: the three
 * doors refuse the text, and the publish gate answers its 422. Each of these
 * texts parsed before the slot was typed, so the refusal is a narrowing no
 * ADR-0087 conversion carries; under the amended 「甲」 (record 6303865025) it
 * ships in 18.x as its own BREAKING minor (the `validatePagePredicateBounds`
 * precedent: advisory first, in #24798, refusal after). The parse is not
 * narrowed: a stored view keeps loading, and its next save is judged here.
 * The containers walked: a view's `list` and each `listViews.<key>`, a
 * standalone list view (the flattened overlay or the ViewItem record), and an
 * object's `listViews.<key>`.
 */
function bulkConfirmTextIssues(
  stack: AnyRec,
  { views: judgeViews, objects: judgeObjects }: { views: boolean; objects: boolean },
): ExprIssue[] {
  const issues: ExprIssue[] = [];
  // Every metadata read below is a literal read off a receiver the #5017
  // meta-test tables (`stack`, `obj`, `bulkDef`, and `viewEntry`, a union of
  // shapes): a `.length` or a label string spelling `listViews.` would read
  // as one more receiver to it, so the loops index by hand and the label is
  // joined from LIST_VIEWS_LABEL.
  const judgeContainer = (container: unknown, at: string): void => {
    if (!container || typeof container !== 'object') return;
    const listed = (container as AnyRec).bulkActionDefs;
    if (!Array.isArray(listed)) return;
    let di = -1;
    for (const bulkDef of listed as AnyRec[]) {
      di += 1;
      if (!bulkDef || typeof bulkDef !== 'object' || bulkDef.confirmText === undefined) continue;
      const confirmSource = templateSlotSource(bulkDef.confirmText);
      if (confirmSource === undefined) continue; // neither a string nor a template envelope: the parse refuses its shape
      const label = typeof bulkDef.name === 'string' ? ` '${bulkDef.name}'` : '';
      const where = `${at} · bulkActionDefs[${di}]${label} confirmText`;
      const refuse = (message: string, quoted: string): void => {
        issues.push({ where, message, source: quoted, severity: 'error' });
      };
      if (BLANK_TEXT.test(confirmSource)) {
        refuse(
          `${BULK_CONFIRM_TEXT_SLOT} is blank, so the confirm step shows an empty sentence where the default one names `
            + 'the record count: write the sentence, or remove the key to show the default.',
          confirmSource,
        );
        continue;
      }
      const refusal = closedScopeTemplateRefusal(confirmSource, { slot: BULK_CONFIRM_TEXT_SLOT, roots: bulkConfirmTemplateRoots(bulkDef) });
      if (refusal !== undefined) {
        refuse(refusal, confirmSource);
        continue;
      }
      for (const e of validateExpression('template', confirmSource).errors) refuse(e.message, e.source);
    }
  };
  const judgeListViews = (named: unknown, owner: string): void => {
    if (!named || typeof named !== 'object' || Array.isArray(named)) return;
    for (const [key, lv] of Object.entries(named as AnyRec)) judgeContainer(lv, `${owner} · ${LIST_VIEWS_LABEL}.${key}`);
  };
  if (judgeViews) {
    let vi = -1;
    for (const viewEntry of recordsOf(stack.views)) {
      vi += 1;
      const viewName = typeof viewEntry.name === 'string' ? viewEntry.name : typeof viewEntry.object === 'string' ? viewEntry.object : `#${vi}`;
      // The two standalone shapes `PUT /api/v1/meta/view` carries and the
      // publish gate snapshots as `views: [item]` — recognised as the list-view
      // field rules recognise them (`validate-list-view-field-refs.ts`): the
      // flattened list overlay (the `ListView` at the top level) and the
      // ViewItem record (one level down, in `config`). Without them a view
      // write would run this pass over nothing.
      if (viewEntry.viewKind === 'list') {
        const record = viewEntry.config !== null && typeof viewEntry.config === 'object' && !Array.isArray(viewEntry.config);
        judgeContainer(record ? viewEntry.config : viewEntry, `view '${viewName}' (${record ? 'ViewItem record' : 'flattened list overlay'})`);
      }
      judgeContainer(viewEntry.list, `view '${viewName}' · list`);
      judgeListViews(viewEntry.listViews, `view '${viewName}'`);
    }
  }
  if (judgeObjects) {
    let oi = -1;
    for (const obj of recordsOf(stack.objects)) {
      oi += 1;
      judgeListViews(obj.listViews, `object '${typeof obj.name === 'string' ? obj.name : `#${oi}`}'`);
    }
  }
  return issues;
}