Files
summercms/.planning/phases/19.7-generic-mcp-module/deferred-items.md

352 lines
22 KiB
Markdown

# Deferred items
Out-of-scope discoveries made while executing phase 19.7 plans. Nothing here
was changed by the plan that recorded it.
## Deferred Items
- Pre-existing `gofmt` drift in cabana (found during 19.7-01 Task 1)
status: open
**What:** `gofmt -l modules/cabana` lists `account_tokens.go`,
`account_tokens_test.go`, `field_trigger_smoke_test.go`,
`token_postgres_smoke_test.go`, `token_routes_test.go` and
`token_scopes_test.go` as unformatted before this plan touched the module
(alignment of map literals and struct tags). Left as is: reformatting
would add diff noise unrelated to the plan (a whole-file `gofmt -w` on
`token_routes_test.go` rewrote 132 lines and was reverted). A one-line
`gofmt -w` on those six files in a `style(cabana)` commit of its own fixes it.
- `AdminRecordAction.Prompt` acceptance grep counted two `prompt,omitempty`
tags in `schema_types.go` (found during 19.7-01 Task 4)
status: resolved
**What:** the second match is the pre-existing `FormField.Prompt` JSON tag
at `schema_types.go:376`, not a duplicate of the new `RecordAction.Prompt`;
the criterion's "prints 1" was written without that line in mind. No change
needed.
- Stateful pier sessions cannot carry the SDK's protocol-version context value (found during 19.7-02 Task 3)
status: open
**What:** go-sdk v1.8.0's `StreamableHTTPHandler.ServeHTTP` stores the
`Mcp-Protocol-Version` header under an unexported context key that the
transport's `servePOST`/`serveGET` read; pier's own session router (needed
for Redis-shared sessions, D-25) serves `StreamableServerTransport`
directly and cannot set that key, so stateful streams run with the SDK's
2025-03-26 defaults for stream close/reconnect hints and the JSON-RPC
batch rule (lenient, spec-compliant for older clients; 2026-07-28 clients
go through the SDK's own stateless handler). Revisit if a later SDK
exports the key or a transport-level setter; plan 05 may add a test
pinning the behaviour.
- `notifications/initialized` landing on another instance than `initialize` (found during 19.7-02 Task 3)
status: open
**What:** the session state is persisted after `initialize` and again
after the client's `initialized` notification; when a load balancer sends
the notification to a second instance, the first instance's local copy
keeps `InitializedParams` nil and refuses calls until that copy is
dropped (session end, revocation or process restart) while the second
instance serves them. Sticky sessions or a per-request re-read of the
stored `initialized` flag would close the gap; not needed for the
single-instance demo.
- cabana's backend subject events never reach pier (found during 19.7-03 Task 2)
status: resolved
**What:** `modules/cabana/subject_events.go` fires `pact.MCPSubjectChanged`
as a value (`app.Events.Fire(ctx, pact.MCPSubjectChanged{...})`), while
`modules/pier/events.go` listens for a pointer
(`func(ctx, ev *pact.MCPSubjectChanged)`). festival.Bus keys listeners by
the type parameter, so pier never sees the backend subject events cabana fires
(admin deletion, permission and role changes, token revocation): no
list_changed and no session close for the `backend` guard from cabana.
cabana also fires inside the save's transaction instead of after commit,
so a rolled-back save would still notify. sm-user-plugin v0.1.10 fires
`*pact.MCPSubjectChanged` (pointer) through `lagoon.AfterCommit`, which
pier does receive. Fix in the framework: fire `&pact.MCPSubjectChanged{}`
from cabana and defer it with `lagoon.AfterCommit`, with a pier test that
a cabana save reaches `handleEvent`. Must be fixed before v0.5.0.
**Resolved:** cabana now fires `&pact.MCPSubjectChanged{}` through
`lagoon.AfterCommit` (immediately outside a transaction);
`subject_events_test.go` pins delivery to a pointer listener, no firing
before commit and none after a rollback.
- pier publishes `*pier.Pier` once per application (found during 19.7-04 Task 1)
status: open
**What:** `pier.Mount` publishes the mounted endpoint on the app, so a
second `surf.BuildRouter`/`surf.Assemble` on the same `*backpack.App`
with `mcp.enabled: true` fails with `backpack: duplicate provider for
*pier.Pier`. A binary builds its router once, so serving is unaffected;
tests that build twice on one app (sm-demo-app `TestRealtimeRoutes`,
`socialServer`) now set `mcp.enabled: false`. A find-or-replace publish
(or skipping the publish when the same app already carries one) in pier
would lift it.
- MCP grants are not in the authorized-apps list (found during 19.7-04 Task 2)
status: open
**What:** the MCP flow (wristband `IssueCode`, sm-oauthserver-plugin's
`MCPStore`) stamps the client's `consented_at` but writes no row to
`golem15_oauthserver_consents`, so `GET /oauth/authorizations` does not
list an MCP client and `DELETE /oauth/authorizations/{client_id}` answers
404 for it. The access token itself can still be revoked (row
`revoked_at`, refused by the verifier at once) and the user cascade
removes every grant, but a user has no self-service "disconnect this
agent" for MCP yet. A consent row per MCP grant (written at `IssueCode`)
would make the existing list and revocation (which already fires the
`revoked` event) cover MCP clients; plan 05's revoke matrix should decide.
**Plan 05 decision:** accepted for this phase (19.7-SECURITY.md AR-19.7-03):
access still ends through client revocation, user deletion or
deactivation, token expiry and the verifier's refusal of a revoked token,
and `TestMCPEndToEnd` pins that the `revoked` event ends the session. The
consent row per MCP grant stays the follow-up.
- Pre-existing `gofmt` drift in sm-journal-plugin (found during 19.7-04 Task 3)
status: open
**What:** `gofmt -l` lists `classes/blog_editor_test.go` before this plan
touched the repository. Left as is.
- sm-demo-app push and the demo deploy wait for the user (found during 19.7-04 Task 5)
status: open
**What:** sm-demo-app master is eight commits ahead of origin (a25444e,
985af53 and this plan's 44cac13, 8668918, the pins aec16c4 oauthserver
v0.1.2, 996586c journal v0.2.3, 7e76957 vue-demo-app 21a22b6, and
c21ae9d with the nginx MCP locations and DEPLOY.md "MCP endpoint"). None
is pushed and nothing is deployed: both need the user's go-ahead. The
deploy also installs the changed vhost (DEPLOY.md, "When
deploy/nginx/demo.summercms.io.conf changed") and runs the MCP smoke.
The sm-oauthserver-plugin v0.1.2 and sm-journal-plugin v0.2.3 tags and
the vue-demo-app commit are pushed.
- Release builds pinning summercms v0.4.4 lack the cabana subject-event fix (found during 19.7-04 Task 5)
status: open
**What:** the demo (GOWORK=off release build), oauthserver v0.1.2 and
Journal v0.2.3 require summercms v0.4.4, which predates d96c726
(cabana fires `*pact.MCPSubjectChanged` after commit). Development
builds use the go.work replace and carry the fix; a release binary does
not: admin deletion, permission or role changes and token revocation in
the admin do not end MCP sessions or send list_changed until the next
framework tag is required by the demo. The verifier and the backend
resolver still refuse at the next request, so access does not outlive
the change; only the live session notification is missing. Deploy the
demo after the next framework tag, or accept the gap for the demo.
- Redis for MCP sessions on rome (found during 19.7-04 Task 5)
status: open
**What:** the demo runs one instance with `mcp.sessions.store: memory`.
A second instance needs `SUMMER_MCP__SESSIONS__STORE=redis` and
`SUMMER_REDIS__URL` on every instance (DEPLOY.md, "MCP endpoint") and a
Redis on rome; also see the `notifications/initialized` item above.
- Real MCP client check of the demo not run (found during 19.7-04 Task 5)
status: open
**What:** Task 5's human check (a real client against the local demo:
OAuth sign-in on /connect, user_me only, link an admin through
/link-admin, reconnect with backend, the journal_ tools, a draft post,
unlink) was not performed in the executor run; the automated
TestMCPEndToEnd covers the same path. The local setup is DEPLOY.md,
"MCP endpoint", "Locally".
- Retracted `github.com/gabriel-vasile/mimetype` v1.4.15 in sm-demo-app (found during 19.7-04 Task 5)
status: open
**What:** `go get` in sm-demo-app warns that mimetype v1.4.15 is
retracted (quadratic time on crafted CDF files). It arrives indirectly
and predates this plan; a `go get github.com/gabriel-vasile/mimetype@latest`
in the framework (and a tag) would lift it for every consumer.
- Framework fixes of plan 05 are on master only (found during 19.7-05 Tasks 1-2)
status: open
**What:** c49983d `fix(cabana)` (the `backend` middleware refuses a
dispatch marker with a frontend principal), c29d228 `fix(pier)` (a
`tools/call` without arguments) and 1111828 `fix(pier)` (an ended session
is not written back by a late request) are not in any tag. Applications
pinning summercms v0.4.4 (the demo's release build, oauthserver v0.1.2,
Journal v0.2.3) lack them until they require the next framework tag
(v0.5.0 at phase completion, after the user's go-ahead).
**Gap closure (19.7-09):** the same holds for every framework fix of plans
06 and 07; they ship together in v0.5.0 (see "Release order after the gap
closure" below).
- Plan 05 test commits are local and untagged (found during 19.7-05 Task 3)
status: resolved
**What:** sm-user-plugin 72de822 (in the sm-demo-app submodule checkout
`plugins/golem15/user`), sm-oauthserver-plugin 2929c91, sm-journal-plugin
a9a9b80 and sm-demo-app 6fa2d56 add tests only; none is pushed or tagged.
sm-demo-app's `plugins/golem15/user` working tree is ahead of its v0.1.10
pin by that test-only commit and the pointer is not committed;
`scripts/check-pins.sh` reports the mismatch, which the phase gate accepts
only because the commits touch `*_test.go` files alone. A patch tag
(sm-user-plugin v0.1.11, sm-oauthserver-plugin v0.1.3, sm-journal-plugin
v0.2.4) is optional; it would change no shipped code. Push and tags wait
for the user.
**Superseded (19.7-09):** the plugins now also carry the non-test fixes of
plan 08 and the tests of plan 09, so the plan 05 test commits ship in the
gap-closure plugin tags that require framework v0.5.0; the entries "Demo
plugin submodules and pointers wait for the release" and "Release order
after the gap closure" below track them.
- Superuser refusal switch, conditional (found during 19.7-05 Task 4)
status: open
**What:** the security review accepted superuser reach through an agent
(19.7-SECURITY.md AR-19.7-02) and did not add
`mcp.refuse_superuser_backend`. When a plugin declares a superuser-only or
destructive backend tool beyond content editing, add the switch (a
`fix(pier)` with README and docs) and cut a framework patch tag with the
user's go-ahead.
- B-IN-05: a prompted record action refused with 422 closes the dialog (found in the code review, deferred by 19.7-07)
status: open
**What:** when a prompted record action answers 422, the SPA shows the
error toast and closes the prompt dialog, so the typed text is lost.
Plan 07 corrected the contract text (the 422 toast behaviour is now what
the docs and the OpenAPI description say). Keeping the dialog open needs a
change to the shared confirm primitive every action uses (the dialog
resolves before the request answers), which is out of the gap closure's
scope. Follow-up: let the confirm primitive keep the dialog open on a
refused submit and show the field error inline.
- B-IN-06: `window.open` after an awaited POST can be blocked by a popup blocker (found in the code review)
status: resolved
**What:** no fix required. My account always renders the answered URL as
a visible link next to the section (`data-account-contribution-url`), so
an administrator whose browser blocked the popup clicks the link
(pinned by `admin/tests/account/AccountContributions.test.ts`).
- `admin:token:revoke` fires no MCP event (found during 19.7-07)
status: open
**What:** the CLI command revokes an admin personal token's row but does
not fire the token-specific `revoked` subject event that the My account
revoke fires (`fireTokenRevoked`). The verifier side refuses the revoked
token on the next request, so access ends; only a live MCP session of
that token keeps its stream until its next request or re-check. Same
shape as before plan 07. Fix: call the same helper from the command after
its transaction.
**Re-review (RB-IN-03):** kept deferred. Calling `fireTokenRevoked` from
the command is not enough: the command runs in its own process, which
mounts no MCP endpoint, so no pier listener receives the event and nothing
reaches the store a running server reads. Closing it needs the command to
publish into pier's store directly (a cross-module seam). 4d7eb9d
documents in the cabana README that only the My account revoke fires the
event.
- RB-IN-04 optional narrowing: a focused widget host also mutes Esc, / and ? (found in the gap-closure re-review)
status: open
**What:** 89b85f5 documents the trade-off in `admin/src/app/hotkeys.ts`.
The optional narrowing to plugin field types (a `data-field-type` marker)
was not made: a `type: widget` element with an input in a closed shadow
root would then let Esc leave the form while the admin types in it.
- OIDC grants on a ban or a password reset (decided during 19.7-08)
status: resolved
**What:** the user decided on 2026-10-23 that a ban, a password reset, an
administrator setting a password and the user's own password change end
both the MCP and the OIDC grants of the user (tokens revoked, consents
and unused codes deleted, subjects kept). Implemented by
`Cascade.OnAccessRevoked` (sm-oauthserver-plugin 671513d) and pinned by
`TestMCPGrantRevocation` ("access revoked ends earlier MCP and OIDC
grants and keeps later ones") and `TestMCPRevocationSmoke`.
- Local sm-oauthserver-plugin go.work retarget (found during 19.7-08 Task 2)
status: open
**What:** the tracked `go.work` of sm-oauthserver-plugin is modified in
the working tree only: its `sm-user-plugin` replace points at
`../sm-demo-app/plugins/golem15/user` (the canonical user checkout of the
gap closure) instead of the committed `../fonoteka.go/plugins/golem15/user`.
The phase gate's workspace check requires exactly that target, so the
gate passes on this machine only with the local edit. Before the release
either restore the committed line or decide whether go.work should leave
version control; never commit the local retarget.
- Demo plugin submodules and pointers wait for the release (found during 19.7-08, updated by 19.7-09)
status: open
**What:** in sm-demo-app the working-tree checkouts of
`plugins/golem15/oauthserver` (671513d, its canonical checkout is at
65f71dc with plan 09's test), `plugins/golem15/journal` (b129902,
canonical at 2aeeccc) and `plugins/golem15/user` (the canonical user
checkout itself, 38551a4) are ahead of their committed pins (v0.1.2,
v0.2.3, v0.1.10) by unreleased commits. The gate reports them as
`pins: … is ahead of its pin by unreleased commits` and refuses them with
`PHASE197_RELEASED=1`. The pointers are committed only after the plugin
tags. sm-demo-app's `vue-demo-app` pointer is committed (00f57bf, then
f53d30a for the link code test): vue-demo-app (0125e29, b973a76) must be
pushed before sm-demo-app.
- Release order after the gap closure (decided 2026-10-23)
status: open
**What:** nothing of plans 06-09 is tagged or pushed. After the re-review
of the gap closure, phase verification, Nyquist validation and UAT pass,
and on the user's go-ahead:
1. framework v0.5.0 (and the changelog post);
2. the sm-user-plugin, sm-oauthserver-plugin and sm-journal-plugin tags
that require it;
3. the bumps in sm-demo-app, fonoteka.go and sm-bm-app, with vue-demo-app
pushed before sm-demo-app;
4. sm-servers-app picks up E-1 and E-2 after the user plugin tag;
5. then `PHASE197_RELEASED=1 bash scripts/check-phase19.7.sh --consumers`
must pass (every demo pin on its tag, no drift).
- `readLinkCode` accepts a valid code next to other fragment parameters (found during 19.7-09 Task 3)
status: resolved (gap-closure re-review: not a defect; vue-demo-app 9c247ab pins the lenient parse)
**What:** plan 09 described "extra parameters give ''" for the link page's
code reader. `readLinkCode` parses the fragment with URLSearchParams, so
`#code=<64 hex>&next=/x` answers the code, while an extended or foreign
value (`#code=<hex>x`, `#other=<hex>`) answers ''. `linkCode.test.ts`
pins the latter and leaves the former unasserted. My account only ever
sends `#code=<code>`, so nothing depends on it; the re-review decides
whether to keep the lenient parse or require the fragment to be exactly
`code=<64 hex>`.
- `docs/examples/blog` test failed once on GOPROXY=off (found during 19.7-09 Task 1)
status: open
**What:** one `go test -short ./...` run of the gate's go stage failed in
`docs/examples/blog` with "module lookup disabled by GOPROXY=off" for
`golang.org/x/exp`; the package passed alone and in more than twenty later
full runs. The test builds a scratch module offline and depends on the
module cache holding every dependency; a run that coincides with a cache
change may miss one. Not caused by this phase's code; watch for a
recurrence.
- RA-IN-04: the cap of the non-reserving store fallback is still check-then-act (found in the gap-closure re-review, deferred by its lane A fixes)
status: open
**What:** 034aa19 makes `serveNew`'s fallback for a store without
`Reserve` write the record before the server is built, so a reaper pass
can no longer close a session that has no record yet. The Count-then-Put
cap of that fallback remains racy. Closing it means making `Reserve` part
of the exported `pier.Store` interface or refusing a store without it at
mount, which changes pier's exported API for a branch only a test wrapper
(`WrapStore`) reaches; both shipped stores reserve atomically.
- RA-WR-06 optional: the demo pin check does not require unreleased commits to be on the canonical checkout's upstream (found in the gap-closure re-review)
status: open
**What:** 2fdda99 qualifies the gate's verdict ("Phase 19.7 gate passed
WITH UNRELEASED PINS: the release pins are not yet proven") while demo
submodules carry unreleased non-test commits; the exit status stays 0 so
the pre-release verification can run. The review's optional
`git branch -r --contains` check was not added: the gap-closure commits
are deliberately unpushed until the release order runs, so it would
refuse every pre-release run. `PHASE197_RELEASED=1` after the tags is
the release proof.
- RC-CR-01 optional: base the session cutoff on `auth_time` (found in the gap-closure re-review, lane C)
status: open
**What:** the self-service password change now revokes every OAuth grant
as of the request (sm-user-plugin 30f7a01). The calling session's own
cutoff is still its `iat` second, so an attacker's frontend session JWT
refreshed after the victim's `iat` survives the change too. That predates
this phase; closing it means basing `tokens_valid_after` on the calling
token's `auth_time` and having `POST /refresh` and the jwt guard compare
`auth_time` with the cutoff, a change to session revocation in a core
plugin (and to how bouncer's refresh is checked) that needs its own
decision.
- RC-IN-01 nginx: keep the deprecated link GET route's code out of access logs (found in the gap-closure re-review, lane C)
status: open
**What:** sm-user-plugin 92676ba makes the show and confirm POSTs ignore
a code in the query string. `GET /_user/api/v1/backend-link/{code}` stays
for compatibility (removed only in a major release), so nginx still logs
the code if a third-party client calls it. `access_log off;` (or a
`log_format` without `$request_uri`) for
`location ~ ^/_user/api/v1/backend-link/` in the demo's nginx config is a
deploy change, made with the next demo deploy; the shipped page never
calls the GET route.
- RC-IN-06: the legacy MintAPIToken fallback is widened before the phrase-key check (found in the gap-closure re-review, lane C)
status: open
**What:** `classes.CompileAPITokenScopes` adds the declared names to the
process-wide fallback set before `bootAPITokenScopes` checks their phrase
keys, so a boot that fails on a missing key has already widened what
`MintAPIToken` accepts. Moving the add after the check needs a new
exported seam or a behaviour change of the exported
`CompileAPITokenScopes` in a core plugin; a failed boot ends the process,
so the widened set is never used in production. `MintAPIToken` is now
marked `Deprecated:` in favour of `MintAPITokenFor` (sm-user-plugin
9892404), which checks the application's own catalog.
- RC-IN-07: sm-oauthserver-plugin builds only through its workspace file (found in the gap-closure re-review, lane C)
status: open (release-time)
**What:** the plugin uses `userclasses.AccessRevokedEvent`,
`FireSubjectEvent` and `FireSubjectEventAfterCommit`, which the required
sm-user-plugin v0.1.10 lacks, so `GOWORK=off go build ./...` fails. The
release checklist for the oauthserver tag must bump `sm-user-plugin` to
the new user plugin tag and pass `GOWORK=off go build ./...` before the
tag; the requires are not bumped before the user plugin is tagged.
- Lane C re-review fixes moved the demo's oauthserver checkout (gap-closure re-review, lane C)
status: open
**What:** pier now gives a backend subject only to a grant that records
its consented administrator (`pact.MCPGrant.BackendUserID`, framework
c37c6ce), so the demo's e2e tests need the oauthserver commits that
record it. The working-tree checkout of sm-demo-app's
`plugins/golem15/oauthserver` was moved from 671513d to the canonical
b6a9586 (detached, fast-forward; the pointer stays uncommitted until the
plugin tag, as before). Canonical heads after the lane C fixes:
sm-user-plugin 9892404, sm-oauthserver-plugin 9813c1d,
sm-journal-plugin 521df9a (its prompt test's fake grants now name the
consented administrator), vue-demo-app 9c247ab. `backend` grants issued before the oauthserver
migration `202610230001` record no administrator and stop acting as one
until the agent is connected again.