spec(api): make ApiEndpoint.target optional; publish gate holds the flow requirement (#11290)

* spec(api): make ApiEndpoint.target optional; gate holds the flow requirement (#10338)

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

* test(spec): replace old required-target pin with gate-level pins; changeset (#10338)

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

---------

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

Author: claude[bot]

.changeset/lazy-pugs-shake.md

@@ -0,0 +1,14 @@
+---
+"@objectstack/spec": minor
+---
+
+`ApiEndpoint.target` is now **optional** in the vocabulary (#10338, maintainer ruling
+2026-08-23). The key was required on every endpoint but read only for `type: 'flow'`
+(executor, OpenAPI enrichment and the publish gate all address an `object_operation`
+via `objectParams.object` / `.operation`) — so an `object_operation` author was forced
+to write a dead string nothing consumed or cross-checked. Authoring guidance: omit
+`target` on `object_operation` endpoints. The publish gate still **requires** `target`
+for `type: 'flow'` — a flow endpoint that names no target flow is refused at publish,
+and the runtime's structural backstop answers `501 NOT_IMPLEMENTED` for one that
+reached the store another way. No migration: this is a pure widening — every previously
+valid declaration (all of which carry a string `target`) still parses unchanged.

content/docs/api/declarative-endpoints.mdx

@@ -68,10 +68,10 @@ export default defineStack({
       summary: 'Lead feed',
       description: 'Open leads, for the partner portal.',
       type: 'object_operation',
-      // `target` is required on every entry by the vocabulary. An
-      // object_operation is addressed by `objectParams`, so nothing reads this
-      // one — name the object it works on and keep the two in step.
-      target: 'acme_lead',
+      // No `target` — an object_operation is addressed by `objectParams`
+      // alone, so the key is unread for this type and omitting it is the
+      // correct spelling. `target` is required (at publish) only for
+      // `type: 'flow'`, as `acme_lead_intake` below shows.
       objectParams: { object: 'acme_lead', operation: 'find' },
       // Omitting `authRequired` is the safe spelling — it defaults to `true`.
       cacheTtl: 30,
@@ -149,10 +149,13 @@ under that mount.
 | `type: 'flow'` with no `target` | rejected |
 | `type: 'script'`, `type: 'proxy'` | rejected at publish |
 
-`target` is required on **every** entry, whatever the `type`. A `flow` endpoint is executed
-by it; an `object_operation` is addressed by `objectParams` instead, so nothing reads its
-`target` — write the object name there and keep the two in step, because leaving the key
-out is a type error before it is anything else.
+`target` is **per-type**: a `flow` endpoint is executed by it, so publish requires it
+there and refuses a flow that names no target flow. An `object_operation` is addressed by
+`objectParams` instead — nothing reads its `target`, and the key is optional in the
+vocabulary precisely so you can leave it out. Do: omit it on `object_operation` entries.
+A `target` written there is a dead string nothing checks against `objectParams.object` —
+a declaration whose first line says one object while `objectParams` serves another
+publishes green, which is why the dead spelling is not worth teaching.
 
 `script` and `proxy` are **not servable declarations**. Nothing in the platform verifies
 that a script target is reachable, and forwarding to an arbitrary outbound URL is an

content/docs/getting-started/quick-reference.mdx

@@ -324,7 +324,8 @@ export const leadFeed: ApiEndpoint = {
   path: '/api/v1/apps/acme/leads',   // /api/v1/apps/<namespace>/<subpath>
   method: 'GET',
   type: 'object_operation',
-  target: 'acme_lead',
+  // No `target` — object_operation is addressed by `objectParams` alone;
+  // `target` is required (at publish) only for `type: 'flow'`.
   objectParams: { object: 'acme_lead', operation: 'find' },
   // `authRequired` omitted → defaults to true (a session is required).
   cacheTtl: 30,

content/docs/protocol/kernel/http-protocol.mdx

@@ -1186,7 +1186,9 @@ export default defineStack({
       method: 'GET',
       summary: 'Lead feed',
       type: 'object_operation',
-      target: 'acme_lead',
+      // No `target` — an object_operation endpoint is addressed by
+      // `objectParams` alone; `target` is required (at publish) only for
+      // `type: 'flow'`, where it names the flow to trigger.
       objectParams: { object: 'acme_lead', operation: 'find' },
       // Defaults to `true`. Omitting it is safe; see the policy table below.
       authRequired: true,

content/docs/references/api/endpoint.mdx

@@ -36,7 +36,7 @@ const result = ApiEndpointSchema.parse(data);
 | **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 (#5040) 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` | ✅ | Target Flow ID or Script Name or Proxy URL, per `type` — but only the Flow ID is reachable in 17.x, since publish rejects `type: 'script'` and `type: 'proxy'` (an `object_operation` endpoint is addressed by `objectParams.object` / `.operation`; neither the publish gate nor the executor reads `target` for that type) |
+| **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` (#10338 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'` |
 | **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 |

examples/app-showcase/src/system/apis/index.ts

@@ -71,7 +71,10 @@ export const TaskFeedEndpoint: ApiEndpoint = {
   summary: 'Task feed',
   description: 'Returns tasks via a declarative object_operation endpoint — no handler code.',
   type: 'object_operation',
-  target: 'showcase_task',
+  // No `target`: an object_operation endpoint is addressed by `objectParams`
+  // alone — nothing reads `target` for this type, and #10338 made the key
+  // optional so an example stops teaching a dead string (`target` is required
+  // at publish only for `type: 'flow'`, as InquiryPurgeEndpoint below shows).
   objectParams: {
     object: 'showcase_task',
     operation: 'find',

examples/app-showcase/test/gap-fill.test.ts

@@ -130,11 +130,14 @@ describe('[#5112] showcase declares its api endpoints again (#5040 E8)', () => {
     }
   });
 
-  it('object_operation endpoints target objects that exist', () => {
-    const apis = (stack as { apis?: Array<{ type: string; target: string }> }).apis ?? [];
+  it('object_operation endpoints address objects that exist (via objectParams.object — `target` is unread for this type, #10338)', () => {
+    const apis = (stack as { apis?: Array<{ type: string; objectParams?: { object?: string } }> }).apis ?? [];
     const objectNames = ((stack as { objects?: Array<{ name: string }> }).objects ?? []).map((o) => o.name);
     for (const api of apis.filter((a) => a.type === 'object_operation')) {
-      expect(objectNames, `api endpoint targets missing object '${api.target}'`).toContain(api.target);
+      // `objectParams.object` is what the executor delegates on; `target` is
+      // unread for this type and the example no longer writes it.
+      expect(objectNames, `api endpoint addresses missing object '${api.objectParams?.object}'`)
+        .toContain(api.objectParams?.object);
     }
   });
 

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

@@ -529,6 +529,28 @@ describe('an unsupported declaration gets a structured 501, never invented seman
         expect((await executeEndpointTarget(ctx, deps)).status).toBe(501);
         expect(execute).not.toHaveBeenCalled();
     });
+
+    // [#10338] `target` is OPTIONAL in the vocabulary now, so a flow endpoint
+    // with the key OMITTED is a parseable declaration — the publish gate
+    // refuses it (`apis-publish-gates.test.ts`), and this is the runtime
+    // counterpart that gate mirrors (`planEndpointTarget`), for a declaration
+    // that reached the store without passing publish. Pinned as `code` AND
+    // `status` (ADR-0112): a bare status assertion would stay green on a
+    // refusal that lost its envelope.
+    it('a flow that OMITS target answers 501 NOT_IMPLEMENTED — code AND status — and calls nothing', async () => {
+        const execute = vi.fn();
+        const deps = depsWith({ automationService: { execute } });
+        const ctx = contextFor(endpoint({ type: 'flow', target: undefined, objectParams: undefined }));
+
+        const answer = await executeEndpointTarget(ctx, deps);
+
+        expect(answer.status).toBe(501);
+        const error = expectConformantError(answer);
+        expect(error.code).toBe(DispatcherErrorCode.enum.NOT_IMPLEMENTED);
+        expect(error.message).toContain('names no target flow');
+        expect(execute).not.toHaveBeenCalled();
+        expect(deps.callData).not.toHaveBeenCalled();
+    });
 });
 
 // ---------------------------------------------------------------------------

packages/spec/src/api/apis-publish-gates.test.ts

@@ -99,6 +99,21 @@ describe('[#5111] the flip — a well-formed `apis:` publishes', () => {
     expect(() => defineStack({ manifest, apis: [validObjectEndpoint, validFlowEndpoint] })).not.toThrow();
   });
 
+  // [#10338] The acceptance half of the ruling that made `target` optional:
+  // an `object_operation` endpoint is addressed by `objectParams.object` /
+  // `.operation`, and NO consumer reads `target` for that type (executor,
+  // OpenAPI enrichment and this gate all branch on `objectParams` alone) — so
+  // the author-facing contract stops demanding a dead string. Restoring
+  // required-ness in the vocabulary turns exactly this case red.
+  it('accepts an object_operation endpoint that omits `target` — nothing consumes it for that type', () => {
+    const { target: _dead, ...objectEndpointWithoutTarget } = validObjectEndpoint;
+    const apis = accept({ manifest, apis: [objectEndpointWithoutTarget] });
+    expect(apis).toHaveLength(1);
+    // Anti-vacuity: the endpoint parses whole, addressed by objectParams.
+    expect(apis?.[0]?.objectParams).toEqual({ object: 'showcase_task', operation: 'find' });
+    expect(apis?.[0]?.target).toBeUndefined();
+  });
+
   it('accepts an anonymous endpoint that arms its rate limit (ADR-0121 D6 satisfied)', () => {
     const apis = accept({
       manifest,
@@ -296,6 +311,17 @@ describe('[#5111] gate (a) — the supported subset (mirrors `planEndpointTarget
     const message = reject({ manifest, apis: [{ ...validFlowEndpoint, target: '' }] });
     expect(message).toMatch(/names no target flow/);
   });
+
+  // [#10338] `target` is optional in the VOCABULARY (an `object_operation`
+  // author no longer writes a dead string), so omission now reaches this gate
+  // instead of dying as a Zod `invalid_type` — and the gate is what holds the
+  // requirement for `type: 'flow'`. The issue path is asserted too: the author
+  // must be sent to the `target` line, not to the endpoint at large.
+  it('rejects a flow endpoint that omits `target` entirely — the gate holds the requirement now', () => {
+    const { target: _dead, ...flowWithoutTarget } = validFlowEndpoint;
+    const message = reject({ manifest, apis: [flowWithoutTarget] });
+    expect(message).toMatch(/apis\.0\.target: .*names no target flow/);
+  });
 });
 
 describe('[#5111] gate (b) — mapping declarations (mirrors `mappingDeclarationRejection`)', () => {

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

@@ -103,6 +103,25 @@ describe('ApiEndpointSchema', () => {
     expect(endpoint.name).toBe('get_customers');
   });
 
+  // [#10338] `target` is OPTIONAL in the vocabulary: for `object_operation` no
+  // consumer reads it (the executor, the OpenAPI enrichment and the publish
+  // gate all branch on `objectParams` alone), so the author is no longer
+  // forced to write a dead string. The per-type requirement for `type: 'flow'`
+  // lives in the publish gate (`apis-publish-gates.test.ts` pins it), not
+  // here — the vocabulary parses both types without the key.
+  it('parses an object_operation endpoint that omits `target` (#10338)', () => {
+    const endpoint = ApiEndpointSchema.parse({
+      name: 'get_customers',
+      path: '/api/v1/customers',
+      method: 'GET',
+      type: 'object_operation',
+      objectParams: { object: 'customer', operation: 'find' },
+    });
+
+    expect(endpoint.target).toBeUndefined();
+    expect(endpoint.objectParams).toEqual({ object: 'customer', operation: 'find' });
+  });
+
   it('should validate endpoint name format (snake_case)', () => {
     expect(() => ApiEndpointSchema.parse({
       name: 'valid_endpoint_name',