# arena-plm — Arena PLM → SAP S/4HANA Integration (standalone)

> This file is a MAP, not a cache. It says where things are and how to verify
> them — it does not store conclusions. Every factual claim in this repo carries
> a verified-on date; an undated claim is a hypothesis, not a fact.

## What this is

Approval-gated sync of Arena PLM items into SAP S/4HANA Public Cloud
(`my429480.s4hana.cloud.sap` productive; development tenant `my431353.s4hana.cloud.sap` since 2026-09-15 — API-only tenants: no RFC, no custom IDocs):
materials, BOMs, change masters, documents. Standalone successor to the Express
implementation at `~/projects/sap-apps/arena-plm`, which is **reference-only**
— consult it for behavior, never extend it.

## Architecture (ADR-002, 2026-09-04 — on-stack first)

The application lives **in the tenant**: a custom RAP business object for the
approval domain, a Fiori Elements app in the tenant's Fiori launchpad, IAM
app / business catalog / business roles as the only access control, and custom
CDS views for discoverability. Side-by-side is reduced to one hardened
TypeScript **connectivity worker** (Arena webhook/poll/session/files + initial
sync executor) — machine-to-machine only, no UI, no user-facing URLs.

The acceptance test: a business user finds the app in the Fiori launchpad and
its data in the Custom CDS Views app. Anything that fails that test is not done.

## Operating rules

1. **Never guess SAP behavior.** Query the MCP servers below first — do not
   first decide whether the question "needs" a lookup; that judgment is the
   thing that fails. If no source confirms it, say "I don't know."
2. **POC before spec.** Field mappings and integration specs are unusable until
   validated by a working POC against real endpoints.
3. **No hand-rolled SAP plumbing.** On-stack: RAP/EML and released ABAP APIs
   only. In the worker: released OData APIs through the established destination
   (`mc-s4hana`) — never hand-managed CSRF or auth.
4. **Mappings live in the tenant.** Evaluate Business Configuration
   maintenance objects before any file-based config (PRD ARN-004).
5. **Read `KNOWLEDGE.md` before designing any SAP write path.** It holds
   paid-for negative results; re-learning them costs hours against live systems.
6. **Cite or it didn't happen.** Every SAP behavioral claim recorded in
   PRD/ADR/KNOWLEDGE carries `[source: <server> <doc-id/URL>, verified
   YYYY-MM-DD]`. Enforcement is structural (ADR-003): hooks inject this charter
   each session, and a consultation gate denies edits to SAP artifacts unless an
   MCP/web consultation happened in the last 30 minutes. (`*.md`, `docs/`, and
   `.claude/` paths are exempt; a denial names the server to consult — consult
   it, then retry the edit.)
7. **API-first (adopted 2026-09-10, PRD ARN-009).** Any interface this package
   creates or changes gets its OpenAPI 3.1 **JSON** contract authored or
   updated under `docs/api/` before or with the change; implementation
   conforms to the contract. Consumed SAP released APIs keep SAP's published
   contracts — `docs/api/` holds only surfaces this package owns.

## MCP routing (this package's loadout — deliberately slim, matched to ADR-002)

| Working on | Server |
|---|---|
| ABAP Cloud / RAP / CDS statement syntax & semantics | `abap-docs` |
| RAP guides, extensibility docs, SAP Help / Community | `sap-docs` |
| Is this SAP object released for ABAP Cloud? Successors? | `sap-released-objects` |
| Fiori Elements, `@UI` annotations, manifest | `fiori-mcp-server` |
| Writing objects INTO the development tenant (create/activate/transport/ATC/unit tests) | `adt-mcp` — SAP ADT MCP Server from `sapse.adt-vscode`, `http://127.0.0.1:2236/mcp`; bearer token lives in `~/.vscode-server/data/Machine/settings.json` and changes on VS Code reload — refresh `.mcp.json` then |
| UI5 controls/views (only if custom UI proves necessary) | `ui5-mcp-server` |

When MCP guidance conflicts with training knowledge, follow MCP.

Live system checks from this box (verified 2026-09-15): the `sap-api` CLI
(`/usr/local/bin/sap-api`) reaches the **development** tenant `my431353` by
default (credentials in `~/projects/sap-integrations/_shared/.env`; the
productive credential is `.env.prod-my429480.bak`) and Arena — API catalog search,
EDMX fetch, OpenAPI generation (`sap-api apis generateOpenapi --service …`),
communication arrangements (`comm`), user/role admin (`users`), and read paths
for the released business APIs and Arena items. Read commands are fair game
for design and acceptance; mutating commands are delegated like any other
write.

## Delegation (project agents in `.claude/agents/`)

Implementation goes to the specialists below; their tool restrictions are the
role contract (the reviewer cannot write, the test agent runs on the low-cost
model). All inherit the ADR-003 hooks automatically. Design record and
verified sources: `docs/agent-roster.md`.

| Work | Agent |
|---|---|
| On-stack ABAP Cloud: RAP BO, CDS, behavior, IAM artifacts | `rap-developer` |
| Fiori Elements app, `@UI` annotations, manifest, launchpad | `fiori-developer` |
| TS connectivity worker: Arena API, Cloud SDK OData writes | `worker-developer` |
| Read-only SAP review: clean core, contracts, tombstones | `sap-code-reviewer` |
| Tests for worker + service layers | `test-engineer` |

## Repo state & commands (verified 2026-09-14)

Implementation so far: the TypeScript connectivity worker in `worker/`
(Fastify surface + Arena session core; sync executors are stubs until V-2).
The on-stack RAP track has no code yet — gated on V-1. The Fiori Elements app
(`app/`, TypeScript) is scaffolded against a **mock** OData V4 service:
`npm run start-mock` serves it on port 8082; its service identity is
provisional until reconciled with the live RAP UI binding at V-2.

In `worker/`: `npm run build` (tsc), `npm run lint` (eslint), `npm test`
(vitest), `npm run dev` (tsx watch). The worker's HTTP surface is governed by
`docs/api/worker.openapi.json` (rule 7) — change the contract first.

## Files

| File | Purpose |
|---|---|
| `PRD.md` | Living requirements, target architecture, contracts, verification items |
| `CHANGELOG.md` | Append-only decision log |
| `KNOWLEDGE.md` | Dated tombstones & landmines — the only knowledge carried from the predecessor; also check it when anything unexpected appears in the repo |
| `docs/adr/` | Architecture decision records (ADR-001 amended by ADR-002) |
| `docs/agent-roster.md` | Specialist-agent design + verified sources |
| `docs/predecessor-flow.md` | How the Express predecessor actually works (extracted 2026-09-10) — read before designing executor, poller, or approval behavior |
| `.claude/hooks/` | ADR-003 enforcement scripts (grounding injections, consult gate, consult marker); `tests/run.sh` pipe-tests them — run it after any hook change |