arc-1 0.7.1 → 0.8.0

package/dist/handlers/intent.js

@@ -224,7 +224,7 @@ function buildBaseErrorMessage(err, message, tool, args) {
         // Append additional SAP messages (line numbers, secondary errors) if available
         const enriched = enrichWithSapDetails(err, message);
         const argType = String(args.type ?? '').toUpperCase();
-        const classification = classifySapDomainError(err.statusCode, err.responseBody);
+        const classification = classifySapDomainError(err.statusCode, err.responseBody, err.path);
         if (classification) {
             const transactionLine = classification.transaction ? `\nSAP Transaction: ${classification.transaction}` : '';
             return `${enriched}\n\nHint: ${classification.hint}${transactionLine}`;
@@ -712,7 +712,7 @@ function getBehaviorPoolSaveFailureHint(err, args) {
 }
 function classifyError(err) {
     if (err instanceof AdtApiError) {
-        const classification = classifySapDomainError(err.statusCode, err.responseBody);
+        const classification = classifySapDomainError(err.statusCode, err.responseBody, err.path);
         return classification ? `AdtApiError:${classification.category}` : 'AdtApiError';
     }
     if (err instanceof AdtNetworkError)
@@ -834,7 +834,7 @@ export async function handleToolCall(client, config, toolName, args, authInfo, _
                     result = await handleSAPWrite(client, args, config, cachingLayer);
                     break;
                 case 'SAPActivate':
-                    result = await handleSAPActivate(client, args);
+                    result = await handleSAPActivate(client, args, cachingLayer);
                     break;
                 case 'SAPNavigate':
                     result = await handleSAPNavigate(client, args);
@@ -928,23 +928,92 @@ const BTP_HINTS = {
     SOBJ: 'BOR business objects (SOBJ) are not available on BTP ABAP Environment. Use RAP behavior definitions (BDEF) instead.',
     TRAN: 'Transaction codes (TRAN) are not available on BTP ABAP Environment. Use SAPSearch to find apps and services instead.',
 };
+const VERSIONED_SOURCE_READ_TYPES = new Set([
+    'PROG',
+    'CLAS',
+    'INTF',
+    'FUNC',
+    'INCL',
+    'DDLS',
+    'DCLS',
+    'BDEF',
+    'SRVD',
+    'DDLX',
+    'SRVB',
+    'SKTD',
+    'TABL',
+    'VIEW',
+    'STRU',
+]);
+function inactiveTypeMatches(readType, inactiveType) {
+    return (inactiveType.split('/')[0] ?? inactiveType).toUpperCase() === readType.toUpperCase();
+}
+async function resolveVersionAndDraftInfo(client, cachingLayer, type, name, requestedVersion) {
+    if (!VERSIONED_SOURCE_READ_TYPES.has(type)) {
+        return { effectiveVersion: requestedVersion === 'auto' ? 'active' : requestedVersion };
+    }
+    let draft;
+    if (cachingLayer || requestedVersion !== 'active') {
+        try {
+            const inactiveObjects = cachingLayer
+                ? await cachingLayer.inactiveLists.getOrFetch(client)
+                : await client.getInactiveObjects();
+            const upperName = name.toUpperCase();
+            draft = inactiveObjects.find((object) => inactiveTypeMatches(type, object.type) && object.name.toUpperCase() === upperName);
+        }
+        catch (err) {
+            logger.debug('Inactive object list unavailable while resolving source version', {
+                type,
+                name,
+                requestedVersion,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    if (requestedVersion === 'auto') {
+        return { effectiveVersion: draft ? 'inactive' : 'active', draft };
+    }
+    return { effectiveVersion: requestedVersion, draft };
+}
+function sourceVersionWarning(effectiveVersion, draft) {
+    if (effectiveVersion === 'active' && draft) {
+        const deletion = draft.deleted ? ' deletion' : '';
+        const transport = draft.transport ? ` (in transport ${draft.transport})` : '';
+        return `Note: You have an unactivated${deletion} draft of this object${transport}. The source below is the LAST ACTIVATED version. To work with your draft, activate it first via SAPActivate or re-run with version='inactive' to read it directly.`;
+    }
+    if (effectiveVersion === 'inactive' && !draft) {
+        return 'Note: No inactive draft exists for this object on the server. Returning the active version.';
+    }
+    return undefined;
+}
 async function handleSAPRead(client, args, cachingLayer) {
     const type = normalizeObjectType(String(args.type ?? ''));
     const name = String(args.name ?? '');
+    const requestedVersion = (args.version ?? 'active');
     // BTP: return helpful error for unavailable types
     if (isBtpSystem() && BTP_HINTS[type]) {
         return errorResult(BTP_HINTS[type]);
     }
+    if (args.force_refresh === true && cachingLayer && VERSIONED_SOURCE_READ_TYPES.has(type)) {
+        cachingLayer.inactiveLists.invalidate(client.username);
+        cachingLayer.invalidate(type, name, 'all');
+    }
+    const { effectiveVersion, draft } = await resolveVersionAndDraftInfo(client, cachingLayer, type, name, requestedVersion);
+    const versionWarning = sourceVersionWarning(effectiveVersion, draft);
     // Helper: get source with cache support, returns cache hit status
-    const cachedGet = async (objType, objName, fetcher) => {
-        if (!cachingLayer)
-            return { source: await fetcher(), cacheHit: false };
-        const { source, hit } = await cachingLayer.getSource(objType, objName, fetcher);
-        return { source, cacheHit: hit };
+    const cachedGet = async (objType, objName, version, fetcher) => {
+        if (!cachingLayer) {
+            const result = await fetcher(undefined);
+            return { source: result.source, cacheHit: false, revalidated: false };
+        }
+        const { source, hit, revalidated } = await cachingLayer.getSource(objType, objName, fetcher, { version });
+        return { source, cacheHit: hit, revalidated };
     };
-    /** Prepend [cached] indicator when result came from cache */
-    const cachedTextResult = (source, cacheHit) => {
-        return textResult(cacheHit ? `[cached]\n${source}` : source);
+    /** Prepend draft-awareness notes and cache indicator when the server revalidated a cached source. */
+    const cachedTextResult = (source, cacheHit, revalidated, warning) => {
+        const note = warning ? `${warning}\n\n` : '';
+        const indicator = cacheHit && revalidated ? '[cached:revalidated]\n' : '';
+        return textResult(`${note}${indicator}${source}`);
     };
     // Structured format is only supported for CLAS type
     if (args.format === 'structured' && type !== 'CLAS') {
@@ -952,8 +1021,8 @@ async function handleSAPRead(client, args, cachingLayer) {
     }
     switch (type) {
         case 'PROG': {
-            const { source, cacheHit } = await cachedGet('PROG', name, () => client.getProgram(name));
-            return cachedTextResult(source, cacheHit);
+            const { source, cacheHit, revalidated } = await cachedGet('PROG', name, effectiveVersion, (ifNoneMatch) => client.getProgram(name, { ifNoneMatch, version: effectiveVersion }));
+            return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'CLAS': {
             // Structured format: return JSON with metadata + decomposed source
@@ -964,7 +1033,7 @@ async function handleSAPRead(client, args, cachingLayer) {
             const methodParam = args.method;
             if (methodParam && !args.include) {
                 // Method-level read — fetch full source then extract (no cache indicator for derived results)
-                const { source: fullSource } = await cachedGet('CLAS', name, () => client.getClass(name));
+                const { source: fullSource } = await cachedGet('CLAS', name, effectiveVersion, (ifNoneMatch) => client.getClass(name, undefined, { ifNoneMatch, version: effectiveVersion }));
                 const abaplintVer = cachedFeatures?.abapRelease
                     ? mapSapReleaseToAbaplintVersion(cachedFeatures.abapRelease)
                     : undefined;
@@ -976,18 +1045,21 @@ async function handleSAPRead(client, args, cachingLayer) {
                 if (!extracted.success) {
                     return errorResult(extracted.error ?? `Method "${methodParam}" not found in ${name}.`);
                 }
-                return textResult(extracted.methodSource);
+                return cachedTextResult(extracted.methodSource, false, false, versionWarning);
             }
             // Only cache the full merged source (no include param), not individual includes
             if (!args.include) {
-                const { source, cacheHit } = await cachedGet('CLAS', name, () => client.getClass(name));
-                return cachedTextResult(source, cacheHit);
+                const { source, cacheHit, revalidated } = await cachedGet('CLAS', name, effectiveVersion, (ifNoneMatch) => client.getClass(name, undefined, { ifNoneMatch, version: effectiveVersion }));
+                return cachedTextResult(source, cacheHit, revalidated, versionWarning);
             }
-            return textResult(await client.getClass(name, args.include));
+            const includeResult = await client.getClass(name, args.include, {
+                version: effectiveVersion,
+            });
+            return cachedTextResult(includeResult.source, false, false, versionWarning);
         }
         case 'INTF': {
-            const { source, cacheHit } = await cachedGet('INTF', name, () => client.getInterface(name));
-            return cachedTextResult(source, cacheHit);
+            const { source, cacheHit, revalidated } = await cachedGet('INTF', name, effectiveVersion, (ifNoneMatch) => client.getInterface(name, { ifNoneMatch, version: effectiveVersion }));
+            return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'FUNC': {
             let group = String(args.group ?? '');
@@ -1001,13 +1073,13 @@ async function handleSAPRead(client, args, cachingLayer) {
                 }
                 group = resolved;
             }
-            const { source, cacheHit } = await cachedGet('FUNC', name, () => client.getFunction(group, name));
-            return cachedTextResult(source, cacheHit);
+            const { source, cacheHit, revalidated } = await cachedGet('FUNC', name, effectiveVersion, (ifNoneMatch) => client.getFunction(group, name, { ifNoneMatch, version: effectiveVersion }));
+            return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'FUGR': {
             const expand = Boolean(args.expand_includes);
             if (expand) {
-                const source = await client.getFunctionGroupSource(name);
+                const { source } = await client.getFunctionGroupSource(name, { version: effectiveVersion });
                 // Match INCLUDE statements but skip ABAP comment lines (starting with *)
                 const includePattern = /^[^*\n]*\bINCLUDE\s+(\S+)\s*\./gim;
                 const parts = [`=== FUGR ${name} (main) ===\n${source}`];
@@ -1015,7 +1087,7 @@ async function handleSAPRead(client, args, cachingLayer) {
                 while ((m = includePattern.exec(source)) !== null) {
                     const inclName = m[1];
                     try {
-                        const inclSource = await client.getInclude(inclName);
+                        const { source: inclSource } = await client.getInclude(inclName, { version: effectiveVersion });
                         parts.push(`\n=== ${inclName} ===\n${inclSource}`);
                     }
                     catch {
@@ -1028,37 +1100,37 @@ async function handleSAPRead(client, args, cachingLayer) {
             return textResult(JSON.stringify(fg, null, 2));
         }
         case 'INCL': {
-            const { source, cacheHit } = await cachedGet('INCL', name, () => client.getInclude(name));
-            return cachedTextResult(source, cacheHit);
+            const { source, cacheHit, revalidated } = await cachedGet('INCL', name, effectiveVersion, (ifNoneMatch) => client.getInclude(name, { ifNoneMatch, version: effectiveVersion }));
+            return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'DDLS': {
-            const { source: ddlSource, cacheHit } = await cachedGet('DDLS', name, () => client.getDdls(name));
+            const { source: ddlSource, cacheHit, revalidated, } = await cachedGet('DDLS', name, effectiveVersion, (ifNoneMatch) => client.getDdls(name, { ifNoneMatch, version: effectiveVersion }));
             if (ddlSource.trim() === '') {
                 return textResult(`DDLS ${name} exists in the object directory but has no source code stored. ` +
                     `The DDL source may need to be written via SAPWrite(action="create" or "update", type="DDLS", name="${name}", source="...").`);
             }
             if (args.include?.toLowerCase() === 'elements') {
                 // Elements extraction is derived from source — no cache indicator
-                return textResult(extractCdsElements(ddlSource, name));
+                return cachedTextResult(extractCdsElements(ddlSource, name), false, false, versionWarning);
             }
-            return cachedTextResult(ddlSource, cacheHit);
+            return cachedTextResult(ddlSource, cacheHit, revalidated, versionWarning);
         }
         case 'DCLS': {
-            const { source, cacheHit } = await cachedGet('DCLS', name, () => client.getDcl(name));
-            return cachedTextResult(source, cacheHit);
+            const { source, cacheHit, revalidated } = await cachedGet('DCLS', name, effectiveVersion, (ifNoneMatch) => client.getDcl(name, { ifNoneMatch, version: effectiveVersion }));
+            return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'BDEF': {
-            const { source, cacheHit } = await cachedGet('BDEF', name, () => client.getBdef(name));
-            return cachedTextResult(source, cacheHit);
+            const { source, cacheHit, revalidated } = await cachedGet('BDEF', name, effectiveVersion, (ifNoneMatch) => client.getBdef(name, { ifNoneMatch, version: effectiveVersion }));
+            return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'SRVD': {
-            const { source, cacheHit } = await cachedGet('SRVD', name, () => client.getSrvd(name));
-            return cachedTextResult(source, cacheHit);
+            const { source, cacheHit, revalidated } = await cachedGet('SRVD', name, effectiveVersion, (ifNoneMatch) => client.getSrvd(name, { ifNoneMatch, version: effectiveVersion }));
+            return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'DDLX': {
             try {
-                const { source, cacheHit } = await cachedGet('DDLX', name, () => client.getDdlx(name));
-                return cachedTextResult(source, cacheHit);
+                const { source, cacheHit, revalidated } = await cachedGet('DDLX', name, effectiveVersion, (ifNoneMatch) => client.getDdlx(name, { ifNoneMatch, version: effectiveVersion }));
+                return cachedTextResult(source, cacheHit, revalidated, versionWarning);
             }
             catch (err) {
                 if (isNotFoundError(err)) {
@@ -1068,16 +1140,16 @@ async function handleSAPRead(client, args, cachingLayer) {
             }
         }
         case 'SRVB': {
-            const { source, cacheHit } = await cachedGet('SRVB', name, () => client.getSrvb(name));
-            return cachedTextResult(source, cacheHit);
+            const { source, cacheHit, revalidated } = await cachedGet('SRVB', name, effectiveVersion, (ifNoneMatch) => client.getSrvb(name, { ifNoneMatch, version: effectiveVersion }));
+            return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'SKTD': {
             try {
                 // ADT returns a <sktd:docu> XML envelope with the Markdown body base64-encoded
                 // inside <sktd:text>. Cache the raw envelope (update flow re-uses it) and
                 // return the decoded Markdown to the LLM.
-                const { source, cacheHit } = await cachedGet('SKTD', name, () => client.getKtd(name));
-                return cachedTextResult(decodeKtdText(source), cacheHit);
+                const { source, cacheHit, revalidated } = await cachedGet('SKTD', name, effectiveVersion, (ifNoneMatch) => client.getKtd(name, { ifNoneMatch, version: effectiveVersion }));
+                return cachedTextResult(decodeKtdText(source), cacheHit, revalidated, versionWarning);
             }
             catch (err) {
                 if (isNotFoundError(err)) {
@@ -1087,16 +1159,16 @@ async function handleSAPRead(client, args, cachingLayer) {
             }
         }
         case 'TABL': {
-            const { source, cacheHit } = await cachedGet('TABL', name, () => client.getTable(name));
-            return cachedTextResult(source, cacheHit);
+            const { source, cacheHit, revalidated } = await cachedGet('TABL', name, effectiveVersion, (ifNoneMatch) => client.getTable(name, { ifNoneMatch, version: effectiveVersion }));
+            return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'VIEW': {
-            const { source, cacheHit } = await cachedGet('VIEW', name, () => client.getView(name));
-            return cachedTextResult(source, cacheHit);
+            const { source, cacheHit, revalidated } = await cachedGet('VIEW', name, effectiveVersion, (ifNoneMatch) => client.getView(name, { ifNoneMatch, version: effectiveVersion }));
+            return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'STRU': {
-            const { source, cacheHit } = await cachedGet('STRU', name, () => client.getStructure(name));
-            return cachedTextResult(source, cacheHit);
+            const { source, cacheHit, revalidated } = await cachedGet('STRU', name, effectiveVersion, (ifNoneMatch) => client.getStructure(name, { ifNoneMatch, version: effectiveVersion }));
+            return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'DOMA': {
             const domain = await client.getDomain(name);
@@ -1208,7 +1280,7 @@ async function handleSAPRead(client, args, cachingLayer) {
                     if (!prog) {
                         return errorResult(`BOR method "${method}" on "${name}" has no program assigned.`);
                     }
-                    const source = await client.getProgram(prog);
+                    const { source } = await client.getProgram(prog);
                     return textResult(`=== BOR ${name}.${method} (program: ${prog}, form: ${String(data.rows[0].FORMNAME ?? '').trim()}) ===\n${source}`);
                 }
                 return errorResult(`BOR method "${method}" not found on object type "${name}". Use SAPRead(type="SOBJ", name="${name}") without method to list all methods.`);
@@ -1280,18 +1352,8 @@ async function handleSAPRead(client, args, cachingLayer) {
             return textResult(JSON.stringify(info, null, 2));
         }
         case 'INACTIVE_OBJECTS': {
-            try {
-                const objects = await client.getInactiveObjects();
-                return textResult(JSON.stringify({ count: objects.length, objects }, null, 2));
-            }
-            catch (err) {
-                if (isNotFoundError(err)) {
-                    return textResult('Inactive objects listing is not available on this SAP system ' +
-                        '(the /sap/bc/adt/activation/inactive endpoint returned 404). ' +
-                        'Use SAPDiagnose(action="syntax", type="...", name="...") to check specific objects instead.');
-                }
-                throw err;
-            }
+            const objects = await client.getInactiveObjects();
+            return textResult(JSON.stringify({ count: objects.length, objects }, null, 2));
         }
         default:
             return errorResult(`Unknown SAPRead type: "${type}". Supported types: PROG, CLAS, INTF, FUNC, FUGR, INCL, DDLS, DCLS, DDLX, BDEF, SRVD, SRVB, SKTD, TABL, VIEW, STRU, DOMA, DTEL, AUTH, FTG2, ENHO, VERSIONS, VERSION_SOURCE, TRAN, TABLE_CONTENTS, DEVC, SOBJ, SYSTEM, COMPONENTS, MESSAGES, TEXT_ELEMENTS, VARIANTS, BSP, BSP_DEPLOY, API_STATE, INACTIVE_OBJECTS. ` +
@@ -1658,7 +1720,7 @@ async function mergeMetadataWriteProperties(client, type, name, provided) {
             };
         }
         if (type === 'SRVB') {
-            const existingRaw = await client.getSrvb(name);
+            const { source: existingRaw } = await client.getSrvb(name);
             const existing = JSON.parse(existingRaw);
             return {
                 _description: existing.description,
@@ -2195,6 +2257,10 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
     }
     const objectUrl = objectUrlForType(type, name);
     const srcUrl = sourceUrlForType(type, name);
+    const invalidateWrittenObject = (objType = type, objName = name) => {
+        cachingLayer?.invalidate(objType, objName, 'all');
+        cachingLayer?.inactiveLists.invalidate(client.username);
+    };
     // Helper: enforce allowedPackages for existing objects (update/delete/edit_method/scaffold_rap_handlers).
     // Only fetches metadata when package restrictions are configured — no extra HTTP call otherwise.
     async function enforcePackageForExistingObject() {
@@ -2215,10 +2281,10 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                 // no-ops (or 415s on strict systems). Fetch the current envelope,
                 // replace only the <sktd:text> body, and PUT it back — preserves
                 // responsible/masterLanguage/packageRef/refObject metadata.
-                const currentEnvelope = await client.getKtd(name);
+                const { source: currentEnvelope } = await client.getKtd(name);
                 const body = rewriteKtdText(currentEnvelope, source);
                 await safeUpdateObject(client.http, client.safety, objectUrl, body, SKTD_V2_CONTENT_TYPE, transport);
-                cachingLayer?.invalidate(type, name);
+                invalidateWrittenObject();
                 return textResult(`Successfully updated ${type} ${name}.`);
             }
             if (isMetadataWriteType(type)) {
@@ -2231,7 +2297,7 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                 const pkg = String(args.package ?? existingPackage ?? mergedProps._package ?? '$TMP');
                 const body = buildCreateXml(type, name, pkg, description, mergedProps);
                 await safeUpdateObject(client.http, client.safety, objectUrl, body, vendorContentTypeForType(type), transport);
-                cachingLayer?.invalidate(type, name);
+                invalidateWrittenObject();
                 return textResult(`Successfully updated ${type} ${name}.`);
             }
             // RAP deterministic preflight validation
@@ -2251,7 +2317,7 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
             // 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);
+            invalidateWrittenObject();
             const msg = `Successfully updated ${type} ${name}.`;
             const cdsUpdateHint = type === 'DDLS' ? await buildCdsUpdateCrudHint(client, name, objectUrl) : undefined;
             const warnings = mergePreWriteWarnings(preflightWarnings.warnings, lintWarnings.warnings, checkNotes, cdsUpdateHint);
@@ -2338,13 +2404,13 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                 // PUT back exactly the shape SAP gave us (with all the server-assigned
                 // metadata), only swapping <sktd:text>.
                 if (source) {
-                    const currentEnvelope = await client.getKtd(name);
+                    const { source: currentEnvelope } = await client.getKtd(name);
                     const body = rewriteKtdText(currentEnvelope, source);
                     await safeUpdateObject(client.http, client.safety, objectUrl, body, SKTD_V2_CONTENT_TYPE, effectiveTransport);
-                    cachingLayer?.invalidate(type, name);
+                    invalidateWrittenObject();
                     return textResult(`Created SKTD ${name} in package ${pkg} and wrote Markdown content.\nNext step: SAPActivate(type="SKTD", name="${name}").\n${ktdResult}`);
                 }
-                cachingLayer?.invalidate(type, name);
+                invalidateWrittenObject();
                 return textResult(`Created SKTD ${name} in package ${pkg} (no Markdown content written — pass "source" to write the body).\nNext step: SAPActivate(type="SKTD", name="${name}").\n${ktdResult}`);
             }
             // Build type-specific creation XML body.
@@ -2403,7 +2469,7 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                         }
                     });
                 }
-                cachingLayer?.invalidate(type, name);
+                invalidateWrittenObject();
                 const followUpHint = type === 'SRVB'
                     ? `\n\nNext steps:\n1. SAPActivate(type="SRVB", name="${name}")\n2. SAPActivate(action="publish_srvb", name="${name}")`
                     : '';
@@ -2417,7 +2483,7 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                     return textResult(`Created ${type} ${name} in package ${pkg}, but source was rejected by lint:\n${lintWarnings.result.content[0].text}`);
                 }
                 await safeUpdateSource(client.http, client.safety, objectUrl, srcUrl, source, effectiveTransport);
-                cachingLayer?.invalidate(type, name);
+                invalidateWrittenObject();
                 const msg = `Created ${type} ${name} in package ${pkg} and wrote source code.`;
                 const warnings = mergePreWriteWarnings(preflightWarnings.warnings, lintWarnings.warnings);
                 return warnings ? textResult(`${msg}\n\n${warnings}`) : textResult(msg);
@@ -2435,8 +2501,8 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
             await enforcePackageForExistingObject();
             // Fetch current full source (use cache if available)
             const currentSource = cachingLayer
-                ? (await cachingLayer.getSource('CLAS', name, () => client.getClass(name))).source
-                : await client.getClass(name);
+                ? (await cachingLayer.getSource('CLAS', name, (ifNoneMatch) => client.getClass(name, undefined, { ifNoneMatch }))).source
+                : (await client.getClass(name)).source;
             // Use detected ABAP version from probe if available
             const abaplintVer = cachedFeatures?.abapRelease
                 ? mapSapReleaseToAbaplintVersion(cachedFeatures.abapRelease)
@@ -2454,7 +2520,7 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
             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);
+            invalidateWrittenObject();
             const msg = `Successfully updated method "${method}" in ${type} ${name}.`;
             const extras = [lintWarnings.warnings, checkNotes].filter(Boolean).join('\n\n');
             return extras ? textResult(`${msg}\n\n${extras}`) : textResult(msg);
@@ -2510,8 +2576,9 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                 .filter(Boolean)
                 .join('\n\n');
             const bdefSource = cachingLayer
-                ? (await cachingLayer.getSource('BDEF', bdefName, () => client.getBdef(bdefName))).source
-                : await client.getBdef(bdefName);
+                ? (await cachingLayer.getSource('BDEF', bdefName, (ifNoneMatch) => client.getBdef(bdefName, { ifNoneMatch })))
+                    .source
+                : (await client.getBdef(bdefName)).source;
             let requirements = extractRapHandlerRequirements(bdefSource);
             if (targetAlias) {
                 requirements = requirements.filter((req) => req.entityAlias.toLowerCase() === targetAlias);
@@ -2622,7 +2689,7 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                     }
                 }
             });
-            cachingLayer?.invalidate(type, name);
+            invalidateWrittenObject();
             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);
@@ -2672,7 +2739,7 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                 }
                 throw err;
             }
-            cachingLayer?.invalidate(type, name);
+            invalidateWrittenObject();
             return textResult(`Deleted ${type} ${name}.`);
         }
         case 'batch_create': {
@@ -2809,7 +2876,7 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                         });
                         break;
                     }
-                    cachingLayer?.invalidate(objType, objName);
+                    invalidateWrittenObject(objType, objName);
                     results.push({ type: objType, name: objName, status: 'success' });
                 }
                 catch (err) {
@@ -3002,7 +3069,7 @@ async function runPreWriteSyntaxCheck(client, type, source, objectUrl, config, p
     }
 }
 // ─── SAPActivate Handler ─────────────────────────────────────────────
-async function handleSAPActivate(client, args) {
+async function handleSAPActivate(client, args, cachingLayer) {
     const action = String(args.action ?? 'activate');
     const name = String(args.name ?? '');
     const version = String(args.version ?? '0001');
@@ -3013,7 +3080,7 @@ async function handleSAPActivate(client, args) {
         if (explicitServiceType === 'odatav4' || explicitServiceType === 'odatav2')
             return explicitServiceType;
         try {
-            const srvbJson = await client.getSrvb(name);
+            const { source: srvbJson } = await client.getSrvb(name);
             const srvb = JSON.parse(srvbJson);
             if (srvb.odataVersion === 'V4')
                 return 'odatav4';
@@ -3035,7 +3102,7 @@ async function handleSAPActivate(client, args) {
         }
         let srvbInfo;
         try {
-            srvbInfo = await client.getSrvb(name);
+            srvbInfo = (await client.getSrvb(name)).source;
         }
         catch {
             if (result.severity === 'UNKNOWN') {
@@ -3070,7 +3137,7 @@ async function handleSAPActivate(client, args) {
         }
         let srvbInfo;
         try {
-            srvbInfo = await client.getSrvb(name);
+            srvbInfo = (await client.getSrvb(name)).source;
         }
         catch {
             // Readback failed — fall through with what we have
@@ -3108,6 +3175,10 @@ async function handleSAPActivate(client, args) {
         const batchStatuses = buildBatchActivationStatuses(objects, result);
         const statusDetails = formatBatchActivationStatuses(batchStatuses);
         if (result.success) {
+            for (const object of objects) {
+                cachingLayer?.invalidate(object.type, object.name, 'all');
+            }
+            cachingLayer?.inactiveLists.invalidate(client.username);
             return textResult(`Successfully activated ${objects.length} objects: ${names}.${statusDetails}`);
         }
         // On batch failure enrich with per-object inactive-version syntax errors —
@@ -3124,6 +3195,8 @@ async function handleSAPActivate(client, args) {
     const objectUrl = objectUrlForType(type, name);
     const result = await activate(client.http, client.safety, objectUrl, { ...activateOpts, name });
     if (result.success) {
+        cachingLayer?.invalidate(type, name, 'all');
+        cachingLayer?.inactiveLists.invalidate(client.username);
         return textResult(`Successfully activated ${type} ${name}.${formatActivationMessages(result)}`);
     }
     // On failure, try to enrich with the actual compiler errors from the inactive version —
@@ -3973,7 +4046,7 @@ async function handleSAPContext(client, args, cachingLayer) {
     // Helper: get source with cache support
     const cachedGet = async (objType, objName, fetcher) => {
         if (!cachingLayer)
-            return fetcher();
+            return (await fetcher()).source;
         const { source } = await cachingLayer.getSource(objType, objName, fetcher);
         return source;
     };
@@ -3981,7 +4054,7 @@ async function handleSAPContext(client, args, cachingLayer) {
         if (type !== 'DDLS') {
             return errorResult('SAPContext(action="impact") supports DDLS only. For non-CDS objects, use SAPNavigate(action="references").');
         }
-        const ddlSource = await cachedGet('DDLS', name, () => client.getDdls(name));
+        const ddlSource = await cachedGet('DDLS', name, (ifNoneMatch) => client.getDdls(name, { ifNoneMatch }));
         const upstream = buildCdsUpstream(extractCdsDependencies(ddlSource));
         const includeIndirect = args.includeIndirect === true;
         const siblingCheck = args.siblingCheck !== false;
@@ -4146,24 +4219,24 @@ async function handleSAPContext(client, args, cachingLayer) {
     else {
         switch (type) {
             case 'CLAS':
-                source = await cachedGet('CLAS', name, () => client.getClass(name));
+                source = await cachedGet('CLAS', name, (ifNoneMatch) => client.getClass(name, undefined, { ifNoneMatch }));
                 break;
             case 'INTF':
-                source = await cachedGet('INTF', name, () => client.getInterface(name));
+                source = await cachedGet('INTF', name, (ifNoneMatch) => client.getInterface(name, { ifNoneMatch }));
                 break;
             case 'PROG':
-                source = await cachedGet('PROG', name, () => client.getProgram(name));
+                source = await cachedGet('PROG', name, (ifNoneMatch) => client.getProgram(name, { ifNoneMatch }));
                 break;
             case 'FUNC': {
                 const group = String(args.group ?? '');
                 if (!group) {
                     return errorResult('The "group" parameter is required for FUNC type. Use SAPSearch to find the function group.');
                 }
-                source = await cachedGet('FUNC', name, () => client.getFunction(group, name));
+                source = await cachedGet('FUNC', name, (ifNoneMatch) => client.getFunction(group, name, { ifNoneMatch }));
                 break;
             }
             case 'DDLS': {
-                const ddlSource = await cachedGet('DDLS', name, () => client.getDdls(name));
+                const ddlSource = await cachedGet('DDLS', name, (ifNoneMatch) => client.getDdls(name, { ifNoneMatch }));
                 const cdsResult = await compressCdsContext(client, ddlSource, name, maxDeps, depth, cachingLayer);
                 return textResult(cdsResult.output);
             }
@@ -4536,6 +4609,7 @@ async function handleSAPManage(client, config, args, cachingLayer, isPerUserClie
                 enabled: true,
                 warmupAvailable: cachingLayer.isWarmupAvailable,
                 ...stats,
+                inactiveListCache: cachingLayer.inactiveLists.stats(),
             }, null, 2));
         }
         case 'probe': {