arc-1 0.9.5 → 0.9.7

package/dist/handlers/intent.js

@@ -11,8 +11,9 @@
  */
 import { checkRepo as abapGitCheckRepo, createBranch as abapGitCreateBranch, createRepo as abapGitCreateRepo, getExternalInfo as abapGitGetExternalInfo, listRepos as abapGitListRepos, pullRepo as abapGitPullRepo, pushRepo as abapGitPushRepo, stageRepo as abapGitStageRepo, switchBranch as abapGitSwitchBranch, unlinkRepo as abapGitUnlinkRepo, } from '../adt/abapgit.js';
 import { buildSiblingExtensionFinding, classifyCdsImpact, deriveSiblingStem, isSiblingNameMatch, } from '../adt/cds-impact.js';
+import { diffMethodSets, extractMethodNameFromClause, findSectionAnchor, insertMethodPair, moveMethodDefinition, removeMethodPair, spliceClassDefinition, spliceMethodSignature, } from '../adt/class-structure.js';
 import { findDefinition, findInterfaceImplementersViaSeoMetaRel, findReferences, findWhereUsed, getCompletion, getWhereUsedScope, } from '../adt/codeintel.js';
-import { createObject, deleteObject, lockObject, safeUpdateObject, safeUpdateSource, unlockObject, updateObject, updateSource, } from '../adt/crud.js';
+import { createObject, deleteObject, lockObject, safeUpdateClassInclude, safeUpdateObject, safeUpdateSource, unlockObject, updateObject, updateSource, } from '../adt/crud.js';
 import { buildDataElementXml, buildDomainXml, buildMessageClassXml, buildPackageXml, buildServiceBindingXml, decodeKtdText, rewriteKtdText, } from '../adt/ddic-xml.js';
 import { activate, activateBatch, applyFixProposal, getFixProposals, getPrettyPrinterSettings, prettyPrint, publishServiceBinding, runAtcCheck, runUnitTests, setPrettyPrinterSettings, syntaxCheck, unpublishServiceBinding, } from '../adt/devtools.js';
 import { getDump, getGatewayErrorDetail, getObjectState, getTraceDbAccesses, getTraceHitlist, getTraceStatements, listDumps, listGatewayErrors, listSystemMessages, listTraces, } from '../adt/diagnostics.js';
@@ -31,12 +32,14 @@ import { getAppInfo } from '../adt/ui5-repository.js';
 import { validateAffHeader } from '../aff/validator.js';
 import { extractCdsDependencies, extractCdsElements } from '../context/cds-deps.js';
 import { compressCdsContext, compressContext } from '../context/compressor.js';
+import { grepSource } from '../context/grep.js';
 import { extractMethod, formatMethodListing, listMethods, spliceMethod } from '../context/method-surgery.js';
 import { buildLintConfig, listRulesFromConfig, } from '../lint/config-builder.js';
 import { detectFilename, lintAbapSource, lintAndFix, validateBeforeWrite } from '../lint/lint.js';
 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,8 +228,12 @@ 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 classification = classifySapDomainError(err.statusCode, err.responseBody, err.path);
+        const argType = canonicalTablType(String(args.type ?? '').toUpperCase());
+        // Pass the detected SAP_BASIS release so the 423 lock-handle hint can specialize
+        // (< 7.51 → point at abapfs_extensions; see issue #293). cachedFeatures is set by the
+        // startup probe; config.abapRelease is the manual SAP_ABAP_RELEASE override fallback.
+        const abapRelease = cachedFeatures?.abapRelease ?? config.abapRelease;
+        const classification = classifySapDomainError(err.statusCode, err.responseBody, err.path, abapRelease);
         if (classification) {
             const transactionLine = classification.transaction ? `\nSAP Transaction: ${classification.transaction}` : '';
             return `${enriched}\n\nHint: ${classification.hint}${transactionLine}`;
@@ -262,6 +269,14 @@ function buildBaseErrorMessage(err, message, tool, args, config) {
                     `sqlFilter="MANDT = '100'" or sqlFilter="MATNR LIKE 'Z%'".`);
             }
         }
