arc-1 0.6.10 → 0.7.0

package/dist/handlers/intent.js

@@ -2,7 +2,7 @@
  * Intent-based tool handler for ARC-1.
  *
  * Routes MCP tool calls to the appropriate ADT client methods.
- * Each of the 11 tools (SAPRead, SAPSearch, etc.) dispatches
+ * Each of the 12 tools (SAPRead, SAPSearch, etc.) dispatches
  * based on its `type` or `action` parameter.
  *
  * Error handling: all errors are caught and returned as MCP error
@@ -10,16 +10,18 @@
  * leaked to the LLM — only user-friendly error messages.
  */
 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 { classifyCdsImpact } from '../adt/cds-impact.js';
-import { findDefinition, findReferences, findWhereUsed, getCompletion, } from '../adt/codeintel.js';
-import { createObject, deleteObject, lockObject, safeUpdateObject, safeUpdateSource, unlockObject, updateObject, } from '../adt/crud.js';
+import { buildSiblingExtensionFinding, classifyCdsImpact, deriveSiblingStem, isSiblingNameMatch, } from '../adt/cds-impact.js';
+import { findDefinition, findReferences, findWhereUsed, getCompletion, getWhereUsedScope, } from '../adt/codeintel.js';
+import { createObject, deleteObject, lockObject, 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, getTraceDbAccesses, getTraceHitlist, getTraceStatements, listDumps, listTraces, } from '../adt/diagnostics.js';
+import { getDump, getGatewayErrorDetail, getTraceDbAccesses, getTraceHitlist, getTraceStatements, listDumps, listGatewayErrors, listSystemMessages, listTraces, } from '../adt/diagnostics.js';
 import { AdtApiError, AdtNetworkError, AdtSafetyError, classifySapDomainError, isNotFoundError, } from '../adt/errors.js';
 import { classifyTextSearchError, mapSapReleaseToAbaplintVersion, probeFeatures } from '../adt/features.js';
 import { addTileToGroup, createCatalog, createGroup, createTile, deleteCatalog, listCatalogs, listGroups, listTiles, } from '../adt/flp.js';
 import { cloneRepo as gctsCloneRepo, commitRepo as gctsCommitRepo, createBranch as gctsCreateBranch, deleteRepo as gctsDeleteRepo, getCommitHistory as gctsGetCommitHistory, getConfig as gctsGetConfig, getUserInfo as gctsGetUserInfo, listBranches as gctsListBranches, listRepoObjects as gctsListRepoObjects, listRepos as gctsListRepos, pullRepo as gctsPullRepo, switchBranch as gctsSwitchBranch, } from '../adt/gcts.js';
+import { applyRapHandlerScaffold, extractRapHandlerRequirements, findMissingRapHandlerImplementationStubs, findMissingRapHandlerRequirements, } from '../adt/rap-handlers.js';
+import { formatRapPreflightFindings, validateRapSource } from '../adt/rap-preflight.js';
 import { changePackage } from '../adt/refactoring.js';
 import { checkOperation, checkPackage, isOperationAllowed, OperationType } from '../adt/safety.js';
 import { createTransport, deleteTransport, getObjectTransports, getTransport, getTransportInfo, listTransports, reassignTransport, releaseTransport, releaseTransportRecursive, } from '../adt/transport.js';
@@ -33,66 +35,46 @@ 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 { expandHyperfocusedArgs, getHyperfocusedScope } from './hyperfocused.js';
+import { expandHyperfocusedArgs } from './hyperfocused.js';
 import { getToolSchema } from './schemas.js';
 import { formatZodError } from './zod-errors.js';
 /**
  * Scope required for each tool.
  *
  * Scope enforcement is ADDITIVE to the safety system:
- * - Safety system (readOnly, allowedOps, etc.) gates operations at the ADT client level
+ * - Safety system (allowWrites, allowedPackages, etc.) gates operations at the ADT client level
  * - Scopes gate operations at the MCP tool level (only enforced when authInfo is present)
  * - Both must pass for an operation to succeed
  *
- * A user with `write` scope but `readOnly=true` in config still can't write.
+ * A user with `write` scope but `allowWrites=false` in config still can't write.
+ *
+ * Scope lookup and implication rules are defined in `src/authz/policy.ts` (ACTION_POLICY,
+ * getActionPolicy, hasRequiredScope). This module routes through them.
  */
