refactor(formula): remove the never-bound EvalContext.api declaration

[huangyiirene]

Fixes #18318

Clause-②: yes

Execution of the maintainer ruling on batch #148 item 1, letter B (comment 5716041368, 「同意」): EvalContext declared a kernel query API — api?: { exists, count, lookup }, docblocked as os.exists / os.count / os.lookup, "implemented opportunistically by call sites that have a query engine" — and buildScope() never read it. The declaration is removed, with the reason written at the deletion site. No shim, no alias, no reserved spelling; the three functions are not implemented here, and the real capability need (reading a related record's field inside a predicate) is tracked on its own card, #18682, which nothing in this PR advances or blocks.

The premise, re-measured on the branch base (df1b275)

reading	value	control
ctx.api / .api in packages/formula/src	0 hits	ctx.user in stdlib.ts: 3 hits
os.exists / os.count / os.lookup in the tree, CHANGELOGs and dist/ excluded	1 hit — the docblock being deleted	the same grep finds the three names nowhere else, so no stdlib entry, validator row, doc page or skill file has to follow

So the card's reading holds exactly: the member was declared, documented, and bound nowhere.

The LEVEL is minor, and that is a reading rather than an assumption

The question the grade turns on: can a consumer set api today and get anything out of it? No.

• buildScope() binds record, previous, input, os.user / os.org / os.env, and extra — it has never read ctx.api, so every implementation ever passed there was discarded before evaluation.
• A predicate calling os.lookup fails whether or not the call site supplies api — pinned as a test in this PR.
• The whole of the break is therefore a compile error on an EvalContext literal that carries api, and the sweep below finds zero such literals in this repo and zero in the pinned sibling.

This is the shape PR #18717 graded minor in the same round — what changed never delivered the semantics it reported, so depending on it meant depending on nothing. The launch-window major ban (scripts/check-changeset-no-major.mjs) also applies and is recorded here as a constraint, not the justification. The changeset is @objectstack/formula: minor and carries the migration line it owes: api: { … } → delete the property; there is no replacement key and no result changes.

Consumer sweep — derived by TYPE, with a firing control

⛔ Not by text. A text grep is structurally useless here: the identically-named ctx.api on the hook ScopedContext (packages/spec/src/contracts/scoped-context.ts) is a live, unrelated surface this PR does not touch, which is why the dispatching seat's own api: *{ grep returned 234 files and was reported as an instrument failure.

Population — the 19 workspace packages that declare @objectstack/formula. Every one has a typecheck script, so no filter matched zero scripts and exited 0 without running anything.

Measurement leg (at d706b60b57, after turbo run build — 73 tasks successful, so each package resolves formula through its rebuilt dist/index.d.ts): all 19 packages typecheck green, error TS count 0.

Firing control — the same 19-package run with a REQUIRED member injected into EvalContext (__ablationProbeFiringControl: 'fire'), formula rebuilt, and the marker proved present in dist/ by node scripts/ablation-dist-preflight.mjs @objectstack/formula '__ablationProbeFiringControl' before the colour was read:

• 12 of 19 packages red; 21 distinct error TS2345 supply sites across 13 files, plus two more files caught a layer down by the test-typecheck ledger gate (platform-objects, plugin-auth) — e.g. metadata-protocol/src/seed-loader.ts:1026, objectql/src/validation/rule-validator.ts (6 sites), service-automation/src/engine.ts, plugin-approvals/src/approval-service.ts.
• ⇒ the instrument reaches consumer code and goes red when EvalContext changes incompatibly. The green above is a measurement, not a silence.

Restore leg: git checkout HEAD -- packages/formula/src/types.ts, git hash-object equal to the HEAD blob 27f991bbd7…, whole-tree git status --porcelain empty, formula rebuilt, and ablation-dist-preflight … --absent green — so no mutated byte survives in dist/ for a later run to read.

The opposite direction the card asked about — does anything CONSTRUCT an EvalContext carrying api? — is answered by the same green leg: after the removal such a literal is a compile error, and none exists.

Pinned sibling (Post-Task Checklist step 4, Console Pin Gate): objectui at .objectui-sha = 53ded82bf7a494f54e344e19099dbf00854b8694 names EvalContext zero times; control in the same tree — four distinct from '@objectstack/formula' import lines (ExpressionEngine, validateExpression, collectCelRootIdentifiers, firstUndeclaredReference) across packages/app-shell. Nothing there is broken by this removal and no pin bump is owed.

Tests

packages/formula: 31 files / 876 tests pass, pnpm typecheck green. The new src/eval-context-no-query-api.test.ts pins the retirement in both directions — a type-level pin (@ts-expect-error on api in an EvalContext literal) and two runtime pins (buildScope binds nothing from a context still carrying one; a predicate calling os.lookup is refused even when an implementation is supplied).

The type-level pin is verified live rather than assumed: formula's test-typecheck ledger reports the same 3 files / 7 errors / 4 signatures as before this PR. That ledger is exact and shrink-only, so an @ts-expect-error that had become unused would arrive as TS2578 and red it. It stayed silent, which means the directive is used — api really is rejected.

Gates

