feat: pending group_role domains (#106), Bereiche + security levels as managed resources (#108/#110), commentViewer refs (#102), and an audit that can see past OpenAPI (#111)

[2000game]

Closes #106, #108, #110, #111, and the cdb_comment_viewer half of #102. #109 is closed as overtaken — see the bottom.

All five started as one defect: docs/runbook-manual-surface.md defined the manual surface by grepping the OpenAPI spec, which structurally cannot see the legacy endpoint ChurchTools' admin UI writes master data through — and then wrote the results down as "permanently", "never", "not resources at all". Fixing the procedure first, then re-probing, turned three "impossible" items into shipped features. It also caught a wrong claim in this PR's own first commit.

Everything below was probed live against eqrm-dev, CT 3.135.2, 2026-08-14. Every write experiment restored the instance to its prior state.

#106 — a group and its own groupRole plan on a fresh host

The domain half of #29's deadlock. A ct.groupRole whose group was declared in the same config but absent from the target host was a hard error, so the identical config planned clean on prod and exited 1 on dev — non-portable by construction, and one logical change had to be split across two merges.

The information was already available: executePlan runs the resource tiers before applyPermissionPlan. So the domain resolves to a PendingRef, renders as <group-role(group=…, role=…) (created this apply)>, and is completed at apply time by reading the freshly created group's own /groups/{id}/roles. A role the group turns out not to have is still a hard error listing the roles it does have — shared code path with plan time, so the message cannot drift.

Pending group-roles are opt-in per call site. This is the one pending ref reresolvePendingValue cannot finish from state alone — a pairing id is not the group's id — and only the permission-domain position gets the live fetch. Everywhere else keeps the old fail-fast error.

#108 — Bereiche are a managed resource

GET /departments is a normal catalog; no REST write verb exists. The admin UI writes Bereiche through POST /index.php?q=churchdb/ajax func=saveMasterData, and ct does now too:

ct.department({ key: "equippers_koblenz", name: "Equippers Koblenz", shorty: "EQKO" });

Verified end to end on dev with the real CLI — plan → apply → re-plan no-op → update → delete. deleteMasterData exists: a made-up delMasterData answers "Function delMasterData was not defined as Function!", so the endpoint validates function names and the success is real, not a silent no-op.

Reads stay REST, columns are validated against the instance's own DESCRIBE before posting (the legacy endpoint does not 400 on an unknown colN — it ignores it, so an unvalidated write looks like a success while dropping the field), and create refuses to guess when it cannot identify the row it just wrote by name.

A bug only the live run could catch: there is no /departments/{id} path at all. The default read 404d, every caller read that as "vanished in ChurchTools", and the second plan proposed creating the same Bereich again — forever. A mock answers whatever path it is asked for. Fixed with a fetchOne hook and pinned.

#110 — security levels are a managed resource with a declared id

The issue said "no REST write verb". Wrong, and I repeated it in this PR's first commit before re-probing. /securitylevels/{id} has POST (create), PATCH (update, incl. reorder via newid + forcereorder) and DELETE. Corrected in a follow-up commit.

The id is caller-assigned — you POST to the id you want, CT 409s if taken:

ct.securityLevel({ key: "stufe_3_hoch", id: 3, name: "Stufe 3 (Hoch)" });

That is the first such type here, and it resolves the issue's worry from the other end: a config that owns its levels makes numeric scope: [1, 2, 3] genuinely portable. The name-based ref form ships too, for configs that don't own them.

Two guard rails: changing a declared id is refused at plan time (that is a renumber, which rewrites what every numeric scope on the dimension grants, and the executor would otherwise emit a PATCH {id} CT ignores or 409s — a plan that never converges), and ct destroy warns that a delete reaches every person field and grant referencing the level.

#102 (partial) — commentViewer scope refs

/person/commentviewers is plain REST CRUD, so { commentViewer: "gemeindeleitung" } is one more catalog ref — no legacy endpoint, contrary to #109's assumption. Unblocks the three Pastoral Care role instances each blocked by exactly one comment_viewer-scoped grant. id: 0 is a real row ("Alle"), pinned by a test so nothing treats a falsy id as missing. The preserveUnknown half of #102 is untouched.

#111 — the audit that produced all of the above

A "no write API" verdict now requires both the REST/OpenAPI probe and a getMasterData → masterDataTables probe, plus a UI capture where neither settles it, plus a record of which probes ran and when. The three buckets are relabelled ("No write API ct can drive" / "Not yet implemented" / "Out of tool scope") so a capability fact, a roadmap item and a product decision stop reading alike, with an explicit rule for when an absolute is allowed.

Down-scoped claims across the runbook, api-coverage.md, both handbook pages, and the code comments in refs.ts, resolver.ts, scope.ts, types.ts, adopt.ts and report.ts. The two rows still carrying only a REST probe (member statuses, meeting points) are flagged as such rather than left looking verified.

#109 — closed as overtaken

The epic assumed most of the 24 registry tables lack a REST write. Live, 15 have one (campuses, group types, person statuses, security levels, comment viewers, group categories, roles, age/target groups, meeting templates, dbfields, sexes, relationship types, growpaths, contact labels) — and per your rule, REST stays authoritative for all of them. Of the 9 without, 8 are person master data or field option lists outside this tool's mandate. Bereiche were the only table both in-mandate and REST-less, so the generic driver would have had exactly one in-scope user.

Full 24-table inventory posted on #109 before closing, so the finding survives if the mandate ever widens. #96 needs no change either — /statuses is full REST CRUD and person statuses are already adoptable.

Verification

npm run typecheck, npm test (729 passed, 5 skipped), npm run format:check, npx eslint src tests, and mkdocs build --strict all pass. Docs-staleness re-signed for every touched page. Pre-existing repo-wide eslint . failures come from a local .venv-docs/ and are unrelated.

Live on eqrm-dev, each restoring the instance: security-level create/rename/delete (levels 1–4 untouched throughout, confirming an insert does not implicitly renumber); Bereich create/update/delete via saveMasterData; and a full ct plan/apply/re-plan cycle for a declared Bereich through the real CLI.

New tests cover the pending group-role apply path end to end, the caller-assigned-id create and the renumber refusal, the department writer including the fetchOne regression and the unidentifiable-create refusal, column validation against the instance's schema, and the two new scope refs.

https://claude.ai/code/session_016TacHkv3oVczwXGHBwckq2