upload current sources

2026-09-16 01:47:28 -07:00
commit f8b45ea4a5
109 changed files with 26012 additions and 0 deletions
@@ -0,0 +1,187 @@
+# KNOWLEDGE — tombstones & landmines
+
+Carried across the 2026-09-04 knowledge bankruptcy from the working Express
+predecessor. Filter applied: an item was kept only if it (a) cannot be
+re-derived from code or a live query, AND (b) is expensive or harmful to
+re-learn. Everything else was deliberately left behind to be re-derived from
+ground truth. Every entry is dated; re-verify on first POC contact. Add new
+entries the same way — dated and falsifiable.
+
+## SAP S/4HANA (tenant `my429480`, Public Cloud, API-only)
+
+- [2026-09-04, verified by predecessor in live use] **BOM items must be POSTed
+  sequentially** after the header POST. Parallel item POSTs fail SAP's
+  consistency check.
+- [2026-09-04, same] **`AvailabilityCheckType` is not exposed in the Product
+  API V4** — requires the V2 `API_PRODUCT_SRV` fallback for that one field.
+- [2026-09-04, same] **BOM read works only on the v1 service**;
+  `API_BILL_OF_MATERIAL_SRV;v=0002` rejects guid key lookups. Writes go to
+  `;v=0002`.
+- [2026-09-04, same] OData V2 date format is `/Date(ms)/`; the "end of time"
+  value (9999-12-31) is `/Date(253402214400000)/`.
+- [2026-09-04, same] **Idempotency pattern that works: SAP is the ledger.** The
+  Arena ECO number is stamped into `ReasonForChangeText`; no local sync-state
+  database is needed or wanted.
+- [2026-09-10, predecessor code read] **BOM header create must use
+  `EngineeringChangeDocForEdit`** — `EngineeringChangeDocument` is
+  `sap:creatable=false` and silently dropped. ECM BOM items must carry
+  `HeaderChangeDocument` = the header's change number or SAP answers "Input
+  parameters are initial". (arena-plm.js:785-846)
+- [2026-09-10, same] **`A_ChangeMasterObjTypeAssgmt` POST requires
+  `IsActiveForChangeNumber: true`** — without it SAP returns 201 and silently
+  discards the row. (arena-plm.js:914-924)
+- [2026-09-10, same] **ProductDescription updates: PATCH by full key**
+  (`Product=…,Language='EN'`); PATCH via the nav property returns HTTP 501;
+  fall back to POST on 404/405. (arena-plm.js:1411-1414)
+- [2026-09-10, same] `ProcurementType` can only be written together with
+  `MRPType` in the same `ProductPlantSupplyPlanning` PATCH.
+  (arena-plm.js:1623-1640)
+
+## Arena PLM API (`api.arenasolutions.com/v1`)
+
+- [2026-09-04, same] Session auth: `POST /login` → `arenaSessionId`, ~25-minute
+  TTL. Concurrent logins race — serialize login behind a promise lock and
+  re-login automatically on 401.
+- [2026-09-10, predecessor code read] **WORKING-revision overlay is
+  load-bearing**: the seven SAP classification attributes (SAP Product Type,
+  SAP Plant, …) are writable only on the WORKING revision (Arena error 3224),
+  while `/items?number=` resolves the EFFECTIVE revision — merge those
+  attributes from WORKING over EFFECTIVE, and treat overlay failure as fatal
+  (the predecessor's best-effort overlay silently turned valid items into
+  NO_PRODUCT_TYPE errors). (arena-plm.js:508-552)
+- [2026-09-10, same] `/items/{guid}/changes` does not exist (404) — derive the
+  ECO from `/items/{guid}/revisions`, first EFFECTIVE revision with
+  `change.number`. (arena-plm.js:1799-1806)
+- [2026-09-10, same] The `/changes` feed has **no working server-side date
+  filter** — delta detection must filter client-side (the predecessor pages
+  the whole feed, O(history)). The outbound-integration queue
+  (`/outboundintegrations/{guid}/events`, `reconciled` flag as a cursor held
+  by Arena) is the clean delta mechanism. (arena-plm.js:1117-1263)
+
+## Toolchain (worker)
+
+- [2026-09-10, npm registry] **TypeScript `latest` is the 7.x native-compiler
+  major** (no stable 6.x; only `6.0.0-beta`). typescript-eslint 8.70.0
+  declares peer `typescript >=4.8.4 <6.1.0`, silently forcing the 5.9.x line —
+  the worker pins `~5.9.3`. Falsifiable: recheck
+  `npm view typescript-eslint peerDependencies` before any TS bump.
+- [2026-09-10, npm registry] **`@types/node` `latest` dist-tag points at
+  22.x** while 24.x/26.x lines exist — an unpinned install silently targets
+  Node 22 types. Pin the major (`^24`) to match the runtime.
+
+## Landmines
+
+- [2026-09-15] **abapGit is not a prerequisite for SAP's ADT for VS Code.** The
+  `sapse.adt-vscode` extension talks ADT/HTTP to the tenant and ships no git or
+  abapGit commands (extension 1.1.2 `package.json`/readme, verified 2026-09-15).
+  The "abapGit must be set up in the ABAP system" idea comes from the community
+  extension `murbani.vscode-abap-remote-fs` (installed on this host), whose
+  abapGit commands need the open-source `ZABAPGIT` report in the backend — which
+  cannot be installed in a Public Cloud tenant. In ABAP Cloud, abapGit exists
+  only as SAP's supported fork behind the **Eclipse** ADT plug-in
+  (`https://eclipse.abapgit.org/updatesite/`, "abapGit Repositories" view); no
+  VS Code variant exists [source: sap-docs sap-help loio
+  2002380aeda84875a5fae4adc66b3fdb; /btp-cloud-platform/30-development/
+  import-content-from-abapgit-repository-into-the-abap-environment-0b0d894;
+  https://github.com/abapGit/ADT_Frontend, verified 2026-09-15]. It imports
+  released object types only, from an internet-reachable repository (no Cloud
+  Connector), into a chosen package/transport.
+
+- [2026-09-15] **ADT MCP `x-ui-service` generator quirks (my431353, ADT VS
+  Code 1.1.2):** every field needs `semanticType` (else "Builtin type of
+  field is invalid"); it prepends its own `Z` to your prefix and appends
+  `000` even with an empty suffix (`Z` + `ARENA_CHANGE_APPROVAL` →
+  `ZZUI_ARENA_CHANGE_APPRVL000_O4`), names SRVD and SRVB identically, and
+  the schema's `required` lists a non-existent `businessEntity` key — omit
+  it. `get_schema` session ids are single-use. It returns only the SRVB URI;
+  other object URIs follow `abap:/repotree-v1/<dest>/System Library/ZLOCAL/<pkg>/…`
+  with extensions `.tabl.json`, `.ddls.acds`, `.bdef.json`, `.ddlx.acds`,
+  `.dcls.acds`, `.clas.abap`, `.srvd.acds`, `.srvb.json`, `.ront.json`,
+  `.nont.json`. `create_object` for SRVD needs `"sourceType":"S"`; BDEF and
+  SRVB creation validate the referenced object's ACTIVE version, so create
+  and activate DDLS/SRVD sources first. ATC via MCP rejects RONT/NONT.
+
+- [2026-09-15] **Developer business catalogs: `SAP_A4C_BC_*` is the Public
+  Cloud / BTP ABAP family; `SAP_A4_BC_*` is on-premise / Private Cloud.** On
+  `my431353` the developer role carries the A4C catalogs (e.g.
+  `SAP_A4C_BC_DEV_OBJ_DIS_PC`, `SAP_A4C_BC_DEV_UID_PC` [source: sap-docs
+  sap-help loio f4881a9b9141430dba1c6a76e7f456dc, verified 2026-09-15]); the
+  `SAP_A4_BC_DEV_UID_PC` name in the fiori-tools-samples README is the wrong
+  family for this tenant. Split stated by the tenant owner 2026-09-15; no SAP
+  Help page in the loadout spells it out — do not "fix" a role toward A4.
+- [2026-09-15] **Write probes on the dev tenant: `$TMP` and `ZLOCAL` both
+  fail, for different reasons.** `$TMP` is a classic package, so creating
+  there checks the Standard ABAP language version and a cloud-development
+  role is denied with "not authorized to make changes (S_ABPLNGVS)"; `ZLOCAL`
+  is a structure package ("cannot contain development objects"). Objects go
+  in a sub-package of `ZLOCAL` (prototyping, no workbench request for
+  sub-packages created from release 2508) or of `ZCUSTOM_DEVELOPMENT`
+  (transport layer YDEV, importable into test/prod); ZLOCAL→ZCUSTOM
+  reassignment is allowed, the reverse is not; `ZLOCAL` plays the `$TMP` role
+  in Public Cloud [source: sap-docs sap-help loio
+  a0d80f14fcb74cb1ac8fb6f3d9ad48cc (2608), verified 2026-09-15]. Refusals
+  verified live via ADT MCP, 2026-09-15.
+
+- [2026-09-14] `sap-released-objects` has no `DDLS` type for public_cloud;
+  CDS views are catalogued as `CDS_STOB`. A "not found" for `I_PRODUCT` under
+  `DDLS` is a type-key artefact, not a release verdict — query with
+  `object_type=CDS_STOB` (verified 2026-09-14).
+- [2026-09-14] **A Fiori Elements app generated on hand-written mock metadata
+  agrees with itself and hides service-shape mismatches.** ABAP Cloud OData V4
+  services emit `Schema Namespace="com.sap.gateway.<srvd|srvd_a2x>.<service-binding-name>.v0001"
+  Alias="SAP__self"` — the name in the namespace is the **service binding
+  (group)**, which is also the first URL segment; the service definition /
+  alias is the second segment (`/api_currencyexchangerate/srvd_a2x/sap/currencyexchangerate/0001`
+  → `…srvd_a2x.api_currencyexchangerate.v0001`; `/api_product/srvd_a2x/sap/product/0002`
+  [source: sap-docs sap-help loio 5f45f125dfe84c20beb18f5de1512f5a, verified
+  2026-09-14]). Shown for released A2X services; for custom UI (`srvd`)
+  bindings it is strongly indicated, not proven — V-2 confirms. Also, entity types suffixed `_Type`, un-suffixed entity sets,
+  and vocabulary aliases `SAP__common`/`SAP__capabilities`/`SAP__core`
+  [source: live tenant my429480 EDMX `~/projects/sap-apps/exchange-rates-cap/srv/external/API_CURRENCYEXCHANGERATE.edmx`
+  lines 13–31, 55, 57, 95, verified 2026-09-14]. Front-end annotation targets
+  written against any other namespace silently match nothing at runtime (no
+  columns, no filters, no actions). Reconcile every `Annotations Target`, the
+  `edmx:Reference` include namespace, and every `DataFieldForAction.Action`
+  against the live `$metadata` before the first deploy — never trust the mock.
+
+- [2026-09-04] The predecessor's `config/procurement-type.json`,
+  `catalog-to-planning-strategy.json`, and `arena-category-to-sap.json` were
+  loaded but **never read by any code path**, and procurement-type's keys
+  (`MTS`/`OTS`) and values (`E`) do not match the Arena field (`1`–`9` Item
+  Type) or SAP values (`X`) the code actually used. Do not port these configs
+  on trust — re-derive every mapping via POC.
+- [2026-09-04] Deployment/exposure target is an OPEN decision (PRD OQ-3). The
+  old estate fronts apps through a shared `mcl-apps` approuter with shared
+  XSUAA; a CF route mapped to more than one app round-robins and causes ~50%
+  intermittent 404s. Whatever is chosen, audit routes after every push.
+- [2026-09-04] HANA Cloud compute is the dominant cost lever of the old estate;
+  an auto-stop systemd timer (`sap-apps/ops/hana-autostop`) guards it. If this
+  package binds HANA, account for the stop/start cycle in the design.
+- [2026-09-04] The predecessor kept its approval queue in a SQLite file inside
+  the CF droplet — wiped on every restart. Durable persistence is a hard
+  requirement of the rebuild (PRD ARN-003), not an optimization.
+- [2026-09-10] Predecessor BOM and DOCUMENTS syncs are **non-idempotent**
+  (re-approval creates a second MaterialBOM header / duplicate attachments) —
+  the rebuild's executors must check existence first (ARN-006).
+- [2026-09-10] The predecessor uses **two disagreeing change-master lookup
+  keys** (`startswith(ChangeNumberDescription,'ECO:')` in the product link vs
+  `ReasonForChangeText eq 'ARENA <eco>'` everywhere else; the 40-char
+  truncation can split them). The rebuild uses exactly one key.
+- [2026-09-10] Document sync links only Arena files with
+  `storageMethodName === 'WEB'` (URL links, no bytes) — blob-stored files are
+  silently skipped, and the DOKAR mapping config existed but was ignored
+  (`BUS1001006`/`text/url` hardcoded). Decide blob handling explicitly in the
+  rebuild.
+- [2026-09-04] **If `.github/agents/sap-odata-*.agent.md`, a root `AGENTS.md`
+  about "SAP OData Workspace", or `.vscode/mcp.json` pointing at
+  `sap-odata-mcp.exe` appear in this repo — delete them.** They are scaffolded
+  (evidence points to the `harieprasad.sap-odata-mcp` VS Code extension writing
+  its workspace kit on folder open; observed 2026-09-04 14:40, removed same
+  day). The referenced MCP binary is a Windows .exe that cannot run on this
+  host, so those agents fabricate SAP results — the documented failure the
+  founding kit exists to prevent. The root `AGENTS.md` is the dangerous part:
+  Claude Code reads it as project instructions. [Update 2026-09-04 15:32] The
+  suspect extension was uninstalled from all machines (verified: deregistered
+  and marked obsolete on this host; directory purges on next VS Code reload).
+  If the bundle STILL reappears after this, the extension hypothesis was wrong
+  — hunt the real writer instead of re-deleting silently.