arc-1 0.9.4 → 0.9.6

package/dist/handlers/intent.js

@@ -37,6 +37,7 @@ import { detectFilename, lintAbapSource, lintAndFix, validateBeforeWrite } from
 import { sanitizeArgs } from '../server/audit.js';
 import { generateRequestId, requestContext } from '../server/context.js';
 import { logger } from '../server/logger.js';
+import { resolveRateLimitUserKey } from '../server/mcp-rate-limit.js';
 import { expandHyperfocusedArgs } from './hyperfocused.js';
 import { getToolSchema } from './schemas.js';
 import { formatZodError } from './zod-errors.js';
@@ -225,7 +226,7 @@ function buildBaseErrorMessage(err, message, tool, args, config) {
     if (err instanceof AdtApiError) {
         // Append additional SAP messages (line numbers, secondary errors) if available
         const enriched = enrichWithSapDetails(err, message);
-        const argType = String(args.type ?? '').toUpperCase();
+        const argType = canonicalTablType(String(args.type ?? '').toUpperCase());
         const classification = classifySapDomainError(err.statusCode, err.responseBody, err.path);
         if (classification) {
             const transactionLine = classification.transaction ? `\nSAP Transaction: ${classification.transaction}` : '';
@@ -295,7 +296,7 @@ function buildBaseErrorMessage(err, message, tool, args, config) {
         return enriched;
     }
     if (err instanceof AdtSafetyError) {
-        const argType = String(args.type ?? '').toUpperCase();
+        const argType = canonicalTablType(String(args.type ?? '').toUpperCase());
         if (tool === 'SAPRead' && argType === 'TABLE_CONTENTS') {
             return (`${message}\n\nHint: TABLE_CONTENTS is blocked by safety configuration or missing data scope. ` +
                 'Set SAP_ALLOW_DATA_PREVIEW=true at the server level and, in authenticated HTTP mode, ' +
@@ -658,7 +659,7 @@ async function inactiveSyntaxDiagnostic(client, type, name) {
     }
 }
 async function tryPostSaveSyntaxCheck(client, type, name) {
-    if (!DDIC_POST_SAVE_CHECK_TYPES.has(type.toUpperCase()))
+    if (!DDIC_POST_SAVE_CHECK_TYPES.has(canonicalTablType(type.toUpperCase())))
         return '';
     return inactiveSyntaxDiagnostic(client, type, name);
 }
@@ -746,7 +747,7 @@ function classifyError(err) {
  *   all tools are allowed (backward compatibility).
  * @param server - MCP Server instance for elicitation support.
  */
-export async function handleToolCall(client, config, toolName, args, authInfo, _server, cachingLayer, isPerUserClient) {
+export async function handleToolCall(client, config, toolName, args, authInfo, _server, cachingLayer, isPerUserClient, mcpRateLimiter) {
     const reqId = generateRequestId();
     const start = Date.now();
     // Build user context for audit logging
@@ -763,17 +764,70 @@ export async function handleToolCall(client, config, toolName, args, authInfo, _
         tool: toolName,
         args: sanitizeArgs(args),
     });
+    // ─── Layer 2: per-user MCP tool-call rate limit ─────────────────────
+    // Applied immediately so we don't waste any work on denied calls. Stdio mode
+    // (no authInfo) is exempt — there's no user identity to key on. On denial we
+    // return an MCP tool error (not HTTP 429) so the LLM client surfaces it as a
+    // tool failure and the agent loop backs off via its own retry policy.
+    // See docs_page/rate-limiting.md (Layer 2). Cost weighting per tool is deferred
+    // to v2 — every consume call counts as one point.
+    if (mcpRateLimiter && authInfo) {
+        // Walks the most-specific identity claim first (userName → email → sub →
+        // preferred_username → clientId) so OIDC users sharing one `azp` clientId
+        // don't collapse into a single bucket. See resolveRateLimitUserKey.
+        const userKey = resolveRateLimitUserKey(authInfo);
+        const decision = await mcpRateLimiter.consume(userKey, toolName);
+        if (!decision.allowed) {
+            const retryAfter = Math.ceil(decision.retryAfterMs / 1000);
+            logger.emitAudit({
+                timestamp: new Date().toISOString(),
+                level: 'warn',
+                event: 'mcp_rate_limited',
+                requestId: reqId,
+                clientId,
+                user: userKey,
+                tool: toolName,
+                limitPerMinute: decision.limitPerMinute,
+                retryAfterMs: decision.retryAfterMs,
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: 'rate_limited',
+                            retryAfter,
+                            message: `Rate limit exceeded (${decision.limitPerMinute}/min per user). Retry after ${retryAfter} seconds.`,
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
     // Unified scope enforcement via ACTION_POLICY — routes through action/type-aware lookup.
     // For SAPRead, the policy key is Tool.{type}; for other action-bearing tools, Tool.{action};
     // for tools without an action/type enum (SAPSearch, SAPQuery), the tool-level default applies.
+    // For SAPSearch.tadir_lookup with source='db'|'both', synthesize a sub-action key so the
+    // sql-scoped policy entry kicks in (otherwise viewer-only profiles could piggyback on the
+    // ADT info-system route to issue freestyle SQL).
     // Runs BEFORE Zod validation so scope errors don't leak schema details to unauthorized callers.
-    const actionOrType = toolName === 'SAPRead'
+    let actionOrType = toolName === 'SAPRead'
         ? typeof args.type === 'string'
             ? args.type
             : undefined
         : typeof args.action === 'string'
             ? args.action
             : undefined;
+    if (toolName === 'SAPSearch' &&
+        typeof args.searchType === 'string' &&
+        args.searchType === 'tadir_lookup' &&
+        typeof args.source === 'string') {
+        const src = args.source.toLowerCase();
+        if (src === 'db' || src === 'both') {
+            actionOrType = `tadir_lookup_${src}`;
+        }
+    }
     const policy = getActionPolicy(toolName, actionOrType);
     if (authInfo && policy) {
         if (!hasRequiredScope(authInfo, policy.scope)) {
@@ -933,6 +987,28 @@ export async function handleToolCall(client, config, toolName, args, authInfo, _
 function isBtpSystem() {
     return cachedFeatures?.systemType === 'btp';
 }
+/** Return whether the SAP ADT discovery feed advertises the /sap/bc/adt/ddic/tables
+ *  collection (the transparent-table editor endpoint). Absent on NW 7.50/7.51 —
+ *  SAP added it in NW 7.52 along with the new database-table editor. When the
+ *  discovery cache is empty (e.g. probe never ran, tests that bypass SAPManage),
+ *  returns `undefined` so callers can decide whether to default-allow.
+ *  See issue #285. */
+function isTablesEndpointAvailable() {
+    const map = cachedFeatures?.discoveryMap ?? cachedDiscovery;
+    if (!map || map.size === 0)
+        return undefined;
+    return map.has('/sap/bc/adt/ddic/tables');
+}
+/** Stable hint surfaced when ARC-1 refuses a TABL/DT write because the connected
+ *  system does not expose /sap/bc/adt/ddic/tables/. Shared between the
+ *  resolver-driven update/delete/activate paths and the discovery-gated create
+ *  paths so the LLM always sees the same recovery instructions. */
+const TABL_DT_WRITE_UNAVAILABLE_HINT = 'Transparent table writes via ADT REST are not available on this system ' +
+    '(/sap/bc/adt/ddic/tables/ is not exposed — NW 7.50/7.51 ship the DDIC ' +
+    'structures endpoint only; the table editor was added in NW 7.52). ' +
+    'Use SE11 in SAPGUI, or connect ARC-1 to an SAP_BASIS ≥ 7.52 system. ' +
+    'Writing the source via /sap/bc/adt/ddic/structures/ would silently flip ' +
+    'DD02L-TABCLASS to INTTAB and corrupt the table.';
 /** BTP-specific error messages for unavailable operations */
 const BTP_HINTS = {
     PROG: 'Executable programs (reports) are not available on BTP ABAP Environment. Use CLAS with IF_OO_ADT_CLASSRUN for console applications.',
@@ -1425,16 +1501,92 @@ async function handleSAPSearch(client, args) {
             return errorResult('SAPSearch(searchType="tadir_lookup") requires names[] or query with at least one name.');
         }
         const objectTypes = extractLookupObjectTypes(args.objectType, args.objectTypes);
-        const lookups = await client.lookupObjects(names, { maxResults, objectTypes });
-        const missing = lookups.filter((l) => !l.found).map((l) => l.name);
-        const matchCount = lookups.reduce((count, lookup) => count + lookup.matches.length, 0);
+        const rawSource = typeof args.source === 'string' ? args.source.toLowerCase() : 'adt';
+        const source = rawSource === 'db' || rawSource === 'both' ? rawSource : 'adt';
+        // Stamp each match with provenance so a merged 'both' result is unambiguous and
+        // viewer tooling can colour-code ghost rows. The DB path already stamps `_origin:'db'`
+        // (see `lookupObjectsViaDb`); we stamp ADT matches here.
+        const tagOrigin = (lookups, origin) => lookups.map((l) => ({
+            ...l,
+            matches: l.matches.map((m) => ({ ...m, _origin: m._origin ?? origin })),
+        }));
+        let finalLookups;
         const wildcardNames = names.filter((name) => name.includes('*'));
-        const warnings = wildcardNames.length > 0
-            ? [
-                `tadir_lookup performs exact-name lookup; wildcard characters are treated literally for: ${wildcardNames.join(', ')}`,
-            ]
-            : undefined;
-        return textResult(JSON.stringify({ count: matchCount, lookups, missing, ...(warnings ? { warnings } : {}) }, null, 2));
+        const warnings = [];
+        let splitBrain = [];
+        if (source === 'adt') {
+            finalLookups = tagOrigin(await client.lookupObjects(names, { maxResults, objectTypes }), 'adt');
+        }
+        else if (source === 'db') {
+            // The 'db' path bypasses ADT info-system entirely; `lookupObjectsViaDb` already
+            // tags matches with `_origin:'db'`. Safety/scope gating runs at handleToolCall
+            // and in client.runQuery (FreeSQL operation), so unauthorized callers never reach here.
+            finalLookups = await client.lookupObjectsViaDb(names, { maxResults, objectTypes });
+        }
+        else {
+            // 'both' — parallel ADT + DB, merge per name with dedupe.
+            const [adtLookups, dbLookups] = await Promise.all([
+                client.lookupObjects(names, { maxResults, objectTypes }).then((r) => tagOrigin(r, 'adt')),
+                client.lookupObjectsViaDb(names, { maxResults, objectTypes }),
+            ]);
+            const dbByName = new Map(dbLookups.map((l) => [l.name.toUpperCase(), l]));
+            const adtByName = new Map(adtLookups.map((l) => [l.name.toUpperCase(), l]));
+            finalLookups = names.map((rawName) => {
+                const upper = rawName.toUpperCase();
+                const adt = adtByName.get(upper);
+                const db = dbByName.get(upper);
+                const adtMatches = adt?.matches ?? [];
+                const dbMatches = db?.matches ?? [];
+                // Dedupe by (baseObjectType, objectName) — TADIR stores bare types ('DDLS')
+                // while ADT info-system returns slash-form ('DDLS/DF'). Stripping the suffix
+                // keeps the same logical object from appearing twice in the merged matches.
+                // Preserve the more-specific slash form when both originate from ADT+DB.
+                const seen = new Map();
+                const baseKey = (m) => `${(m.objectType.split('/')[0] || m.objectType).toUpperCase()}${m.objectName.toUpperCase()}`;
+                for (const m of adtMatches)
+                    seen.set(baseKey(m), m);
+                for (const m of dbMatches) {
+                    const k = baseKey(m);
+                    if (!seen.has(k))
+                        seen.set(k, m);
+                }
+                const mergedMatches = [...seen.values()];
+                // Split-brain detection: an object is divergent if exactly one source has matches.
+                // (Zero matches on both sides = consistent absence; matches on both = consistent presence.)
+                if (adtMatches.length > 0 !== dbMatches.length > 0) {
+                    splitBrain.push(rawName);
+                }
+                return { name: rawName, found: mergedMatches.length > 0, matches: mergedMatches };
+            });
+            // Compose human-friendly warnings per split-brain name. Keep them grounded in
+            // the most common cause (TADIR ghost from aborted create/delete) so LLM clients
+            // can suggest the right cleanup path without inventing a new pointer.
+            for (const name of splitBrain) {
+                const adt = adtByName.get(name.toUpperCase());
+                const db = dbByName.get(name.toUpperCase());
+                const adtHas = (adt?.matches.length ?? 0) > 0;
+                const dbHas = (db?.matches.length ?? 0) > 0;
+                if (dbHas && !adtHas) {
+                    warnings.push(`${name} exists in TADIR (DB) but ADT cannot resolve it — likely a TADIR ghost from an aborted create/delete cycle. Consider RS_DD_TADIR_CLEANUP or manual SE03 cleanup.`);
+                }
+                else if (adtHas && !dbHas) {
+                    warnings.push(`${name} resolves via ADT but is not present in the TADIR row scan — likely a release-time mismatch or a type filter excluding the row. Re-run with broader objectTypes or no filter to confirm.`);
+                }
+            }
+        }
+        // Dedupe split-brain names (defensive; merge loop should already avoid duplicates).
+        splitBrain = [...new Set(splitBrain)];
+        if (wildcardNames.length > 0) {
+            warnings.push(`tadir_lookup performs exact-name lookup; wildcard characters are treated literally for: ${wildcardNames.join(', ')}`);
+        }
+        const missing = finalLookups.filter((l) => !l.found).map((l) => l.name);
+        const matchCount = finalLookups.reduce((count, lookup) => count + lookup.matches.length, 0);
+        const payload = { count: matchCount, lookups: finalLookups, missing };
+        if (splitBrain.length > 0)
+            payload.splitBrain = splitBrain;
+        if (warnings.length > 0)
+            payload.warnings = warnings;
+        return textResult(JSON.stringify(payload, null, 2));
     }
     if (searchType === 'source_code') {
         // Source code search: do NOT transliterate — source can contain umlauts in strings/comments
@@ -2165,18 +2317,24 @@ export function buildCreateXml(type, name, pkg, description, properties) {
   <adtcore:packageRef adtcore:name="${escapeXml(pkg)}"/>
 </dcl:dclSource>`;
         case 'TABL':
-            // TABL creation also uses SAP's "blue" framework envelope, then source is written via /source/main.
+        case 'TABL/DT':
+        case 'TABL/DS': {
+            // Bare TABL is the legacy alias for TABL/DT (transparent table). The same
+            // <blue:blueSource> envelope works for both subtypes — only adtcore:type
+            // and the POST URL differ. See docs/plans/completed/fix-tabl-ds-create-routing.md.
+            const adtType = type === 'TABL/DS' ? 'TABL/DS' : 'TABL/DT';
             return `<?xml version="1.0" encoding="UTF-8"?>
 <blue:blueSource xmlns:blue="http://www.sap.com/wbobj/blue"
                  xmlns:adtcore="http://www.sap.com/adt/core"
                  adtcore:description="${escapeXml(description)}"
                  adtcore:name="${escapeXml(name)}"
-                 adtcore:type="TABL/DT"
+                 adtcore:type="${adtType}"
                  adtcore:masterLanguage="EN"
                  adtcore:masterSystem="H00"
                  adtcore:responsible="DEVELOPER">
   <adtcore:packageRef adtcore:name="${escapeXml(pkg)}"/>
 </blue:blueSource>`;
+        }
         case 'BDEF':
             // BDEF uses SAP's "blue" framework — blue:blueSource with http://www.sap.com/wbobj/blue namespace.
             // Confirmed by vibing-steampunk (Go) and fr0ster (TypeScript) reference implementations.
@@ -2481,6 +2639,37 @@ export function normalizeObjectType(type) {
         return '';
     return SLASH_TYPE_MAP[normalized] ?? normalized;
 }
+/** TABL subtypes that SAPWrite preserves (instead of collapsing to bare 'TABL' via
+ *  SLASH_TYPE_MAP) so the create path can route TABL/DT → /ddic/tables and
+ *  TABL/DS → /ddic/structures. See docs/plans/completed/fix-tabl-ds-create-routing.md. */
+const TABL_WRITE_SUBTYPES = new Set(['TABL/DT', 'TABL/DS']);
+/** Legacy slash-form aliases SAPWrite remaps to a canonical subtype before
+ *  SLASH_TYPE_MAP runs — otherwise STRU/DS would collapse to bare 'TABL' and
+ *  route the structure create to /ddic/tables. */
+const SAPWRITE_TABL_ALIAS = {
+    'STRU/DS': 'TABL/DS',
+};
+/** SAPWrite-only normalizer: preserves TABL/DT and TABL/DS and remaps STRU/DS
+ *  to TABL/DS. Every other tool keeps the global collapsing behaviour of
+ *  `normalizeObjectType`. */
+function normalizeWriteObjectType(type) {
+    const normalized = String(type).trim().toUpperCase();
+    if (!normalized)
+        return '';
+    const aliased = SAPWRITE_TABL_ALIAS[normalized];
+    if (aliased)
+        return aliased;
+    if (TABL_WRITE_SUBTYPES.has(normalized))
+        return normalized;
+    return SLASH_TYPE_MAP[normalized] ?? normalized;
+}
+/** Collapse TABL/DT and TABL/DS back to bare 'TABL' for downstream Set-membership
+ *  checks (DDIC hints, RAP preflight, CDS dependency hints, cache invalidation)
+ *  that only know about canonical types. The slash form survives at URL routing
+ *  + XML envelope sites. */
+function canonicalTablType(type) {
+    return type === 'TABL/DT' || type === 'TABL/DS' ? 'TABL' : type;
+}
 /** Normalize type fields before schema validation so slash/case aliases are accepted. */
 function normalizeTypeArgsForValidation(toolName, args) {
     switch (toolName) {
@@ -2491,14 +2680,15 @@ function normalizeTypeArgsForValidation(toolName, args) {
                 objectType: args.objectType === undefined ? undefined : normalizeObjectType(String(args.objectType ?? '')),
             };
         case 'SAPWrite':
+            // SAPWrite preserves TABL/DT and TABL/DS so the create path can route by subtype.
             return {
                 ...args,
-                type: args.type === undefined ? undefined : normalizeObjectType(String(args.type ?? '')),
+                type: args.type === undefined ? undefined : normalizeWriteObjectType(String(args.type ?? '')),
                 objects: Array.isArray(args.objects)
                     ? args.objects.map((obj) => typeof obj === 'object' && obj !== null
                         ? {
                             ...obj,
-                            type: normalizeObjectType(String(obj.type ?? '')),
+                            type: normalizeWriteObjectType(String(obj.type ?? '')),
                         }
                         : obj)
                     : args.objects,
@@ -2600,10 +2790,13 @@ export function objectBasePath(type) {
         case 'SRVB':
             return '/sap/bc/adt/businessservices/bindings/';
         case 'TABL':
-            // Default URL prefix for TABL: /tables/ (transparent tables). DDIC structures
-            // live at /sap/bc/adt/ddic/structures/<name>; for those, callers must use
-            // AdtClient.resolveTablObjectUrl(name) which falls back on 404.
+        case 'TABL/DT':
+            // Bare TABL defaults to transparent table. For reads, callers should use
+            // AdtClient.resolveTablObjectUrl(name) which falls back to /structures/ on 404.
             return '/sap/bc/adt/ddic/tables/';
+        case 'TABL/DS':
+            // DDIC structures only route through this collection; see follow-up to #285.
+            return '/sap/bc/adt/ddic/structures/';
         case 'DOMA':
             return '/sap/bc/adt/ddic/domains/';
         case 'DTEL':
@@ -2733,7 +2926,7 @@ function stripIncludeHeader(source) {
 // ─── SAPWrite Handler ────────────────────────────────────────────────
 async function handleSAPWrite(client, args, config, cachingLayer) {
     const action = String(args.action ?? '');
-    const type = normalizeObjectType(String(args.type ?? ''));
+    const type = normalizeWriteObjectType(String(args.type ?? ''));
     const name = String(args.name ?? '');
     const source = String(args.source ?? '');
     const hasSource = typeof args.source === 'string';
@@ -2772,8 +2965,22 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
     // `buildCreateXml('FUNC', …, properties)` finds it.
     let objectUrl;
     let srcUrl;
-    if (type === 'TABL' && action !== 'create' && action !== 'batch_create') {
-        objectUrl = await client.resolveTablObjectUrl(name);
+    if ((type === 'TABL' || type === 'TABL/DT' || type === 'TABL/DS') &&
+        action !== 'create' &&
+        action !== 'batch_create') {
+        // All TABL forms route through the search-first resolver on update/delete/activate
+        // so the PR #286 SE11-hint refusal applies even when callers pass an explicit slash form.
+        try {
+            objectUrl = await client.resolveTablObjectUrlForWrite(name, {
+                tablesEndpointAvailable: isTablesEndpointAvailable(),
+            });
+        }
+        catch (resolveErr) {
+            if (resolveErr instanceof AdtSafetyError) {
+                return errorResult(resolveErr.message);
+            }
+            throw resolveErr;
+        }
         srcUrl = `${objectUrl}/source/main`;
     }
     else if (type === 'FUNC') {
@@ -2798,11 +3005,20 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
         args.group = group;
     }
     else {
+        // Discovery gate: refuse transparent-table creates upfront on systems that
+        // don't expose /ddic/tables/ (NW 7.50/7.51). TABL/DS skips this — /structures/
+        // is always available. See issue #285.
+        if ((type === 'TABL' || type === 'TABL/DT') && (action === 'create' || action === 'batch_create')) {
+            if (isTablesEndpointAvailable() === false) {
+                return errorResult(TABL_DT_WRITE_UNAVAILABLE_HINT);
+            }
+        }
         objectUrl = objectUrlForType(type, name);
         srcUrl = sourceUrlForType(type, name);
     }
     const invalidateWrittenObject = (objType = type, objName = name) => {
-        cachingLayer?.invalidate(objType, objName, 'all');
+        // Source cache is keyed by canonical type (SAPRead collapses TABL/DT, TABL/DS).
+        cachingLayer?.invalidate(canonicalTablType(objType), objName, 'all');
         cachingLayer?.inactiveLists.invalidate(client.username);
     };
     // Helper: enforce allowedPackages for existing objects (update/delete/edit_method/scaffold_rap_handlers).
@@ -3047,7 +3263,7 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
             // 'application/*' — the wildcard lets the SAP server resolve the correct
             // handler (matching how ADT Eclipse and abap-adt-api send requests).
             const contentType = createContentTypeForType(type);
-            const needsPackageParam = type === 'BDEF' || type === 'TABL';
+            const needsPackageParam = type === 'BDEF' || type === 'TABL' || type === 'TABL/DT' || type === 'TABL/DS';
             let result;
             try {
                 result = await createObject(client.http, client.safety, createUrl, body, contentType, effectiveTransport, needsPackageParam ? pkg : undefined, cachedFeatures?.abapRelease);
@@ -3493,7 +3709,9 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                 });
             }
             catch (err) {
-                if (err instanceof AdtApiError && CDS_DEPENDENCY_SENSITIVE_TYPES.has(type) && isDeleteDependencyError(err)) {
+                if (err instanceof AdtApiError &&
+                    CDS_DEPENDENCY_SENSITIVE_TYPES.has(canonicalTablType(type)) &&
+                    isDeleteDependencyError(err)) {
                     const hint = await buildCdsDeleteDependencyHint(client, type, name, objectUrl);
                     if (hint) {
                         // Attach via extraHint so the LLM-facing formatter renders it after
@@ -3513,9 +3731,14 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
             if (!objects || !Array.isArray(objects) || objects.length === 0) {
                 return errorResult('"objects" array is required and must be non-empty for batch_create action.');
             }
+            // Opt-in deferred-activation: writes every object as an inactive draft first,
+            // then issues a single terminal activateBatch over the written subset. Use case:
+            // composition-linked DDLS / interdependent RAP graphs where per-object inline
+            // activate() can't resolve cross-references to not-yet-active siblings.
+            const activateAtEnd = args.activateAtEnd === true || String(args.activateAtEnd) === 'true';
             const defaultPackage = normalizePackageOverride(args.package, '$TMP');
             const batchPlan = objects.map((obj) => {
-                const objType = normalizeObjectType(String(obj.type ?? ''));
+                const objType = normalizeWriteObjectType(String(obj.type ?? ''));
                 const objName = String(obj.name ?? '');
                 const objPackage = normalizePackageOverride(obj.package, defaultPackage);
                 const explicitTransport = normalizeTransportOverride(obj.transport) ?? transport;
@@ -3574,6 +3797,9 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
             // guard fires for every MSAG entry, but a batch typically shares one transport — cache
             // the lookup result to avoid one HTTP roundtrip per object.
             const transportLookupCache = new Map();
+            // Accumulated objects whose create + source-write phase succeeded — used by the
+            // terminal activateBatch when activateAtEnd=true. Order matches the input order.
+            const writtenObjects = [];
             for (const plan of batchPlan) {
                 const { obj, type: objType, name: objName, packageName: objPackage } = plan;
                 const objTransport = plan.explicitTransport ?? autoTransportByPackage.get(objPackage);
@@ -3653,13 +3879,24 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                             break;
                         }
                     }
-                    // Step 1: Create the object
+                    // Step 1: Create the object (per-entry transparent-table discovery gate;
+                    // mirrors the single-create site above. TABL/DS skips it — /structures/ always exists.)
+                    if ((objType === 'TABL' || objType === 'TABL/DT') && isTablesEndpointAvailable() === false) {
+                        results.push({
+                            type: objType,
+                            name: objName,
+                            packageName: objPackage,
+                            status: 'failed',
+                            error: TABL_DT_WRITE_UNAVAILABLE_HINT,
+                        });
+                        break;
+                    }
                     const objUrl = objectUrlForType(objType, objName);
                     const createUrl = objUrl.replace(/\/[^/]+$/, '');
                     const objMetadataProps = getMetadataWriteProperties(obj);
                     const body = buildCreateXml(objType, objName, objPackage, objDescription, objMetadataProps);
                     const contentType = createContentTypeForType(objType);
-                    const needsPackageParam = objType === 'BDEF' || objType === 'TABL';
+                    const needsPackageParam = objType === 'BDEF' || objType === 'TABL' || objType === 'TABL/DT' || objType === 'TABL/DS';
                     try {
                         await createObject(client.http, client.safety, createUrl, body, contentType, objTransport, needsPackageParam ? objPackage : undefined, cachedFeatures?.abapRelease);
                     }
@@ -3690,20 +3927,50 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                         const srcUrl = sourceUrlForType(objType, objName);
                         await safeUpdateSource(client.http, client.safety, objUrl, srcUrl, objSource, objTransport, cachedFeatures?.abapRelease);
                     }
-                    // Step 3: Activate the object
-                    const activationResult = await activate(client.http, client.safety, objUrl);
-                    if (!activationResult.success) {
-                        results.push({
-                            type: objType,
-                            name: objName,
-                            packageName: objPackage,
-                            status: 'failed',
-                            error: `activation failed: ${activationResult.messages.join('; ')}`,
-                        });
-                        break;
+                    // Resolve the activation URL up front so both the inline path and the
+                    // deferred terminal-activate path use the same URL. FUNC needs the parent
+                    // function-group baked into the path (issue #250); objectUrlForType throws
+                    // for FUNC so we mirror the FUNC-aware resolver from handleSAPActivate. For
+                    // TABL we keep objUrl (already resolved to /tables/) — DDIC-structure FMs
+                    // aren't a real concept and the create path doesn't expose one.
+                    let activationUrl = objUrl;
+                    if (objType === 'FUNC') {
+                        let group = String(obj.group ?? args.group ?? '').trim();
+                        if (!group) {
+                            const resolved = cachingLayer
+                                ? await cachingLayer.resolveFuncGroup(client, objName)
+                                : await client.resolveFunctionGroup(objName);
+                            if (!resolved) {
+                                throw new Error(`Cannot resolve function group for FM "${objName}" in batch_create activation step. Provide "group" on the FUNC entry.`);
+                            }
+                            group = resolved;
+                        }
+                        const groupLc = encodeURIComponent(group.toLowerCase());
+                        activationUrl = `/sap/bc/adt/functions/groups/${groupLc}/fmodules/${encodeURIComponent(objName.toLowerCase())}`;
+                    }
+                    if (activateAtEnd) {
+                        // Step 3 deferred: track this object for the terminal activateBatch call.
+                        // Cache invalidation also moves to AFTER the terminal activate succeeds —
+                        // invalidating now would let the next read see a draft we couldn't activate.
+                        writtenObjects.push({ type: objType, name: objName, url: activationUrl });
+                        results.push({ type: objType, name: objName, packageName: objPackage, status: 'success' });
+                    }
+                    else {
+                        // Step 3: Activate the object (inline, default behavior).
+                        const activationResult = await activate(client.http, client.safety, activationUrl);
+                        if (!activationResult.success) {
+                            results.push({
+                                type: objType,
+                                name: objName,
+                                packageName: objPackage,
+                                status: 'failed',
+                                error: `activation failed: ${activationResult.messages.join('; ')}`,
+                            });
+                            break;
+                        }
+                        invalidateWrittenObject(objType, objName);
+                        results.push({ type: objType, name: objName, packageName: objPackage, status: 'success' });
                     }
-                    invalidateWrittenObject(objType, objName);
-                    results.push({ type: objType, name: objName, packageName: objPackage, status: 'success' });
                 }
                 catch (err) {
                     results.push({
@@ -3728,6 +3995,52 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                     error: 'skipped — stopped after previous failure',
                 });
             }
+            // ── Terminal activateBatch (activateAtEnd=true) ─────────────────────
+            // After every write-phase succeeded (or broke off early), issue ONE batch
+            // activate over the already-written subset. This is the killer feature
+            // for composition-linked DDLS and RAP behavior stacks — SAP's activator
+            // sees the whole graph in a single POST and resolves cross-references
+            // internally, so parent → child siblings activate cleanly.
+            let terminalActivationFailure;
+            if (activateAtEnd && writtenObjects.length > 0) {
+                const activationOutcome = await activateBatch(client.http, client.safety, writtenObjects);
+                if (activationOutcome.success) {
+                    // Defensive: per-object status was already 'success' from the write phase.
+                    // Cache invalidation moves here so a failed terminal activate doesn't strand
+                    // a stale 'active' cache entry. Invalidate inactive-lists once for the user.
+                    for (const o of writtenObjects) {
+                        cachingLayer?.invalidate(o.type, o.name, 'all');
+                    }
+                    cachingLayer?.inactiveLists.invalidate(client.username);
+                }
+                else {
+                    // Flip every written-but-not-yet-activated entry to 'failed', preserving the
+                    // "create + source-write succeeded" context. Reuse the existing per-object
+                    // diagnostic mapper so callers see the activation messages keyed by object name.
+                    const batchStatuses = buildBatchActivationStatuses(writtenObjects, activationOutcome);
+                    const statusDetails = formatBatchActivationStatuses(batchStatuses);
+                    terminalActivationFailure = statusDetails;
+                    const statusByName = new Map(batchStatuses.map((s) => [`${s.type}${s.name}`, s]));
+                    for (const result of results) {
+                        if (result.status !== 'success')
+                            continue;
+                        const key = `${result.type}${result.name}`;
+                        const matched = statusByName.get(key);
+                        if (!matched)
+                            continue;
+                        // Some entries may still report status 'active' if the activator returned
+                        // success: false but had no per-object error details — keep them as 'success'.
+                        if (matched.status === 'active')
+                            continue;
+                        result.status = 'failed';
+                        const detail = matched.messages.length > 0 ? ` — ${matched.messages.join('; ')}` : '';
+                        // Preserve the "create + source-write succeeded" context so the user sees that
+                        // the failure was specifically the activation step, not the write step.
+                        result.error = `${writtenObjects.length}/${writtenObjects.length} written, batch activation failed${detail}`;
+                    }
+                }
+            }
+            // ────────────────────────────────────────────────────────────────────
             const summary = results
                 .map((r) => r.status === 'success'
                 ? `${r.name} (${r.type}) ✓ [${r.packageName}]`
@@ -3736,19 +4049,21 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
             const successCount = results.filter((r) => r.status === 'success').length;
             const hasFailure = results.some((r) => r.status === 'failed');
             const warningSuffix = batchWarnings.length > 0 ? `\n\nRAP preflight warnings:\n- ${batchWarnings.join('\n- ')}` : '';
+            const activateAtEndSuffix = terminalActivationFailure !== undefined ? `\n\nBatch activation diagnostics:${terminalActivationFailure}` : '';
             const packageNames = [...new Set(batchPlan.map((item) => item.packageName))];
             const packageSummary = packageNames.length === 1
                 ? `in package ${packageNames[0]}`
                 : packageNames.length <= 3
                     ? `across packages [${packageNames.join(', ')}]`
                     : `across ${packageNames.length} packages`;
+            const activateAtEndPrefix = activateAtEnd ? '; activated as a single batch' : '';
             if (hasFailure) {
                 const cleanupHint = successCount > 0
                     ? ` Note: ${successCount} already-created object(s) remain on the SAP system and may need manual cleanup.`
                     : '';
-                return errorResult(`Batch created ${successCount}/${objects.length} objects ${packageSummary}: ${summary}${cleanupHint}${warningSuffix}`);
+                return errorResult(`Batch created ${successCount}/${objects.length} objects ${packageSummary}${activateAtEndPrefix}: ${summary}${cleanupHint}${warningSuffix}${activateAtEndSuffix}`);
             }
-            return textResult(`Batch created ${successCount} objects ${packageSummary}: ${summary}${warningSuffix}`);
+            return textResult(`Batch created ${successCount} objects ${packageSummary}${activateAtEndPrefix}: ${summary}${warningSuffix}${activateAtEndSuffix}`);
         }
         default:
             return errorResult(`Unknown SAPWrite action: ${action}. Supported: create, update, delete, edit_method, batch_create, scaffold_rap_handlers, generate_behavior_implementation`);
@@ -3768,7 +4083,8 @@ function runRapPreflightValidation(source, type, name, features, configSystemTyp
         return { blocked: false };
     }
     const systemType = features?.systemType ?? (configSystemType !== 'auto' ? configSystemType : undefined);
-    const result = validateRapSource(type, source, {
+    // Canonicalize so validateRapSource's 'TABL' case matches TABL/DT and TABL/DS.
+    const result = validateRapSource(canonicalTablType(type), source, {
         systemType,
         abapRelease: features?.abapRelease,
     });
@@ -4022,7 +4338,12 @@ async function handleSAPActivate(client, args, cachingLayer) {
             const objName = String(o.name ?? '');
             let url;
             if (objType === 'TABL') {
-                url = await client.resolveTablObjectUrl(objName);
+                // Use the write-path resolver: refuses TABL/DT activation on systems
+                // that don't expose /sap/bc/adt/ddic/tables/ (NW 7.50/7.51), where
+                // activate would hit the wrong endpoint. See issue #285.
+                url = await client.resolveTablObjectUrlForWrite(objName, {
+                    tablesEndpointAvailable: isTablesEndpointAvailable(),
+                });
             }
             else if (objType === 'FUNC') {
                 let group = String(o.group ?? args.group ?? '').trim();
@@ -4064,15 +4385,26 @@ async function handleSAPActivate(client, args, cachingLayer) {
             .join('');
         return errorResult(`Batch activation failed for: ${names}.${statusDetails}\n${formatActivationMessages(result)}${combinedDiag}`);
     }
-    // Single activation (existing behavior). For TABL we resolve the URL because
-    // the existing object may live at /tables/ (transparent) or /structures/
-    // (DDIC structure); using the wrong one would produce a confusing 404.
+    // Single activation (existing behavior). For TABL we use the write-path
+    // resolver so transparent-table activations on NW 7.50/7.51 are refused
+    // with the SE11 hint instead of silently activating against /structures/
+    // (which would not even be the right object). See issue #285.
     // For FUNC the URL needs the parent function group baked into the path
     // (issue #250) — `objectBasePath('FUNC')` deliberately throws so generic
     // builders fail loudly. Auto-resolve the group when omitted.
     let objectUrl;
     if (type === 'TABL') {
-        objectUrl = await client.resolveTablObjectUrl(name);
+        try {
+            objectUrl = await client.resolveTablObjectUrlForWrite(name, {
+                tablesEndpointAvailable: isTablesEndpointAvailable(),
+            });
+        }
+        catch (resolveErr) {
+            if (resolveErr instanceof AdtSafetyError) {
+                return errorResult(resolveErr.message);
+            }
+            throw resolveErr;
+        }
     }
     else if (type === 'FUNC') {
         let group = String(args.group ?? '').trim();