rename: tutorials-poc -> tutorials-ims (Tier 2: MTA id + Tier 3: xsappname) — pre-production cutover

[jung-thomas]

Context

The codebase identifies itself as tutorials-poc in three identity domains. Tier 1 (cosmetic / package metadata) was cleaned up in #TBD-PR-FOR-CURRENT-BRANCH — that fixed the "Serving tutorials-poc undefined" message on the CAP welcome page. The remaining two tiers carry real deployment + identity consequences and must be planned + executed as a coordinated cutover, ideally before the PROD cutover end-of-July 2026.

Tier 2 — MTA deployment identity

Files that still say tutorials-poc:

• mta.yaml:2 — ID: tutorials-poc
• .deploy/mta.yaml:2 — ID: tutorials-poc
• .deploy/DEPLOY.md — references to mta_archives/tutorials-poc_1.0.0.mtar
• .github/workflows/deploy.yml:385,393,606 — cf deploy mta_archives/tutorials-poc_*.mtar, cf mta-ops | grep tutorials-poc, MTAR_FILE=...
• docs/developers/operations/{mta-deployment,deployment,production-ready,qa-channel-bootstrap,github-dispatch-pat-rotation}.md — tutorials-poc_1.0.0.mtar filename references + ID: tutorials-poc-prod / extends: tutorials-poc
• docs/developers/getting-started.md:163 — same
• docs/developers/architecture/build.md:51 — mermaid diagram label

Consequence

The MTA ID is the identity key Cloud Foundry uses to track a deployment. If we change the ID to tutorials-ims and run cf deploy mta_archives/tutorials-ims_1.0.0.mtar:

• CF treats it as a NEW MTA, not an update.
• The existing tutorials-poc MTA is NOT automatically replaced — it stays running alongside.
• All service instances bound to the old MTA (HANA HDI containers, XSUAA, Destination Service, credstore, Application Logs, AI Core) get recreated under the new MTA → HANA schema teardown, fresh HDI deploy.
• Data loss risk if HDI tries to drop schemas during the side-by-side window.

Cutover procedure (DEV first, then PROD)

1. Schedule a downtime window.
2. Snapshot HANA schemas (DEV → backup HDI container, PROD → MDC backup).
3. cf undeploy tutorials-poc --delete-services --delete-service-keys --delete-service-brokers on the target space.
4. Update mta.yaml, .deploy/mta.yaml, all docs, .github/workflows/deploy.yml in one PR.
5. mbt build && cf deploy mta_archives/tutorials-ims_1.0.0.mtar -e ../deploy/<env>.mtaext -f.
6. Restore HANA data from snapshot if HDI did a destructive deploy.
7. Smoke test full path: approuter → CAP → HANA → content serve → admin UI → display dashboard → scanner → analytics.

Estimate

DEV cutover: ~1 hour wall-clock (most of it the HDI redeploy + content republish).
PROD cutover: include in the AEM→IMS PROD cutover plan for end-of-July 2026.

Tier 3 — XSUAA application identity (xsappname)

Files that still say tutorials-poc:

• xs-security.json:2 — "xsappname": "tutorials-poc"
• .deploy/xs-security.json:2 — "xsappname": "tutorials-poc"
• docs/developers/architecture/authentication.md:63 — example scope literal tutorials-poc.DeveloperApp, tutorials-poc.Everyone

Consequence

xsappname is the prefix on every XSUAA scope issued to JWT tokens. So tutorials-poc.Admin, tutorials-poc.Tutorial.Author, tutorials-poc.DisplayApp, tutorials-poc.DeveloperApp, tutorials-poc.Everyone — every scope name carries it.

If we change xsappname to tutorials-ims:

• Every BTP role-collection assignment must be re-bound. The current tutorial-system subaccount has assignments riding on tutorials-poc.* scopes. They will not auto-transfer.
• In-flight JWTs continue to assert old-prefix scopes until users log out + log back in. Users will see 403s until they refresh.
• Every @requires literal in CDS that names a scope must be updated in lockstep (search srv/ for 'tutorials-poc.').
• Admin UI tile / button visibility that gates on scope name will misbehave during the transition.

Cutover procedure

Must be done as part of Tier 2 cutover (same downtime window — cf undeploy tutorials-poc recreates the XSUAA service instance anyway):

1. Pre-stage role-collection updates: every collection currently bound to tutorials-poc.* scopes needs a parallel binding to the same scope name with the new prefix. Script: scripts/migrate-btp-roles.js (already exists for the subaccount migration — extend for prefix migration).
2. Update both xs-security.json files + every @requires literal in srv/.
3. After Tier 2 redeploy, run the role-collection rebind script.
4. Force-logout all users (set token TTL to 0 momentarily, or wait for current TTL to expire — default 12h).
5. Document the change in docs/developers/architecture/authentication.md.

Estimate

Same downtime window as Tier 2. Add ~30 min for role-collection rebinding + ~1 day of user re-login lag.

Out-of-scope items still on tutorials-poc

