Merge origin/main into claude/issue-6825-adr-0005-index-migration-amended — union both sides' adr-anchors entries

adr-anchors.json tail-append conflict: this PR added the two ADR-0005 overlay
owners (overlay-index.ts, sys-metadata.object.ts); main meanwhile added the
ADR-0094 permission-set-projection.ts entry. Resolution keeps all three.
Gates re-run on the merged tree: check-adr-anchors OK (46 anchored files),
check-adr-links OK (531), check-nul-bytes OK.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BPWqbmEFU8gJepBJTHESXd

Author: claude

.changeset/adr0094-d5r-overlay-direction-retired.md

@@ -0,0 +1,25 @@
+---
+"@objectstack/plugin-security": patch
+---
+
+ADR-0094 D5-R: retire the "customize packaged permission sets through an ADR-0005 env
+overlay" direction (2026-07-14), and make the ADR text and the
+`permission-set-projection.ts` header agree with what is enforced.
+
+`#6483` (PR #6608) rolled `permission` back to `allowOrgOverride: false`, so a metadata
+write against a **code-declared (artifact-backed)** permission set is refused with 403
+`NOT_OVERRIDABLE` — ADR-0005's security row ("overlays would create silent privilege
+drift") is enforced again. The supported channel for those sets is the one ADR-0086
+always named: edit the package and re-publish. Environment authoring survives on the
+`allowRuntimeCreate` tier, for sets whose definition lives only in `sys_metadata`
+(data-door creations, and package sets authored + published through the metadata door);
+that tier edits the single stored definition in place and is deliberately **not**
+described as a re-route of the retired overlay channel.
+
+No behaviour change: the four production write points keep their current dispositions.
+The refusal is left to the producer — `plugin-security` does not re-derive
+artifact-backing to pre-empt it — and the two write points that catch a failed metadata
+write (the `restore` leg and the boot backfill) keep reporting on the durability channel.
+What changes is prose, plus test coverage that can now see the gate: the suite's protocol
+stub models ADR-0005's tier gate, so the four cases that pinned the retired direction no
+longer pass for want of a stub that could refuse.

.changeset/audit-consume-bound-previous.md

@@ -0,0 +1,65 @@
+---
+"@objectstack/plugin-audit": patch
+---
+
+fix(plugin-audit): consume the engine's bound `ctx.previous` and record one normalised view on both sides of the diff (#6656)
+
+`plugin-audit` used to fetch its own pre-image. `captureBefore`, registered on
+`beforeUpdate` / `beforeDelete`, issued a `ql.findOne` for the target row and
+stashed it on `ctx.__previous`, because `HookContext.previous` was "officially
+typed but not always populated by the engine itself". That is no longer true on
+any path this plugin registers for, so the read is retired and the writer reads
+the contract value.
+
+**The read that goes away** (measured with a counting driver on the audited
+object, `driver.findOne` per write):
+
+| write | before | after |
+|:--|--:|--:|
+| single-id `update()` | 2 | 1 |
+| single-id `delete()` | 2 | 1 |
+| predicate `update()`, 3 matched rows | 3 | 0 |
+| predicate `delete()`, 3 matched rows | 3 | 0 |
+
+The predicate column is the larger half and was pure waste. #5574 binds
+`input.id` on every per-row *before* context, which defeated the handler's own
+`if (!id) return` bulk guard — so it read every matched row, and every result
+was discarded, because `__previous` landed on the per-row *before* context while
+the per-row *after* contexts (the ones the writer actually runs on) never saw
+it. The engine's own matched-row read is untouched and still serves both phases,
+so the ledger is unchanged.
+
+**What the ledger records changes, and deliberately.** The two sides of an audit
+diff came from two different pipelines: `before` through the engine's read path
+(credentials masked, formulas hydrated, file references resolved) and `after`
+from the raw write result. That asymmetry — not the redundant read — is why a
+write that touched one field recorded phantom "changes" for every secret, file
+and formula field on the record. Retiring the read makes both sides
+same-source; the writer now also gives them one view, so the surface levels
+upward rather than down to raw store contents:
+
+- **Credential fields are masked on both sides.** Single-id delete `old_value`
+  still reads `••••••••` for a `secret` field — that face is byte-identical.
+  Change detection still runs on the raw values, so rotating a secret is still
+  recorded as a change; only the recorded values are masked.
+- **A pre-existing leak is closed.** The stored `secret:` ref was already
+  reaching `sys_audit_log.new_value` on every create and update, and a
+  `password` field — which ADR-0100 stores in cleartext at rest — was landing
+  there **in plaintext**, in the audit ledger and in the `sys_activity` summary
+  rendered in the record feed. Both now record the mask.
+- **Virtual (`formula`) fields leave the full snapshots.** `ctx.result` carries
+  hydrated formulas (#5504) and the raw pre-image structurally cannot, so
+  create `new_value` would have described a field delete `old_value` could
+  never carry. Only genuinely virtual fields are dropped: `autonumber` and
+  `summary` are stored columns present and equal on both sides, and they stay
+  in the snapshot.
+
+Two consequences worth naming, both narrowing single-id delete to what bulk
+delete already did: its `old_value` now records a file field's stored id rather
+than the resolved `{id, name, size, url}` object, and drops formula values. An
+object whose label field is a formula falls back to the record id in the
+`sys_activity` label on delete for the same reason.
+
+No audit coverage is removed: the plugin keeps its `afterInsert` / `afterUpdate`
+/ `afterDelete` registrations, which is what holds the engine's pre-image demand
+gates open, and every one of them keeps the `excludeObjects` face from #5860.

.changeset/hook-retry-policy-declared-defaults.md

@@ -0,0 +1,48 @@
+---
+"@objectstack/objectql": patch
+---
+
+fix(objectql): a hook's `retryPolicy` gets the same defaults whether or not its metadata was parsed (#6832)
+
+`HookSchema` declares `retryPolicy.maxRetries` with `.default(3)` and
+`retryPolicy.backoffMs` with `.default(1000)`. The executor that actually
+performs the retries read both with `?? 0`. So "how many times does an
+under-specified hook retry?" had **two answers**, and which one you got depended
+on whether the metadata had been through `HookSchema`:
+
+- parsed — `defineStack({ hooks })`, `PUT /meta`, the Studio form — got **3
+  retries with a 1000ms backoff**, matching the schema, the generated reference
+  page and the Studio form;
+- unparsed — the public `wrapDeclarativeHook` export, and `bindHooksToEngine`'s
+  own call, which hands it `Hook` metadata verbatim — got **0 and 0**.
+
+The failure was silent and pointed the wrong way: a retry surface that does not
+retry raises no error, logs nothing, and fails no test. It just loses the
+recovery the author believed they had configured. This is the divergence #4247
+removed from flow `errorHandling` ("one contract, one number"), one surface over
+and with the numbers swapped, and the `declared = enforced` case ADR-0049 exists
+to close.
+
+`wrapDeclarativeHook` now reads both defaults **out of `HookSchema`** instead of
+restating them, so the two paths agree by construction and a future key added to
+`hook.retryPolicy` needs no matching edit in the executor.
+
+**The boundary, which is deliberately unchanged — read this if you own hooks.**
+`retryPolicy` is `.optional()` with no `.default({})`, so an absent block and an
+empty one are different declarations, and they stay different:
+
+- **`retryPolicy` omitted entirely → still zero retries.** No policy was
+  declared, so none is applied. This is the behaviour every existing hook has
+  today and it does not change. (Making the omitted case default to 3 would have
+  "fixed" the divergence by silently giving every hook in every existing app
+  three retries it never asked for — a larger behaviour change than the defect.)
+- **`retryPolicy: {}` or a half-filled block → the declared defaults now apply.**
+  `retryPolicy: {}` means 3 retries / 1000ms; `retryPolicy: { backoffMs: 500 }`
+  means 3 retries / 500ms. Previously both of these retried zero times on the
+  unparsed path. If you wrote an empty or partial `retryPolicy` against a host
+  that does not parse its hook metadata, that hook now retries as its schema,
+  docs and Studio form have always said it would.
+
+Any value you wrote explicitly still wins outright, including an explicit
+`maxRetries: 0`. The backoff remains linear (`backoffMs * attempt`), which is
+what the declared shape describes.

.changeset/icontains-status-post-5702.md

@@ -0,0 +1,11 @@
+---
+"@objectstack/spec": patch
+---
+
+filter: `$icontains` 的实施状态改按实测重写(#6947)
+
+`filter.zod.ts` 上 `StringOperatorSchema` 的状态段仍然写着「没有任何后端应答 `$icontains`,五个 driver 一律拒收,直到 #5702 落地」。#5702 已于 2026-08-08 关闭,该段自述的过期条件已经触发,文字与已发布的实现正好相反。
+
+按 driver 逐个实测(同一条 `{ name: { $icontains: 'acme' } }` 打到同时含 `acme corp` 与 `ACME CORP` 的样本上,而不是 grep case 分支 —— grep 看不见继承编译器的那一面,会少数一个):**五个 driver 里三个应答**(`driver-sql`;`driver-sqlite-wasm` 通过继承 `SqlDriver`,在另一套 sql.js 引擎上;`driver-turso` 的 local 与 remote 两条传输都应答),**两个响亮拒收**(`driver-memory`、`driver-mongodb`,均为 `INVALID_FILTER` / 400)。据此改写状态段,并同步 `$icontains` 的 `.describe()`(它会渲染进 `content/docs/references/data/filter.mdx`,原文同样停留在「lowerings land with #5702」)。
+
+⛔ 行为零变化:`FILTER_OPERATORS` 未动,`$icontains` 仍然刻意不在词表里 —— 该数组是运行时 allowlist,收进去会让内存 `match()` 对**不匹配**答 `true`。词表的真实闸口从此写明是 #6520(JS 求值面),不再是已经落地的 #5702。

.changeset/index-failure-dialect-cause-walk.md

@@ -0,0 +1,46 @@
+---
+"@objectstack/metadata-protocol": patch
+---
+
+fix(metadata-protocol): the dialect arm of `classifyIndexFailure` walks `cause` to the same depth the conflict arm does (#6848)
+
+`classifyIndexFailure` had two arms reading two different wrap-depths. #6699
+moved the first arm onto `@objectstack/types`' `isUniqueViolationError`, which
+follows `error.cause` four levels down because pool and query-builder layers
+re-throw with the original attached. The second — the dialect arm — kept reading
+`err.message` and stopping there.
+
+So a dialect refusal arriving behind a wrapper (outer prose `Write failed` or
+`pool query failed`, the actual `near "WHERE": syntax error` one step down
+`cause`) was graded `failed` instead of `unsupported`. The private
+`indexFailureText` helper now collects the message channel of the thrown value
+**and** of each `cause` below it, bounded at the same `MAX_CAUSE_DEPTH` of 4 the
+predicate uses and counted the same way (the thrown value is depth 0). The
+dialect vocabulary itself is unchanged — only the text fed to it.
+
+**Why the verdict matters beyond wording.** The two consumers dispose of
+`unsupported` and `failed` differently. `view-definition-active-index.ts` treats
+them the same (keep the previous index, report at `error`; only the wording
+differs). But `ensureOverlayStateIndex` builds the composite **fallback lookup
+index** on the `unsupported` branch and on no other — offered precisely because
+a dialect that cannot take the partial form should still get the lookup. Under
+a `failed` verdict that branch never ran, so `fallback` came back
+`not-attempted` rather than `ensured` / `refused` and the degradation target was
+silently never attempted.
+
+**Dormant, not a live regression.** No driver shipped today produces the wrapped
+shape — each hands knex's error back with the dialect text on the outer message,
+which is why every existing case matched on the first read. This closes an
+asymmetry before a wrapping raw-SQL driver can land on it; it is also not a
+regression from #6699, which only made the contrast visible by deepening the
+first arm.
+
+Two details worth knowing if you touch this: the collected levels are joined
+with a **newline**, never a space, because two of the dialect alternatives are
+multi-word (`where clause`, `near "where"`) and a space would let a phrase be
+synthesised across a wrapper boundary that no single driver wrote. And a looping
+`cause` chain is **bounded rather than detected** — no visited set — which is
+exactly what the predicate this mirrors does.
+
+Arm order is unchanged and still load-bearing: a conflict reported anywhere in
+the chain still beats a dialect refusal in the outer prose.

.changeset/mcp-diagnose-empty-read-tsdoc-correction.md

@@ -0,0 +1,32 @@
+---
+"@objectstack/mcp": patch
+---
+
+docs(mcp): `diagnoseEmptyRead` 的 TSDoc 更正一句被证伪的事实 (#6724)
+
+`packages/mcp/src/mcp-server-runtime.ts` 里 `diagnoseEmptyRead` 的 TSDoc(#6055
+由 PR #6051 落地)为"在空答案之后再跑一次仅取结论的探针,而不是把
+`getObject` 换成 `getDiagnosed('object', name)`"这个设计选择给出了两条理由。
+其中一条是事实陈述,而它是**错的**:
+
+> `MetadataFacade.getObject`(objectql)返回 `registry.getObject(name)` —— a
+> different shape from its own `get()`,因此等价关系在一般情况下不成立。
+
+`SchemaRegistry.getItem` 对 `'object'` / `'objects'` 类型直接特判回
+`getObject`,所以 facade 的 `get('object', n)` 走的是同一次查找;其后的
+`item?.content ?? item` 解包是空操作 —— 合并后的 `ServiceObject` 根本没有
+`content` 键。实测:命中时两个成员交回**同一个对象引用**,未命中时双方都是
+`undefined`。三个已发布实现由 `packages/objectql/src/
+metadata-service-getobject-equivalence.test.ts`(PR #6839)钉住,契约侧的
+`IMetadataService.getObject` 自 PR #6723(#6505)起也写明了这条等价关系。
+
+同一句话在 `mcp-server-runtime.metadata-outage.test.ts` 里被复述过一次,一并
+更正。
+
+仍然成立的那半条理由被保留:`getObject` 是 `IMetadataService` 自己的成员,
+#6055 当时它并**没有**被文档化的等价关系,在消费端擅自假定一条正是 Prime
+Directive #12 禁止的私有方言 —— 所以解析器当初没有被换掉。
+
+**纯注释,零行为变化。** 这次更正**不**主张把解析器换成
+`getDiagnosed('object', name)`:那是一次独立的判断,由接手的人按其自身利弊
+去做,本次改动既不作出也不预设。

.changeset/search-auto-excluded-types-disjointness-pin.md

@@ -0,0 +1,31 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): 把 `$search` 自动默认集三个类型词表的「互不相交」钉成受检事实 (#6934)
+
+`packages/spec/src/data/search-fields.ts` 的 `autoDefaultFields` 先测一遍
+`SEARCH_AUTO_EXCLUDED_TYPES` 的**否定**守卫，紧接着才是
+`SEARCHABLE_TEXTUAL_TYPES` / `SEARCHABLE_ENUM_TYPES` 的**肯定**白名单。三个集合
+今天两两不相交，所以那行否定守卫改变不了任何一次判定 —— 在完整的 56 个字段类型
+域（`FieldType` 枚举 ∪ 三个词表 ∪ 域外探针）× 9 种调用形态 = 504 次解析上逐一比对，
+删掉它与保留它的结果**逐字节相同**。本次改动因此**不改变任何行为**。
+
+**保留该行，而不是退休它。** 判据是构造出来实测的，不是判断的：给
+`SEARCHABLE_TEXTUAL_TYPES` 补一个已在排除集里的类型（`json`），两种形态给出的是
+**方向相反、同样沉默**的两种解决 —— 有守卫时该类型被悄悄踢出扫描（fail closed），
+没守卫时肯定列表获胜，该类型不仅进入自动默认集，还顺带进入上一层 #4254 的 ingress
+allow-list，于是 `$searchFields=<该字段>` 从「拒绝」翻成「接受」，正是 #4483 为 `id`
+关掉的那类放宽。排除集里写着 `secret` / `password` / `encrypted` / `vector`，
+fail open 意味着对被脱敏或重量级列做 `$contains` 子串扫描。所以那行不是安全网
+（两个方向都不出声），但它是**更安全的那个平局裁决**。
+
+**真正堵住这一类的是钉子。** `search-fields.test.ts` 新增：三个词表两两不相交的
+断言，加上两个方向的行为断言（排除集成员必被拒、白名单成员必被纳）。任一方向出现
+重叠都会变红，且没有任何单点放宽能让它变成空转 —— 已用临时重叠实测两种形态各自
+变红。同时补充：两个肯定列表之间也必须不相交，因为引擎侧
+`fieldClausesForTerm` 先分支到 `SEARCHABLE_ENUM_TYPES`，同时命中的类型只会走
+option label 映射、永远不会按原文 `$contains` 检索。
+
+守卫处的注释如实写明它是 redundant-by-construction、不承重、以及保留它买到的是
+哪个方向，避免下一位作者把它读成「新增可搜索类型时必须同步维护排除集」的规则。

.github/workflows/check-links.yml

@@ -80,6 +80,10 @@ jobs:
           # freeze those 8 on a shrink-only baseline and fail on a NEW one --
           # something neither `exclude` nor `.lycheeignore` can express, because
           # neither ever tells you an entry stopped being needed.
+          # `ARCHITECTURE.md` joined this glob in #6867: unlike `docs/adr/**`, it
+          # carried no pre-existing rot once its 10 dead links + 2 stale path
+          # references were fixed in the same PR, so -- unlike the ADR directory
+          # above -- it needs no KNOWN_DEAD_TARGETS-style baseline to land clean.
           args: >-
             --offline
             --root-dir ${{ github.workspace }}/content
@@ -88,5 +92,6 @@ jobs:
             'content/**/*.md'
             'content/**/*.mdx'
             'README.md'
+            'ARCHITECTURE.md'
           # Fail the job if broken links are found
           fail: true

.github/workflows/ci.yml

@@ -430,6 +430,9 @@ jobs:
     # means a future shard-count change cannot deadlock the repo. `name:` and
     # `if: always()` are therefore both load-bearing: this must not become
     # `if: !cancelled()` (see dogfood-gate), and it must not be renamed.
+    # Both halves are now asserted rather than only written down: the `name:`
+    # literal by `check:required-contexts` (#6865), the `if: always()` and the
+    # attestation roster by `check:shard-attestation` (#6082).
     #
     # ── It COUNTS credentials; it does not read one aggregate word (#6082) ──
     #
@@ -519,7 +522,8 @@ jobs:
   # temporal conformance matrix holds to one standard. Its NAME still says
   # "live PG + MySQL" on purpose: the name IS the required check, so renaming
   # it would silently drop the gate wherever branch protection lists it — the
-  # same trap the dogfood shards note below.
+  # same trap the dogfood shards note below. `check:required-contexts` pins
+  # this literal, parenthetical and all (#6865).
   temporal-conformance:
     name: Temporal Conformance (live PG + MySQL)
     needs: filter
@@ -960,7 +964,10 @@ jobs:
     # EVERY pull request in the repo sat permanently BLOCKED (mergeable, all
     # checks green, merge button dead). #3622's own comment called for updating
     # branch protection; keeping the contract HERE instead means a future
-    # shard-count change cannot deadlock the repo a second time.
+    # shard-count change cannot deadlock the repo a second time — and since
+    # #6865 the bare name is pinned by `check:required-contexts` rather than
+    # only described here, so a rename fails in the ESLint job instead of in
+    # the queue.
     #
     # Also aggregates dogfood-verify (the CLI pass that used to ride shard 1),
     # so the one required context still covers everything it covered before
@@ -1040,8 +1047,9 @@ jobs:
     needs: filter
     # See THE FILTER CONTRACT on the filter job's outputs (#4928). No
     # aggregation gate stands behind this job — its own name IS the required
-    # context — so this `if:` is the only thing between a filter flake and a
-    # green "Build Core" that built nothing.
+    # context, pinned by `check:required-contexts` since #6865 — so this `if:`
+    # is the only thing between a filter flake and a green "Build Core" that
+    # built nothing.
     if: ${{ !cancelled() && needs.filter.outputs.core != 'false' }}
     runs-on: ubuntu-latest
     timeout-minutes: 30
@@ -1273,7 +1281,8 @@ jobs:
   #
   # The NAME is the required-check contract — the same trap the dogfood shards
   # note above: renaming it silently drops the gate wherever branch protection
-  # lists it, with every PR still green.
+  # lists it, with every PR still green. Pinned by `check:required-contexts`
+  # since #6865.
   console-pin:
     name: Console Pin Gate
     needs: filter