feat(cli)!: retire the @capabilities hook-body directive (#10917) (#11043)

The directive was read off the handler's stringified source, and `loadConfig`
runs every config through `bundle-require` and esbuild, which strips `//` line
comments before the handler is ever a runtime function. Measured on all four
ordinary authoring shapes (`.ts`, `.js`, `.mjs`, an imported handler) it reached
the extractor from none of them: the build exited 0, printed nothing, and shipped
the inferred capabilities alone, so the mismatch surfaced far from its cause as a
sandbox refusal at runtime.

Maintainer ruled Option B under ADR-0049 enforce-or-remove. Removed: the override
branch in `extract-hook-body.ts`, its docs block, and the two unit tests that
pinned it. `body.capabilities` — data rather than a comment, measured to survive
the build — remains the covered route for the same need.

Accept behaviour is unchanged: a config still carrying the comment builds to the
same artifact as before.


Claude-Session: https://claude.ai/code/session_019bmVFqoQPq63zhKrxdYG1r

Co-authored-by: Claude <noreply@anthropic.com>

Author: Elon Musk

.changeset/retire-capabilities-hook-directive.md

@@ -0,0 +1,37 @@
+---
+"@objectstack/cli": minor
+---
+
+**BREAKING** Retire the `@capabilities` hook-body directive comment (#10917).
+
+`os build` no longer reads a `@capabilities` line out of a handler body, and the
+docs no longer teach one. A body's capabilities are either inferred from its
+source, or declared as data in `body.capabilities` on the hook or action — the
+route that is measured to survive the build, and now the only way to name a token
+the code itself does not reveal.
+
+**Nothing an author wrote has to change.** The directive was read off the
+handler's stringified source, and `loadConfig` runs every config through
+`bundle-require` and esbuild, which strips `//` line comments before the handler
+is ever a runtime function. Measured on all four ordinary authoring shapes —
+`objectstack.config.ts`, `.js`, `.mjs`, and a handler imported from a local
+module — it reached the extractor from none of them: the build exited 0, printed
+nothing, and shipped the inferred capabilities alone. A config that still carries
+the comment builds to the same artifact before and after this release, so
+deleting it is optional and changes no output. What is gone is the wrong
+convention it taught, silently, to everyone who copied it out of the docs — a
+handler asking for more than inference derived was refused by the sandbox at
+runtime, far from the cause.
+
+Ruled under ADR-0049 enforce-or-remove: a capability declaration nothing parses is
+a false promise, and this one could not even be typed wrongly-but-visibly, because
+every authoring path deleted it before the extractor looked.
+
+The retirement kit: the override branch in `extract-hook-body.ts` and the two unit
+tests that pinned it are gone; the extractor header and
+`content/docs/automation/hook-bodies.mdx` record the removal instead of the
+spelling; the `os build`-level test keeps pinning both halves — the comment
+contributing nothing, and `body.capabilities` surviving — and a unit pin standing
+on the one shape where the override ever fired now asserts it grants nothing.
+
+<!-- adr-0087: not-required (no-migration-prescription) The retired surface is a COMMENT inside a hand-written handler, not metadata. It has no spec schema, no defKey:name row in authorable-surface, and nothing that `objectstack migrate meta` can reach or rewrite, so no ADR-0087 ledger entry is expressible for it; inventing one would misdate a retirement the registry cannot honestly carry. It was also inert on every measured authoring path, so no consumer has a rewrite to perform at all — keeping the comment and deleting it produce the same build output. -->

content/docs/automation/hook-bodies.mdx

@@ -257,7 +257,7 @@ If you have a body that genuinely cannot be expressed in L1+L2 (typically: it ne
 
    Note that a CommonJS `require('node:os')` in a TypeScript config reaches the extractor as esbuild's `__require("node:os")`. Both spellings are refused under the same `require()` reason.
 
-Capabilities are inferred by matching known patterns in the body source (e.g. `ctx.api.object(...).insert(...)` ⇒ `api.write`). A fuller AST-based analysis is planned for a later version. When the inference is wrong, supply `body` yourself with an explicit `capabilities` array — the `// @capabilities` directive comment [does not reach the build](#capability-inference).
+Capabilities are inferred by matching known patterns in the body source (e.g. `ctx.api.object(...).insert(...)` ⇒ `api.write`). A fuller AST-based analysis is planned for a later version. When the inference is wrong, supply `body` yourself with an [explicit `capabilities` array](#capability-inference) — that path is data rather than a comment, so it survives the build.
 
 ## Migration
 
@@ -319,46 +319,46 @@ The extractor scans each body for known patterns and adds the matching capabilit
 | `ctx.crypto.randomUUID` | `crypto.uuid` |
 | `ctx.log.info / warn / error / debug` | `log` |
 
-To override the inference, add a directive comment as the first line of your handler body:
+When inference does not derive what a body needs, declare the tokens yourself by
+supplying `body` on the hook or action instead of a `handler`:
 
 ```ts
-handler: async (ctx) => {
-  // @capabilities api.read api.write log
-  …
-}
+hooks: [
+  {
+    name: 'notify_owner',
+    object: 'account',
+    events: ['afterInsert'],
+    body: {
+      language: 'js',
+      source: "await ctx.api.object('task').insert({ subject: 'follow up' });",
+      capabilities: ['api.write', 'log'],
+    },
+  },
+]
 ```
 
-<Callout type="warn" title="This directive does not reach `objectstack build`">
-  The override is read off the handler's **stringified source** (`String(fn)`), so it
-  only works if the function the CLI holds still carries the comment. Through
-  `objectstack build`, it never does.
-
-  `loadConfig` runs your config through `bundle-require` → esbuild, and esbuild strips
-  `//` line comments before the handler is ever a runtime function. The directive is
-  gone by the time the extractor looks at it. Measured on all four authoring shapes:
-
-  | Authoring shape | `// @capabilities api.write log` reaches the extractor? |
-  |---|---|
-  | `objectstack.config.ts` | **No** — comment stripped by esbuild |
-  | `objectstack.config.js` | **No** — esbuild runs on `.js` too |
-  | `objectstack.config.mjs` | **No** — same path |
-  | handler imported from a local `./handlers.js` | **No** — esbuild bundles it as well |
-
-  In every case the build exits 0, prints nothing, and emits the **inferred**
-  capabilities only. A handler asking for `api.write log` whose body reads
-  `ctx.api.object('x').find({})` ships `"capabilities": ["api.read"]` — inference won,
-  silently, and the directive had no effect at all.
-
-  **So do not rely on this directive.** Write the body so the
-  [inference table](#capability-inference) above derives what you need, or supply
-  `body` yourself on the hook with an explicit `capabilities` array — that path is
-  data, not a comment, and survives the build.
-
-  Inference is unaffected: it matches the *code*, which esbuild keeps. Only the
-  comment-borne override is lost. Tracked in #10678, where the question of whether the
-  directive should get a real authorable surface (or be retired) is open — this page
-  documents the reach as measured, and an `objectstack build`-level test pins it so
-  this page and the extractor cannot drift apart again.
+That path is **data, not a comment**, so nothing in the build pipeline can strip it
+on the way through — which is what makes it the supported way to say what a body
+needs.
+
+<Callout type="warn" title="The `@capabilities` directive comment was removed in 17.1">
+  A directive comment on the first line of a handler body was once documented as a
+  way to override inference. It was **retired** (#10917) and the extractor no longer
+  reads it.
+
+  It had never worked from any ordinary authoring path. The override was read off
+  the handler's stringified source (`String(fn)`), and `loadConfig` runs your config
+  through `bundle-require` → esbuild, which strips `//` line comments before the
+  handler is ever a runtime function. Measured on all four shapes —
+  `objectstack.config.ts`, `.js`, `.mjs`, and a handler imported from a local module
+  — the build exited 0, printed nothing, and emitted the **inferred** capabilities
+  alone. A handler asking for more than inference derived was then refused by the
+  sandbox at runtime, far from the cause.
+
+  **If a config of yours still carries one:** removing it changes nothing, because it
+  was already inert. If you meant the tokens it named, declare them in
+  `body.capabilities` as above. Inference is unaffected either way — it matches the
+  *code*, which esbuild keeps.
 </Callout>
 
 ### Build pipeline at a glance

docs/qa/platform-checklist/areas/cli.json

@@ -1232,14 +1232,14 @@
       "title": "Hook/action body extraction: --strict-body refuses every forbidden pattern with its own worded reason, capability tokens are inferred (and crypto.hash is NOT, #4391), free identifiers fall back to bundling — and the DEFAULT build's silent fallback contradicts the extractor's own contract (expected-fail)",
       "since": "v16",
       "status": "active",
-      "revision": 1,
+      "revision": 2,
       "priority": "P1",
       "surface": "cli",
       "personas": ["build-time author (no session)"],
       "fixtures": {
         "app": "scaffold",
         "requires": [
-          "a scratch blank scaffold whose config authors the probe hooks — one per FORBIDDEN_PATTERNS entry, one per CAPABILITY_PATTERNS shape, the ctx.crypto.hash regression probe, the @capabilities override, the const-api alias, an implicit-return arrow, and one handler calling a module-scope helper",
+          "a scratch blank scaffold whose config authors the probe hooks — one per FORBIDDEN_PATTERNS entry, one per CAPABILITY_PATTERNS shape, the ctx.crypto.hash regression probe, a probe carrying the RETIRED @capabilities first-line comment, a hook declaring body.capabilities as data instead of a handler, the const-api alias, an implicit-return arrow, and one handler calling a module-scope helper",
           "jq over dist/objectstack.json — body presence and body.capabilities per hook are the artifact-side oracle"
         ],
         "knownGaps": [
@@ -1250,7 +1250,7 @@
       "steps": [
         "author the forbidden seven, one hook each: dynamic import(, require(, fetch(, process.<x>, globalThis.<x>, eval(, new Function( — then run `os build --strict-body; echo $?` and capture every per-callable diagnostic verbatim",
         "the default-path pair on the SAME config: `os build; echo $?` — capture the exit, the 'Bundling N handler(s)…' line, and jq the artifact for each hook's body (expect ABSENT) and handler ref (expect present)",
-        "the inference matrix, one hook each on a clean config: ctx.api.object('x').find(…) · ctx.api.object('x').update(…) · const api = ctx.api; api.object('x').find(…) · ctx.crypto.randomUUID() · ctx.log.info(…) · a body whose ONLY crypto call is ctx.crypto.hash(…) · a body with '// @capabilities api.read api.write' as its first line and no matching calls · an implicit-return arrow — `os build` then jq each hook's body.capabilities and isExpression handling",
+        "the inference matrix, one hook each on a clean config: ctx.api.object('x').find(…) · ctx.api.object('x').update(…) · const api = ctx.api; api.object('x').find(…) · ctx.crypto.randomUUID() · ctx.log.info(…) · a body whose ONLY crypto call is ctx.crypto.hash(…) · a body carrying the retired @capabilities first-line comment and no matching calls (#10917 — it must contribute nothing) · a hook supplying body.capabilities as data instead of a handler · an implicit-return arrow — `os build` then jq each hook's body.capabilities and isExpression handling",
         "free-identifier probe: a handler calling a module-scope helper function — `os build; echo $?` (expect green, handler bundled, no body) then `os build --strict-body; echo $?` (expect exit 1 naming the identifier)",
         "all-body-only run: remove every non-extractable handler and confirm the 'Skipping legacy runtime bundle (all N callables are body-only)' line and that no objectstack-runtime.*.mjs remains in dist/",
         "re-run the strict-body failure with --json and capture the { success: false, error: 'strict-body: missing body', issues } payload"
@@ -1275,10 +1275,10 @@
           "evidence": "the three jq captures"
         },
         {
-          "clause": "the '// @capabilities …' first-line override adds exactly the named tokens (from the closed set api.read/api.write/crypto.uuid/log) even when no call pattern matches, merged with any inference — the author's declaration wins additively",
+          "clause": "capabilities the body's own code does not reveal are declared as DATA: a hook supplying body: { language, source, capabilities: [...] } ships exactly those tokens into the artifact. The RETIRED @capabilities first-line comment (#10917, ADR-0049 enforce-or-remove) adds nothing — a config that still carries one builds identically to one that does not, which is the guarantee owed to apps authored while it was documented",
           "oracle": "build",
-          "verify": "the override hook with no matching calls carries ['api.read','api.write'] in the artifact (extract-hook-body.ts:118-131; documented at content/docs/automation/hook-bodies.mdx:320-327)",
-          "evidence": "the jq capture"
+          "verify": "jq shows the declared tokens verbatim on the body-supplying hook; the retired-comment hook carries ONLY what inference derives (['api.read'] for a body reading .object(x).find(…) — never the api.write/log the comment names) and os build exits 0 saying nothing about it. No override branch is left in extract-hook-body.ts to read the comment (retirement note :43-59); content/docs/automation/hook-bodies.mdx documents the removal, not the spelling",
+          "evidence": "both jq captures + the exit code"
         },
         {
           "clause": "#1876 self-containment: a handler referencing a module-scope identifier throws out of extraction naming the identifier(s), the caller catches and keeps the handler BUNDLED (no body, handler ref into the .mjs) so the default build stays green with no behavior change — while --strict-body surfaces the same message as a hard failure",
@@ -1308,15 +1308,16 @@
       ],
       "traps": ["stale-dist", "absence-inference"],
       "source": [
-        "packages/cli/src/utils/extract-hook-body.ts (contract header :3-29 — whose fail-the-build sentence the expected-fail clause tests; FORBIDDEN_PATTERNS :33-41; CAPABILITY_PATTERNS :43-57 with the #4391 removal note :52-55; #1876 free-identifier throw :94-109; @capabilities override :118-131)",
+        "packages/cli/src/utils/extract-hook-body.ts (contract header :4-67, carrying the #10917 retirement note at :43-59; FORBIDDEN_PATTERNS :71-88; CAPABILITY_PATTERNS :90-104 with the #4391 removal note :99-102; #1876 free-identifier throw :146-161 — the @capabilities override branch this item used to cite is retired and gone)",
         "packages/cli/src/utils/lower-callables.ts (:33-36 the warnings field, :63-78 tryExtractBody's catch-all fallback-to-bundle — the seam the default path's silence flows from)",
         "packages/cli/src/commands/compile.ts (:126-149 the --strict-body gate, :366-393 the needsBundle decision + skip line, :437 the --json warnings key that excludes extraction warnings)",
-        "content/docs/automation/hook-bodies.mdx (:254-256 the documented default + --strict-body posture; :311-327 the inference table + override)",
+        "content/docs/automation/hook-bodies.mdx (the documented default + --strict-body posture; the Capability inference section — the inference table, the body.capabilities route, and the callout recording the retired directive)",
         "packages/cli/src/utils/lower-callables.test.ts (the existing unit seam pin — cited, not a substitute for driving os build)",
         "sibling items records-forms (runtime sandbox side, body-runner.ts) and cli.build-own-contract (the build's own exit/output contract)"
       ],
       "history": [
-        { "revision": 1, "date": "2026-08-20", "change": "new — scoped scan-functionality sweep (扫描功能): a security grant derived from a regex had no checklist item — only the runtime side of one token (records-forms) and the build's generic exit contract were covered. RE-VERIFIED against source with one material correction to the hunter brief: a forbidden pattern does NOT fail a default `os build` — lower-callables.ts:63-78 catches every extraction error and falls back to the bundle, the warnings print nowhere on that path, and only --strict-body (compile.ts:126-149) produces the worded refusals; hook-bodies.mdx:256 documents exactly that, while the extractor's own header still promises fail-with-no-fallback. The worded-refusal clauses are therefore pinned to --strict-body, and the default path's silence is encoded as the expected-fail contradiction clause", "ref": "claude/new-session-0pv25p" }
+        { "revision": 1, "date": "2026-08-20", "change": "new — scoped scan-functionality sweep (扫描功能): a security grant derived from a regex had no checklist item — only the runtime side of one token (records-forms) and the build's generic exit contract were covered. RE-VERIFIED against source with one material correction to the hunter brief: a forbidden pattern does NOT fail a default `os build` — lower-callables.ts:63-78 catches every extraction error and falls back to the bundle, the warnings print nowhere on that path, and only --strict-body (compile.ts:126-149) produces the worded refusals; hook-bodies.mdx:256 documents exactly that, while the extractor's own header still promises fail-with-no-fallback. The worded-refusal clauses are therefore pinned to --strict-body, and the default path's silence is encoded as the expected-fail contradiction clause", "ref": "claude/new-session-0pv25p" },
+        { "revision": 2, "date": "2026-08-22", "change": "the '// @capabilities' first-line override was RETIRED (#10917, maintainer ruling under ADR-0049 enforce-or-remove): measured on all four ordinary authoring shapes (.ts/.js/.mjs/an imported handler) it reached the extractor from NONE of them, so a documented directive silently taught a wrong convention and the mismatch surfaced far from its cause as a sandbox refusal. Its acceptance clause asserted behaviour that no longer exists — a runner would have filed a FAIL against the ruling — and is replaced by the covered route (body.capabilities as data) plus the inertness guarantee owed to configs that still carry the comment. Steps, fixtures and the extract-hook-body.ts line citations moved with it. No other clause changed; note the expected-fail clause still describes the pre-#10678 silent default and is stale on its own account, which is NOT this revision's subject", "ref": "claude/issue-10917-retire-capabilities-hook-directive" }
       ]
     },
     {