+        if (tool === 'SAPRead' && argType === 'TABLE_QUERY' && err.statusCode === 400) {
+            const combined = `${err.message}\n${err.responseBody ?? ''}`;
+            if (/is invalid here|due to grammar/i.test(combined)) {
+                return (`${enriched}\n\nHint: TABLE_QUERY parser error — check field names match the actual column names ` +
+                    'exposed by the table/CDS view (use SAPRead(type="DDLS", include="elements") to inspect CDS view fields). ' +
+                    'Also verify value formats (e.g. FiscalPeriod is C(2,0) so use "01" not "001").');
+            }
+        }
         const behaviorPoolHint = getBehaviorPoolSaveFailureHint(err, args);
         if (behaviorPoolHint) {
             return `${enriched}\n\nHint: ${behaviorPoolHint}`;
@@ -295,7 +310,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 +673,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 +761,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,6 +778,47 @@ 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.
@@ -945,6 +1001,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.',
@@ -1041,6 +1119,11 @@ async function handleSAPRead(client, args, cachingLayer) {
         const indicator = cacheHit && revalidated ? '[cached:revalidated]\n' : '';
         return textResult(`${note}${indicator}${source}`);
     };
+    /** When args.grep is set, return only matching source lines (+context) instead of full source. */
+    const grepText = (source) => {
+        const g = grepSource(source, String(args.grep));
+        return g.invalidPattern ? errorResult(g.output) : textResult(g.output);
+    };
     // Structured format is only supported for CLAS type
     if (args.format === 'structured' && type !== 'CLAS') {
         return errorResult('The "structured" format is only supported for CLAS type. Other types return text format.');
@@ -1048,9 +1131,45 @@ async function handleSAPRead(client, args, cachingLayer) {
     switch (type) {
         case 'PROG': {
             const { source, cacheHit, revalidated } = await cachedGet('PROG', name, effectiveVersion, (ifNoneMatch) => client.getProgram(name, { ifNoneMatch, version: effectiveVersion }));
+            if (args.grep)
+                return grepText(source);
             return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'CLAS': {
+            // grep: return only matching source lines (+context), annotated with the owning class/method.
+            if (args.grep) {
+                if (args.method) {
+                    return errorResult('Do not combine grep with method. Use grep to find code, then method="<name>" to read the full method.');
+                }
+                const rawSection = args.include;
+                // 'main' (and the default) live at /source/main, not /includes/main — read via the
+                // cached main path; only real sub-includes go through the raw getClassInclude endpoint.
+                const section = rawSection && rawSection.toLowerCase() !== 'main' ? rawSection : undefined;
+                let clasSource;
+                if (section) {
+                    try {
+                        clasSource = (await client.getClassInclude(name, section, { version: effectiveVersion })).source;
+                    }
+                    catch (err) {
+                        if (isNotFoundError(err)) {
+                            return textResult(`Include "${section}" is not available for class ${name}. Run grep without include= to search the full class source.`);
+                        }
+                        throw err;
+                    }
+                }
+                else {
+                    clasSource = (await cachedGet('CLAS', name, effectiveVersion, (ifNoneMatch) => client.getClass(name, undefined, { ifNoneMatch, version: effectiveVersion }))).source;
+                }
+                const abaplintVer = cachedFeatures?.abapRelease
+                    ? mapSapReleaseToAbaplintVersion(cachedFeatures.abapRelease)
+                    : undefined;
+                // MethodInfo is a structural superset of grepSource's MethodRange — pass through directly.
+                const listing = listMethods(clasSource, name, abaplintVer);
+                const g = grepSource(clasSource, String(args.grep), listing.success ? { methods: listing.methods } : undefined);
+                return g.invalidPattern
+                    ? errorResult(g.output)
+                    : textResult(`[${name} section=${rawSection ?? 'main'}]\n${g.output}`);
+            }
             // Structured format: return JSON with metadata + decomposed source
             if (args.format === 'structured') {
                 const structured = await client.getClassStructured(name);
@@ -1085,6 +1204,8 @@ async function handleSAPRead(client, args, cachingLayer) {
         }
         case 'INTF': {
             const { source, cacheHit, revalidated } = await cachedGet('INTF', name, effectiveVersion, (ifNoneMatch) => client.getInterface(name, { ifNoneMatch, version: effectiveVersion }));
+            if (args.grep)
+                return grepText(source);
             return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'FUNC': {
@@ -1120,6 +1241,8 @@ async function handleSAPRead(client, args, cachingLayer) {
                 };
                 return textResult(JSON.stringify(payload, null, 2));
             }
+            if (args.grep)
+                return grepText(source);
             return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'FUGR': {
@@ -1147,6 +1270,8 @@ async function handleSAPRead(client, args, cachingLayer) {
         }
         case 'INCL': {
             const { source, cacheHit, revalidated } = await cachedGet('INCL', name, effectiveVersion, (ifNoneMatch) => client.getInclude(name, { ifNoneMatch, version: effectiveVersion }));
+            if (args.grep)
+                return grepText(source);
             return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'DDLS': {
@@ -1159,23 +1284,33 @@ async function handleSAPRead(client, args, cachingLayer) {
                 // Elements extraction is derived from source — no cache indicator
                 return cachedTextResult(extractCdsElements(ddlSource, name), false, false, versionWarning);
             }
+            if (args.grep)
+                return grepText(ddlSource);
             return cachedTextResult(ddlSource, cacheHit, revalidated, versionWarning);
         }
         case 'DCLS': {
             const { source, cacheHit, revalidated } = await cachedGet('DCLS', name, effectiveVersion, (ifNoneMatch) => client.getDcl(name, { ifNoneMatch, version: effectiveVersion }));
+            if (args.grep)
+                return grepText(source);
             return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'BDEF': {
             const { source, cacheHit, revalidated } = await cachedGet('BDEF', name, effectiveVersion, (ifNoneMatch) => client.getBdef(name, { ifNoneMatch, version: effectiveVersion }));
+            if (args.grep)
+                return grepText(source);
             return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'SRVD': {
             const { source, cacheHit, revalidated } = await cachedGet('SRVD', name, effectiveVersion, (ifNoneMatch) => client.getSrvd(name, { ifNoneMatch, version: effectiveVersion }));
+            if (args.grep)
+                return grepText(source);
             return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'DDLX': {
             try {
                 const { source, cacheHit, revalidated } = await cachedGet('DDLX', name, effectiveVersion, (ifNoneMatch) => client.getDdlx(name, { ifNoneMatch, version: effectiveVersion }));
+                if (args.grep)
+                    return grepText(source);
                 return cachedTextResult(source, cacheHit, revalidated, versionWarning);
             }
             catch (err) {
@@ -1209,10 +1344,14 @@ async function handleSAPRead(client, args, cachingLayer) {
             // client.getTabl() handles the /tables/ → /structures/ fallback internally
             // and caches the resolved URL for subsequent write/activate paths.
             const { source, cacheHit, revalidated } = await cachedGet('TABL', name, effectiveVersion, (ifNoneMatch) => client.getTabl(name, { ifNoneMatch, version: effectiveVersion }));
+            if (args.grep)
+                return grepText(source);
             return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'VIEW': {
             const { source, cacheHit, revalidated } = await cachedGet('VIEW', name, effectiveVersion, (ifNoneMatch) => client.getView(name, { ifNoneMatch, version: effectiveVersion }));
+            if (args.grep)
+                return grepText(source);
             return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'DOMA': {
@@ -1319,6 +1458,15 @@ async function handleSAPRead(client, args, cachingLayer) {
             const data = await client.getTableContents(name, maxRows, args.sqlFilter);
             return textResult(JSON.stringify(data, null, 2));
         }
+        case 'TABLE_QUERY': {
+            const maxRows = Number(args.maxRows ?? 100);
+            const columns = Array.isArray(args.columns) ? args.columns : undefined;
+            const where = Array.isArray(args.where)
+                ? args.where
+                : undefined;
+            const data = await client.runTableQuery(name, { columns, where, maxRows });
+            return textResult(JSON.stringify(data, null, 2));
+        }
         case 'SOBJ': {
             const method = String(args.method ?? '');
             // Sanitize inputs to prevent SQL injection — BOR names are alphanumeric + underscore only
@@ -1478,7 +1626,7 @@ async function handleSAPSearch(client, args) {
                 // 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()}`;
+                const baseKey = (m) => `${(m.objectType.split('/')[0] || m.objectType).toUpperCase()}\x00${m.objectName.toUpperCase()}`;
                 for (const m of adtMatches)
                     seen.set(baseKey(m), m);
                 for (const m of dbMatches) {
@@ -2253,18 +2401,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.
@@ -2569,6 +2723,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) {
@@ -2579,14 +2764,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,
@@ -2688,10 +2874,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':
@@ -2819,13 +3008,23 @@ function stripIncludeHeader(source) {
     return source.replace(/^=== \w+ ===\n/, '');
 }
 // ─── SAPWrite Handler ────────────────────────────────────────────────
+/**
+ * Single-object actions whose top-level `name` is an SAP object name and must be
+ * uppercase (TADIR convention). `batch_create` is excluded — its names live in
+ * the `objects[]` items and are validated per item in the batch_create branch.
+ */
+const NAME_CASE_GUARD_ACTIONS = new Set(['create', 'update', 'edit_method', 'delete']);
 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';
     const include = normalizeClassWriteInclude(args.include);
+    // Whether a non-empty include was actually requested. Some MCP clients serialize
+    // an omitted optional string as "" — treat empty/whitespace as "not provided" so
+    // those clients aren't rejected with a bogus "Invalid CLAS include" on the MAIN path.
+    const includeProvided = typeof args.include === 'string' && args.include.trim() !== '';
     const transport = args.transport;
     const lintOverride = args.lintBeforeWrite;
     const preflightOverride = args.preflightBeforeWrite;
@@ -2835,12 +3034,16 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
         return errorResult('"type" and "name" are required for this action.');
     }
     // SAP TADIR stores object names uppercase. Mixed-case names cause silent corruption
-    // (e.g. DDLS created as "Zc_MyView" registers as "ZC_MYVIEW" in TADIR but the source body
-    // still contains "Zc_MyView", confusing every downstream tool). Reject pre-flight on create —
-    // applies on every SAP release; this is universal SAP convention, not a 7.50 quirk.
+    // on create (e.g. DDLS "Zc_MyView" registers as "ZC_MYVIEW" in TADIR but the source body
+    // still contains "Zc_MyView", confusing every downstream tool) and broken URL lookups on
+    // mutate/delete — the lock is held against the canonical uppercase name while the request
+    // URL carries the mixed-case one, which surfaces on ECC as 423 "... is not locked" (issue
+    // #293, original report used name "Z_HELLO_world"). Reject pre-flight for every name-bearing
+    // single-object action — universal SAP convention, not a 7.50 quirk. (batch_create validates
+    // each item separately below.)
     // Note: source code INSIDE the object can use mixed case (e.g. for DDLS: name="ZC_MYVIEW"
     // but `define view entity Zc_MyView` is fine inside the source body).
-    if (action === 'create' && name && name !== name.toUpperCase()) {
+    if (NAME_CASE_GUARD_ACTIONS.has(action) && name && name !== name.toUpperCase()) {
         return errorResult(`Object name "${name}" contains lowercase characters. SAP object names must be uppercase (e.g. "${name.toUpperCase()}").\n\n` +
             `Note: the object NAME in TADIR must be uppercase, but the source code inside the object can use mixed case ` +
             `(e.g. for DDLS: name="${name.toUpperCase()}" but source can contain "define view entity ${name}").`);
@@ -2860,8 +3063,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') {
@@ -2886,23 +3103,53 @@ 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).
     // Only fetches metadata when package restrictions are configured — no extra HTTP call otherwise.
+    // Fail-closed: if the package cannot be determined from ADT metadata, refuse the write
+    // rather than silently passing through the allowlist gate.
     async function enforcePackageForExistingObject() {
         if (client.safety.allowedPackages.length === 0)
             return undefined;
         const pkg = await client.resolveObjectPackage(objectUrl);
-        if (pkg)
-            checkPackage(client.safety, pkg);
+        if (!pkg) {
+            throw new AdtSafetyError(`Operations on ${type} '${name}' blocked: ARC-1 could not determine the object's package ` +
+                `from ADT metadata (no adtcore:packageRef in response). Fail-closed because allowedPackages is restricted.`);
+        }
+        await checkPackage(client.safety, pkg, client.getPackageHierarchyResolver());
         return pkg;
     }
+    // Helper for class-section surgery (issue #303): fetch the class structure AND
+    // /source/main at the SAME effective version, so the spliced line ranges line
+    // up with the bytes being edited. resolveVersionAndDraftInfo picks 'inactive'
+    // when an unactivated draft exists. We pass that version to BOTH getClassStructure
+    // (the /objectstructure?version= read) and the source read, AND to the cache opts
+    // (so inactive bytes aren't cached under the 'active' key). Without this, a chained
+    // surgery call on a draft would splice active-version line ranges into inactive
+    // source and silently corrupt the draft.
+    async function fetchClassStructureAndMain(clsName) {
+        const { effectiveVersion } = await resolveVersionAndDraftInfo(client, cachingLayer, 'CLAS', clsName, 'auto');
+        const structure = await client.getClassStructure(clsName, effectiveVersion);
+        const main = cachingLayer
+            ? (await cachingLayer.getSource('CLAS', clsName, (ifNoneMatch) => client.getClass(clsName, undefined, { ifNoneMatch, version: effectiveVersion }), { version: effectiveVersion })).source
+            : (await client.getClass(clsName, undefined, { version: effectiveVersion })).source;
+        return { structure, main, effectiveVersion };
+    }
     switch (action) {
         case 'update': {
             const existingPackage = await enforcePackageForExistingObject();
@@ -2919,9 +3166,14 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                 if (!hasSource) {
                     return errorResult('"source" is required when updating a CLAS include.');
                 }
-                await safeUpdateSource(client.http, client.safety, objectUrl, classIncludeUrl(name, include), source, transport, cachedFeatures?.abapRelease);
+                // Auto-initialise the include if it doesn't exist yet. On a fresh class
+                // the testclasses (CCAU) include is absent — a content PUT alone fails
+                // with HTTP 500 "…CCAU does not have any inactive version". safeUpdateClassInclude
+                // probes the include and POST-creates it (under the same lock) before the PUT.
+                const { initialized } = await safeUpdateClassInclude(client.http, client.safety, objectUrl, classIncludeUrl(name, include), source, transport, cachedFeatures?.abapRelease);
                 invalidateWrittenObject(type, name);
-                return textResult(`Successfully updated ${type} ${name} include ${include}. Active version remains unchanged until activation; read with SAPRead(version="inactive") to verify the draft.`);
+                const initNote = initialized ? ` (initialised the ${include} include first)` : '';
+                return textResult(`Successfully updated ${type} ${name} include ${include}${initNote}. Active version remains unchanged until activation; read with SAPRead(version="inactive") to verify the draft.`);
             }
             if (type === 'SKTD') {
                 // KTD update requires the full <sktd:docu> XML envelope with the Markdown
@@ -3022,7 +3274,7 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
         }
         case 'create': {
             const pkg = String(args.package ?? '$TMP');
-            checkPackage(client.safety, pkg);
+            await checkPackage(client.safety, pkg, client.getPackageHierarchyResolver());
             const description = String(args.description ?? name);
             // Pre-flight: check transport requirements for non-$TMP packages when no transport provided.
             // SAP requires a transport number for objects in transportable packages.
@@ -3135,7 +3387,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);
@@ -3338,6 +3590,261 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
             const extras = [lintWarnings.warnings, checkNotes].filter(Boolean).join('\n\n');
             return extras ? textResult(`${msg}\n\n${extras}`) : textResult(msg);
         }
+        // ─── Class-section surgery actions (issue #303) ─────────────────────
+        //
+        // Four actions share a common shape: fetch objectstructure → optional
+        // diff/refuse → splice into /source/main (or /includes/<inc> when
+        // include= is set) → PUT under lock → no auto-activate.
+        //
+        // Pre-write lint runs on the SPLICED FULL source (not the partial input
+        // fragment) because a raw DEFINITION block alone fails abaplint with
+        // "Expected CLASSIMPLEMENTATION" — verified live on a4h. Lint is skipped
+        // for include= writes (same precedent as `update include=` path).
+        case 'edit_class_definition': {
+            if (type !== 'CLAS')
+                return errorResult('edit_class_definition is only supported for type=CLAS.');
+            if (!hasSource)
+                return errorResult('"source" (new CLASS DEFINITION block) is required for edit_class_definition.');
+            if (includeProvided && !include) {
+                return errorResult(`Invalid CLAS include "${String(args.include)}". Valid values: ${CLASS_WRITE_INCLUDES.join(', ')}.`);
+            }
+            await enforcePackageForExistingObject();
+            const writeUrl = include ? classIncludeUrl(name, include) : srcUrl;
+            let spliced;
+            if (include) {
+                // include= path: whole-replace the local include (CCDEF/CCIMP/macros/
+                // testclasses). The structure-based diff/refuse doesn't apply — the
+                // /objectstructure endpoint reports the GLOBAL class, not the local
+                // include's split DEFINITION/IMPLEMENTATION halves. SAP activation is the
+                // validator here (same precedent as `update include=`). No structure or
+                // source fetch is needed: the caller's `source` IS the new include body.
+                spliced = source.endsWith('\n') ? source : `${source}\n`;
+            }
+            else {
+                // MAIN path: fetch structure + source at the same effective version so
+                // the spliced line ranges align with the bytes being edited.
+                const { structure, main } = await fetchClassStructureAndMain(name);
+                // Refuse-policy: compute the method-set diff against the NEW DEFINITION.
+                const diff = diffMethodSets(structure, source);
+                const missingImpls = [];
+                const orphanImpls = [];
+                for (const add of diff.added) {
+                    // Exempt declarations that never have a METHOD…ENDMETHOD body.
+                    if (add.isAbstract || add.isEvent || add.isInterface || add.isAlias)
+                        continue;
+                    // Does IMPLEMENTATION already have a METHOD <name> header? Match the
+                    // method name followed by a word-boundary so AMDP / event-handler /
+                    // multi-line headers (`METHOD x BY DATABASE PROCEDURE…`, `METHOD x FOR
+                    // EVENT…`, `METHOD x\n  IMPORTING…`) are recognized — NOT only the bare
+                    // `METHOD x.` form. \b after the name prevents matching a longer name
+                    // with the same prefix (METHOD x_helper for added X).
+                    const re = new RegExp(`^\\s*METHOD\\s+${add.name}\\b`, 'im');
+                    if (!re.test(main))
+                        missingImpls.push(add.name);
+                }
+                for (const rem of diff.removed) {
+                    if (rem.implementation) {
+                        // Was concrete, still has impl range — caller didn't remove the body.
+                        orphanImpls.push(rem.name);
+                    }
+                }
+                if (missingImpls.length > 0 || orphanImpls.length > 0) {
+                    const parts = [];
+                    if (missingImpls.length > 0) {
+                        parts.push(`Cannot apply edit_class_definition: the new DEFINITION declares method(s) ${missingImpls.join(', ')} but the existing IMPLEMENTATION block has no matching METHOD…ENDMETHOD body. Either include a METHOD <name>. ENDMETHOD. block per added method in your new source, or use SAPWrite(action="add_method", name="${name}", method="<METHODS clause>") to insert each one atomically.`);
+                    }
+                    if (orphanImpls.length > 0) {
+                        parts.push(`Cannot apply edit_class_definition: the new DEFINITION removes method(s) ${orphanImpls.join(', ')} but the existing IMPLEMENTATION block still has METHOD…ENDMETHOD bodies for them (orphan implementation). Either remove those METHOD blocks in your edit, or use SAPWrite(action="delete_method", name="${name}", method="<name>") to drop each one atomically.`);
+                    }
+                    return errorResult(parts.join('\n\n'));
+                }
+                spliced = spliceClassDefinition(main, structure, source);
+            }
+            // Pre-write lint on the spliced full source (MAIN path only — include=
+            // fragments can't be lint-parsed standalone).
+            if (!include) {
+                const lintWarnings = runPreWriteLint(spliced, type, name, config, lintOverride);
+                if (lintWarnings.blocked)
+                    return lintWarnings.result;
+            }
+            await safeUpdateSource(client.http, client.safety, objectUrl, writeUrl, spliced, transport, cachedFeatures?.abapRelease);
+            invalidateWrittenObject(type, name);
+            const whereLabel = include ? ` (include: ${include})` : '';
+            return textResult(`Successfully updated DEFINITION of ${type} ${name}${whereLabel}. Active version unchanged until activation; read with SAPRead(version="inactive") to verify, then SAPActivate.`);
+        }
+        case 'edit_method_signature': {
+            if (type !== 'CLAS')
+                return errorResult('edit_method_signature is only supported for type=CLAS.');
+            const methodSpecifier = String(args.method ?? '').trim();
+            if (!methodSpecifier) {
+                return errorResult('"method" (the method NAME to re-sign) is required for edit_method_signature.');
+            }
+            if (!hasSource) {
+                return errorResult('"source" (the new METHODS clause) is required for edit_method_signature.');
+            }
+            // MAIN-only action: include= is rejected at the schema layer (this action is
+            // not in SAPWRITE_INCLUDE_AWARE_ACTIONS). Defensive guard for direct CLI calls
+            // that bypass Zod.
+            if (includeProvided) {
+                return errorResult('edit_method_signature targets the global class DEFINITION (/source/main). For local-class (CCDEF) signatures, use edit_class_definition with include=definitions.');
+            }
+            await enforcePackageForExistingObject();
+            const { structure, main } = await fetchClassStructureAndMain(name);
+            const upperName = methodSpecifier.toUpperCase();
+            const method = structure.methods.find((m) => m.name === upperName);
+            if (!method) {
+                const available = structure.methods.map((m) => m.name).join(', ');
+                const hint = methodSpecifier.includes('~')
+                    ? ' Interface-qualified names (e.g. "zif_x~m") are not addressable here — objectstructure lists the implementing method under its bare name; for interface/local-handler bodies use edit_method.'
+                    : '';
+                return errorResult(`Method "${methodSpecifier}" not found in CLAS ${name}. Available methods: ${available || '(none)'}.${hint}`);
+            }
+            const spliced = spliceMethodSignature(main, method, source);
+            // No pre-write lint: edit_method_signature changes ONLY the declaration; the
+            // method body still references the old signature until the caller follows up
+            // with edit_method. Linting the spliced full source here would flag legitimate
+            // in-progress renames (e.g. "param `name` not declared"). SAP activation is the
+            // authoritative check — same rationale as the include= lint skip on edit_method.
+            await safeUpdateSource(client.http, client.safety, objectUrl, srcUrl, spliced, transport, cachedFeatures?.abapRelease);
+            invalidateWrittenObject(type, name);
+            return textResult(`Successfully updated signature of method "${method.name}" in ${type} ${name}. Active version unchanged until activation; if the body still references the old signature, follow up with edit_method, then SAPActivate.`);
+        }
+        case 'add_method': {
+            if (type !== 'CLAS')
+                return errorResult('add_method is only supported for type=CLAS.');
+            const clause = String(args.method ?? '');
+            if (!clause.trim()) {
+                return errorResult('"method" (the full METHODS clause, e.g. "METHODS greet IMPORTING who TYPE string.") is required for add_method.');
+            }
+            const methodName = extractMethodNameFromClause(clause);
+            if (!methodName) {
+                return errorResult('Could not extract method name from the METHODS clause. Provide a clause starting with "METHODS <name>" or "CLASS-METHODS <name>".');
+            }
+            // Interface-qualified names (lhc_x~y, zif_x~m) can't be added to a global
+            // class's DEFINITION/IMPLEMENTATION — `~` is interface-method scope and would
+            // produce invalid ABAP in the METHOD stub. Reject with a clear pointer.
+            if (methodName.includes('~')) {
+                return errorResult(`add_method cannot add the interface-qualified method "${methodName}" to a global class. Implement the interface via "INTERFACES <name>." in the DEFINITION (use edit_class_definition), then provide the body with edit_method.`);
+            }
+            const visibility = args.visibility ?? 'public';
+            const isAbstract = args.abstract === true;
+            // MAIN-only action: include= is rejected at the schema layer (not in
+            // SAPWRITE_INCLUDE_AWARE_ACTIONS). Defensive guard for direct CLI calls.
+            if (includeProvided) {
+                return errorResult('add_method targets the global class DEFINITION (/source/main). For local-class (CCDEF) method additions, use edit_class_definition with include=definitions.');
+            }
+            await enforcePackageForExistingObject();
+            const { structure, main } = await fetchClassStructureAndMain(name);
+            // Refuse if method already exists (would silently duplicate).
+            if (structure.methods.some((m) => m.name === methodName)) {
+                return errorResult(`Method "${methodName}" already exists in CLAS ${name}. Use SAPWrite(action="edit_method_signature", method="${methodName}", source="<new METHODS clause>") to change its signature.`);
+            }
+            // A concrete (non-abstract) method needs an IMPLEMENTATION block to receive
+            // its METHOD…ENDMETHOD stub. A purely-abstract class has no IMPLEMENTATION
+            // half, so inserting a concrete declaration there would leave it unimplemented.
+            if (!isAbstract && !structure.classImplementationBlock) {
+                return errorResult(`CLAS ${name} has no IMPLEMENTATION block (purely abstract class). Pass abstract=true to add an abstract method, or add the IMPLEMENTATION half first via edit_class_definition.`);
+            }
+            // Refuse with hint if the target visibility section header is missing.
+            const anchor = findSectionAnchor(main, structure, visibility);
+            if (!anchor) {
+                return errorResult(`No ${visibility.toUpperCase()} SECTION exists in CLAS ${name}. Use SAPWrite(action="edit_class_definition") to add the section header first, then re-run add_method.`);
+            }
+            const spliced = insertMethodPair(main, structure, {
+                decl: clause,
+                visibility,
+                methodName,
+                isAbstract,
+            });
+            const lintWarnings = runPreWriteLint(spliced, type, name, config, lintOverride);
+            if (lintWarnings.blocked)
+                return lintWarnings.result;
+            await safeUpdateSource(client.http, client.safety, objectUrl, srcUrl, spliced, transport, cachedFeatures?.abapRelease);
+            invalidateWrittenObject(type, name);
+            const stubNote = isAbstract ? ' (abstract — no IMPL stub inserted)' : '';
+            return textResult(`Successfully added method "${methodName}" (${visibility}) to ${type} ${name}${stubNote}. Active version unchanged until activation; SAPActivate next.`);
+        }
+        case 'delete_method': {
+            if (type !== 'CLAS')
+                return errorResult('delete_method is only supported for type=CLAS.');
+            const methodSpecifier = String(args.method ?? '').trim();
+            if (!methodSpecifier) {
+                return errorResult('"method" (the method NAME to delete) is required for delete_method.');
+            }
+            // MAIN-only action: include= is rejected at the schema layer (not in
+            // SAPWRITE_INCLUDE_AWARE_ACTIONS). Defensive guard for direct CLI calls.
+            if (includeProvided) {
+                return errorResult('delete_method targets the global class DEFINITION (/source/main). For local-class (CCDEF/CCIMP) method removal, use edit_class_definition with include=...');
+            }
+            await enforcePackageForExistingObject();
+            const { structure, main } = await fetchClassStructureAndMain(name);
+            const upperName = methodSpecifier.toUpperCase();
+            const method = structure.methods.find((m) => m.name === upperName);
+            if (!method) {
+                const available = structure.methods.map((m) => m.name).join(', ');
+                const hint = methodSpecifier.includes('~')
+                    ? ' Interface-qualified names (e.g. "zif_x~m") are not addressable here; objectstructure lists methods under their bare names.'
+                    : '';
+                return errorResult(`Method "${methodSpecifier}" not found in CLAS ${name}. Available methods: ${available || '(none)'}.${hint}`);
+            }
+            const spliced = removeMethodPair(main, method);
+            const lintWarnings = runPreWriteLint(spliced, type, name, config, lintOverride);
+            if (lintWarnings.blocked)
+                return lintWarnings.result;
+            await safeUpdateSource(client.http, client.safety, objectUrl, srcUrl, spliced, transport, cachedFeatures?.abapRelease);
+            invalidateWrittenObject(type, name);
+            const where = method.implementation ? ' (DEFINITION + IMPLEMENTATION)' : ' (DEFINITION only — was ABSTRACT)';
+            return textResult(`Successfully deleted method "${method.name}" from ${type} ${name}${where}. Active version unchanged until activation; SAPActivate next.`);
+        }
+        case 'change_method_visibility': {
+            // Body-preserving visibility move (issue #303 follow-up). Moves the METHODS
+            // clause from its current section to the target section; the IMPLEMENTATION
+            // block is never touched, so the method body survives. This is the safe
+            // alternative to delete_method + add_method (which discards the body).
+            if (type !== 'CLAS')
+                return errorResult('change_method_visibility is only supported for type=CLAS.');
+            const methodSpecifier = String(args.method ?? '').trim();
+            if (!methodSpecifier) {
+                return errorResult('"method" (the method NAME to move) is required for change_method_visibility.');
+            }
+            const target = args.visibility;
+            if (!target) {
+                return errorResult('"visibility" (target section: public, protected, or private) is required for change_method_visibility.');
+            }
+            // MAIN-only action: include= is rejected at the schema layer (not in
+            // SAPWRITE_INCLUDE_AWARE_ACTIONS). Defensive guard for direct CLI calls.
+            if (includeProvided) {
+                return errorResult('change_method_visibility targets the global class DEFINITION (/source/main). For local-class (CCDEF) methods, use edit_class_definition with include=definitions.');
+            }
+            await enforcePackageForExistingObject();
+            const { structure, main } = await fetchClassStructureAndMain(name);
+            const upperName = methodSpecifier.toUpperCase();
+            const method = structure.methods.find((m) => m.name === upperName);
+            if (!method) {
+                const available = structure.methods.map((m) => m.name).join(', ');
+                const hint = methodSpecifier.includes('~')
+                    ? ' Interface-qualified names (e.g. "zif_x~m") are not addressable here; objectstructure lists methods under their bare names.'
+                    : '';
+                return errorResult(`Method "${methodSpecifier}" not found in CLAS ${name}. Available methods: ${available || '(none)'}.${hint}`);
+            }
+            // Idempotent: already in the requested section → no write.
+            if (method.visibility === target) {
+                return textResult(`Method "${method.name}" is already in the ${target.toUpperCase()} SECTION of ${type} ${name}. No change made.`);
+            }
+            // The target section header must already exist (same constraint as add_method).
+            const anchor = findSectionAnchor(main, structure, target);
+            if (!anchor) {
+                return errorResult(`No ${target.toUpperCase()} SECTION exists in CLAS ${name}. Use SAPWrite(action="edit_class_definition") to add the section header first, then re-run change_method_visibility.`);
+            }
+            // DEFINITION-only move — IMPLEMENTATION (the method body) is preserved verbatim.
+            const spliced = moveMethodDefinition(main, method, anchor.afterLine);
+            const lintWarnings = runPreWriteLint(spliced, type, name, config, lintOverride);
+            if (lintWarnings.blocked)
+                return lintWarnings.result;
+            await safeUpdateSource(client.http, client.safety, objectUrl, srcUrl, spliced, transport, cachedFeatures?.abapRelease);
+            invalidateWrittenObject(type, name);
+            return textResult(`Successfully moved method "${method.name}" from ${method.visibility.toUpperCase()} to ${target.toUpperCase()} SECTION of ${type} ${name} (IMPLEMENTATION preserved). Active version unchanged until activation; SAPActivate next.`);
+        }
         case 'scaffold_rap_handlers': {
             // What this action does:
             //   Given a behavior-pool class (ZBP_*) and its interface BDEF, inspect
@@ -3581,7 +4088,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
@@ -3608,15 +4117,20 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
             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;
                 return { obj, type: objType, name: objName, packageName: objPackage, explicitTransport };
             });
             // Check every target package before starting any creates.
-            for (const pkg of new Set(batchPlan.map((item) => item.packageName))) {
-                checkPackage(client.safety, pkg);
+            // Resolver is shared across the loop so subtree BFS happens once even when
+            // many objects target descendants of the same `ZFOO/**` root.
+            {
+                const resolver = client.getPackageHierarchyResolver();
+                for (const pkg of new Set(batchPlan.map((item) => item.packageName))) {
+                    await checkPackage(client.safety, pkg, resolver);
+                }
             }
             // Pre-flight transport check for batch_create (same logic as single create),
             // but keyed by each effective package because objects can override package.
@@ -3749,13 +4263,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);
                     }
@@ -3879,11 +4404,11 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                     const batchStatuses = buildBatchActivationStatuses(writtenObjects, activationOutcome);
                     const statusDetails = formatBatchActivationStatuses(batchStatuses);
                     terminalActivationFailure = statusDetails;
-                    const statusByName = new Map(batchStatuses.map((s) => [`${s.type}${s.name}`, s]));
+                    const statusByName = new Map(batchStatuses.map((s) => [`${s.type}\x00${s.name}`, s]));
                     for (const result of results) {
                         if (result.status !== 'success')
                             continue;
-                        const key = `${result.type}${result.name}`;
+                        const key = `${result.type}\x00${result.name}`;
                         const matched = statusByName.get(key);
                         if (!matched)
                             continue;
@@ -3942,7 +4467,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,
     });
@@ -4196,7 +4722,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();
@@ -4238,15 +4769,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();
@@ -4906,7 +5448,7 @@ async function handleSAPGit(client, args, _authInfo) {
                     password,
                     token,
                 };
-                result = await gctsCloneRepo(client.http, client.safety, params);
+                result = await gctsCloneRepo(client.http, client.safety, params, client.getPackageHierarchyResolver());
             }
             else {
                 if (!packageName)
@@ -4918,7 +5460,7 @@ async function handleSAPGit(client, args, _authInfo) {
                     transportRequest: String(args.transport ?? '').trim() || undefined,
                     user,
                     password,
-                });
+                }, client.getPackageHierarchyResolver());
             }
             break;
         case 'pull':
@@ -4976,7 +5518,7 @@ async function handleSAPGit(client, args, _authInfo) {
                 result = await gctsCreateBranch(client.http, client.safety, repoId, {
                     branch,
                     ...(packageName ? { package: packageName } : {}),
-                });
+                }, client.getPackageHierarchyResolver());
             }
             else {
                 await abapGitCreateBranch(client.http, client.safety, repoId, branch);
@@ -5477,10 +6019,19 @@ async function handleSAPManage(client, config, args, cachingLayer, isPerUserClie
             if (!description)
                 return errorResult('"description" is required for create_package action.');
             checkOperation(client.safety, OperationType.Create, 'CreatePackage');
-            // Package allowlist is enforced on the parent package, not the new package name.
-            // This enables creating children in allowed parents like $TMP.
+            // Package allowlist gate:
+            // - When `superPackage` is set, gate the parent. This enables creating
+            //   children in allowed parents like $TMP. With subtree (`X/**`) rules,
+            //   the new child will automatically be inside its parent's subtree.
+            // - When `superPackage` is omitted, the new package is created at the
+            //   root and IS the gateable name itself — otherwise an admin's
+            //   allowedPackages restriction would be bypassed by simply omitting
+            //   the parent. Gate the new name in that case.
             if (superPackage) {
-                checkPackage(client.safety, superPackage);
+                await checkPackage(client.safety, superPackage, client.getPackageHierarchyResolver());
+            }
+            else {
+                await checkPackage(client.safety, name, client.getPackageHierarchyResolver());
             }
             let effectiveTransport = transport || undefined;
             const packageUrl = `/sap/bc/adt/packages/${encodeURIComponent(name)}`;
@@ -5523,6 +6074,9 @@ async function handleSAPManage(client, config, args, cachingLayer, isPerUserClie
                 packageType,
             });
             await createObject(client.http, client.safety, '/sap/bc/adt/packages', xml, 'application/*', effectiveTransport, undefined, cachedFeatures?.abapRelease);
+            // Hierarchy changed: invalidate any cached subtree that could contain
+            // the new package. Conservative: clear all (cheap; per-call cost is one BFS).
+            client.invalidatePackageHierarchy();
             return textResult(`Created package ${name}.`);
         }
         case 'delete_package': {
@@ -5531,6 +6085,9 @@ async function handleSAPManage(client, config, args, cachingLayer, isPerUserClie
             if (!name)
                 return errorResult('"name" is required for delete_package action.');
             checkOperation(client.safety, OperationType.Delete, 'DeletePackage');
+            // Gate by allowedPackages: deletion targets the package itself, so the
+            // package name must be in the allowed set (or in an allowed subtree).
+            await checkPackage(client.safety, name, client.getPackageHierarchyResolver());
             const packageUrl = `/sap/bc/adt/packages/${encodeURIComponent(name)}`;
             await client.http.withStatefulSession(async (session) => {
                 const lock = await lockObject(session, client.safety, packageUrl, 'MODIFY', cachedFeatures?.abapRelease);
@@ -5547,6 +6104,8 @@ async function handleSAPManage(client, config, args, cachingLayer, isPerUserClie
                     }
                 }
             });
+            // Hierarchy changed: invalidate cached subtrees.
+            client.invalidatePackageHierarchy();
             return textResult(`Deleted package ${name}.`);
         }
         case 'change_package': {
@@ -5565,8 +6124,11 @@ async function handleSAPManage(client, config, args, cachingLayer, isPerUserClie
             if (!newPackage)
                 return errorResult('"newPackage" is required for change_package action.');
             checkOperation(client.safety, OperationType.Update, 'ChangePackage');
-            checkPackage(client.safety, oldPackage);
-            checkPackage(client.safety, newPackage);
+            {
+                const resolver = client.getPackageHierarchyResolver();
+                await checkPackage(client.safety, oldPackage, resolver);
+                await checkPackage(client.safety, newPackage, resolver);
+            }
             // Resolve object URI via search if not provided
             if (!objectUri) {
                 const searchResp = await client.http.get(`/sap/bc/adt/repository/informationsystem/search?operation=quickSearch&query=${encodeURIComponent(objectName)}&maxResults=10`);
@@ -5612,6 +6174,8 @@ async function handleSAPManage(client, config, args, cachingLayer, isPerUserClie
                 newPackage,
                 transport: effectiveTransport,
             });
+            // Hierarchy may have shifted (object moved between packages); invalidate cache.
+            client.invalidatePackageHierarchy();
             const transportNote = result.transport ? ` (transport: ${result.transport})` : '';
             return textResult(`Moved ${objectName} from package ${oldPackage} to ${newPackage}${transportNote}.`);
         }