These are correct as long as Tier 2/3 are not yet done — don't touch in isolation:

• TUTORIALS_POC_DISPATCH_TOKEN secret name in every *-Contribution GitHub repo (rotation must be coordinated; tracked separately in docs/developers/operations/qa-channel-bootstrap.md).
• Local filesystem path d:/projects/tutorials-poc/... in scripts/git-hooks/pre-commit, docs/developers/operations/agent-isolation-hooks.md, docs/developers/operations/mta-deployment.md — this is the actual on-disk folder name on Tom's machine. Folder rename is a separate physical operation; covered in CLAUDE.md memory project_folder_vs_repo_name already.
• docs/superpowers/ historical specs + plans — intentionally preserved as point-in-time records of how decisions were made.

Done when

• mta.yaml, .deploy/mta.yaml, all docs, .github/workflows/deploy.yml updated in lockstep.
• Both xs-security.json files updated.
• All srv/**/*.cds @requires literals migrated.
• scripts/migrate-btp-roles.js extended (or new script written) to remap collection bindings.
• DEV cutover executed + verified (full smoke).
• PROD cutover scheduled into the AEM→IMS end-of-July 2026 plan.
• CLAUDE.md project_folder_vs_repo_name memory updated to note that local folder rename is the last remaining gap.

Related

• Tier 1 PR: TBD (this branch — package.json + comment + User-Agent string + repo-name bug fix in notify-qa.yml.template)
• CLAUDE.md memory: project_btp_subaccount_migration, project_prod_cutover_july_2026, project_folder_vs_repo_name

[jung-thomas]

Investigation update — DEV cutover plan refined

Investigated the DEV deployment state before drafting the change. The original runbook above is over-cautious for this codebase — the cf undeploy tutorials-poc --delete-services + HANA-snapshot-and-restore path is not required, because every resource in .deploy/mta.yaml:211-289 declares an explicit service-name: (verified). That decouples Cloud Foundry's service-instance identity from the MTA's identity: renaming the MTA ID: lets the deployer adopt the existing tutorials-hana, tutorials-xsuaa, tutorials-credstore, etc. instances rather than recreate them.

PR #754 implements the rename. Highlights vs the original spec above:

What's still true

• Both files renamed: mta.yaml//.deploy/mta.yaml (ID:) and xs-security.json/.deploy/xs-security.json (xsappname).
• .github/workflows/deploy.yml, docs, mermaid diagrams updated in lockstep.
• New scripts/inventory-role-collections.cjs captures pre-flight state; new scripts/migrate-role-collections.cjs verifies/restores post-deploy.
• Out-of-scope items (folder rename, TUTORIALS_POC_DISPATCH_TOKEN secret name, docs/superpowers/ historical specs) explicitly left alone.

What changed vs the spec above

Spec said	Reality on this codebase
cf undeploy --delete-services then full HDI redeploy	Not needed. service-name: is explicit on every resource — adoption is automatic.
HANA schema teardown / data loss risk / restore from snapshot	No data loss. HDI containers adopted; CDS artifact refresh is the normal incremental path.
"Every @requires literal in CDS must be updated in lockstep"	Verified: zero tutorials-poc. literals in srv/**/*.cds. CAP uses bare scope names (@requires: 'Admin') and resolves against $XSAPPNAME at runtime. No source changes needed there.
"Pre-stage role-collection updates" / extend migrate-btp-roles.js for prefix migration	Inline Tutorials * collections in xs-security.json are recreated by cf update-service tutorials-xsuaa -c xs-security.json automatically. User assignments at SUBACCOUNT level survive the recreate (they bind by collection name, not template ref). Verification step still ships in the new script as a safety net; restore is fallback-only.

What's still risky

• Stale JWTs: in-flight tokens issued under tutorials-poc!t<n> continue asserting old-prefix scopes until 12 h TTL. Optional "Reset Client Secret" in cockpit shortens the tail.
• Cutover window: ~5-10 min during the XSUAA descriptor update + app repush where protected routes may 403.

Plan for tonight (DEV)

After PR #754 merges to main, from primary worktree on main:

1. node scripts/inventory-role-collections.cjs --subaccount tutorial-system --out .migration-data/role-collections-pre-rename.json
2. npm run build:all && cd .deploy && mbt build && cf deploy mta_archives/tutorials-ims_1.0.0.mtar -e ../deploy/dev.mtaext -f
3. node scripts/migrate-role-collections.cjs --inventory .migration-data/role-collections-pre-rename.json --verify
4. Optional: cockpit → Security → OAuth → Reset Client Secret on tutorials-xsuaa
5. cf purge-mta tutorials-poc to drop the legacy MTA registration

Full runbook (with rollback) in docs/developers/operations/mta-deployment.md §Rename cutover.

PROD cutover

Same procedure, scheduled into the end-of-July 2026 AEM→IMS PROD window. The cf mta-ops grep at deploy.yml:401 was widened to match both names during the rename cutover; narrow it back to tutorials-ims only after PROD cuts over.