Roadmap §§8–22: the conformance findings, the host strategy, a security review, and the handover

[oblomov-dev]

The written record of the work in cap2UI5/builder-abap2UI5-js#29, cap2UI5/cap2UI5#72 and the upstream seams PR, plus a page for whoever does the parts that need a person.

Important

This PR changes no documentation page. It adds ROADMAP sections and rewrites HANDOVER.md. The 36 pages under docs/ are left exactly as they are, on purpose — see §22 below.

ROADMAP.md §§8–22

Fifteen sections, each written when the thing it describes was measured, not afterwards:

• §8–9 the wire-conformance findings: the port's frontend and backend speak different protocols, and build_core produced a hanging core.
• §10 two corrections, including one to my own earlier analysis: I claimed the 41 transpiled framework classes were "neither maintained nor understood" and should be dropped. Measured, none is shadowed by src/ — all are fill-ins. The recommendation was withdrawn before anything was implemented.
• §11–12 the four upstream seams, the JS-app finding, the CDS draft store, the cold-restart proof.
• §13 the synchronous app API.
• §14 the plugin shape, and a correction to §12: owner coming out anonymous was reported there as "no auth configured". It was not — the route was mounted outside cds.middlewares.before, so the store could never see a user, and a draft answered to the wrong person. Fixed and tested.
• §15 everything that could be done without an org owner: tables and structures as app state, SQLite and performance measured, concurrency tested, the runtime package job, ADR-008.
• §16 it renders in a browser, and the final round is prepared.
• §17 the facade's second slice (popups, nested views, navigation, event arguments) and the three defects it exposed — including two facade members named after the wrong thing, one of which was documented obsolete and does nothing.
• §18 the claim the project rests on, finally tested: a plain CAP OData service running beside the apps, one authorization for both doors, and cap2ui5.Drafts not reachable through it.
• §19 "unsupported" turned out to mean "not attempted": nested structures and tables were called a framework limitation in three documents and were a guard in my own type derivation.
• §20 a security review of my own authorization code, which found a real defect: the draft store's three ownership checks tested the truthiness of the stored owner rather than its presence, so an ownerless row belonged to everybody rather than to nobody — with the proof of concept, the three smaller findings fixed alongside, and what the review cleared.
• §21 "it fails on main too" is an attribution, not a diagnosis — the three red checks across two PRs, root-caused rather than merely attributed (one test was merged red by main's own head), plus a correction to two numbers I had posted about the builder-abap2UI5-js ratchet.
• §22 the documentation is correct today and wrong on merge day — the audit below.

docs/reference/protocol.md gains a danger callout: the page documents S_FRONT.PARAMS, which is what cap2UI5 emits and no longer what abap2UI5 emits.

HANDOVER.md — rewritten, not patched

It had gone stale in a way that mattered: it told a human to open pull requests that are open, with suggested bodies naming an interface that has since been renamed, a workflow job that was reworked, and a file that moved — and it sent step 3 to the builder repository the plugin has since left. It also said to create an npm organisation that already exists and carries three packages.

It now says what to do with each pull request rather than repeating its body, carries the root cause of every red check a reviewer will see, and lists the facade slice as done instead of pending. The one warning that matters is unchanged: disable update_cap in builder-cap2UI5 before merging the plugin, or it overwrites it the next night.

And the part step 4 had left out: what the cutover does to these pages

Merging the plugin invalidates most of this repository's documentation on the same day. Measured over docs/ — 36 pages, 5,434 lines, 27 of them describing the port. Only ROADMAP.md, HANDOVER.md and one line of reference/database.md know the plugin exists.

It is not stale paths. The whole guide teaches the port's app API, and the plugin's is a different API rather than a renamed one:

class my_app extends z2ui5_if_app {     // the plugin: defineApp("ZCL_X", class {
  async main(client) {                  //   main(c) {           <- synchronous
    if (client.check_on_init()) { … }   //     if (c.isFirstRun) { … }
    client.view_display(xml);           //     c.view(xml);
  }                                     //   }
}                                       // })

	pages	lines	what happens
A structure & reference	12	1,949	rewritten from scratch
B app-authoring API	15	2,416	rewritten against defineApp
C survives with corrections	9	1,069	arguments hold, mechanics do not

One finding stands on its own: docs/guide/samples.md is generated and its generator breaks. scripts/gen-samples.mjs line 39 hardcodes …/cap2UI5/blob/main/core/srv/app/samples as its source and lines 122/188 write that path into the prose. The plugin PR deletes that folder, so the page's 98 rows lose their input — silently, into a stale page rather than an error.

Why nothing here is rewritten. These pages are correct today: they describe the cap2UI5 that is published and working. Rewriting them into the future tense would swap accurate documentation for speculative documentation, and a rejected approach would leave the repository with neither. The trigger is step 4.3 of the handover. The maintainer decision about where the docs live belongs before that rewrite, since it decides whether 3,400 lines land here or in the plugin repository.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JoANwtaK8Jm9srGEqSxmUF

---

Generated by Claude Code