fix(objectql): pin the SEARCH-axis remedy agreement and correct the three word-identity comments (#8648)

[hotlong]

Fixes#8648

Three source comments asserted that the SEARCH-axis refusal is worded identically to the SORT/FILTER ones, and one of them further asserted that the conformance pin enforces that identity. Measured from the running doors, neither held. This is the repo's declared-≠-enforced family landing on the refusal vocabulary rather than on a metadata key.

What was measured

Triggered against a real ObjectQL plus the protocol on current main, each refusal's emitted message read verbatim — not from source literals, since a literal in the tree can be dead or shadowed:

axis	doors	envelope	remedy, as emitted
FILTER	ingress + engine.find()	400 INVALID_FIELD	Denormalise the value onto 'showcase_task' (a stored field, written when the source changes) and filter that.
SORT	ingress + engine.find()	400 INVALID_SORT	the same sentence, closing and sort by that.
SEARCH	ingress	400 INVALID_FIELD	Mirror the computed value onto a stored text field on 'showcase_task' and search that instead.

SEARCH cannot match the stem the pin asserted across its four SORT/FILTER doors, so the claim was unpinned in exactly the place where it was false.

The gap, measured in both directions

Reverse verification, with the fix committed first. A substance-preserving rewording of the SEARCH message (Copy the computed value into a stored text column on '...' and search that column.) was applied at the producer and the artifact rebuilt — the test resolves metadata-protocol from built dist/, so an unrebuilt ablation runs the pre-mutation build and stays green; the mutation was proved present in dist/index.js before each leg.

• With the old pin (origin/main's test file, same reworded message): the agreement pin stayed GREEN — 170 passed, 1 failed, and the only failure was an unrelated per-door assertion in the A virtual formula field declared in searchableFields clears lint and the #4254 gate, then silently matches nothing — the same fail-open shape #4254 closed one axis over #6674 block. That is the defect.
• With the new pin: RED on search-ingress remedy wording, printing the expected sentence beside the emitted one.

What changed

Comment and test lines only — no runtime-behaviour lines, and the shipped SEARCH message is untouched.

1. The three comments now claim substance-agreement, which is what actually holds across all three axes: put the value on a stored column of the queried object and query that instead. SEARCH narrows the target to a text column, correct for an axis that scans text-like columns. packages/objectql/src/filter-comparand-shape.ts carries the same sentence but names only the ingress door, so it is accurate as written and is left alone.

2. The agreement pin now covers five doors in three layers, each catching what the others cannot:

   • agreement, emitted-vs-emitted — the four stem-sharing doors are compared against each other via their longest common prefix, which must equal the stem exactly. No single-door drift survives it, and rewording all four together also goes red.
   • wording, per axis including SEARCH — the door the pin used to skip. Rewording any axis now goes red.
   • substance, as a ratchet on those constants — a stored target, named on the queried object, with that axis redirected onto it. When the wording layer goes red and the next author updates the strings, this is what the rewrite cannot quietly walk away from.

   SEARCH's divergence is pinned as deliberate, so a future author cannot "repair" it into the shared stem while believing the wordings were always meant to be identical.

⛔ Route 3 was not taken. Aligning the SEARCH wording onto the shared stem changes a shipped, user-visible error message on an axis that already landed, with zero measured pull, and the text narrowing would need somewhere to live. The pin holds without it, so no fork needed escalating.

Verification

All at bc46f3e8a, the head this PR pushes, after merging origin/main (00ee416) and rebuilding the closure:

pnpm --filter @objectstack/objectql test 206 files / 3629 tests passed
pnpm --filter @objectstack/metadata-protocol test 90 files / 1351 tests passed
pnpm --filter @objectstack/objectql typecheck exit 0

Gate union re-derived against the actual changed paths with node scripts/pm/dispatch-gates.mjs and re-run at this head; exit codes read unpiped, all 0:

check:nul-bytes · check:durability-log-level · check:stack-collection-maps · check:cross-package-test-inputs · check:filter-alias-parity · check:query-options-erasure · check:type-check-coverage · check:type-check-debt (on the built closure) · check-engine-split-ratio

The derivation surfaced no family beyond the ones dispatch named.

Changeset

None — skip-changeset applied. The diff is comments plus one test; no user-visible message, behaviour or export changes, so this PR declares no release of its own.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 14, 2026 8:13pm

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/metadata-protocol, @objectstack/objectql.

16 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/concepts/metadata-lifecycle.mdx(via @objectstack/metadata-protocol, @objectstack/objectql)
• content/docs/data-modeling/formulas.mdx(via packages/objectql)
• content/docs/deployment/migration-from-objectql.mdx(via @objectstack/objectql)
• content/docs/deployment/vercel.mdx(via @objectstack/objectql)
• content/docs/kernel/contracts/data-engine.mdx(via @objectstack/objectql)
• content/docs/kernel/runtime-services/examples.mdx(via packages/objectql)
• content/docs/kernel/services-checklist.mdx(via @objectstack/metadata-protocol, @objectstack/objectql)
• content/docs/kernel/services.mdx(via @objectstack/objectql)
• content/docs/permissions/authentication.mdx(via @objectstack/objectql)
• content/docs/permissions/system-context.mdx(via packages/objectql)
• content/docs/plugins/index.mdx(via @objectstack/objectql)
• content/docs/plugins/packages.mdx(via @objectstack/objectql)
• content/docs/protocol/kernel/http-protocol.mdx(via @objectstack/metadata-protocol)
• content/docs/protocol/kernel/index.mdx(via @objectstack/objectql)
• content/docs/protocol/objectql/query-syntax.mdx(via packages/objectql)
• content/docs/protocol/objectql/state-machine.mdx(via @objectstack/objectql)

⛔ 2 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/implementation-status.mdx(via @objectstack/objectql)
• content/docs/releases/v9.mdx(via @objectstack/metadata-protocol)

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.