@@ -0,0 +1,30 @@
+---
+'@objectstack/spec': minor
+---
+
+feat(spec)!: a view filter rule's `operator` is typed as the canonical `ViewFilterOperator`, not `unknown`
+
+**BREAKING for TypeScript code that writes a view filter rule through a published type**: `ViewFilterRule`, and every carrier of it — `ListView.filter`, a view tab's `filter`, `InterfacePageConfig.filterBy`, and the related-list, record-picker and `object-*` block filter doors. A narrowing of a published TYPE, landing as `minor` (the bump level is not the carrier; this banner and the disposition below are). The runtime accept set does not move at all: no schema's parse, no value and no export changes.
+
+`operator` is a `z.preprocess` over the alias fold, and zod types a preprocess's input from its function's parameter. That parameter was `unknown`, so `ViewFilterRule['operator']` was `unknown`: `{ field: 'status', operator: 42 }` compiled as a rule on every carrier, and was refused only when the schema parsed it. The input type is now `ViewFilterOperator`, the vocabulary the alias table's own contract says new producers emit, so an alias spelling or a non-string is refused by the compiler.
+
+What does not change:
+
+- **The runtime.** `ViewFilterRuleSchema` still folds every legacy spelling it folded before (`eq`, `gt`, `notIn`, `isNull`, …) to its canonical id, and still refuses a non-string at `operator` with the enum's own issue. Stored `sys_metadata` rows, YAML and JSON bodies and plain-JS producers that carry an alias parse exactly as before, and `os validate` answers as before.
+- **`normalizeFilterOperator`.** Its parameter stays `unknown`: it exists to fold untyped stored metadata, and its callers pass raw strings by design.
+- **The parsed type.** `ViewFilterRuleParsed['operator']` was already the canonical enum.
+
+## FROM → TO
+
+| Wrote (TypeScript) | Write instead |
+| --- | --- |
+| `{ field: 'status', operator: 'eq', value: 'open' }` | `{ field: 'status', operator: 'equals', value: 'open' }` |
+| `{ field: 'amount', operator: 'gte', value: 100 }` | `{ field: 'amount', operator: 'greater_than_or_equal', value: 100 }` |
+| `{ field: 'stage', operator: 'notIn', value: ['lost'] }` | `{ field: 'stage', operator: 'not_in', value: ['lost'] }` |
+| `operator: someString` (a value typed `string`) | type the unvalidated rule `unknown` and `ViewFilterRuleSchema.safeParse` it, or fold it with `normalizeFilterOperator` and check it against `VIEW_FILTER_OPERATORS` first |
+
+The one-line fix: write the canonical id. Every alias maps to exactly one, and `VIEW_FILTER_OPERATOR_ALIASES` is that map; the rewritten rule selects the same rows, because the schema already folded the alias to that id.
+
+Clause-②: yes (narrowing)
+
+<!-- adr-0087: registered view-filter-rule-operator-input-canonical -->
@@ -0,0 +1,51 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { SemanticMigration } from '../../types.js';
+
+// A TYPE-surface narrowing registered here for the reason
+// `spec-type-alias-input-suffix-retired` is: the surface is a TypeScript
+// declaration, so there is no stored source for a D2 conversion to rewrite, and
+// the compiler error it produces names the canonical vocabulary but not which
+// member an alias spelling maps to. This guide is the channel that carries that
+// second half. Nothing at rest moves and the runtime accept set is unchanged.
+export const entry: SemanticMigration = {
+  id: 'view-filter-rule-operator-input-canonical',
+  // No backticks in `surface` — build-upgrade-guide renders it inside a code
+  // span already, and a nested backtick would close it.
+  surface:
+    'ui.ViewFilterRule operator — the TypeScript INPUT type of a view filter rule, on every '
+    + 'carrier of ViewFilterRuleSchema (ListView.filter, a view tab filter, Page.filterBy, the '
+    + 'related-list, record-picker and object-* block filter doors)',
+  replacement:
+    'the canonical operator id, a member of ViewFilterOperator (VIEW_FILTER_OPERATORS). A '
+    + 'typed rule written operator: "eq" becomes operator: "equals"; every legacy spelling maps '
+    + 'to exactly one canonical id, and VIEW_FILTER_OPERATOR_ALIASES is that map (ne and neq to '
+    + 'not_equals, gt to greater_than, gte to greater_than_or_equal, nin and notIn to not_in, '
+    + 'isNull to is_null, and the rest). A value that is not yet known to be an operator — '
+    + 'read from storage, a URL or user input — is typed unknown and handed to '
+    + 'ViewFilterRuleSchema.safeParse, or folded with normalizeFilterOperator first; the '
+    + 'schema stays the judge',
+  reason:
+    'The operator key is a z.preprocess over the alias fold, and zod types a preprocess\'s '
+    + 'INPUT from its function\'s parameter. That parameter was unknown, so ViewFilterRule (a '
+    + 'z.input) typed operator as unknown: a rule with operator: 42, or any string at all, '
+    + 'compiled on every carrier and was refused only when the door parsed it. The typed input '
+    + 'is now the canonical ViewFilterOperator, the vocabulary the alias table\'s own contract '
+    + 'says new producers emit. '
+    + 'The RUNTIME does not move: the door still folds every spelling it folded before to '
+    + 'canonical and still refuses a non-string with the enum\'s own '
+    + 'issue at operator, so a stored sys_metadata row, a YAML or JSON body, and a plain-JS '
+    + 'producer that carries an alias keep parsing exactly as before, and os validate answers '
+    + 'as before. Metadata AT REST is deliberately NOT rewritten and this entry adds no D2 '
+    + 'conversion: what narrows is only what TypeScript source may write. '
+    + 'The exported normalizeFilterOperator keeps its unknown parameter on purpose — it exists '
+    + 'to fold untyped stored metadata, and its callers pass raw strings by design. ADR-0087 / '
+    + 'ADR-0122.',
+  acceptanceCriteria:
+    'Your TypeScript compiles: tsc reports each typed rule whose operator is an alias or a '
+    + 'non-string, naming the canonical vocabulary. Rewrite each alias to the id '
+    + 'VIEW_FILTER_OPERATOR_ALIASES maps it to — the rule selects the same rows, because the '
+    + 'door already folded it to that id — and for a value typed string that is really '
+    + 'unvalidated input, type it unknown and parse it rather than casting it. Stored views need '
+    + 'no action: they load and parse as before.',
+};
@@ -16902,6 +16902,53 @@ const step18: MigrationStep = {
         + 'query before this change, so re-check what it is supposed to show rather than assuming '
         + 'any earlier result set.',
     },
