@@ -0,0 +1,23 @@
+---
+'@objectstack/lint': minor
+'@objectstack/spec': patch
+---
+
+fix(lint)!: a `lookup` or `master_detail` field whose `reference` is a stored-metadata-body table is refused where it is declared
+
+Clause-②: no (narrowing)
+
+<!-- adr-0087: not-required (no-migration-prescription) No spec key, stored shape or authorable spelling is added, removed or renamed. The expression rule's object pass now refuses one field declaration it accepted before: a `lookup` or `master_detail` whose `reference` is `sys_metadata` or `sys_metadata_history`, which the engine never hydrates. Nothing stored is rewritten, so there is nothing for `objectstack migrate meta` to convert; the `@objectstack/spec` change is the text of the `reference` describe only. -->
+
+**BREAKING** (an authoring narrowing), shipped as `minor` under the launch-window convention for breaking changes.
+
+A `lookup` or `master_detail` whose `reference` names a table of the stored-metadata-body family (`STORED_METADATA_BODY_OBJECTS`: `sys_metadata`, `sys_metadata_history`) is an error. The engine never hydrates such a field: `$expand` keeps the stored id and never nests the row, a formula or a validation rule never reads through it, and a master-detail child's `parent` root stays unbound, so every write a `parent` rule judges is refused. `os validate`, `os build` and the object save door (`PUT /api/v1/meta/object/:name`, and a draft's promotion) run the same pass, under the existing `EXPRESSION_INVALID` rule, located at the field's `reference`.
+
+- FROM: `meta: { type: 'lookup', reference: 'sys_metadata' }` (or a `master_detail`, or `sys_metadata_history`) saved with a 200 and built with exit 0, and then only ever showed an id. TO: refused, with `422 INVALID_METADATA` at the save door and an error at `os validate` / `os build`. The message names the field, its type and the target, and ends on the family's one prescription.
+- A reference to any other table, platform tables such as `sys_user` included, is unchanged.
+- A `user` field whose authored `reference` names a family table is refused the same way: the parse accepts an authored `reference` on a `user` field, and it is the target every reader resolves.
+- The refusal of a formula or a validation rule that reads through such a field is unchanged, and is still reported at that expression.
+- A stored object row that already declares such a field keeps loading: no authoring rule runs when a stored row is rehydrated, and the engine guards keep refusing every relationship read into the family. Its next active save, or a draft's promotion, through the metadata API is refused until the field is removed or retargeted. The engine guards stay, for every path that runs no authoring rule.
+- `@objectstack/spec` (`patch`): the `reference` describe states the convention, so the generated field reference says it too.
+
+What to do. Remove the field, or retarget it. To point a record at a metadata item, store the item's type and name in `text` fields and read the item through the metadata API (`GET /api/v1/meta/:type/:name`), where its body is projected.
@@ -0,0 +1,12 @@
+---
+'@objectstack/plugin-security': patch
+---
+
+fix(plugin-security): a delegated administrator's position assignment is judged on every permission set the assignment grants, the set of the position's own name included
+
+Clause-②: no
+
+- **The rule (ADR-0090 D12, as amended 2026-10-17).** The sets a position carries are every set an assignment of it grants: the names its definition's `permissionSets` lists and, while the authorization resolver folds held position names into the requested set names, the permission set of the position's own name when the catalog holds one. The organization-level branch already counted that set. The delegated branch now does too, through the same helper.
+- **What a delegate is now refused.** A `sys_user_position` insert, update or delete by an `adminScope` holder whose allowlist does not cover the position's own-name set is refused `403 PERMISSION_DENIED`. The message names the set and says it is the set of the position's own name. An own-name set that carries an `adminScope` is held to strict containment like any other distributed set. A delegatable position whose own-name set carries an `adminScope` can no longer be self-delegated.
+- **What the delegable-scope report offers.** `GET /api/v1/security/my-delegable-scope` no longer lists a position for a delegate whose allowlist misses that position's own-name set, so the picker offers only what the write admits.
+- **Unchanged.** A position with no permission set of its own name is judged on its listed sets alone, as before. Tenant-level administrators and the organization-level branch are untouched, and the resolver's fold itself is not changed. To keep a delegate able to assign such a position, add the own-name set to the scope's `assignablePermissionSets`.
@@ -0,0 +1,29 @@
+---
+'@objectstack/plugin-auth': patch
+'@objectstack/runtime': patch
+'@objectstack/cli': patch
+'@objectstack/service-settings': patch
+---
+
+fix(plugin-auth): the auth IP allow-list judges the client address the server established (#24739)
+
+Clause-②: no
+
+The `allowed_ip_ranges` auth setting (ADR-0069 D5) and the `last_login_ip` login audit (D7) now establish a request's client address by the same rule as the inbound rate limiter: `X-Forwarded-For` (its first entry), then `X-Real-IP`, count only when the stack declares `server.trustProxy`. Otherwise the address is the connection's peer address.
+
+**For operators who set `allowed_ip_ranges`:**
+
+- Behind a reverse proxy or load balancer, declare `server: { trustProxy: true }` in the stack before you upgrade. Without it, the allow-list judges the proxy's own address for every request.
+- A request whose client address cannot be established (the transport reports no peer address, and no forwarded header is trusted) is now refused with `403 IP_NOT_ALLOWED`. Before, it was admitted. The first such refusal logs a warning that names `allowed_ip_ranges` and `server.trustProxy`.
+- `CF-Connecting-IP` is no longer read. Behind Cloudflare, declare `server.trustProxy`, and the `X-Forwarded-For` it sets is used.
+- A dual-stack listener reports an IPv4 client in IPv4-mapped form (`::ffff:203.0.113.7`). That address is now matched as the IPv4 address it denotes.
+- With `allowed_ip_ranges` unset or empty, nothing changes.
+
+**`last_login_ip`** records the address the allow-list judged, or no address when none could be established. It is no longer read from a forwarded header the deployment does not trust.
+
+**By package:**
+
+- `@objectstack/plugin-auth`: the rule is published as the dependency-free `@objectstack/plugin-auth/client-address` entry (`resolveClientAddress`). `AuthPlugin` and `AuthManager` take a `trustProxy` option. `AuthManager.handleRequest` takes an optional second argument that carries the transport's `remoteAddress`.
+- `@objectstack/runtime`: the inbound rate limiter imports the rule from that entry instead of keeping its own copy. Its keys are unchanged.
+- `@objectstack/cli`: `objectstack serve` passes the stack's `server.trustProxy` to `AuthPlugin` as well as to the dispatcher. A host that composes `AuthPlugin` itself passes `trustProxy` the same way.
+- `@objectstack/service-settings`: the `allowed_ip_ranges` help text says which address is judged.
@@ -0,0 +1,14 @@
+---
+'@objectstack/plugin-audit': minor
+'@objectstack/plugin-auth': patch
+---
+
+fix(plugin-audit,plugin-auth): a refused sign-in and an account lockout each write a `sys_audit_log` row, as a successful sign-in already does
+
+Clause-②: no
+
+- **Two new ledger actions, each with its writer.** `sys_audit_log.action` gains `login_failed` and `account_locked`. A refused `/sign-in/email` that names an existing account writes one `login_failed` row. The refused sign-in that stamps the account lockout (`lockoutThreshold`, ADR-0069 D2) also writes one `account_locked` row. A sign-in refused while the account is locked writes `login_failed` with the reason `ACCOUNT_LOCKED`. A successful sign-in still writes `login`, unchanged.
+- **What each row records.** `user_id` is the account the sign-in named, and the row names `sys_user` and that account's id as its target. The outcome is the action, plus the refusal's machine code in `metadata` (`INVALID_EMAIL_OR_PASSWORD`, `ACCOUNT_LOCKED`, …), and the lock's `locked_until` and `threshold` on an `account_locked` row. `created_at` is the time. `ip_address` and `user_agent` are resolved by the rule better-auth applies to a session row, which is where a `login` row's values come from. `actor` is null, because a refused attempt authenticated nobody. A row never carries the attempted credential, and an identifier that resolves to no account writes no row.
+- **Where they show.** Setup → Audit Log's *Auth* preset (the `auth_events` list view) now lists `login`, `logout`, `login_failed` and `account_locked`. Each row is about the account it names, so the ledger's record read gate judges it by that `sys_user` record, as for any row about a user. It carries no `tenant_id`: a refused attempt has no session to take an organization from, so it is a deployment-level row under the ledger's organization scope.
+- **Recorded with or without a lockout.** A refused sign-in writes its row whether or not `lockoutThreshold` is set.
+- **`@objectstack/plugin-audit` types.** `AuthSessionAuditEvent.action` widens to `AuthEventAuditAction` (`'login' | 'logout' | 'login_failed' | 'account_locked'`). `AuthEventAuditAction` and `AuthAccountAuditAction` are new exported types, and `AuthSessionAuditAction` is unchanged.
@@ -0,0 +1,119 @@
+# Opt-in pre-merge 18.x upgrade harness (#24522, step 0 of the 18.x line).
+#
+# ## The gap this closes
+#
+# Ruling record 6266750393 on #15194 makes `main` the release line: every PR on
+# the 18.x line, once merged, leaves `main` releasable, and its R2 reads "a
+# database an 18.0 install created upgrades to that commit, boots, and keeps
+# its data" — a check each of the line's PRs passes BEFORE it merges. The
+# harness that answers R2 is a dogfood test,
+# `packages/qa/dogfood/test/upgrade-18x-harness.dogfood.test.ts`, and the
+# dogfood jobs in `ci.yml` run only on `main`'s full battery (THE TWO SPEEDS,
+# #22998): they skip `pull_request` and `merge_group`. So without this workflow
+# the line's PRs get their first R2 answer after the merge.
+#
+# This workflow adds the missing TRIGGER for that ONE file, and nothing else.
+# The test, its fixture and its assertions stay where they are, and the full
+# battery keeps running the same file with the rest of dogfood on `main`.
+#
+# ## Opt-in, label-gated — the cheapest wiring measured
+#
+# Measured on the step-0 branch (the card's report carries the readings):
+#
+#   - the harness file alone: ~54 s of vitest wall (one 4-vCPU box, ~43 s of it
+#     module import), against the dogfood suite's ~5 min per shard × 3;
+#   - its build closure is the dogfood package's (`turbo run build
+#     --filter=@objectstack/dogfood`, 66 tasks), which the turbo cache below
+#     replays; cold, it is the step's whole cost.
+#
+# Three shapes were weighed. Running it on every PR taxes the whole repository
+# for one release line. Dispatching `ci.yml` by hand on a line PR's branch needs
+# no diff but runs the entire full battery (three dogfood shards, Temporal
+# Conformance, the console pin) for one file, and is a manual act with no
+# trigger a PR carries. The label lane runs one file, only where asked: the
+# shape `pack-smoke-optin.yml` already ruled for a pre-merge check that most
+# PRs do not need. The epic seat hangs `needs:upgrade-harness` on each 18.x
+# line PR; ⛔ never auto-applied, never in `.github/labeler.yml`.
+#
+# ## Wiring decisions (the `pack-smoke-optin.yml` ones, for the same reasons)
+#
+# `types:` restates GitHub's defaults beside `labeled` (naming `types:`
+# REPLACES the default set). The guard has two limbs: the PR carries the label
+# now, and on a `labeled` event the label just added is OURS — otherwise every
+# size label would start another run of an unchanged tree. `concurrency` sits at
+# JOB level, so a skipped run never cancels a real one. ⛔ No `merge_group:`
+# trigger: a `merge_group` event carries no pull request, so the label cannot be
+# read there, and this context is NOT a required one
+# (`scripts/check-required-contexts.mjs`) — the seat reads it before it queues a
+# line PR, the way the ruling's R2 asks.
+
+name: Upgrade Harness (opt-in)
+
+on:
+  pull_request:
+    branches:
+      - main
+    types: [opened, synchronize, reopened, labeled]
+
+permissions:
+  contents: read
+
+jobs:
+  upgrade-harness:
+    name: 18.x upgrade harness (opt-in)
+    if: >-
+      contains(github.event.pull_request.labels.*.name, 'needs:upgrade-harness')
+      && (github.event.action != 'labeled' || github.event.label.name == 'needs:upgrade-harness')
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    concurrency:
+      group: upgrade-harness-optin-${{ github.event.pull_request.number }}
+      cancel-in-progress: true
+    steps:
+      # No `ref:` — the MERGE PREVIEW: what `main` will contain once this PR
+      # lands, which is the commit R2 is a statement about.
+      - name: Checkout the merge preview
+        uses: actions/checkout@v7
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+
+      - name: Setup pnpm
+        uses: ./.github/actions/setup-pnpm
+
+      - name: Get pnpm store directory
+        shell: bash
+        run: echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
+
+      - name: Setup pnpm cache
+        uses: actions/cache@v6
+        with:
+          path: ${{ env.STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-v3-
+
+      # Restore-only: the dogfood job's entries (seeded from `main`) replay this
+      # closure; a PR never writes the cache, as in ci.yml.
+      - name: Restore Turbo cache
+        uses: actions/cache/restore@v6
+        with:
+          path: .turbo/cache
+          key: ${{ runner.os }}-turbo-dogfood-1-main-${{ github.sha }}
+          restore-keys: |
+            ${{ runner.os }}-turbo-dogfood-1-main-
+            ${{ runner.os }}-turbo-dogfood-
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build the dogfood package's dependency closure
+        run: pnpm turbo run build --filter=@objectstack/dogfood --concurrency=4
+
+      # One file, named: the dogfood config's filter preflight refuses a path
+      # that selects no test, so a renamed harness reds here instead of
+      # passing over nothing.
+      - name: Boot HEAD on the 18.0 fixture (R2) and check the v17 refusal (R3)
+        run: pnpm --filter @objectstack/dogfood exec vitest run test/upgrade-18x-harness.dogfood.test.ts
@@ -11,6 +11,10 @@
 >
 > 本体即软件。
 >
+> Ontology-driven: database, API, UI and agent tools all derive from that one
+> definition of the business, so there is no second application to keep in step
+> with it.
+>
 > Apps small enough for AI to hold whole.
 
 `Executable` · `AI-writable` · `Agent-operable` · `You own it` · Apache-2.0
@@ -90,6 +94,13 @@ runtime, as hooks, action bodies, CEL, and constrained JSX. The full account is
 [Business Ontology](https://objectstack.ai/docs/concepts/ontology); the short
 form is the [glossary entry](https://objectstack.ai/docs/getting-started/glossary#business-ontology).
 
+Metadata-driven, as the previous generation of platforms used the word, names
+the mechanism — behaviour derived from a declarative definition instead of
+written as code — and ObjectStack keeps it. Calling the stack ontology-driven
+names what that definition is and whose it is: a definition of the business
+rather than configuration of a platform, an open format in your repository
+rather than inside a vendor's system, and written for an agent to read.
+
 [How it compares](https://objectstack.ai/docs/concepts/compare) sets ObjectStack
 beside knowledge ontologies, semantic layers, operational ontologies, metadata
 platforms, and AI code generation. [When to use it](https://objectstack.ai/docs/concepts/when-to-use)
 
@@ -307,7 +307,7 @@ Reference to a record in another object (foreign key).
 
 | Property | Type | Default | Description |
 |:---|:---|:---|:---|
-| `reference` | `string` | **required** | Target object name (snake_case) |
+| `reference` | `string` | **required** | Target object name (snake_case). A stored-metadata table (`sys_metadata`, `sys_metadata_history`) is refused — see [below](#a-relationship-never-targets-a-stored-metadata-table) |
 | `referenceFilters` | `string[]` | — | **Removed** (#2377, ADR-0049) — no longer a recognized field property. `FieldSchema` is a strict object, so an unknown key is **rejected with guidance**, not silently stripped (ADR-0078): the error echoes the offending key and prescribes the replacement. Use structured `lookupFilters` + `dependsOn` instead; see [Relationships](/docs/data-modeling/relationships) |
 | `deleteBehavior` | `'restrict' \| 'cascade' \| 'set_null'` | `'set_null'` | Behavior when referenced record is deleted. On a *required* lookup `set_null` is escalated to `restrict`, since a NOT NULL foreign key cannot be cleared — **whether the `set_null` was defaulted or written out explicitly**. On a `multiple: true` required lookup the escalation is judged per referencing row: only a row the member removal would leave EMPTY is refused. `cascade` and `restrict` are the values honored as written. Where `set_null` does run, a `multiple: true` lookup loses only the deleted **member** — the other members are kept, and a set emptied that way is stored as `[]`, never `null` |
 
@@ -329,7 +329,7 @@ Parent-child relationship (cascading delete by default).
 
 | Property | Type | Default | Description |
 |:---|:---|:---|:---|
-| `reference` | `string` | **required** | Target (master) object name |
+| `reference` | `string` | **required** | Target (master) object name. A stored-metadata table is refused — see [below](#a-relationship-never-targets-a-stored-metadata-table) |
 | `referenceFilters` | `string[]` | — | **Removed** (#2377, ADR-0049) — no longer a recognized field property. `FieldSchema` is a strict object, so an unknown key is **rejected with guidance**, not silently stripped (ADR-0078): the error echoes the offending key and prescribes the replacement. Use structured `lookupFilters` + `dependsOn` instead; see [Relationships](/docs/data-modeling/relationships) |
 | `deleteBehavior` | `'restrict' \| 'cascade'` | `'cascade'` | Behavior when parent is deleted. `restrict` refuses the parent delete while children exist; `cascade` (and omitting the key) deletes the children with the parent. An explicit `set_null` is a **parse-time rejection** on this type (#9689) — a detail row cannot outlive its master; use a `lookup` if children must survive the parent |
 | `inlineEdit` | `boolean \| 'grid' \| 'form'` | — | Edit child records inline on the parent create/edit form (`true` = auto-pick, `'grid'`, or `'form'`) |
@@ -347,6 +347,10 @@ Parent-child relationship (cascading delete by default).
 }
 ```
 
+#### A relationship never targets a stored-metadata table
+
+A `lookup` or `master_detail` whose `reference` is `sys_metadata` or `sys_metadata_history` is refused by `os validate`, `os build` and the object save door alike. Those rows carry serialized metadata bodies, which are served only through the metadata API (`GET /api/v1/meta/:type/:name`), where the body is projected; the engine never hydrates a reference into them, so `$expand` would keep the stored id and never nest the row, and a master-detail child's `parent` root would stay unbound, refusing every write a `parent` rule judges. To point a record at a metadata item, store its type and name in `text` fields and read the item through the metadata API.
+
 ### `tree`
 Self-referential hierarchy (e.g., categories, org chart).