fix: draft-technical 422 on /predict, mocked-service crash; feat: opt-in recommendation mode

[sleibach]

This PR bundles two fixes and one feature for the recommendations plugin. Each is an independent commit; happy to split into separate PRs if preferred.

---

1. fix: exclude association elements from RPT-1 prediction rows (5e55030)

The draft branch of the recommendations READ handler builds its column list from all elements of req.target.actives, filtering out only audit fields, cds.LargeBinary and cds.Vector. Association/composition elements pass the filter — including the compiler-added DraftAdministrativeData on draft-enabled entities. These have no RPT-1 dtype (cdsToPythonDtype returns undefined), so they are omitted from data_schema but still present in rows. Whenever other edit drafts of the entity exist, context rows resolve DraftAdministrativeData to a non-scalar value and AI Core rejects the whole payload:

422 {"detail":[{"loc":["rows",7,"DraftAdministrativeData","str"],"msg":"Input should be a valid string",...}]}

The error is swallowed (empty predictions), so recommendations silently disappear while every draft READ with $expand=SAP_Recommendations still pays a full failed round-trip to AI Core — observed as recurring latency on a production-adjacent stage with concurrent drafts.

Repro: open an edit draft of an entity with @UI.Recommendations, then READ another draft of that entity with $expand=SAP_Recommendations.

Fix: skip isAssociation elements when building the column list. Flattened foreign keys (author_ID, …) are separate scalar elements and remain included — they are the actual prediction targets and features. A regression test opens an edit draft (so an active context row carries draft administrative data) and asserts the rows handed to fetchPredictions contain no association keys or non-scalar values; it fails on main and passes with the fix.

---

2. feat: opt-in recommendation mode (533e7ac)

Today the plugin is opt-out: every value-helped field auto-enrolls, and each unwanted one must be silenced with @UI.RecommendationState : 0. On large existing models this enrolls dozens of fields at once and generates unnecessary /predict traffic. New config flag:

// cds.requires
"AICore": { "recommendations": "opt-in" }

• "auto" (default): unchanged behavior — absence of the flag is byte-for-byte identical to today.
• "opt-in": a field is enrolled only if it carries a truthy @UI.RecommendationState (1 or a dynamic expression); value-helped fields without it stay out.

@UI.RecommendationState : 0 wins in both modes; entities with zero enrolled fields get no SAP_Recommendations companion (existing guard). Tests boot the bookshop in opt-in mode in its own process; README and CHANGELOG updated.

---

3. fix: skip mocked services and guard undefined req.target (2b3fc60)

cds-plugin.js registered the recommendations READ handler on every served service, including external services running with a mock fallback (srv.mocked). A free-form READ on such a service (e.g. srv.send(new cds.Request({ method, path }))) has no req.target, so the handler crashed with a TypeError on req.target.isDraft. Mocked services are now skipped at registration, and the handler additionally bails out early when req.target is undefined (defense in depth).

---

Verification

• npm test: 18/18 (node --test, sqlite bookshop + MockAICoreService), including the new 422 regression test and 3 opt-in mode tests
• eslint and prettier --check clean

[SirSimon04]

Hi @sleibach, thank you for your contribution! In general, it looks really good and sounds like a good feature to us.

Could you remove those big comments or shorten them? Most of the times, the code speaks for itself

[SirSimon04]

Can you check whether the service is external right on the service? Because remote services can exist without mocking, and relying on mocked instead may lead to confusion.

[sleibach]

Thanks @SirSimon04 for the feedback! External services are now detected directly, and the comments have been shortened.