+    // A TYPE-surface narrowing registered here for the reason
+    // `spec-type-alias-input-suffix-retired` is: the surface is a TypeScript
+    // declaration, so there is no stored source for a D2 conversion to rewrite, and
+    // the compiler error it produces names the canonical vocabulary but not which
+    // member an alias spelling maps to. This guide is the channel that carries that
+    // second half. Nothing at rest moves and the runtime accept set is unchanged.
+    {
+      id: 'view-filter-rule-operator-input-canonical',
+      // No backticks in `surface` — build-upgrade-guide renders it inside a code
+      // span already, and a nested backtick would close it.
+      surface:
+        'ui.ViewFilterRule operator — the TypeScript INPUT type of a view filter rule, on every '
+        + 'carrier of ViewFilterRuleSchema (ListView.filter, a view tab filter, Page.filterBy, the '
+        + 'related-list, record-picker and object-* block filter doors)',
+      replacement:
+        'the canonical operator id, a member of ViewFilterOperator (VIEW_FILTER_OPERATORS). A '
+        + 'typed rule written operator: "eq" becomes operator: "equals"; every legacy spelling maps '
+        + 'to exactly one canonical id, and VIEW_FILTER_OPERATOR_ALIASES is that map (ne and neq to '
+        + 'not_equals, gt to greater_than, gte to greater_than_or_equal, nin and notIn to not_in, '
+        + 'isNull to is_null, and the rest). A value that is not yet known to be an operator — '
+        + 'read from storage, a URL or user input — is typed unknown and handed to '
+        + 'ViewFilterRuleSchema.safeParse, or folded with normalizeFilterOperator first; the '
+        + 'schema stays the judge',
+      reason:
+        'The operator key is a z.preprocess over the alias fold, and zod types a preprocess\'s '
+        + 'INPUT from its function\'s parameter. That parameter was unknown, so ViewFilterRule (a '
+        + 'z.input) typed operator as unknown: a rule with operator: 42, or any string at all, '
+        + 'compiled on every carrier and was refused only when the door parsed it. The typed input '
+        + 'is now the canonical ViewFilterOperator, the vocabulary the alias table\'s own contract '
+        + 'says new producers emit. '
+        + 'The RUNTIME does not move: the door still folds every spelling it folded before to '
+        + 'canonical and still refuses a non-string with the enum\'s own '
+        + 'issue at operator, so a stored sys_metadata row, a YAML or JSON body, and a plain-JS '
+        + 'producer that carries an alias keep parsing exactly as before, and os validate answers '
+        + 'as before. Metadata AT REST is deliberately NOT rewritten and this entry adds no D2 '
+        + 'conversion: what narrows is only what TypeScript source may write. '
+        + 'The exported normalizeFilterOperator keeps its unknown parameter on purpose — it exists '
+        + 'to fold untyped stored metadata, and its callers pass raw strings by design. ADR-0087 / '
+        + 'ADR-0122.',
+      acceptanceCriteria:
+        'Your TypeScript compiles: tsc reports each typed rule whose operator is an alias or a '
+        + 'non-string, naming the canonical vocabulary. Rewrite each alias to the id '
+        + 'VIEW_FILTER_OPERATOR_ALIASES maps it to — the rule selects the same rows, because the '
+        + 'door already folded it to that id — and for a value typed string that is really '
+        + 'unvalidated input, type it unknown and parse it rather than casting it. Stored views need '
+        + 'no action: they load and parse as before.',
+    },
     // The scalar half of the coupling #6227 declared and did not judge. Recorded
     // here rather than amended onto `view-filter-rule-value-shaped-by-operator`
     // because that entry's own prose states the OPPOSITE reading as accepted, and