• node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 57 gate families from the change set itself (the 3 paths above). All 57 were run at this branch's head and every one exited 0; --ran reconciliation with the exit codes recorded reports 57 derived / 57 run / 0 NOT-MEASURED / 0 UNRUN. The artifact-roster, wide-population and path-scheduled families the same tool prints outside that total remain CI's.
• pnpm lint is CI's repo-wide run; the local delivery is a declared narrowing with its three readings: ① the population eslint's own config admits is 6819 files (git ls-files filtered to lintable extensions, each asked through ESLint#isPathIgnored; 0 ignored) — note eslint.config.mjs's own header records 4659 from an older tree, a drift this PR does not touch; ② the narrowed run linted 2 files (--format json, result length), 0 errors / 0 warnings; ③ the config enables no type-aware linting (no parserOptions.project, no projectService, no typed @typescript-eslint rules — its header says so and the config carries no such key), so this diff cannot move any untouched file's verdict.
• skip-changeset measured rather than assumed: @objectstack/formula's files[] is dist, README.md, CHANGELOG.md; after the build, packages/formula/dist/index.d.ts carries the EvalContext interface with grep -c "api?:" = 0 — positive control grep -c "EvalContext" = 10 in the same file. Published bytes move, so the label would be wrong and a changeset is owed and present.

Acceptance notes

• Out of scope, noted and not filed: eslint.config.mjs's header states "across all 4659 linted files" while the population reads 6819 today. A stale prose count in a config header — an observation, not a defect, a contract violation or an authoring trap. Carrier: the next PR that edits that header.
• The identically-named ctx.api on the hook ScopedContext is untouched and stays live; nothing in this PR narrows it.
• needs:contract-review belongs to the dispatching seat, which hangs it on both carriers. This PR neither hangs, removes nor waits on it.
• Draft on purpose: the PR body is written once, in the opening stroke, and never patched — anything it needs later is named in the dev report for the seat to edit.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

1 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• 1 name(s) were too generic to anchor anything (single lowercase words)
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 7 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 4691ad17d273f23d90bd5ef495728dd2a12ee020 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 43bff01ddc6bda3558ad94763e72262c6697163e — the merge of head 2b053aebd7ba4bd24fe469c91790308d31333b28 into base 4691ad17d273f23d90bd5ef495728dd2a12ee020, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 43bff01ddc6bda3558ad94763e72262c6697163e && git checkout 43bff01ddc6bda3558ad94763e72262c6697163e
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 4691ad17d273f23d90bd5ef495728dd2a12ee020 2b053aebd7ba4bd24fe469c91790308d31333b28 && git checkout -B drift-repro 4691ad17d273f23d90bd5ef495728dd2a12ee020 && git merge --no-ff 2b053aebd7ba4bd24fe469c91790308d31333b28

node scripts/docs-audit/affected-docs.mjs --json 4691ad17d273f23d90bd5ef495728dd2a12ee020

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

[huangyiirene]

needs:contract-review cleared from both carriers — provenance for the stroke, written 2026-09-17T18:32Z.

contract-review record	card #18318, comment 5718801694 — ## Contract review, Served-tier: present, VERDICT: PASS
head judged by that record	2b053aebd7ba4bd24fe469c91790308d31333b28 — the head this PR still carries, ⛔ not a predecessor
carriers	card #18318 cleared · PR #18736 cleared, one stroke, label-write.mjs with read-back on each

Pre-landing checks, all three re-taken at this stroke — ⛔ none carried over.

• ① the in-seat clause-② review is in case, in the template's shape, at the tier the fuse reads — and it PASSED only after a patch round this seat demanded: the changeset now carries **BREAKING** plus one ADR-0087 disposition, which is how breaking-ness is declared while the launch window refuses major (pr-automation.yml:723-724).
• ② check-clause2-carriers.mjs --pair 18736 → exit 0, and it reports that a review of record names this head.
• ③ CI on 2b053aebd7: 34 names, 0 pending, 0 non-green; all seven required contexts green. The three skips — Build Docs · Console Pin Gate · Packed-tarball smoke (opt-in) — are each on check-expected-skips' roster with a declared reason this diff satisfies. ⭐ Note what is not skipped here: Check Changeset ran, because this PR carries no skip-changeset label — the changeset was judged by the gate, ⛔ not by the seat alone.

Governed-surface predicate, derived by the script from this PR's own file list: check-governed-merges.mjs --pr 18736 → 0 of 3 paths ⇒ ordinary queue landing.

⚠️ ⛔ Two things this provenance records against the seat rather than the dev.

1. The needs:contract-review PR carrier was hung by the seat only after the dev reported row C1; the card side was hung at the claim stroke as it should be.
2. ⭐ The patch order named the wrong ADR-0087 category (type-surface-only). The dev derived runtime-interface-only instead and proved it — the gate answers not-required (runtime-interface-only) -- verified: packages/formula/src/types.ts#EvalContext (interface), exit 0. ⇒ The record is right because the order also said 「⛔ do not take my spelling on trust; derive it from the gate and prove it」, and the dev did exactly that.

⇒ Going ready and into the merge queue (SQUASH). This seat follows it to MERGED.

---

Generated by Claude Code