fix(spec, runtime): endpoint refusal, hint and describes no longer name 17.x as the running major (#24699)

Closes #24654

Clause-②: no

## What changed

Four customer-facing sentences said "in 17.x", but 18.x is the running
major and the behaviour they describe has not changed. Each one now says
what the runtime does without naming a version, so it cannot go stale
again at 19.0. ⛔ No behaviour change, no new gate.

| where | reader | now reads |
|:--|:--|:--|
| `packages/spec/src/api/endpoint-publish-gate.ts` | the `os build` /
`os validate` refusal for a `script` / `proxy` endpoint | "This runtime
executes only 'object_operation' and 'flow' endpoints. `script` is
refused because ..." |
| `packages/runtime/src/endpoint-executor.ts` (`hint`) | the API caller,
in the `unsupported` answer | "This runtime executes only
'object_operation' and 'flow' endpoints. 'script' and 'proxy' are
rejected at publish ..." (word for word the same first sentence as the
spec refusal) |
| `packages/spec/src/api/endpoint.zod.ts` `type` describe | readers of
the published schema | "Implementation type — this runtime EXECUTES only
'object_operation' and 'flow'. ..." |
| `packages/spec/src/api/endpoint.zod.ts` `ApiMapping.transform`
describe | the same | "Transformation function name — NOT EXECUTED by
this runtime, and publish REJECTS the key ..." |

Same PR, maintainer-facing JSDoc: `packages/runtime/src/api-mapping.ts`
(the mirrored `transform` describe row) and
`packages/runtime/src/endpoint-executor.ts` (the `params` "always `{}`"
notes and the `planEndpointTarget` doc).

**Bounded in-place fix, named here:**
`packages/spec/src/api/endpoint.zod.ts`, `ApiEndpoint.target` describe,
said the Script Name / Proxy URL spellings "stay unreachable in 17.x".
It is the same defect class, in the same file, on the same schema, and
the same gate family covers it (`check:docs`). It now reads "stay
unreachable on this runtime". Evidence: the regenerated
`content/docs/references/api/endpoint.mdx` row for `target`.

Pins: no test asserted the old text (`git grep -nE "execute in
17|EXECUTED in 17|EXECUTE in 17"` over `*.test.ts` returns 0 hits). Two
test TITLES in `packages/runtime/src/endpoint-executor.test.ts` repeated
"in 17.x". They were reworded and their assertions are unchanged.

Regenerated with repo tooling: `pnpm --filter @objectstack/spec
check:generated --fix` found `check:docs` stale (1 of 14), regenerated
`content/docs/references/api/endpoint.mdx` and re-checked it green.
Changeset: `.changeset/24654-endpoint-text-version-free.md`, `patch` for
`@objectstack/spec` and `@objectstack/runtime`.

## Verification (head `f8e3a95abf`, which includes a merge of
`origin/main` `0431002104`)

- `pnpm --filter @objectstack/spec build && pnpm --filter
@objectstack/spec check:generated`, post-merge: "All 14 generated
artifacts are up to date", lock VERDICT command-exit 0.
- `pnpm --filter @objectstack/spec test` at `f8e3a95abf`: 701 files
passed, 1 skipped; 21347 tests passed. `pnpm --filter @objectstack/spec
typecheck`: exit 0.
- `pnpm --filter @objectstack/runtime test && pnpm --filter
@objectstack/runtime typecheck` at `018b472bd5` (the change itself,
before the merge): 425 files passed; 6678 tests passed, 19 skipped;
typecheck exit 0. The merge brought no change to the files this PR
edits. The runtime suite was not re-run on the merge head; CI runs it
there.
- `node scripts/pm/dispatch-gates.mjs --commands` derived 110 commands
at `f8e3a95abf`. All of them were run, and `--ran` reconciles: "110
derived famil(ies) accounted for — 109 run, 1 NOT-MEASURED".
- NOT MEASURED: `check:dual-build-cjs-loads`. Reason: PREREQUISITE NOT
MET (exit 3). It needs a full workspace build, and this worktree only
built the runtime dependency closure.
- `check:lean-entry-closure` first exited 1 because `@objectstack/spec`
dist was missing: a spec rebuild was running at the same time. Re-run
after the build finished: exit 0.