-export const TOOL_SCOPES = {
-    SAPRead: 'read',
-    SAPSearch: 'read',
-    SAPQuery: 'sql',
-    SAPGit: 'read',
-    SAPNavigate: 'read',
-    SAPContext: 'read',
-    SAPLint: 'read',
-    SAPDiagnose: 'read',
-    SAPWrite: 'write',
-    SAPActivate: 'write',
-    SAPManage: 'write',
-    SAPTransport: 'write',
-};
-const SAPGIT_ACTION_SCOPES = {
-    list_repos: 'read',
-    whoami: 'read',
-    config: 'read',
-    branches: 'read',
-    external_info: 'read',
-    history: 'read',
-    objects: 'read',
-    check: 'read',
-    clone: 'write',
-    pull: 'write',
-    push: 'write',
-    commit: 'write',
-    stage: 'write',
-    switch_branch: 'write',
-    create_branch: 'write',
-    unlink: 'write',
-};
+import { getActionPolicy, hasRequiredScope as hasScopeHelper } from '../authz/policy.js';
+/**
+ * Back-compat re-export of a tool→scope map derived from ACTION_POLICY.
+ * New code should use `getActionPolicy(tool, action)` directly.
+ */
+export const TOOL_SCOPES = Object.fromEntries([
+    'SAPRead',
+    'SAPSearch',
+    'SAPQuery',
+    'SAPGit',
+    'SAPNavigate',
+    'SAPContext',
+    'SAPLint',
+    'SAPDiagnose',
+    'SAPWrite',
+    'SAPActivate',
+    'SAPManage',
+    'SAPTransport',
+].map((t) => [t, getActionPolicy(t)?.scope ?? 'read']));
 /**
- * Check if authInfo has the required scope, respecting implied scopes:
- * - `write` implies `read`
- * - `sql` implies `data`
+ * Check if authInfo has the required scope, routing through policy.hasRequiredScope.
  */
 export function hasRequiredScope(authInfo, requiredScope) {
-    const scopes = authInfo.scopes;
-    if (scopes.includes(requiredScope))
-        return true;
-    // Implied scopes
-    if (requiredScope === 'read' && scopes.includes('write'))
-        return true;
-    if (requiredScope === 'data' && scopes.includes('sql'))
-        return true;
-    return false;
+    return hasScopeHelper(authInfo.scopes, requiredScope);
 }
 function textResult(text) {
     return { content: [{ type: 'text', text }] };
@@ -102,6 +84,64 @@ function errorResult(message) {
 }
 const DDIC_SAVE_HINT_TYPES = new Set(['TABL', 'DDLS', 'DCLS', 'BDEF', 'SRVD', 'SRVB', 'DDLX', 'DOMA', 'DTEL']);
 const DDIC_POST_SAVE_CHECK_TYPES = new Set(['TABL', 'DDLS', 'DCLS', 'BDEF', 'SRVD', 'SRVB', 'DDLX']);
+const CDS_DEPENDENCY_SENSITIVE_TYPES = new Set(['DDLS', 'DCLS', 'DDLX', 'BDEF', 'SRVD', 'SRVB', 'TABL']);
+const CDS_IMPACT_BUCKET_ORDER = [
+    'projectionViews',
+    'bdefs',
+    'serviceDefinitions',
+    'serviceBindings',
+    'accessControls',
+    'metadataExtensions',
+    'abapConsumers',
+    'tables',
+    'documentation',
+    'other',
+];
+const CDS_IMPACT_BUCKET_LABEL = {
+    projectionViews: 'Projection views (DDLS)',
+    bdefs: 'Behavior definitions (BDEF)',
+    serviceDefinitions: 'Service definitions (SRVD)',
+    serviceBindings: 'Service bindings (SRVB)',
+    accessControls: 'Access controls (DCLS)',
+    metadataExtensions: 'Metadata extensions (DDLX)',
+    abapConsumers: 'ABAP consumers',
+    tables: 'Tables',
+    documentation: 'Documentation (SKTD)',
+    other: 'Other',
+};
+const CDS_REACTIVATION_BUCKET_ORDER = [
+    'projectionViews',
+    'accessControls',
+    'metadataExtensions',
+    'bdefs',
+    'serviceDefinitions',
+    'serviceBindings',
+    'other',
+];
+const CDS_DELETE_BUCKET_ORDER = [
+    'serviceBindings',
+    'serviceDefinitions',
+    'bdefs',
+    'metadataExtensions',
+    'accessControls',
+    'projectionViews',
+    'other',
+];
+const CDS_ORDERABLE_TYPES = new Set(['DDLS', 'DCLS', 'DDLX', 'BDEF', 'SRVD', 'SRVB']);
+const CDS_IMPACT_WHERE_USED_TYPES = new Set([
+    'DDLS',
+    'DCLS',
+    'DDLX',
+    'BDEF',
+    'SRVD',
+    'SRVB',
+    'CLAS',
+    'INTF',
+    'PROG',
+    'FUGR',
+    'TABL',
+    'SKTD',
+]);
 // ─── Search Helpers ─────────────────────────────────────────────────
 /**
  * Transliterate non-ASCII characters in search queries.
@@ -142,8 +182,44 @@ export function looksLikeFieldName(query) {
         return false;
     return true;
 }
+function hasSqlParserSignature(text) {
+    const normalized = text.toLowerCase();
+    return (normalized.includes('only one select statement is allowed') ||
+        normalized.includes('only select statement is allowed') ||
+        normalized.includes('invalid query string') ||
+        normalized.includes('due to grammar') ||
+        normalized.includes('is invalid here') ||
+        normalized.includes('is invalid at this position'));
+}
+function getWriteInfrastructureHint(err, tool, args) {
+    if (tool !== 'SAPWrite')
+        return undefined;
+    const action = String(args.action ?? '').toLowerCase();
+    if (!['create', 'update', 'batch_create', 'edit_method', 'delete'].includes(action))
+        return undefined;
+    // These failures happen around ADT session management, often after SAP has
+    // already accepted a mutation. They need cleanup guidance, not DDIC syntax hints.
+    const combined = `${err.message}\n${err.responseBody ?? ''}\n${err.path}`.toLowerCase();
+    const failedDuringCsrfFetch = err.path.includes('/sap/bc/adt/core/discovery') || combined.includes('no csrf token');
+    const failedDuringUnlock = combined.includes('_action=unlock');
+    const serviceRoutingFailure = combined.includes('service cannot be reached');
+    if (!failedDuringCsrfFetch && !failedDuringUnlock && !serviceRoutingFailure)
+        return undefined;
+    return ('SAP ADT write/session infrastructure failed, not a DDIC source save failure. ' +
+        'The object may have been partially created or changed before the session failed; verify with SAPRead/SAPSearch, ' +
+        'wait briefly, then retry cleanup. If an edit lock remains, release it in ADT/SM12 or ask Basis to clear it.');
+}
 /** Format error messages with LLM-friendly remediation hints */
-function formatErrorForLLM(err, message, _tool, args) {
+function formatErrorForLLM(err, message, tool, args) {
+    const base = buildBaseErrorMessage(err, message, tool, args);
+    // Handler-attached remediation hints (e.g., CDS delete blocker list) always
+    // appear last so the message reads "what happened → diagnostics → how to fix".
+    if (err instanceof AdtApiError && err.extraHint && !base.includes(err.extraHint)) {
+        return `${base}\n\n${err.extraHint}`;
+    }
+    return base;
+}
+function buildBaseErrorMessage(err, message, tool, args) {
     if (err instanceof AdtApiError) {
         // Append additional SAP messages (line numbers, secondary errors) if available
         const enriched = enrichWithSapDetails(err, message);
@@ -154,6 +230,10 @@ function formatErrorForLLM(err, message, _tool, args) {
             return `${enriched}\n\nHint: ${classification.hint}${transactionLine}`;
         }
         if (err.isNotFound) {
+            const diagnosticsHint = buildDiagnosticsNotFoundHint(tool, args);
+            if (diagnosticsHint) {
+                return `${enriched}\n\nHint: ${diagnosticsHint}`;
+            }
             const name = String(args.name ?? '');
             const type = String(args.type ?? '');
             return `${enriched}\n\nHint: Object "${name}" (type ${type}) was not found. Use SAPSearch with query "${name}" to verify the name exists and check the correct type.`;
@@ -166,7 +246,31 @@ function formatErrorForLLM(err, message, _tool, args) {
         if (transportHint) {
             return `${enriched}\n\nHint: ${transportHint}`;
         }
-        if ((err.statusCode === 400 || err.statusCode === 409) && DDIC_SAVE_HINT_TYPES.has(argType)) {
+        if (tool === 'SAPRead' && argType === 'TABLE_CONTENTS' && err.statusCode === 400) {
+            const combined = `${err.message}\n${err.responseBody ?? ''}`;
+            if (hasSqlParserSignature(combined)) {
+                return (`${enriched}\n\nHint: TABLE_CONTENTS sqlFilter must be a condition expression only ` +
+                    '(no WHERE, no SELECT, no semicolon). Examples: ' +
+                    `sqlFilter="MANDT = '100'" or sqlFilter="MATNR LIKE 'Z%'".`);
+            }
+        }
+        const behaviorPoolHint = getBehaviorPoolSaveFailureHint(err, args);
+        if (behaviorPoolHint) {
+            return `${enriched}\n\nHint: ${behaviorPoolHint}`;
+        }
+        const writeInfrastructureHint = getWriteInfrastructureHint(err, tool, args);
+        if (writeInfrastructureHint) {
+            return `${enriched}\n\nHint: ${writeInfrastructureHint}`;
+        }
+        // Save hint — applies to create/update/batch_create/edit_method, not delete.
+        // Delete failures on DDIC types have different remediation (dependency resolution, not annotation fixes).
+        const action = String(args.action ?? '').toLowerCase();
+        const isSaveAction = action === '' ||
+            action === 'create' ||
+            action === 'update' ||
+            action === 'batch_create' ||
+            action === 'edit_method';
+        if ((err.statusCode === 400 || err.statusCode === 409) && DDIC_SAVE_HINT_TYPES.has(argType) && isSaveAction) {
             return (`${enriched}\n\nHint: DDIC save failed. Check the diagnostic details above for specific field or annotation errors. ` +
                 'Common fixes: add missing @AbapCatalog annotations, fix field type names, check key field definitions.');
         }
@@ -182,11 +286,92 @@ function formatErrorForLLM(err, message, _tool, args) {
         }
         return enriched;
     }
+    if (err instanceof AdtSafetyError) {
+        const argType = 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, ' +
+                'ensure the token includes data (or sql) scope.');
+        }
+        return message;
+    }
     if (err instanceof AdtNetworkError) {
-        return `${message}\n\nHint: Cannot reach the SAP system. This is a connectivity issue, not a usage error.`;
+        if (tool === 'SAPRead' && String(args.type ?? '').toUpperCase() === 'SYSTEM') {
+            return (`${message}\n\nHint: Connectivity probe failed. Fix connectivity first, then retry ` +
+                'SAPRead(type="SYSTEM") before running any batch or parallel tool calls.');
+        }
+        return (`${message}\n\nHint: Cannot reach the SAP system. Run SAPRead(type="SYSTEM") once as a connectivity ` +
+            'probe before retrying batch/parallel calls.');
     }
     return message;
 }
+function buildDiagnosticsNotFoundHint(tool, args) {
+    if (tool !== 'SAPDiagnose')
+        return undefined;
+    const action = String(args.action ?? '');
+    const id = String(args.id ?? '').trim();
+    const detailUrl = String(args.detailUrl ?? '').trim();
+    if (action === 'dumps' && id) {
+        return `Dump ID "${id}" was not found. Re-list dumps with SAPDiagnose(action="dumps", maxResults=50), then retry with a fresh ID from that list.`;
+    }
+    if (action === 'traces' && id) {
+        return `Trace ID "${id}" was not found. Re-list traces with SAPDiagnose(action="traces") and retry using an existing trace ID.`;
+    }
+    if (action === 'gateway_errors' && (detailUrl || id)) {
+        return 'Gateway error detail was not found. Re-list SAPDiagnose(action="gateway_errors") and reuse a current detailUrl from the list output.';
+    }
+    return undefined;
+}
+function buildAuditResultPreview(toolName, args, fullText) {
+    const maxLen = 500;
+    const truncate = (value) => (value.length > maxLen ? `${value.slice(0, maxLen)}...` : value);
+    if (toolName !== 'SAPDiagnose')
+        return truncate(fullText);
+    const action = String(args.action ?? '');
+    const isDetailDump = action === 'dumps' && Boolean(args.id);
+    const isDetailGateway = action === 'gateway_errors' && (Boolean(args.detailUrl) || (Boolean(args.id) && Boolean(args.errorType)));
+    if (!isDetailDump && !isDetailGateway)
+        return truncate(fullText);
+    try {
+        const payload = JSON.parse(fullText);
+        if (isDetailDump) {
+            const sections = payload.sections && typeof payload.sections === 'object' ? payload.sections : {};
+            const compact = {
+                id: payload.id,
+                error: payload.error,
+                program: payload.program,
+                user: payload.user,
+                timestamp: payload.timestamp,
+                selectedSectionIds: payload.selectedSectionIds,
+                sections: Object.fromEntries(Object.entries(sections).map(([key, value]) => {
+                    if (typeof value === 'string')
+                        return [key, `[omitted ${value.length} chars]`];
+                    return [key, '[omitted]'];
+                })),
+                formattedText: typeof payload.formattedText === 'string' ? `[omitted ${payload.formattedText.length} chars]` : undefined,
+            };
+            return truncate(JSON.stringify(compact));
+        }
+        if (isDetailGateway && payload.sourceCode && typeof payload.sourceCode === 'object') {
+            const sourceCode = payload.sourceCode;
+            const lines = Array.isArray(sourceCode.lines) ? sourceCode.lines.length : 0;
+            const compact = {
+                type: payload.type,
+                shortText: payload.shortText,
+                transactionId: payload.transactionId,
+                username: payload.username,
+                dateTime: payload.dateTime,
+                sourceCode: `[omitted ${lines} lines]`,
+                callStackCount: Array.isArray(payload.callStack) ? payload.callStack.length : 0,
+            };
+            return truncate(JSON.stringify(compact));
+        }
+        return truncate(JSON.stringify(payload));
+    }
+    catch {
+        return truncate(fullText);
+    }
+}
 /** Enrich error message with additional SAP XML diagnostic detail (extra messages, properties) */
 function enrichWithSapDetails(err, message) {
     if (!err.responseBody)
@@ -218,9 +403,225 @@ function enrichWithSapDetails(err, message) {
     }
     return parts.join('\n');
 }
-async function tryPostSaveSyntaxCheck(client, type, name) {
-    if (!DDIC_POST_SAVE_CHECK_TYPES.has(type.toUpperCase()))
+function isDeleteDependencyError(err) {
+    const clean = AdtApiError.extractCleanMessage(err.responseBody ?? err.message).toLowerCase();
+    const body = (err.responseBody ?? '').toLowerCase();
+    const diagnostics = err.responseBody ? AdtApiError.extractDdicDiagnostics(err.responseBody) : [];
+    if (diagnostics.some((diag) => diag.messageNumber === '039'))
+        return true;
+    return /could not be deleted|cannot be deleted|still in use|used by|dependent object|existing reference/.test(`${clean}\n${body}`);
+}
+function formatCdsImpactBuckets(downstream, maxNames = 4) {
+    const lines = [];
+    for (const bucket of CDS_IMPACT_BUCKET_ORDER) {
+        const entries = downstream[bucket];
+        if (entries.length === 0)
+            continue;
+        const unique = Array.from(new Set(entries.map((entry) => {
+            const mainType = entry.type.split('/')[0] || entry.type || '?';
+            return `${entry.name} (${mainType})`;
+        })));
+        const listed = unique.slice(0, maxNames).join(', ');
+        const more = unique.length > maxNames ? ` (+${unique.length - maxNames} more)` : '';
+        lines.push(`- ${CDS_IMPACT_BUCKET_LABEL[bucket]}: ${listed}${more}`);
+    }
+    return lines;
+}
+function mainObjectType(type) {
+    return type.split('/')[0]?.toUpperCase() ?? '';
+}
+function collectOrderedCdsObjects(downstream, bucketOrder) {
+    const seen = new Set();
+    const ordered = [];
+    for (const bucket of bucketOrder) {
+        for (const entry of downstream[bucket]) {
+            const type = mainObjectType(entry.type);
+            const name = String(entry.name ?? '').toUpperCase();
+            if (!type || !name || !CDS_ORDERABLE_TYPES.has(type))
+                continue;
+            const key = `${type}:${name}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            ordered.push({ type, name });
+        }
+    }
+    return ordered;
+}
+function dedupeCdsObjects(objects) {
+    const seen = new Set();
+    const deduped = [];
+    for (const obj of objects) {
+        const key = `${obj.type}:${obj.name.toUpperCase()}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        deduped.push(obj);
+    }
+    return deduped;
+}
+function formatCdsObjectList(objects, max = 8) {
+    if (objects.length === 0)
         return '';
+    const listed = objects
+        .slice(0, max)
+        .map((obj) => `${obj.type} ${obj.name}`)
+        .join(', ');
+    return objects.length > max ? `${listed} (+${objects.length - max} more)` : listed;
+}
+function formatCdsActivationPayload(objects, max = 8) {
+    if (objects.length === 0)
+        return '[]';
+    const listed = objects
+        .slice(0, max)
+        .map((obj) => `{type:"${obj.type}",name:"${obj.name}"}`)
+        .join(', ');
+    return objects.length > max ? `[${listed}, ...] (+${objects.length - max} more)` : `[${listed}]`;
+}
+function dedupeWhereUsedResults(results) {
+    const seen = new Set();
+    const deduped = [];
+    for (const result of results) {
+        const uriKey = result.uri.toLowerCase();
+        const fallbackKey = `${mainObjectType(result.type)}:${String(result.name ?? '').toUpperCase()}`;
+        const key = uriKey || fallbackKey;
+        if (!key || seen.has(key))
+            continue;
+        seen.add(key);
+        deduped.push(result);
+    }
+    return deduped;
+}
+function isCdsImpactWhereUsedType(objectType) {
+    return CDS_IMPACT_WHERE_USED_TYPES.has(mainObjectType(objectType));
+}
+async function loadScopedCdsWhereUsedResults(client, objectUrl) {
+    try {
+        const scope = await getWhereUsedScope(client.http, client.safety, objectUrl);
+        const scopedTypes = Array.from(new Set(scope.entries
+            .filter((entry) => entry.count > 0 && isCdsImpactWhereUsedType(entry.objectType))
+            .map((entry) => entry.objectType)));
+        const scopedResults = [];
+        for (const objectType of scopedTypes) {
+            try {
+                scopedResults.push(...(await findWhereUsed(client.http, client.safety, objectUrl, objectType)));
+            }
+            catch {
+                // Scoped results only enrich guidance; one unsupported filter must not
+                // make the write/delete/activate path fail.
+            }
+        }
+        return scopedResults;
+    }
+    catch (err) {
+        if (err instanceof AdtApiError && [404, 405, 415, 501].includes(err.statusCode)) {
+            return [];
+        }
+        // Where-used enrichment is advisory; the original write/delete/activate
+        // result should not fail just because a scoped lookup is unavailable.
+        return [];
+    }
+}
+async function loadCdsImpactDownstream(client, objectUrl) {
+    try {
+        const whereUsed = await findWhereUsed(client.http, client.safety, objectUrl);
+        // Some SAP releases return a shallow/default result set for unfiltered
+        // usageReferences. Scope + object-type filters usually expose the full
+        // bucket fan-out, which is exactly what CRUD guidance needs.
+        const scopedWhereUsed = await loadScopedCdsWhereUsedResults(client, objectUrl);
+        const combinedWhereUsed = dedupeWhereUsedResults([...whereUsed, ...scopedWhereUsed]);
+        return classifyCdsImpact(combinedWhereUsed, { includeIndirect: true });
+    }
+    catch (err) {
+        if (err instanceof AdtApiError && [404, 405, 415, 501].includes(err.statusCode)) {
+            return undefined;
+        }
+        return undefined;
+    }
+}
+async function buildCdsUpdateCrudHint(client, name, objectUrl) {
+    const lines = [];
+    lines.push(`CDS update follow-up for ${name}:`);
+    const downstream = await loadCdsImpactDownstream(client, objectUrl);
+    let orderedReactivation = [];
+    if (downstream) {
+        const bucketLines = formatCdsImpactBuckets(downstream);
+        if (bucketLines.length > 0) {
+            lines.push(`- Downstream consumers in ADT where-used index: ${downstream.summary.total}`);
+            lines.push(...bucketLines);
+            orderedReactivation = collectOrderedCdsObjects(downstream, CDS_REACTIVATION_BUCKET_ORDER);
+        }
+        else {
+            lines.push('- No downstream consumers found in the current ADT where-used index.');
+        }
+    }
+    else {
+        lines.push('- Where-used index is unavailable on this system (impact list could not be fetched).');
+    }
+    lines.push(`- SAPWrite(update) stores inactive source only. Run SAPActivate(type="DDLS", name="${name}").`);
+    lines.push('- Field/alias/signature changes may require re-activation of dependent DDLS/BDEF/SRVD/DDLX objects.');
+    if (orderedReactivation.length > 0) {
+        const activationPlan = dedupeCdsObjects([{ type: 'DDLS', name }, ...orderedReactivation]);
+        lines.push(`- Suggested re-activation order: ${formatCdsObjectList(activationPlan)}.`);
+        lines.push(`- Batch call template: SAPActivate(objects=${formatCdsActivationPayload(activationPlan)}).`);
+    }
+    return lines.join('\n');
+}
+async function buildCdsDeleteDependencyHint(client, type, name, objectUrl) {
+    const downstream = await loadCdsImpactDownstream(client, objectUrl);
+    if (!downstream || downstream.summary.total === 0) {
+        const lines = [];
+        lines.push(`Delete dependency follow-up for ${type} ${name}:`);
+        if (!downstream) {
+            lines.push('- ADT where-used lookup is unavailable on this system or failed during error enrichment.');
+        }
+        else {
+            lines.push('- No current ADT where-used dependents were returned, but SAP still rejected delete with a DDIC dependency error.');
+        }
+        lines.push('- If dependents were just deleted, wait briefly and retry; SAP active dependency/index state can lag in the same cleanup session.');
+        lines.push(`- If source was stripped or restored, run SAPActivate(type="${type}", name="${name}") first; delete checks active DDIC dependencies.`);
+        lines.push(`- If it keeps failing, run SAPNavigate(action="references", type="${type}", name="${name}") and check for edit locks/inactive objects before retrying.`);
+        return lines.join('\n');
+    }
+    const lines = [];
+    lines.push(`Blocking dependents for ${type} ${name} (ADT where-used):`);
+    lines.push(...formatCdsImpactBuckets(downstream));
+    const orderedDelete = collectOrderedCdsObjects(downstream, CDS_DELETE_BUCKET_ORDER);
+    if (orderedDelete.length > 0) {
+        lines.push(`Suggested delete order: ${formatCdsObjectList(orderedDelete)}, then ${type} ${name}.`);
+    }
+    lines.push(`Delete/refactor these dependents first, then retry SAPWrite(action="delete", type="${type}", name="${name}").`);
+    lines.push('If the listed dependents were just deleted, wait briefly and retry; SAP active dependency/index state can lag in the same cleanup session.');
+    lines.push('For cyclic CDS projection graphs, temporarily strip redirected/composition associations, activate stripped DDLS, then delete.');
+    lines.push('If source was already stripped, activate first — delete checks active version dependencies.');
+    return lines.join('\n');
+}
+async function buildCdsActivationDependencyHint(client, name, objectUrl) {
+    const lines = [];
+    const downstream = await loadCdsImpactDownstream(client, objectUrl);
+    let orderedReactivation = [];
+    lines.push(`CDS activation impact for ${name}:`);
+    if (!downstream || downstream.summary.total === 0) {
+        lines.push('- No downstream consumers found in ADT where-used index, or index is unavailable.');
+    }
+    else {
+        lines.push(...formatCdsImpactBuckets(downstream));
+        orderedReactivation = collectOrderedCdsObjects(downstream, CDS_REACTIVATION_BUCKET_ORDER);
+    }
+    lines.push('- When fields/elements change, dependents may fail until re-activated in dependency order.');
+    if (orderedReactivation.length > 0) {
+        const activationPlan = dedupeCdsObjects([{ type: 'DDLS', name }, ...orderedReactivation]);
+        lines.push(`- Suggested re-activation order: ${formatCdsObjectList(activationPlan)}.`);
+        lines.push(`- Batch call template: SAPActivate(objects=${formatCdsActivationPayload(activationPlan)}).`);
+    }
+    else {
+        lines.push(`- Try SAPActivate(objects=[{type:"DDLS",name:"${name}"}, ...dependents...]).`);
+    }
+    return lines.join('\n');
+}
+/** Run a syntax check on the inactive version and format the errors for appending to an
+ *  error message. Returns '' on any failure or when no errors are reported. */
+async function inactiveSyntaxDiagnostic(client, type, name) {
     try {
         const checkResult = await syntaxCheck(client.http, client.safety, objectUrlForType(type, name), {
             version: 'inactive',
@@ -231,8 +632,9 @@ async function tryPostSaveSyntaxCheck(client, type, name) {
         if (errors.length === 0)
             return '';
         const lines = errors.map((msg) => {
-            const line = msg.line ? `Line ${msg.line}` : 'Line ?';
-            return `  - ${line}: ${msg.text}`;
+            const prefix = msg.line ? `[line ${msg.line}] ` : '';
+            const suffix = msg.uri ? ` (${msg.uri})` : '';
+            return `- ${prefix}${msg.text}${suffix}`;
         });
         return `\nServer syntax check (inactive):\n${lines.join('\n')}`;
     }
@@ -240,6 +642,11 @@ async function tryPostSaveSyntaxCheck(client, type, name) {
         return '';
     }
 }
+async function tryPostSaveSyntaxCheck(client, type, name) {
+    if (!DDIC_POST_SAVE_CHECK_TYPES.has(type.toUpperCase()))
+        return '';
+    return inactiveSyntaxDiagnostic(client, type, name);
+}
 /** Detect transport/corrNr failure signatures and return a remediation hint, or undefined if not transport-related. */
 function getTransportHint(err) {
     const body = (err.responseBody ?? '').toLowerCase();
@@ -275,6 +682,34 @@ function getTransportHint(err) {
     }
     return undefined;
 }
+function inferBdefNameFromBehaviorPoolSource(source) {
+    const match = source.match(/\bfor\s+behavior\s+of\s+([A-Za-z_][\w/]+)/i);
+    return match?.[1];
+}
+function getBehaviorPoolSaveFailureHint(err, args) {
+    const type = normalizeObjectType(String(args.type ?? ''));
+    if (type !== 'CLAS')
+        return undefined;
+    const name = String(args.name ?? '');
+    const source = String(args.source ?? '');
+    const clean = AdtApiError.extractCleanMessage(err.responseBody ?? '').toLowerCase();
+    const body = (err.responseBody ?? '').toLowerCase();
+    const isGenericSaveFailure = clean.includes('an error occured during the save operation') ||
+        clean.includes('an error occurred during the save operation') ||
+        body.includes('an error occured during the save operation') ||
+        body.includes('an error occurred during the save operation');
+    if (!isGenericSaveFailure)
+        return undefined;
+    const looksLikeBehaviorPool = /\bfor\s+behavior\s+of\b/i.test(source) || /^zbp_/i.test(name) || /^ybp_/i.test(name);
+    if (!looksLikeBehaviorPool)
+        return undefined;
+    const inferredBdef = inferBdefNameFromBehaviorPoolSource(source);
+    const bdefHint = inferredBdef ? `, bdefName="${inferredBdef}"` : ', bdefName="<interface_bdef_name>"';
+    return (`Behavior-pool class save failed on handler declarations. Use ` +
+        `SAPWrite(action="scaffold_rap_handlers", type="CLAS", name="${name}"${bdefHint}) ` +
+        `to list missing RAP handler signatures, then rerun with autoApply=true to inject declarations. ` +
+        `If SAP still rejects the full-class write, use ADT quick-fix to stamp signatures and continue with SAPWrite(action="edit_method").`);
+}
 function classifyError(err) {
     if (err instanceof AdtApiError) {
         const classification = classifySapDomainError(err.statusCode, err.responseBody);
@@ -313,10 +748,20 @@ export async function handleToolCall(client, config, toolName, args, authInfo, _
         tool: toolName,
         args: sanitizeArgs(args),
     });
-    // Scope enforcement — only when authInfo is present (XSUAA/OIDC mode)
-    if (authInfo) {
-        const requiredScope = TOOL_SCOPES[toolName];
-        if (requiredScope && !hasRequiredScope(authInfo, requiredScope)) {
+    // 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.
+    // Runs BEFORE Zod validation so scope errors don't leak schema details to unauthorized callers.
+    const actionOrType = toolName === 'SAPRead'
+        ? typeof args.type === 'string'
+            ? args.type
+            : undefined
+        : typeof args.action === 'string'
+            ? args.action
+            : undefined;
+    const policy = getActionPolicy(toolName, actionOrType);
+    if (authInfo && policy) {
+        if (!hasRequiredScope(authInfo, policy.scope)) {
             logger.emitAudit({
                 timestamp: new Date().toISOString(),
                 level: 'warn',
@@ -325,16 +770,32 @@ export async function handleToolCall(client, config, toolName, args, authInfo, _
                 user,
                 clientId,
                 tool: toolName,
-                requiredScope,
+                requiredScope: policy.scope,
                 availableScopes: authInfo.scopes,
             });
-            return errorResult(`Insufficient scope: '${requiredScope}' required for ${toolName}. Your scopes: [${authInfo.scopes.join(', ')}]`);
+            const actionLabel = actionOrType
+                ? `${toolName}(${toolName === 'SAPRead' ? 'type' : 'action'}="${actionOrType}")`
+                : toolName;
+            return errorResult(`Insufficient scope: '${policy.scope}' required for ${actionLabel}. Your scopes: [${authInfo.scopes.join(', ')}]`);
         }
     }
-    // Validate tool arguments with Zod schema
+    // Server-level denyActions (SAP_DENY_ACTIONS) — blocks before any per-user scope allows it.
+    const { isActionDenied } = await import('../server/deny-actions.js');
+    if (isActionDenied(toolName, actionOrType, config.denyActions ?? [])) {
+        logger.emitAudit({
+            timestamp: new Date().toISOString(),
+            level: 'warn',
+            event: 'safety_blocked',
+            requestId: reqId,
+            user,
+            clientId,
+            operation: `${toolName}${actionOrType ? `.${actionOrType}` : ''}`,
+            reason: 'Action denied by SAP_DENY_ACTIONS',
+        });
+        return errorResult(`Action '${toolName}${actionOrType ? `.${actionOrType}` : ''}' is denied by server policy (SAP_DENY_ACTIONS).`);
+    }
+    // Validate tool arguments with Zod schema (runs AFTER scope + deny check).
     const isBtp = config.systemType === 'btp';
-    // Always use the full search schema for validation — the handler checks text search availability
-    // and returns a proper error message with the probe reason when source_code search is unavailable
     const schema = getToolSchema(toolName, isBtp);
     if (schema) {
         args = normalizeTypeArgsForValidation(toolName, args);
@@ -403,15 +864,8 @@ export async function handleToolCall(client, config, toolName, args, authInfo, _
                         result = errorResult(expanded.error);
                         break;
                     }
-                    // Check scope for the delegated action
-                    if (authInfo) {
-                        const requiredScope = getHyperfocusedScope(String(args.action ?? ''));
-                        if (!hasRequiredScope(authInfo, requiredScope)) {
-                            result = errorResult(`Insufficient scope: '${requiredScope}' required for SAP(action="${args.action}"). Your scopes: [${authInfo.scopes.join(', ')}]`);
-                            break;
-                        }
-                    }
                     // Delegate to the real handler (recursive call, but with the mapped tool name)
+                    // The concrete tool/action policy is enforced by the recursive call.
                     result = await handleToolCall(client, config, expanded.toolName, expanded.expandedArgs, authInfo, _server, cachingLayer, isPerUserClient);
                     break;
                 }
@@ -421,7 +875,7 @@ export async function handleToolCall(client, config, toolName, args, authInfo, _
             const durationMs = Date.now() - start;
             const fullText = result.content.map((c) => c.text).join('');
             const resultSize = fullText.length;
-            const resultPreview = fullText.length > 500 ? `${fullText.slice(0, 500)}...` : fullText;
+            const resultPreview = buildAuditResultPreview(toolName, args, fullText);
             logger.emitAudit({
                 timestamp: new Date().toISOString(),
                 level: result.isError ? 'error' : 'info',
@@ -893,6 +1347,25 @@ async function handleSAPSearch(client, args) {
     }
     return textResult(transliterationNote + JSON.stringify(results, null, 2));
 }
+function classifySapQueryParserError(err, sql) {
+    if (err.statusCode !== 400)
+        return undefined;
+    const combined = `${err.message}\n${err.responseBody ?? ''}`;
+    if (!hasSqlParserSignature(combined))
+        return undefined;
+    const hints = [
+        'ADT freestyle SQL parser rejected this query on this backend/version.',
+        'Submit exactly one SELECT statement (no semicolons, no multi-statement scripts).',
+        'Remove ABAP target clauses from SQL text (INTO, APPENDING, PACKAGE SIZE).',
+    ];
+    if (/\bJOIN\b/i.test(sql)) {
+        hints.push('JOIN parsing can fail on some systems (SAP Note 3605050); split into staged single-table queries.');
+    }
+    if (/\bINTO\b|\bAPPENDING\b|\bPACKAGE\s+SIZE\b/i.test(sql)) {
+        hints.push('Use the MCP maxRows parameter for row limits instead of ABAP target-table clauses.');
+    }
+    return `${err.message}\n\nHint: ${hints.join(' ')}`;
+}
 async function handleSAPQuery(client, args) {
     const sql = String(args.sql ?? '');
     const maxRows = Number(args.maxRows ?? 100);
@@ -921,9 +1394,10 @@ async function handleSAPQuery(client, args) {
                 }
             }
         }
-        // JOIN-aware error: ADT freestyle SQL parser has known edge cases with JOINs (SAP Note 3605050)
-        if (err instanceof AdtApiError && err.statusCode === 400 && /\bJOIN\b/i.test(sql)) {
-            return errorResult(`${err.message}\n\nMulti-table JOIN query failed. The ADT freestyle SQL endpoint has known parser edge cases with JOINs (SAP Note 3605050). Try splitting into separate single-table queries.`);
+        if (err instanceof AdtApiError) {
+            const parserHint = classifySapQueryParserError(err, sql);
+            if (parserHint)
+                return errorResult(parserHint);
         }
         throw err;
     }
@@ -1701,6 +2175,10 @@ function objectUrlForTypeRaw(type, name) {
 function sourceUrlForType(type, name) {
     return `${objectUrlForType(type, name)}/source/main`;
 }
+/** Get a CLAS include URL (definitions/implementations/macros/testclasses) */
+function classIncludeUrl(name, include) {
+    return `/sap/bc/adt/oo/classes/${encodeURIComponent(name)}/includes/${include}`;
+}
 // ─── SAPWrite Handler ────────────────────────────────────────────────
 async function handleSAPWrite(client, args, config, cachingLayer) {
     const action = String(args.action ?? '');
@@ -1709,13 +2187,15 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
     const source = String(args.source ?? '');
     const transport = args.transport;
     const lintOverride = args.lintBeforeWrite;
+    const preflightOverride = args.preflightBeforeWrite;
+    const checkOverride = args.checkBeforeWrite;
     // type and name are required for all actions except batch_create
     if (action !== 'batch_create' && (!type || !name)) {
         return errorResult('"type" and "name" are required for this action.');
     }
     const objectUrl = objectUrlForType(type, name);
     const srcUrl = sourceUrlForType(type, name);
-    // Helper: enforce allowedPackages for existing objects (update/delete/edit_method).
+    // 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.
     async function enforcePackageForExistingObject() {
         if (client.safety.allowedPackages.length === 0)
@@ -1754,6 +2234,10 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                 cachingLayer?.invalidate(type, name);
                 return textResult(`Successfully updated ${type} ${name}.`);
             }
+            // RAP deterministic preflight validation
+            const preflightWarnings = runRapPreflightValidation(source, type, name, cachedFeatures, config.systemType, preflightOverride);
+            if (preflightWarnings.blocked)
+                return preflightWarnings.result;
             // CDS pre-write validation: reject unsupported syntax early
             const cdsGuardUpdate = guardCdsSyntax(type, source, cachedFeatures);
             if (cdsGuardUpdate)
@@ -1762,10 +2246,16 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
             const lintWarnings = runPreWriteLint(source, type, name, config, lintOverride);
             if (lintWarnings.blocked)
                 return lintWarnings.result;
+            // Pre-write server-side syntax check (opt-in; never blocks — warnings only).
+            const checkNotes = await runPreWriteSyntaxCheck(client, type, source, objectUrl, config, checkOverride);
+            // If safeUpdateSource throws (lock conflict, network error, etc.), checkNotes
+            // is intentionally discarded — pre-check warnings only matter when the write succeeded.
             await safeUpdateSource(client.http, client.safety, objectUrl, srcUrl, source, transport);
             cachingLayer?.invalidate(type, name);
             const msg = `Successfully updated ${type} ${name}.`;
-            return lintWarnings.warnings ? textResult(`${msg}\n\n${lintWarnings.warnings}`) : textResult(msg);
+            const cdsUpdateHint = type === 'DDLS' ? await buildCdsUpdateCrudHint(client, name, objectUrl) : undefined;
+            const warnings = mergePreWriteWarnings(preflightWarnings.warnings, lintWarnings.warnings, checkNotes, cdsUpdateHint);
+            return warnings ? textResult(`${msg}\n\n${warnings}`) : textResult(msg);
         }
         case 'create': {
             const pkg = String(args.package ?? '$TMP');
@@ -1809,6 +2299,10 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
             const cdsGuard = guardCdsSyntax(type, source, cachedFeatures);
             if (cdsGuard)
                 return cdsGuard;
+            // RAP deterministic preflight validation (before object creation to avoid stubs)
+            const preflightWarnings = runRapPreflightValidation(source, type, name, cachedFeatures, config.systemType, preflightOverride);
+            if (preflightWarnings.blocked)
+                return preflightWarnings.result;
             // AFF header validation (if schema available for this type)
             const affResult = validateAffHeader(type, { description, originalLanguage: 'en' });
             if (!affResult.valid) {
@@ -1925,7 +2419,8 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                 await safeUpdateSource(client.http, client.safety, objectUrl, srcUrl, source, effectiveTransport);
                 cachingLayer?.invalidate(type, name);
                 const msg = `Created ${type} ${name} in package ${pkg} and wrote source code.`;
-                return lintWarnings.warnings ? textResult(`${msg}\n\n${lintWarnings.warnings}`) : textResult(msg);
+                const warnings = mergePreWriteWarnings(preflightWarnings.warnings, lintWarnings.warnings);
+                return warnings ? textResult(`${msg}\n\n${warnings}`) : textResult(msg);
             }
             return textResult(`Created ${type} ${name} in package ${pkg}.\n${result}`);
         }
@@ -1955,31 +2450,229 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
             const lintWarnings = runPreWriteLint(spliced.newSource, type, name, config, lintOverride);
             if (lintWarnings.blocked)
                 return lintWarnings.result;
+            // Pre-write server-side syntax check on the full spliced source (opt-in; warnings only).
+            const checkNotes = await runPreWriteSyntaxCheck(client, type, spliced.newSource, objectUrl, config, checkOverride);
             // Write the full source back (existing lock/modify/unlock flow)
             await safeUpdateSource(client.http, client.safety, objectUrl, srcUrl, spliced.newSource, transport);
             cachingLayer?.invalidate(type, name);
             const msg = `Successfully updated method "${method}" in ${type} ${name}.`;
-            return lintWarnings.warnings ? textResult(`${msg}\n\n${lintWarnings.warnings}`) : textResult(msg);
-        }
-        case 'delete': {
-            await enforcePackageForExistingObject();
-            // Lock, delete, unlock pattern (works for all types including SKTD) — auto-propagate lock corrNr if no explicit transport
+            const extras = [lintWarnings.warnings, checkNotes].filter(Boolean).join('\n\n');
+            return extras ? textResult(`${msg}\n\n${extras}`) : textResult(msg);
+        }
+        case 'scaffold_rap_handlers': {
+            // What this action does:
+            //   Given a behavior-pool class (ZBP_*) and its interface BDEF, inspect
+            //   the class for every `lhc_<alias>` local handler class and make
+            //   sure it declares a METHOD for every action / determination /
+            //   validation / authorization master the BDEF requires. When autoApply
+            //   is true, missing METHODS signatures plus empty METHOD stubs are
+            //   inserted directly and the class is saved.
+            //
+            // Why this exists:
+            //   Without it, the LLM agent trying to author a RAP behavior pool has
+            //   to manually read the BDEF, compute the required handler signatures,
+            //   paste them into the correct local class, and then save — a
+            //   boilerplate-heavy step that is easy to get wrong (alias case,
+            //   RESULT vs no RESULT, factory/static modifiers). The activation
+            //   errors for an incomplete pool are particularly unhelpful. See
+            //   docs/plans/completed/rap-onprem-agent-gap-closure.md.
+            if (type !== 'CLAS') {
+                return errorResult('scaffold_rap_handlers is only supported for type=CLAS behavior pool classes.');
+            }
+            const bdefName = String(args.bdefName ?? '').trim();
+            if (!bdefName) {
+                return errorResult('"bdefName" is required for scaffold_rap_handlers (interface behavior definition name).');
+            }
+            const autoApply = Boolean(args.autoApply ?? false);
+            const targetAlias = String(args.targetAlias ?? '')
+                .trim()
+                .toLowerCase();
+            if (autoApply) {
+                await enforcePackageForExistingObject();
+            }
+            // Why scan all three CLAS includes (main, definitions, implementations):
+            //   Behavior-pool handler classes CAN live in any of the three, and
+            //   which include they occupy depends on how the pool was generated:
+            //     - "main" (source/main) — unusual; some hand-written pools put
+            //       lhc_* alongside the global class definition
+            //     - "definitions" (CCDEF) — the ADT "Create Behavior Impl Class"
+            //       wizard default target
+            //     - "implementations" (CCIMP) — older SAP templates and every
+            //       example under /DMO/* ship the handler classes here
+            //   We read all three so the diff (findMissingRapHandlerRequirements)
+            //   reflects what's actually declared anywhere in the class, and the
+            //   apply flow can fall through main → definitions → implementations.
+            const classStructured = await client.getClassStructured(name);
+            const classMainSource = classStructured.main ?? '';
+            const classDefinitionsSource = classStructured.definitions ?? '';
+            const classImplementationsSource = classStructured.implementations ?? '';
+            const classCombinedSource = [classMainSource, classDefinitionsSource, classImplementationsSource]
+                .filter(Boolean)
+                .join('\n\n');
+            const bdefSource = cachingLayer
+                ? (await cachingLayer.getSource('BDEF', bdefName, () => client.getBdef(bdefName))).source
+                : await client.getBdef(bdefName);
+            let requirements = extractRapHandlerRequirements(bdefSource);
+            if (targetAlias) {
+                requirements = requirements.filter((req) => req.entityAlias.toLowerCase() === targetAlias);
+            }
+            if (requirements.length === 0) {
+                const allAliases = Array.from(new Set(extractRapHandlerRequirements(bdefSource).map((req) => req.entityAlias)));
+                const aliasHint = targetAlias && allAliases.length > 0
+                    ? ` Available aliases in ${bdefName}: ${allAliases.join(', ')}.`
+                    : ' No RAP action/determination/validation/auth handler declarations were found in the BDEF source.';
+                return errorResult(`No RAP handler requirements were found for the requested scope.${aliasHint}`);
+            }
+            const missing = findMissingRapHandlerRequirements(requirements, classCombinedSource);
+            const missingImplementationStubs = findMissingRapHandlerImplementationStubs(requirements, classCombinedSource);
+            const summary = {
+                className: name,
+                bdefName,
+                targetAlias: targetAlias || undefined,
+                scannedSections: [
+                    'main',
+                    classDefinitionsSource ? 'definitions' : undefined,
+                    classImplementationsSource ? 'implementations' : undefined,
+                ].filter(Boolean),
+                requiredCount: requirements.length,
+                missingCount: missing.length,
+                missing,
+                missingImplementationStubCount: missingImplementationStubs.length,
+                missingImplementationStubs,
+            };
+            if (!autoApply || (missing.length === 0 && missingImplementationStubs.length === 0)) {
+                return textResult(JSON.stringify({ ...summary, applied: false }, null, 2));
+            }
+            // Pure RAP transformation planning lives in rap-handlers.ts. Keep this
+            // handler focused on MCP/ADT concerns: safety, linting, locking, writes.
+            const scaffoldPlan = applyRapHandlerScaffold({
+                main: classMainSource,
+                definitions: classDefinitionsSource || undefined,
+                implementations: classImplementationsSource || undefined,
+            }, missing, missingImplementationStubs);
+            if (scaffoldPlan.changedSections.length === 0) {
+                const unresolvedHandlerClasses = Array.from(new Set(scaffoldPlan.unresolved.map((req) => req.targetHandlerClass)));
+                const unresolvedHint = unresolvedHandlerClasses.length > 0
+                    ? `No source changes were applied because handler class skeleton(s) ${unresolvedHandlerClasses.join(', ')} were not found in main, definitions, or implementations. Create the local handler class skeleton(s) first (for example with the ADT quick fix "Create local handler class"), then rerun with autoApply=true.`
+                    : undefined;
+                return textResult(JSON.stringify({
+                    ...summary,
+                    applied: false,
+                    hint: unresolvedHint,
+                    applyResult: {
+                        main: scaffoldPlan.signatures.main,
+                        definitions: scaffoldPlan.signatures.definitions,
+                        implementations: scaffoldPlan.signatures.implementations,
+                        implementationStubs: scaffoldPlan.implementationStubs,
+                        unresolved: scaffoldPlan.unresolved,
+                    },
+                }, null, 2));
+            }
+            const finalMainSource = scaffoldPlan.sections.main;
+            const finalDefinitionsSource = scaffoldPlan.sections.definitions;
+            const finalImplementationsSource = scaffoldPlan.sections.implementations;
+            const { changed } = scaffoldPlan;
+            // Run lint for every section we are about to update; block before any write to avoid partial state.
+            let lintWarningsMain;
+            if (changed.main) {
+                lintWarningsMain = runPreWriteLint(finalMainSource, type, name, config, lintOverride);
+                if (lintWarningsMain.blocked)
+                    return lintWarningsMain.result;
+            }
+            let lintWarningsDefinitions;
+            if (changed.definitions && finalDefinitionsSource) {
+                lintWarningsDefinitions = runPreWriteLint(finalDefinitionsSource, type, name, config, lintOverride);
+                if (lintWarningsDefinitions.blocked)
+                    return lintWarningsDefinitions.result;
+            }
+            let lintWarningsImplementations;
+            if (changed.implementations && finalImplementationsSource) {
+                lintWarningsImplementations = runPreWriteLint(finalImplementationsSource, type, name, config, lintOverride);
+                if (lintWarningsImplementations.blocked)
+                    return lintWarningsImplementations.result;
+            }
+            // All modified includes share one lock so we never end up in a partial-state
+            // (e.g. main written, implementations errored → handler class declares but
+            // doesn't implement methods → class cannot activate). The lock is taken once
+            // at the class object URL, and every include PUT carries the same lockHandle.
+            // This mirrors how ADT-in-Eclipse saves a multi-include class in one commit.
             await client.http.withStatefulSession(async (session) => {
                 const lock = await lockObject(session, client.safety, objectUrl);
                 const effectiveTransport = transport ?? (lock.corrNr || undefined);
                 try {
-                    await deleteObject(session, client.safety, objectUrl, lock.lockHandle, effectiveTransport);
+                    if (changed.main) {
+                        await updateSource(session, client.safety, srcUrl, finalMainSource, lock.lockHandle, effectiveTransport);
+                    }
+                    if (changed.definitions && finalDefinitionsSource) {
+                        await updateSource(session, client.safety, classIncludeUrl(name, 'definitions'), finalDefinitionsSource, lock.lockHandle, effectiveTransport);
+                    }
+                    if (changed.implementations && finalImplementationsSource) {
+                        await updateSource(session, client.safety, classIncludeUrl(name, 'implementations'), finalImplementationsSource, lock.lockHandle, effectiveTransport);
+                    }
                 }
                 finally {
+                    // Best-effort unlock — if the object was already removed or the session
+                    // expired, we still want to surface the original error instead of masking
+                    // it with an unlock failure.
                     try {
                         await unlockObject(session, objectUrl, lock.lockHandle);
                     }
                     catch {
-                        // Object may already be deleted — unlock failure is expected
+                        // Swallowed intentionally; see comment above.
                     }
                 }
             });
             cachingLayer?.invalidate(type, name);
+            const msg = `Scaffolded ${scaffoldPlan.insertedSignatureCount} RAP handler signature(s) and ${scaffoldPlan.insertedImplementationStubCount} implementation stub(s) in ${type} ${name} from BDEF ${bdefName}. ` +
+                `Updated section(s): ${scaffoldPlan.changedSections.join(', ')}.`;
+            const warnings = mergePreWriteWarnings(lintWarningsMain?.warnings, lintWarningsDefinitions?.warnings, lintWarningsImplementations?.warnings);
+            const details = JSON.stringify({
+                ...summary,
+                applied: true,
+                applyResult: {
+                    main: scaffoldPlan.signatures.main,
+                    definitions: scaffoldPlan.signatures.definitions,
+                    implementations: scaffoldPlan.signatures.implementations,
+                    implementationStubs: scaffoldPlan.implementationStubs,
+                    unresolved: scaffoldPlan.unresolved,
+                },
+            }, null, 2);
+            return warnings ? textResult(`${msg}\n\n${warnings}\n\n${details}`) : textResult(`${msg}\n\n${details}`);
+        }
+        case 'delete': {
+            await enforcePackageForExistingObject();
+            // Lock, delete, unlock pattern (works for all types including SKTD) — auto-propagate lock corrNr if no explicit transport
+            try {
+                await client.http.withStatefulSession(async (session) => {
+                    const lock = await lockObject(session, client.safety, objectUrl);
+                    const effectiveTransport = transport ?? (lock.corrNr || undefined);
+                    try {
+                        await deleteObject(session, client.safety, objectUrl, lock.lockHandle, effectiveTransport);
+                    }
+                    finally {
+                        try {
+                            await unlockObject(session, objectUrl, lock.lockHandle);
+                        }
+                        catch {
+                            // Object may already be deleted — unlock failure is expected
+                        }
+                    }
+                });
+            }
+            catch (err) {
+                if (err instanceof AdtApiError && CDS_DEPENDENCY_SENSITIVE_TYPES.has(type) && isDeleteDependencyError(err)) {
+                    const hint = await buildCdsDeleteDependencyHint(client, type, name, objectUrl);
+                    if (hint) {
+                        // Attach via extraHint so the LLM-facing formatter renders it after
+                        // DDIC diagnostics ("what happened → diagnostics → how to fix").
+                        // Mutating err.message would surface the hint before diagnostics and
+                        // leak into any other consumer of the same error instance.
+                        err.extraHint = hint;
+                    }
+                }
+                throw err;
+            }
+            cachingLayer?.invalidate(type, name);
             return textResult(`Deleted ${type} ${name}.`);
         }
         case 'batch_create': {
@@ -2022,6 +2715,7 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                 }
             }
             const results = [];
+            const batchWarnings = [];
             for (const obj of objects) {
                 const objType = normalizeObjectType(String(obj.type ?? ''));
                 const objName = String(obj.name ?? '');
@@ -2043,6 +2737,19 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                     // Pre-validate source with lint BEFORE creating the object to avoid orphaned objects.
                     // Metadata objects (DOMA/DTEL) are XML-only and intentionally skip source lint.
                     if (!metadataObject && objSource) {
+                        const preflightWarnings = runRapPreflightValidation(objSource, objType, objName, cachedFeatures, config.systemType, preflightOverride);
+                        if (preflightWarnings.blocked) {
+                            results.push({
+                                type: objType,
+                                name: objName,
+                                status: 'failed',
+                                error: preflightWarnings.result.content[0].text,
+                            });
+                            break;
+                        }
+                        if (preflightWarnings.warnings) {
+                            batchWarnings.push(`${objType} ${objName}: ${preflightWarnings.warnings}`);
+                        }
                         const lintWarnings = runPreWriteLint(objSource, objType, objName, config, lintOverride);
                         if (lintWarnings.blocked) {
                             results.push({
@@ -2130,18 +2837,59 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                 .join(', ');
             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- ')}` : '';
             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 in package ${pkg}: ${summary}${cleanupHint}`);
+                return errorResult(`Batch created ${successCount}/${objects.length} objects in package ${pkg}: ${summary}${cleanupHint}${warningSuffix}`);
             }
-            return textResult(`Batch created ${successCount} objects in package ${pkg}: ${summary}`);
+            return textResult(`Batch created ${successCount} objects in package ${pkg}: ${summary}${warningSuffix}`);
         }
         default:
-            return errorResult(`Unknown SAPWrite action: ${action}. Supported: create, update, delete, edit_method, batch_create`);
+            return errorResult(`Unknown SAPWrite action: ${action}. Supported: create, update, delete, edit_method, batch_create, scaffold_rap_handlers`);
     }
 }
+/**
+ * Run deterministic RAP preflight checks for non-ABAP RAP artifact types.
+ *
+ * Unlike lint, this check is intentionally narrow and rule-based. It focuses on
+ * known activation churn patterns (TABL curr/quan semantics, BDEF enum/header
+ * misuse, DDLX scope/duplicate annotations) and can cover types that offline
+ * abaplint does not parse well.
+ */
+function runRapPreflightValidation(source, type, name, features, configSystemType, perCallOverride) {
+    const enabled = perCallOverride ?? true;
+    if (!enabled || !source) {
+        return { blocked: false };
+    }
+    const systemType = features?.systemType ?? (configSystemType !== 'auto' ? configSystemType : undefined);
+    const result = validateRapSource(type, source, {
+        systemType,
+        abapRelease: features?.abapRelease,
+    });
+    if (result.errors.length > 0) {
+        const details = formatRapPreflightFindings(result.errors);
+        return {
+            blocked: true,
+            result: errorResult(`RAP preflight validation failed for ${type} ${name}. Fix these issues before writing:\n${details}\n\n` +
+                'Set preflightBeforeWrite=false only when you intentionally need to bypass these checks.'),
+        };
+    }
+    if (result.warnings.length > 0) {
+        return {
+            blocked: false,
+            warnings: `RAP preflight warnings:\n${formatRapPreflightFindings(result.warnings)}`,
+        };
+    }
+    return { blocked: false };
+}
+function mergePreWriteWarnings(...warnings) {
+    const parts = warnings.filter((w) => Boolean(w));
+    if (parts.length === 0)
+        return undefined;
+    return parts.join('\n\n');
+}
 /**
  * Run pre-write lint validation on source code.
  *
@@ -2203,6 +2951,56 @@ function runPreWriteLint(source, type, name, config, perCallOverride) {
         return { blocked: false };
     }
 }
+/** Types that carry source code that SAP's /checkruns endpoint can meaningfully compile.
+ *  Metadata-write types (DOMA/DTEL/TABL/STRU/MSAG/DEVC/SKTD) have no /source/main artifact. */
+const SYNTAX_CHECKABLE_TYPES = new Set([
+    'PROG',
+    'CLAS',
+    'INTF',
+    'FUNC',
+    'FUGR',
+    'INCL',
+    'DDLS',
+    'DCLS',
+    'DDLX',
+    'BDEF',
+    'SRVD',
+]);
+/** Pre-write SAP server-side syntax check via /checkruns with inline <chkrun:content>.
+ *  Sends the proposed source to SAP's compiler without writing. Surfaces errors AND
+ *  warnings as informational text appended to the write's success message — never
+ *  blocks the write. Rationale: multi-file edits have inter-object dependencies, so
+ *  intermediate writes legitimately trip compile errors that resolve once the whole
+ *  sequence lands. Real blocking is deferred to SAPActivate, which runs after all
+ *  dependencies are in place. Best-effort: network/endpoint failures return ''. */
+async function runPreWriteSyntaxCheck(client, type, source, objectUrl, config, perCallOverride) {
+    const enabled = perCallOverride ?? config.checkBeforeWrite;
+    if (!enabled || !source)
+        return '';
+    if (!SYNTAX_CHECKABLE_TYPES.has(type.toUpperCase()))
+        return '';
+    try {
+        const result = await syntaxCheck(client.http, client.safety, objectUrl, { content: source, version: 'active' });
+        if (result.messages.length === 0)
+            return '';
+        const errors = result.messages.filter((m) => m.severity === 'error');
+        const warnings = result.messages.filter((m) => m.severity === 'warning');
+        const parts = [];
+        if (errors.length > 0) {
+            const lines = errors.map((m) => `  Line ${m.line || '?'}${m.column ? `:${m.column}` : ''}: ${m.text}`).join('\n');
+            parts.push(`Server syntax check errors (source was still written — activate to confirm whether these resolve once dependencies are in place):\n${lines}`);
+        }
+        if (warnings.length > 0) {
+            const lines = warnings.map((m) => `  Line ${m.line || '?'}: ${m.text}`).join('\n');
+            parts.push(`Server syntax check warnings:\n${lines}`);
+        }
+        return parts.join('\n\n');
+    }
+    catch {
+        // Best-effort: never let a failing pre-check fail the write.
+        return '';
+    }
+}
 // ─── SAPActivate Handler ─────────────────────────────────────────────
 async function handleSAPActivate(client, args) {
     const action = String(args.action ?? 'activate');
@@ -2299,25 +3097,45 @@ async function handleSAPActivate(client, args) {
     const preaudit = args.preaudit !== undefined ? Boolean(args.preaudit) : undefined;
     const activateOpts = preaudit !== undefined ? { preaudit } : undefined;
     if (args.objects && Array.isArray(args.objects)) {
-        const objects = args.objects.map((o) => {
+        const rawObjects = args.objects;
+        const objects = rawObjects.map((o) => {
             const objType = normalizeObjectType(String(o.type ?? type));
             const objName = String(o.name ?? '');
-            return { url: objectUrlForType(objType, objName), name: objName };
+            return { type: objType, name: objName, url: objectUrlForType(objType, objName) };
         });
         const result = await activateBatch(client.http, client.safety, objects, activateOpts);
         const names = objects.map((o) => o.name).join(', ');
+        const batchStatuses = buildBatchActivationStatuses(objects, result);
+        const statusDetails = formatBatchActivationStatuses(batchStatuses);
         if (result.success) {
-            return textResult(`Successfully activated ${objects.length} objects: ${names}.${formatActivationMessages(result)}`);
-        }
-        return errorResult(`Batch activation failed for: ${names}.\n${formatActivationMessages(result)}`);
+            return textResult(`Successfully activated ${objects.length} objects: ${names}.${statusDetails}`);
+        }
+        // On batch failure enrich with per-object inactive-version syntax errors —
+        // only for objects whose activation returned no error details, to avoid duplicating messages.
+        const objectsNeedingSyntaxCheck = objects.filter((_o, i) => batchStatuses[i].status !== 'error');
+        const diagnostics = await Promise.all(objectsNeedingSyntaxCheck.map((o) => inactiveSyntaxDiagnostic(client, o.type, o.name)));
+        const combinedDiag = diagnostics
+            .map((d, i) => (d ? `\n[${objectsNeedingSyntaxCheck[i].name}]${d}` : ''))
+            .filter(Boolean)
+            .join('');
+        return errorResult(`Batch activation failed for: ${names}.${statusDetails}\n${formatActivationMessages(result)}${combinedDiag}`);
     }
     // Single activation (existing behavior)
     const objectUrl = objectUrlForType(type, name);
-    const result = await activate(client.http, client.safety, objectUrl, activateOpts);
+    const result = await activate(client.http, client.safety, objectUrl, { ...activateOpts, name });
     if (result.success) {
         return textResult(`Successfully activated ${type} ${name}.${formatActivationMessages(result)}`);
     }
-    return errorResult(`Activation failed for ${type} ${name}.\n${formatActivationMessages(result)}`);
+    // On failure, try to enrich with the actual compiler errors from the inactive version —
+    // especially useful when SAP returned <ioc:inactiveObjects> with no <msg> detail.
+    // Skip when activation already returned error details to avoid duplicating the same messages.
+    const hasActivationErrors = result.details.some((d) => d.severity === 'error');
+    const syntaxDetail = hasActivationErrors ? '' : await inactiveSyntaxDiagnostic(client, type, name);
+    let activationError = `Activation failed for ${type} ${name}.\n${formatActivationMessages(result)}${syntaxDetail}`;
+    if (type === 'DDLS') {
+        activationError += `\n\n${await buildCdsActivationDependencyHint(client, name, objectUrl)}`;
+    }
+    return errorResult(activationError);
 }
 /** Format activation result messages with structured detail (line numbers, URIs) when available */
 function formatActivationMessages(result) {
@@ -2347,6 +3165,67 @@ function formatActivationMessages(result) {
     }
     return parts.length > 0 ? `\n${parts.join('\n')}` : '';
 }
+function normalizeActivationUri(uri) {
+    if (!uri)
+        return undefined;
+    return uri.replace(/#.*$/, '').replace(/\/+$/, '').toLowerCase();
+}
+function buildBatchActivationStatuses(objects, result) {
+    // Group error details by object. SAP error URIs may be subpaths of the object URL
+    // (e.g. .../classes/zcl_demo/source/main for object .../classes/ZCL_DEMO) and may
+    // differ in case, so we lowercase and use startsWith for matching.
+    const objectKeys = objects.map((obj) => normalizeActivationUri(obj.url) ?? '');
+    const perObject = objects.map(() => []);
+    const unassigned = [];
+    for (const detail of result.details) {
+        const detailUri = normalizeActivationUri(detail.uri);
+        const prefix = detail.line ? `[line ${detail.line}] ` : '';
+        const suffix = detail.uri ? ` (${detail.uri})` : '';
+        if (!detailUri) {
+            unassigned.push(`${prefix}${detail.text}${suffix}`);
+            continue;
+        }
+        const matchIdx = objectKeys.findIndex((k) => k && detailUri.startsWith(k));
+        if (matchIdx >= 0) {
+            perObject[matchIdx].push({ severity: detail.severity, text: `${prefix}${detail.text}${suffix}` });
+        }
+        else {
+            unassigned.push(`${prefix}${detail.text}${suffix}`);
+        }
+    }
+    return objects.map((obj, index) => {
+        const details = perObject[index];
+        const hasError = details.some((detail) => detail.severity === 'error');
+        const hasWarning = details.some((detail) => detail.severity === 'warning');
+        const status = hasError ? 'error' : hasWarning ? 'warning' : 'active';
+        const messages = details.map((detail) => detail.text);
+        if (index === 0 && unassigned.length > 0) {
+            messages.push(...unassigned);
+        }
+        return {
+            type: obj.type,
+            name: obj.name,
+            status,
+            messages,
+        };
+    });
+}
+function formatBatchActivationStatuses(statuses) {
+    if (statuses.length === 0)
+        return '';
+    const lines = [];
+    for (const status of statuses) {
+        if (status.messages.length === 0) {
+            lines.push(`- ${status.name} (${status.type}): ${status.status}`);
+        }
+        else {
+            for (const msg of status.messages) {
+                lines.push(`- ${status.name} (${status.type}) ${msg}`);
+            }
+        }
+    }
+    return `\n${lines.join('\n')}`;
+}
 // ─── SAPNavigate Handler ─────────────────────────────────────────────
 async function handleSAPNavigate(client, args) {
     const action = String(args.action ?? '');
@@ -2437,7 +3316,8 @@ async function handleSAPNavigate(client, args) {
             const canQuery = isOperationAllowed(client.safety, OperationType.Query);
             if (!canFreeSQL && !canQuery) {
                 return errorResult('Class hierarchy requires data access permissions. ' +
-                    'Enable free SQL (--block-free-sql=false) or table preview (--block-data=false).');
+                    'Enable free SQL (SAP_ALLOW_FREE_SQL=true / --allow-free-sql=true) or table preview ' +
+                    '(SAP_ALLOW_DATA_PREVIEW=true / --allow-data-preview=true), and grant the matching sql/data scope in HTTP auth mode.');
             }
             try {
                 let ownRels;
@@ -2490,7 +3370,14 @@ async function handleSAPDiagnose(client, args) {
     switch (action) {
         case 'syntax': {
             const objectUrl = objectUrlForType(type, name);
-            const result = await syntaxCheck(client.http, client.safety, objectUrl);
+            const version = args.version === 'inactive' ? 'inactive' : args.version === 'active' ? 'active' : undefined;
+            const content = typeof args.source === 'string' ? args.source : undefined;
+            const opts = {};
+            if (version)
+                opts.version = version;
+            if (content !== undefined)
+                opts.content = content;
+            const result = await syntaxCheck(client.http, client.safety, objectUrl, Object.keys(opts).length > 0 ? opts : undefined);
             return textResult(JSON.stringify(result, null, 2));
         }
         case 'unittest': {
@@ -2553,11 +3440,31 @@ async function handleSAPDiagnose(client, args) {
         case 'dumps': {
             const id = args.id;
             if (id) {
-                // Get single dump detail
                 const detail = await getDump(client.http, client.safety, id);
-                return textResult(JSON.stringify(detail, null, 2));
+                const includeFullText = args.includeFullText === true || String(args.includeFullText ?? '') === 'true';
+                const selectedSections = selectDumpSections(detail, args.sections);
+                const payload = {
+                    id: detail.id,
+                    error: detail.error,
+                    exception: detail.exception,
+                    program: detail.program,
+                    user: detail.user,
+                    timestamp: detail.timestamp,
+                    chapters: detail.chapters,
+                    terminationUri: detail.terminationUri,
+                    sections: selectedSections,
+                    selectedSectionIds: Object.keys(selectedSections),
+                    availableSections: detail.chapters.map((chapter) => ({
+                        id: chapter.name,
+                        title: chapter.title,
+                        line: chapter.line,
+                    })),
+                };
+                if (includeFullText) {
+                    payload.formattedText = detail.formattedText;
+                }
+                return textResult(JSON.stringify(payload, null, 2));
             }
-            // List dumps
             const user = args.user;
             const maxResults = args.maxResults ? Number(args.maxResults) : undefined;
             const dumps = await listDumps(client.http, client.safety, { user, maxResults });
@@ -2589,10 +3496,95 @@ async function handleSAPDiagnose(client, args) {
             const traces = await listTraces(client.http, client.safety);
             return textResult(JSON.stringify(traces, null, 2));
         }
+        case 'system_messages': {
+            const user = args.user;
+            const maxResults = args.maxResults ? Number(args.maxResults) : undefined;
+            const from = args.from;
+            const to = args.to;
+            const messages = await listSystemMessages(client.http, client.safety, { user, maxResults, from, to });
+            return textResult(JSON.stringify(messages, null, 2));
+        }
+        case 'gateway_errors': {
+            if (isBtpSystem()) {
+                return errorResult('SAP Gateway error log is not available on BTP ABAP Environment. Use this action on on-prem systems.');
+            }
+            const user = args.user;
+            const maxResults = args.maxResults ? Number(args.maxResults) : undefined;
+            const from = args.from;
+            const to = args.to;
+            const detailUrl = args.detailUrl;
+            const id = args.id;
+            const errorType = args.errorType;
+            if (detailUrl || id) {
+                const detail = await getGatewayErrorDetail(client.http, client.safety, { detailUrl, id, errorType });
+                return textResult(JSON.stringify(detail, null, 2));
+            }
+            const errors = await listGatewayErrors(client.http, client.safety, { user, maxResults, from, to });
+            return textResult(JSON.stringify(errors, null, 2));
+        }
         default:
-            return errorResult(`Unknown SAPDiagnose action: ${action}. Supported: syntax, unittest, atc, quickfix, apply_quickfix, dumps, traces`);
+            return errorResult(`Unknown SAPDiagnose action: ${action}. Supported: syntax, unittest, atc, quickfix, apply_quickfix, dumps, traces, system_messages, gateway_errors`);
     }
 }
+function selectDumpSections(detail, requestedSections) {
+    const availableSections = detail.sections ?? {};
+    const availableIds = Object.keys(availableSections);
+    if (availableIds.length === 0)
+        return {};
+    const requestedIds = resolveRequestedDumpSectionIds(detail, requestedSections);
+    const selectedIds = requestedIds.length > 0 ? requestedIds : pickDefaultDumpSectionIds(detail);
+    const finalIds = selectedIds.length > 0 ? selectedIds : availableIds.slice(0, 5);
+    return Object.fromEntries(finalIds.map((id) => [id, availableSections[id] ?? '']));
+}
+function resolveRequestedDumpSectionIds(detail, requestedSections) {
+    if (!Array.isArray(requestedSections))
+        return [];
+    const availableIds = new Set(Object.keys(detail.sections ?? {}));
+    const resolved = requestedSections
+        .map((entry) => resolveDumpSectionId(detail, String(entry ?? '')))
+        .filter((entry) => typeof entry === 'string' && availableIds.has(entry));
+    return Array.from(new Set(resolved));
+}
+function resolveDumpSectionId(detail, candidate) {
+    const normalizedCandidate = normalizeDumpSectionKey(candidate);
+    if (!normalizedCandidate)
+        return undefined;
+    const direct = detail.chapters.find((chapter) => normalizeDumpSectionKey(chapter.name) === normalizedCandidate)?.name;
+    if (direct)
+        return direct;
+    const exactTitle = detail.chapters.find((chapter) => normalizeDumpSectionKey(chapter.title) === normalizedCandidate)?.name;
+    if (exactTitle)
+        return exactTitle;
+    const fuzzyTitle = detail.chapters.find((chapter) => normalizeDumpSectionKey(chapter.title).includes(normalizedCandidate))?.name;
+    return fuzzyTitle;
+}
+function pickDefaultDumpSectionIds(detail) {
+    const wanted = ['short text', 'what happened', 'error analysis', 'source code extract', 'active calls', 'call stack'];
+    const selected = [];
+    for (const pattern of wanted) {
+        const found = detail.chapters.find((chapter) => normalizeDumpSectionKey(chapter.title).includes(normalizeDumpSectionKey(pattern)) && chapter.name);
+        if (found?.name && !selected.includes(found.name) && detail.sections[found.name]) {
+            selected.push(found.name);
+        }
+    }
+    if (selected.length > 0)
+        return selected;
+    const ordered = [...detail.chapters]
+        .sort((a, b) => {
+        if (a.line !== b.line)
+            return a.line - b.line;
+        return a.chapterOrder - b.chapterOrder;
+    })
+        .map((chapter) => chapter.name)
+        .filter((name) => Boolean(name) && Boolean(detail.sections[name]));
+    return Array.from(new Set(ordered)).slice(0, 5);
+}
+function normalizeDumpSectionKey(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, ' ')
+        .trim();
+}
 function resolveSapGitBackend(args) {
     const forced = args.backend;
     const hasGcts = Boolean(cachedFeatures?.gcts?.available);
@@ -2619,15 +3611,13 @@ async function loadAbapGitRepo(client, repoId) {
     }
     return repo;
 }
-async function handleSAPGit(client, args, authInfo) {
+async function handleSAPGit(client, args, _authInfo) {
+    // Scope enforcement happens at handleToolCall level via ACTION_POLICY.
+    // This handler only dispatches action logic.
     const action = String(args.action ?? '');
-    const scope = SAPGIT_ACTION_SCOPES[action];
-    if (!scope) {
+    if (!getActionPolicy('SAPGit', action)) {
         return errorResult(`Unknown SAPGit action: ${action}`);
     }
-    if (authInfo && !hasRequiredScope(authInfo, scope)) {
-        return errorResult(`Insufficient scope: '${scope}' required for SAPGit(action="${action}"). Your scopes: [${authInfo.scopes.join(', ')}]`);
-    }
     const resolved = resolveSapGitBackend(args);
     if (!resolved.backend) {
         return errorResult(resolved.error ?? 'Unable to resolve SAPGit backend.');
@@ -2868,7 +3858,7 @@ async function handleSAPTransport(client, args) {
         }
         case 'check': {
             // Check transport requirements for an object/package combination.
-            // Does NOT require enableTransports — this is a read-only check.
+            // Does NOT require allowTransportWrites — this is a read-only check.
             const objectType = String(args.type ?? '');
             const objectName = String(args.name ?? '');
             const pkg = String(args.package ?? '');
@@ -2936,6 +3926,15 @@ async function handleSAPTransport(client, args) {
     }
 }
 // ─── SAPContext Handler ───────────────────────────────────────────────
+const DEFAULT_SIBLING_MAX_CANDIDATES = 4;
+const HARD_MAX_SIBLING_MAX_CANDIDATES = 10;
+function parseSiblingMaxCandidates(value) {
+    const parsed = Number(value ?? DEFAULT_SIBLING_MAX_CANDIDATES);
+    if (!Number.isFinite(parsed))
+        return DEFAULT_SIBLING_MAX_CANDIDATES;
+    const rounded = Math.trunc(parsed);
+    return Math.min(Math.max(rounded, 1), HARD_MAX_SIBLING_MAX_CANDIDATES);
+}
 async function handleSAPContext(client, args, cachingLayer) {
     const action = String(args.action ?? '');
     // action="impact" is DDLS-only on the server side — default the type so LLMs
@@ -2985,8 +3984,12 @@ async function handleSAPContext(client, args, cachingLayer) {
         const ddlSource = await cachedGet('DDLS', name, () => client.getDdls(name));
         const upstream = buildCdsUpstream(extractCdsDependencies(ddlSource));
         const includeIndirect = args.includeIndirect === true;
+        const siblingCheck = args.siblingCheck !== false;
+        const siblingMaxCandidates = parseSiblingMaxCandidates(args.siblingMaxCandidates);
         let downstream = classifyCdsImpact([], { includeIndirect });
         const warnings = [];
+        const consistencyHints = [];
+        let siblingExtensionAnalysis;
         try {
             const whereUsed = await findWhereUsed(client.http, client.safety, objectUrlForType('DDLS', name));
             downstream = classifyCdsImpact(whereUsed, { includeIndirect });
@@ -2999,6 +4002,125 @@ async function handleSAPContext(client, args, cachingLayer) {
                 throw err;
             }
         }
+        if (siblingCheck && warnings.length === 0) {
+            try {
+                const targetName = name.toUpperCase();
+                const stem = deriveSiblingStem(targetName);
+                // Guard against over-broad sibling searches for short/degenerate stems
+                // (e.g., target "Z1" -> stem "Z" -> searchQuery "Z*" would scan the full Z namespace).
+                if (stem.length < 3) {
+                    warnings.push(`Sibling consistency check skipped: derived stem "${stem}" is too short to identify siblings safely.`);
+                }
+                else {
+                    const targetMatches = await client.searchObject(targetName, 25);
+                    const targetMatch = targetMatches.find((candidate) => normalizeObjectType(candidate.objectType) === 'DDLS' && candidate.objectName.toUpperCase() === targetName);
+                    const targetPackageName = targetMatch?.packageName;
+                    if (!targetPackageName) {
+                        warnings.push(`Sibling consistency check skipped: could not resolve package for DDLS "${targetName}".`);
+                    }
+                    else {
+                        const searchQuery = `${stem}*`;
+                        const searchMaxResults = Math.min(100, Math.max(siblingMaxCandidates * 4, siblingMaxCandidates + 4));
+                        const siblingCandidates = await client.searchObject(searchQuery, searchMaxResults);
+                        const skipped = {
+                            self: 0,
+                            nonDdls: 0,
+                            packageMismatch: 0,
+                            nameMismatch: 0,
+                            overLimit: 0,
+                        };
+                        const filteredCandidates = [];
+                        const seenNames = new Set();
+                        for (const candidate of siblingCandidates) {
+                            if (normalizeObjectType(candidate.objectType) !== 'DDLS') {
+                                skipped.nonDdls += 1;
+                                continue;
+                            }
+                            const candidateName = candidate.objectName.toUpperCase();
+                            if (candidateName === targetName) {
+                                skipped.self += 1;
+                                continue;
+                            }
+                            if (candidate.packageName !== targetPackageName) {
+                                skipped.packageMismatch += 1;
+                                continue;
+                            }
+                            if (!isSiblingNameMatch(targetName, candidateName, stem)) {
+                                skipped.nameMismatch += 1;
+                                continue;
+                            }
+                            if (seenNames.has(candidateName)) {
+                                continue;
+                            }
+                            seenNames.add(candidateName);
+                            filteredCandidates.push({ name: candidateName, packageName: candidate.packageName });
+                        }
+                        const selectedCandidates = filteredCandidates.slice(0, siblingMaxCandidates);
+                        skipped.overLimit = Math.max(filteredCandidates.length - selectedCandidates.length, 0);
+                        const checkedCandidates = [];
+                        let skippedWhereUsedCandidates = 0;
+                        for (const candidate of selectedCandidates) {
+                            try {
+                                const siblingWhereUsed = await findWhereUsed(client.http, client.safety, objectUrlForType('DDLS', candidate.name));
+                                const siblingDownstream = classifyCdsImpact(siblingWhereUsed, { includeIndirect });
+                                checkedCandidates.push({
+                                    name: candidate.name,
+                                    packageName: candidate.packageName,
+                                    metadataExtensions: siblingDownstream.metadataExtensions.length,
+                                    downstreamTotal: siblingDownstream.summary.total,
+                                });
+                            }
+                            catch (err) {
+                                if (err instanceof AdtApiError && [404, 405, 415, 501].includes(err.statusCode)) {
+                                    skippedWhereUsedCandidates += 1;
+                                    continue;
+                                }
+                                throw err;
+                            }
+                        }
+                        if (skippedWhereUsedCandidates > 0) {
+                            warnings.push(`Sibling consistency check skipped ${skippedWhereUsedCandidates} candidate(s) due to where-used endpoint errors.`);
+                        }
+                        const siblingFinding = buildSiblingExtensionFinding({
+                            targetName,
+                            targetPackageName,
+                            stem,
+                            targetMetadataExtensions: downstream.metadataExtensions.length,
+                            siblings: checkedCandidates,
+                        });
+                        if (siblingFinding) {
+                            consistencyHints.push(siblingFinding.message);
+                        }
+                        siblingExtensionAnalysis = {
+                            enabled: true,
+                            stem,
+                            searchQuery,
+                            includeIndirect,
+                            maxCandidates: siblingMaxCandidates,
+                            filters: {
+                                samePackage: true,
+                                siblingStem: stem,
+                            },
+                            target: {
+                                name: targetName,
+                                packageName: targetPackageName,
+                                metadataExtensions: downstream.metadataExtensions.length,
+                            },
+                            consideredCandidates: filteredCandidates.length,
+                            checkedCandidates,
+                            skipped,
+                        };
+                    }
+                }
+            }
+            catch (err) {
+                logger.debug('Sibling consistency check aborted', {
+                    name,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                warnings.push('Sibling consistency check skipped due to search or where-used processing errors.');
+            }
+        }
         const upstreamCount = upstream.tables.length + upstream.views.length + upstream.associations.length + upstream.compositions.length;
         const response = {
             name,
@@ -3010,6 +4132,8 @@ async function handleSAPContext(client, args, cachingLayer) {
                 downstreamTotal: downstream.summary.total,
                 downstreamDirect: downstream.summary.direct,
             },
+            ...(consistencyHints.length > 0 ? { consistencyHints } : {}),
+            ...(siblingExtensionAnalysis ? { siblingExtensionAnalysis } : {}),
             ...(warnings.length > 0 ? { warnings } : {}),
         };
         return textResult(JSON.stringify(response, null, 2));
@@ -3449,7 +4573,7 @@ async function handleSAPManage(client, config, args, cachingLayer, isPerUserClie
             return textResult(JSON.stringify(probed, null, 2));
         }
         default:
-            return errorResult(`Unknown SAPManage action: ${action}. Supported: features, probe, cache_stats, create_package, delete_package, flp_list_catalogs, flp_list_groups, flp_list_tiles, flp_create_catalog, flp_create_group, flp_create_tile, flp_add_tile_to_group, flp_delete_catalog`);
+            return errorResult(`Unknown SAPManage action: ${action}. Supported: features, probe, cache_stats, create_package, delete_package, change_package, flp_list_catalogs, flp_list_groups, flp_list_tiles, flp_create_catalog, flp_create_group, flp_create_tile, flp_add_tile_to_group, flp_delete_catalog`);
     }
 }
 /** Reset cached features (for testing) */