## Acceptance notes

Other "in 17.x" sites outside this card's file surface. None of them was
edited here:

- `packages/rest/src/openapi-endpoints.ts:218`: `unsupportedReason` says
"which this runtime does not execute in 17.x". This is customer-facing
OpenAPI output for the same endpoint family. It is reported to the seat
as a finding.
- `skills/objectstack-api/SKILL.md:163`: "`script` / `proxy` do not
execute in 17.x". This is the published skill text, a Tier H surface. It
is reported to the seat.
- `packages/spec/src/stack.zod.ts:845` (JSDoc),
`packages/spec/src/contracts/metadata-service.ts:210` (JSDoc, with the
test title `metadata-service.test.ts:485`),
`packages/spec/src/automation/flow-node-expression-paths.ts:126`
(JSDoc), `packages/spec/liveness/api.json:15` (ledger note):
maintainer-facing only.

---

_Generated by [Claude
Code](https://claude.ai/code/session_01D6F9axfoPzR7t8G1J7Ytzz)_

---------

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

Author: objectstack-fleet[bot]

.changeset/24654-endpoint-text-version-free.md

@@ -0,0 +1,11 @@
+---
+'@objectstack/spec': patch
+'@objectstack/runtime': patch
+---
+
+fix(spec, runtime): the endpoint publish refusal, the runtime's `unsupported` hint and the endpoint schema describes no longer say "in 17.x"
+
+Clause-②: no (no accept set, served body shape or authz answer moves: only the wording of a refusal, a hint and three schema descriptions changes)
+
+- These sentences named 17.x as the running major. On an 18.x runtime that made the refusal read as if the author were on the wrong version. Each one now states what the runtime does without naming a version: "This runtime executes only 'object_operation' and 'flow' endpoints." The behaviour is unchanged: `script` and `proxy` endpoints are still refused at publish, and `ApiMapping.transform` is still rejected.
+- Where it shows: the `os build` / `os validate` refusal for a `script` or `proxy` endpoint, the `hint` in the runtime's `unsupported` answer (word for word the same sentence), and the published `ApiEndpoint.type`, `ApiEndpoint.target` and `ApiMapping.transform` descriptions in the JSON Schema and reference docs.

content/docs/references/api/endpoint.mdx

@@ -33,8 +33,8 @@ const result = ApiEndpointSchema.parse(data);
 | **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'>` | ✅ | HTTP Method |
 | **summary** | `string` | optional |  |
 | **description** | `string` | optional |  |
-| **type** | `Enum<'flow' \| 'script' \| 'object_operation' \| 'proxy'>` | ✅ | Implementation type — only 'object_operation' and 'flow' EXECUTE in 17.x. 'script' and 'proxy' stay in the frozen vocabulary and are rejected at publish, not parsed and ignored: express script logic as a flow whose script node runs your registered function, and an outbound call as a flow using a declared connector |
-| **target** | `string` | optional | Target Flow ID, per `type` — REQUIRED at publish for `type: 'flow'` (the gate refuses a flow endpoint that names no target flow) and UNREAD for `type: 'object_operation'`, so do not write it there: that endpoint is addressed by `objectParams.object` / `.operation`, and a `target` beside them is a dead string nothing checks against `objectParams.object` (made the key optional for exactly that reason). The vocabulary's other spellings — a Script Name or Proxy URL — stay unreachable in 17.x, since publish rejects `type: 'script'` and `type: 'proxy'` |
+| **type** | `Enum<'flow' \| 'script' \| 'object_operation' \| 'proxy'>` | ✅ | Implementation type — this runtime EXECUTES only 'object_operation' and 'flow'. 'script' and 'proxy' stay in the frozen vocabulary and are rejected at publish, not parsed and ignored: express script logic as a flow whose script node runs your registered function, and an outbound call as a flow using a declared connector |
+| **target** | `string` | optional | Target Flow ID, per `type` — REQUIRED at publish for `type: 'flow'` (the gate refuses a flow endpoint that names no target flow) and UNREAD for `type: 'object_operation'`, so do not write it there: that endpoint is addressed by `objectParams.object` / `.operation`, and a `target` beside them is a dead string nothing checks against `objectParams.object` (made the key optional for exactly that reason). The vocabulary's other spellings — a Script Name or Proxy URL — stay unreachable on this runtime, since publish rejects `type: 'script'` and `type: 'proxy'` |
 | **objectParams** | `{ object?: string; operation?: Enum<'find' \| 'get' \| 'create' \| 'update' \| 'delete'> }` | optional | For object_operation type |
 | **inputMapping** | `{ source: string; target: string; transform?: string }[]` | optional | Map Request Body to Internal Params |
 | **outputMapping** | `{ source: string; target: string; transform?: string }[]` | optional | Map Internal Result to Response Body |
@@ -56,15 +56,15 @@ const result = ApiEndpointSchema.parse(data);
 | :--- | :--- | :--- | :--- |
 | **source** | `string` | ✅ | Source field/path |
 | **target** | `string` | ✅ | Target field/path |
-| **transform** | `string` | optional | Transformation function name — NOT EXECUTED in 17.x, and publish REJECTS the key: there is no transformation-function registry anywhere in the platform, so it stays in the frozen vocabulary and is refused rather than parsed and ignored (E7). A mapping entry moves and renames fields by dot path and nothing more — shape the value where it is produced instead (a flow endpoint whose flow computes it, or a formula field on the object) |
+| **transform** | `string` | optional | Transformation function name — NOT EXECUTED by this runtime, and publish REJECTS the key: there is no transformation-function registry anywhere in the platform, so it stays in the frozen vocabulary and is refused rather than parsed and ignored (E7). A mapping entry moves and renames fields by dot path and nothing more — shape the value where it is produced instead (a flow endpoint whose flow computes it, or a formula field on the object) |
 
 ### Nested Shape: `ApiEndpoint.outputMapping[number]`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **source** | `string` | ✅ | Source field/path |
 | **target** | `string` | ✅ | Target field/path |
-| **transform** | `string` | optional | Transformation function name — NOT EXECUTED in 17.x, and publish REJECTS the key: there is no transformation-function registry anywhere in the platform, so it stays in the frozen vocabulary and is refused rather than parsed and ignored (E7). A mapping entry moves and renames fields by dot path and nothing more — shape the value where it is produced instead (a flow endpoint whose flow computes it, or a formula field on the object) |
+| **transform** | `string` | optional | Transformation function name — NOT EXECUTED by this runtime, and publish REJECTS the key: there is no transformation-function registry anywhere in the platform, so it stays in the frozen vocabulary and is refused rather than parsed and ignored (E7). A mapping entry moves and renames fields by dot path and nothing more — shape the value where it is produced instead (a flow endpoint whose flow computes it, or a formula field on the object) |
 
 ### Nested Shape: `ApiEndpoint.rateLimit`
 
@@ -85,7 +85,7 @@ const result = ApiEndpointSchema.parse(data);
 | :--- | :--- | :--- | :--- |
 | **source** | `string` | ✅ | Source field/path |
 | **target** | `string` | ✅ | Target field/path |
-| **transform** | `string` | optional | Transformation function name — NOT EXECUTED in 17.x, and publish REJECTS the key: there is no transformation-function registry anywhere in the platform, so it stays in the frozen vocabulary and is refused rather than parsed and ignored (E7). A mapping entry moves and renames fields by dot path and nothing more — shape the value where it is produced instead (a flow endpoint whose flow computes it, or a formula field on the object) |
+| **transform** | `string` | optional | Transformation function name — NOT EXECUTED by this runtime, and publish REJECTS the key: there is no transformation-function registry anywhere in the platform, so it stays in the frozen vocabulary and is refused rather than parsed and ignored (E7). A mapping entry moves and renames fields by dot path and nothing more — shape the value where it is produced instead (a flow endpoint whose flow computes it, or a formula field on the object) |
 
 
 ---

packages/runtime/src/api-mapping.ts

@@ -22,7 +22,7 @@
  * | `outputMapping` | *Map Internal Result to Response Body* |
  * | `ApiMapping.source` | *Source field/path* |
  * | `ApiMapping.target` | *Target field/path* |
- * | `ApiMapping.transform` | *Transformation function name — NOT EXECUTED in 17.x, and publish REJECTS the key: there is no transformation-function registry anywhere in the platform, so it stays in the frozen vocabulary and is refused rather than parsed and ignored (#5040 E7). A mapping entry moves and renames fields by dot path and nothing more — shape the value where it is produced instead (a flow endpoint whose flow computes it, or a formula field on the object)* |
+ * | `ApiMapping.transform` | *Transformation function name — NOT EXECUTED by this runtime, and publish REJECTS the key: there is no transformation-function registry anywhere in the platform, so it stays in the frozen vocabulary and is refused rather than parsed and ignored (#5040 E7). A mapping entry moves and renames fields by dot path and nothing more — shape the value where it is produced instead (a flow endpoint whose flow computes it, or a formula field on the object)* |
  *
  * Five short sentences, and everything below is the MINIMAL faithful reading of
  * them — `transform`'s now says out loud, at the point of authoring, what this

packages/runtime/src/endpoint-executor.test.ts

@@ -135,7 +135,7 @@ describe('buildEndpointExecutionContext — a projection, not an interpretation'
         expect(ctx.remoteAddress).toBe('203.0.113.9');
     });
 
-    it('carries the match: the parsed endpoint, and `params` — always {} in 17.x', () => {
+    it('carries the match: the parsed endpoint, and `params` — always {}', () => {
         const ep = endpoint({});
         const ctx = contextFor(ep);
         expect(ctx.endpoint).toBe(ep);
@@ -204,7 +204,7 @@ describe('planEndpointTarget — the unsupported subset is enumerated once', ()
         expect((plan as any).reason).toContain(expected);
     });
 
-    it.each(['script', 'proxy'])('refuses `%s` — declared by the vocabulary, not executed in 17.x', (type) => {
+    it.each(['script', 'proxy'])('refuses `%s` — declared by the vocabulary, not executed by this runtime', (type) => {
         const plan = planEndpointTarget(endpoint({ type, objectParams: undefined }));
         expect(plan.kind).toBe('unsupported');
         // The reason names the type so an author is not left guessing which of

packages/runtime/src/endpoint-executor.ts

@@ -75,7 +75,7 @@ import type { HttpProtocolContext } from './http-dispatcher.js';
  *
  * `params` is deliberately NOT here: the transport's own route params are
  * meaningless for a path no route matched, and the endpoint's path parameters
- * arrive on {@link ApiEndpointMatch.params} instead (always `{}` in 17.x — the
+ * arrive on {@link ApiEndpointMatch.params} instead (always `{}` — the
  * frozen vocabulary defines no template syntax).
  */
 export interface EndpointExecutionRequest {
@@ -133,7 +133,7 @@ export interface EndpointExecutionContext {
     /** Matched endpoint, schema defaults materialized. */
     endpoint: ApiEndpoint;
     /**
-     * Path parameters from the match. **Always `{}` in 17.x** and deliberately
+     * Path parameters from the match. **Always `{}`** and deliberately
      * NOT consulted when resolving a record id — the id comes from `query.id`
      * (#5040 §2), because reading it from a template segment would require a
      * template syntax the vocabulary does not define.
@@ -225,7 +225,7 @@ export type EndpointTargetPlan =
 /**
  * Classify a declaration into the pipeline that will run it.
  *
- * `script` and `proxy` are declared by the vocabulary and NOT executed in 17.x,
+ * `script` and `proxy` are declared by the vocabulary and NOT executed by this runtime,
  * on purpose (#5040 §7-3, restated in the E5 card): the automation contract's
  * `execute` doc mentions "flow or script" but nothing in this repo verifies a
  * script target is reachable that way, and `proxy` is an entirely new outbound
@@ -265,7 +265,7 @@ export function planEndpointTarget(endpoint: ApiEndpoint): EndpointTargetPlan {
     return {
         kind: 'unsupported',
         reason: `Endpoint '${endpoint.name}' declares type '${endpoint.type}', which this runtime does not execute.`,
-        hint: "Only 'object_operation' and 'flow' endpoints execute in 17.x. 'script' and 'proxy' "
+        hint: "This runtime executes only 'object_operation' and 'flow' endpoints. 'script' and 'proxy' "
             + 'are rejected at publish pending their own rulings — script reachability through the '
             + 'automation service is unverified, and proxy is an outbound (SSRF) surface.',
     };

packages/spec/src/api/endpoint-publish-gate.ts

@@ -368,7 +368,7 @@ function targetGate(
         path: at('type'),
         message:
             `${named} declares \`type: '${endpoint.type}'\`, which this runtime does not execute. `
-            + "Only 'object_operation' and 'flow' endpoints execute in 17.x. `script` is refused because "
+            + "This runtime executes only 'object_operation' and 'flow' endpoints. `script` is refused because "
             + 'no path in this repo verifies that a script target is reachable through the automation '
             + 'service — express the logic as a flow (`type: \'flow\'`) whose script node runs your '
             + 'registered function. `proxy` is refused because forwarding to an arbitrary outbound URL is '

packages/spec/src/api/endpoint.zod.ts

@@ -14,7 +14,7 @@ import { retiredKey } from '../shared/retired-key';
 export const ApiMappingSchema = lazySchema(() => z.object({
   source: z.string().describe('Source field/path'),
   target: z.string().describe('Target field/path'),
-  transform: z.string().optional().describe('Transformation function name — NOT EXECUTED in 17.x, and publish REJECTS the key: there is no transformation-function registry anywhere in the platform, so it stays in the frozen vocabulary and is refused rather than parsed and ignored (E7). A mapping entry moves and renames fields by dot path and nothing more — shape the value where it is produced instead (a flow endpoint whose flow computes it, or a formula field on the object)'),
+  transform: z.string().optional().describe('Transformation function name — NOT EXECUTED by this runtime, and publish REJECTS the key: there is no transformation-function registry anywhere in the platform, so it stays in the frozen vocabulary and is refused rather than parsed and ignored (E7). A mapping entry moves and renames fields by dot path and nothing more — shape the value where it is produced instead (a flow endpoint whose flow computes it, or a formula field on the object)'),
 }));
 export type ApiMapping = z.input<typeof ApiMappingSchema>;
 
@@ -171,8 +171,8 @@ export const ApiEndpointSchema = strictObject({
   description: z.string().optional(),
 
   /** Execution Logic */
-  type: z.enum(['flow', 'script', 'object_operation', 'proxy']).describe("Implementation type — only 'object_operation' and 'flow' EXECUTE in 17.x. 'script' and 'proxy' stay in the frozen vocabulary and are rejected at publish, not parsed and ignored: express script logic as a flow whose script node runs your registered function, and an outbound call as a flow using a declared connector"),
-  target: z.string().optional().describe("Target Flow ID, per `type` — REQUIRED at publish for `type: 'flow'` (the gate refuses a flow endpoint that names no target flow) and UNREAD for `type: 'object_operation'`, so do not write it there: that endpoint is addressed by `objectParams.object` / `.operation`, and a `target` beside them is a dead string nothing checks against `objectParams.object` (made the key optional for exactly that reason). The vocabulary's other spellings — a Script Name or Proxy URL — stay unreachable in 17.x, since publish rejects `type: 'script'` and `type: 'proxy'`"),
+  type: z.enum(['flow', 'script', 'object_operation', 'proxy']).describe("Implementation type — this runtime EXECUTES only 'object_operation' and 'flow'. 'script' and 'proxy' stay in the frozen vocabulary and are rejected at publish, not parsed and ignored: express script logic as a flow whose script node runs your registered function, and an outbound call as a flow using a declared connector"),
+  target: z.string().optional().describe("Target Flow ID, per `type` — REQUIRED at publish for `type: 'flow'` (the gate refuses a flow endpoint that names no target flow) and UNREAD for `type: 'object_operation'`, so do not write it there: that endpoint is addressed by `objectParams.object` / `.operation`, and a `target` beside them is a dead string nothing checks against `objectParams.object` (made the key optional for exactly that reason). The vocabulary's other spellings — a Script Name or Proxy URL — stay unreachable on this runtime, since publish rejects `type: 'script'` and `type: 'proxy'`"),
 
   /** Logic Config */
   objectParams: z.object({