arc-1 0.9.3 → 0.9.5

package/dist/handlers/intent.js

@@ -15,11 +15,13 @@ import { findDefinition, findInterfaceImplementersViaSeoMetaRel, findReferences,
 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, getGatewayErrorDetail, getTraceDbAccesses, getTraceHitlist, getTraceStatements, listDumps, listGatewayErrors, listSystemMessages, listTraces, } from '../adt/diagnostics.js';
+import { getDump, getGatewayErrorDetail, getObjectState, 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 { parseFmSignature, spliceFmSignature } from '../adt/fm-signature.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 { generateBehaviorImplementation, isRapGenerateResultSuccess } from '../adt/rap-generate.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';
@@ -764,14 +766,26 @@ export async function handleToolCall(client, config, toolName, args, authInfo, _
     // Unified scope enforcement via ACTION_POLICY — routes through action/type-aware lookup.
     // For SAPRead, the policy key is Tool.{type}; for other action-bearing tools, Tool.{action};
     // for tools without an action/type enum (SAPSearch, SAPQuery), the tool-level default applies.
+    // For SAPSearch.tadir_lookup with source='db'|'both', synthesize a sub-action key so the
+    // sql-scoped policy entry kicks in (otherwise viewer-only profiles could piggyback on the
+    // ADT info-system route to issue freestyle SQL).
     // Runs BEFORE Zod validation so scope errors don't leak schema details to unauthorized callers.
-    const actionOrType = toolName === 'SAPRead'
+    let actionOrType = toolName === 'SAPRead'
         ? typeof args.type === 'string'
             ? args.type
             : undefined
         : typeof args.action === 'string'
             ? args.action
             : undefined;
+    if (toolName === 'SAPSearch' &&
+        typeof args.searchType === 'string' &&
+        args.searchType === 'tadir_lookup' &&
+        typeof args.source === 'string') {
+        const src = args.source.toLowerCase();
+        if (src === 'db' || src === 'both') {
+            actionOrType = `tadir_lookup_${src}`;
+        }
+    }
     const policy = getActionPolicy(toolName, actionOrType);
     if (authInfo && policy) {
         if (!hasRequiredScope(authInfo, policy.scope)) {
@@ -1086,6 +1100,26 @@ async function handleSAPRead(client, args, cachingLayer) {
                 group = resolved;
             }
             const { source, cacheHit, revalidated } = await cachedGet('FUNC', name, effectiveVersion, (ifNoneMatch) => client.getFunction(group, name, { ifNoneMatch, version: effectiveVersion }));
+            // Issue #252: when caller asks for includeSignature, return JSON with the
+            // source body and the parsed structured signature.
+            if (args.includeSignature === true) {
+                const parsed = parseFmSignature(source);
+                const grouped = {
+                    importing: [],
+                    exporting: [],
+                    changing: [],
+                    tables: [],
+                    exceptions: [],
+                    raising: [],
+                };
+                for (const p of parsed.params)
+                    grouped[p.kind].push(p);
+                const payload = {
+                    source,
+                    signature: grouped,
+                };
+                return textResult(JSON.stringify(payload, null, 2));
+            }
             return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'FUGR': {
@@ -1397,6 +1431,99 @@ async function handleSAPSearch(client, args) {
     const rawQuery = String(args.query ?? '');
     const maxResults = Number(args.maxResults ?? 100);
     const searchType = String(args.searchType ?? 'object');
+    if (searchType === 'tadir_lookup') {
+        const names = extractLookupNames(rawQuery, args.names);
+        if (names.length === 0) {
+            return errorResult('SAPSearch(searchType="tadir_lookup") requires names[] or query with at least one name.');
+        }
+        const objectTypes = extractLookupObjectTypes(args.objectType, args.objectTypes);
+        const rawSource = typeof args.source === 'string' ? args.source.toLowerCase() : 'adt';
+        const source = rawSource === 'db' || rawSource === 'both' ? rawSource : 'adt';
+        // Stamp each match with provenance so a merged 'both' result is unambiguous and
+        // viewer tooling can colour-code ghost rows. The DB path already stamps `_origin:'db'`
+        // (see `lookupObjectsViaDb`); we stamp ADT matches here.
+        const tagOrigin = (lookups, origin) => lookups.map((l) => ({
+            ...l,
+            matches: l.matches.map((m) => ({ ...m, _origin: m._origin ?? origin })),
+        }));
+        let finalLookups;
+        const wildcardNames = names.filter((name) => name.includes('*'));
+        const warnings = [];
+        let splitBrain = [];
+        if (source === 'adt') {
+            finalLookups = tagOrigin(await client.lookupObjects(names, { maxResults, objectTypes }), 'adt');
+        }
+        else if (source === 'db') {
+            // The 'db' path bypasses ADT info-system entirely; `lookupObjectsViaDb` already
+            // tags matches with `_origin:'db'`. Safety/scope gating runs at handleToolCall
+            // and in client.runQuery (FreeSQL operation), so unauthorized callers never reach here.
+            finalLookups = await client.lookupObjectsViaDb(names, { maxResults, objectTypes });
+        }
+        else {
+            // 'both' — parallel ADT + DB, merge per name with dedupe.
+            const [adtLookups, dbLookups] = await Promise.all([
+                client.lookupObjects(names, { maxResults, objectTypes }).then((r) => tagOrigin(r, 'adt')),
+                client.lookupObjectsViaDb(names, { maxResults, objectTypes }),
+            ]);
+            const dbByName = new Map(dbLookups.map((l) => [l.name.toUpperCase(), l]));
+            const adtByName = new Map(adtLookups.map((l) => [l.name.toUpperCase(), l]));
+            finalLookups = names.map((rawName) => {
+                const upper = rawName.toUpperCase();
+                const adt = adtByName.get(upper);
+                const db = dbByName.get(upper);
+                const adtMatches = adt?.matches ?? [];
+                const dbMatches = db?.matches ?? [];
+                // Dedupe by (baseObjectType, objectName) — TADIR stores bare types ('DDLS')
+                // while ADT info-system returns slash-form ('DDLS/DF'). Stripping the suffix
+                // keeps the same logical object from appearing twice in the merged matches.
+                // Preserve the more-specific slash form when both originate from ADT+DB.
+                const seen = new Map();
+                const baseKey = (m) => `${(m.objectType.split('/')[0] || m.objectType).toUpperCase()}${m.objectName.toUpperCase()}`;
+                for (const m of adtMatches)
+                    seen.set(baseKey(m), m);
+                for (const m of dbMatches) {
+                    const k = baseKey(m);
+                    if (!seen.has(k))
+                        seen.set(k, m);
+                }
+                const mergedMatches = [...seen.values()];
+                // Split-brain detection: an object is divergent if exactly one source has matches.
+                // (Zero matches on both sides = consistent absence; matches on both = consistent presence.)
+                if (adtMatches.length > 0 !== dbMatches.length > 0) {
+                    splitBrain.push(rawName);
+                }
+                return { name: rawName, found: mergedMatches.length > 0, matches: mergedMatches };
+            });
+            // Compose human-friendly warnings per split-brain name. Keep them grounded in
+            // the most common cause (TADIR ghost from aborted create/delete) so LLM clients
+            // can suggest the right cleanup path without inventing a new pointer.
+            for (const name of splitBrain) {
+                const adt = adtByName.get(name.toUpperCase());
+                const db = dbByName.get(name.toUpperCase());
+                const adtHas = (adt?.matches.length ?? 0) > 0;
+                const dbHas = (db?.matches.length ?? 0) > 0;
+                if (dbHas && !adtHas) {
+                    warnings.push(`${name} exists in TADIR (DB) but ADT cannot resolve it — likely a TADIR ghost from an aborted create/delete cycle. Consider RS_DD_TADIR_CLEANUP or manual SE03 cleanup.`);
+                }
+                else if (adtHas && !dbHas) {
+                    warnings.push(`${name} resolves via ADT but is not present in the TADIR row scan — likely a release-time mismatch or a type filter excluding the row. Re-run with broader objectTypes or no filter to confirm.`);
+                }
+            }
+        }
+        // Dedupe split-brain names (defensive; merge loop should already avoid duplicates).
+        splitBrain = [...new Set(splitBrain)];
+        if (wildcardNames.length > 0) {
+            warnings.push(`tadir_lookup performs exact-name lookup; wildcard characters are treated literally for: ${wildcardNames.join(', ')}`);
+        }
+        const missing = finalLookups.filter((l) => !l.found).map((l) => l.name);
+        const matchCount = finalLookups.reduce((count, lookup) => count + lookup.matches.length, 0);
+        const payload = { count: matchCount, lookups: finalLookups, missing };
+        if (splitBrain.length > 0)
+            payload.splitBrain = splitBrain;
+        if (warnings.length > 0)
+            payload.warnings = warnings;
+        return textResult(JSON.stringify(payload, null, 2));
+    }
     if (searchType === 'source_code') {
         // Source code search: do NOT transliterate — source can contain umlauts in strings/comments
         if (cachedFeatures?.textSearch && !cachedFeatures.textSearch.available) {
@@ -1441,6 +1568,37 @@ async function handleSAPSearch(client, args) {
     }
     return textResult(transliterationNote + JSON.stringify(results, null, 2));
 }
+function extractLookupNames(query, rawNames) {
+    const fromNames = Array.isArray(rawNames) ? rawNames.map((n) => String(n).trim()).filter(Boolean) : [];
+    const fromQuery = query
+        .split(/[,\s]+/)
+        .map((n) => n.trim())
+        .filter(Boolean);
+    return [...new Set([...fromNames, ...fromQuery].map((n) => n.toUpperCase()))];
+}
+function extractLookupObjectTypes(rawObjectType, rawObjectTypes) {
+    const types = Array.isArray(rawObjectTypes)
+        ? rawObjectTypes.map((t) => normalizeObjectType(String(t))).filter(Boolean)
+        : [];
+    if (typeof rawObjectType === 'string' && rawObjectType.trim()) {
+        types.push(normalizeObjectType(rawObjectType));
+    }
+    return [...new Set(types)];
+}
+function normalizePackageOverride(rawPackage, fallback) {
+    if (rawPackage === undefined || rawPackage === null) {
+        return fallback;
+    }
+    const value = String(rawPackage).trim();
+    return value || fallback;
+}
+function normalizeTransportOverride(rawTransport) {
+    if (rawTransport === undefined || rawTransport === null) {
+        return undefined;
+    }
+    const value = String(rawTransport).trim();
+    return value || undefined;
+}
 function classifySapQueryParserError(err, sql) {
     if (err.statusCode !== 400)
         return undefined;
@@ -1460,11 +1618,136 @@ function classifySapQueryParserError(err, sql) {
     }
     return `${err.message}\n\nHint: ${hints.join(' ')}`;
 }
+const SAPQUERY_IN_LIST_CHUNK_SIZE = 8;
+function planSimpleInListChunking(sql, chunkSize = SAPQUERY_IN_LIST_CHUNK_SIZE) {
+    const maskedSql = maskSqlStringLiterals(sql);
+    if (maskedSql.includes(';'))
+        return undefined;
+    if (countSelectKeywords(maskedSql) !== 1)
+        return undefined;
+    const matches = [...maskedSql.matchAll(/\b[A-Za-z_][A-Za-z0-9_~.]*\s+IN\s*\(/gi)];
+    if (matches.length !== 1)
+        return undefined;
+    const match = matches[0];
+    const matchText = match[0];
+    const fieldName = matchText.match(/^([A-Za-z_][A-Za-z0-9_~.]*)\s+IN\s*\(/i)?.[1];
+    if (!fieldName || fieldName.toUpperCase() === 'NOT')
+        return undefined;
+    const matchStart = match.index ?? 0;
+    const openParen = matchStart + matchText.lastIndexOf('(');
+    const closeParen = findMatchingParen(maskedSql, openParen);
+    if (closeParen < 0)
+        return undefined;
+    const literals = parseSingleQuotedLiteralList(sql.slice(openParen + 1, closeParen));
+    if (!literals || literals.length <= chunkSize)
+        return undefined;
+    const prefix = sql.slice(0, openParen + 1);
+    const suffix = sql.slice(closeParen);
+    const statements = [];
+    for (let i = 0; i < literals.length; i += chunkSize) {
+        statements.push(`${prefix}${literals.slice(i, i + chunkSize).join(', ')}${suffix}`);
+    }
+    return { statements };
+}
+function maskSqlStringLiterals(sql) {
+    let masked = '';
+    let inString = false;
+    for (let i = 0; i < sql.length; i++) {
+        const ch = sql[i];
+        if (ch === "'") {
+            if (inString && sql[i + 1] === "'") {
+                masked += '  ';
+                i++;
+                continue;
+            }
+            inString = !inString;
+            masked += ' ';
+            continue;
+        }
+        masked += inString ? ' ' : ch;
+    }
+    return masked;
+}
+function countSelectKeywords(maskedSql) {
+    return [...maskedSql.matchAll(/\bSELECT\b/gi)].length;
+}
+function findMatchingParen(text, openParen) {
+    let depth = 0;
+    for (let i = openParen; i < text.length; i++) {
+        if (text[i] === '(')
+            depth++;
+        if (text[i] === ')') {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return -1;
+}
+function parseSingleQuotedLiteralList(listText) {
+    const literals = [];
+    let i = 0;
+    let expectingValue = true;
+    while (i < listText.length) {
+        while (i < listText.length && /\s/.test(listText[i]))
+            i++;
+        if (i >= listText.length)
+            return expectingValue && literals.length > 0 ? undefined : literals;
+        if (!expectingValue || listText[i] !== "'")
+            return undefined;
+        const start = i;
+        i++;
+        let closed = false;
+        while (i < listText.length) {
+            if (listText[i] === "'") {
+                if (listText[i + 1] === "'") {
+                    i += 2;
+                    continue;
+                }
+                i++;
+                closed = true;
+                break;
+            }
+            i++;
+        }
+        if (!closed)
+            return undefined;
+        literals.push(listText.slice(start, i));
+        expectingValue = false;
+        while (i < listText.length && /\s/.test(listText[i]))
+            i++;
+        if (i >= listText.length)
+            return literals;
+        if (listText[i] !== ',')
+            return undefined;
+        i++;
+        expectingValue = true;
+    }
+    return expectingValue && literals.length > 0 ? undefined : literals;
+}
+async function runChunkedSapQuery(client, plan, maxRows) {
+    const rowLimit = Number.isFinite(maxRows) && maxRows > 0 ? Math.floor(maxRows) : 100;
+    const rows = [];
+    let columns = [];
+    for (const statement of plan.statements) {
+        const remaining = Math.max(0, rowLimit - rows.length);
+        if (remaining === 0)
+            break;
+        const chunk = await client.runQuery(statement, remaining);
+        if (columns.length === 0)
+            columns = chunk.columns;
+        rows.push(...chunk.rows);
+    }
+    return { columns, rows: rows.slice(0, rowLimit) };
+}
 async function handleSAPQuery(client, args) {
     const sql = String(args.sql ?? '');
     const maxRows = Number(args.maxRows ?? 100);
+    const chunkPlan = planSimpleInListChunking(sql);
+    let chunkingAttempted = false;
     try {
-        const data = await client.runQuery(sql, maxRows);
+        chunkingAttempted = chunkPlan != null;
+        const data = chunkPlan ? await runChunkedSapQuery(client, chunkPlan, maxRows) : await client.runQuery(sql, maxRows);
         return textResult(JSON.stringify(data, null, 2));
     }
     catch (err) {
@@ -1489,7 +1772,11 @@ async function handleSAPQuery(client, args) {
             }
         }
         if (err instanceof AdtApiError) {
-            const parserHint = classifySapQueryParserError(err, sql);
+            let parserHint = classifySapQueryParserError(err, sql);
+            if (parserHint && chunkingAttempted) {
+                parserHint +=
+                    '\nARC-1 already split this simple long IN list into smaller ADT freestyle queries; this backend still rejected one chunk. Reduce the query further or use staged named-table previews.';
+            }
             if (parserHint)
                 return errorResult(parserHint);
         }
@@ -1527,9 +1814,12 @@ async function handleSAPLint(client, args, config) {
             const rules = listRulesFromConfig(lintConfig);
             const enabled = rules.filter((r) => r.enabled);
             const disabled = rules.filter((r) => !r.enabled);
+            const effectiveAbapRelease = configOptions.abapRelease ?? 'unknown';
+            const syntax = lintConfig.get().syntax;
             return textResult(JSON.stringify({
                 preset: configOptions.systemType === 'btp' ? 'cloud' : 'onprem',
-                abapVersion: cachedFeatures?.abapRelease ?? 'unknown',
+                abapVersion: effectiveAbapRelease,
+                syntaxVersion: syntax?.version ?? 'unknown',
                 enabledRules: enabled.length,
                 disabledRules: disabled.length,
                 rules: enabled,
@@ -1578,7 +1868,7 @@ function buildLintConfigOptions(config, ruleOverrides) {
     const systemType = cachedFeatures?.systemType ?? (config.systemType !== 'auto' ? config.systemType : undefined);
     return {
         systemType,
-        abapRelease: cachedFeatures?.abapRelease,
+        abapRelease: cachedFeatures?.abapRelease ?? config.abapRelease,
         configFile: config.abaplintConfig,
         ruleOverrides,
     };
@@ -2482,16 +2772,60 @@ function objectUrlForTypeRaw(type, name) {
 function sourceUrlForType(type, name) {
     return `${objectUrlForType(type, name)}/source/main`;
 }
+const CLASS_WRITE_INCLUDES = ['definitions', 'implementations', 'macros', 'testclasses'];
 /** Get a CLAS include URL (definitions/implementations/macros/testclasses) */
 function classIncludeUrl(name, include) {
     return `/sap/bc/adt/oo/classes/${encodeURIComponent(name)}/includes/${include}`;
 }
+function normalizeClassWriteInclude(include) {
+    if (typeof include !== 'string')
+        return undefined;
+    const normalized = include.toLowerCase();
+    return CLASS_WRITE_INCLUDES.includes(normalized) ? normalized : undefined;
+}
+/**
+ * Auto-detect which class include a method specifier targets, based on the
+ * local-class prefix on the LHS of `<localclass>~<method>`. Used by
+ * `edit_method` so callers can pass `lhc_project~approve_project` and have
+ * ARC-1 transparently route the read+write to `/includes/implementations`
+ * instead of `/source/main`.
+ *
+ * Prefix → include mapping (intentionally narrow; extend via explicit
+ * `include` parameter when a code-base uses other conventions):
+ *   - `lhc_*`  → implementations (RAP behavior pool handler classes)
+ *   - `lcl_*`  → implementations (local helper classes)
+ *   - `ltc_*`  → testclasses    (ABAP Unit local test classes)
+ *
+ * Returns `undefined` for:
+ *   - Specifiers with no `~` (route to MAIN)
+ *   - Global-interface methods like `zif_order~create`, `if_oo_adt_classrun~main`
+ *     (route to MAIN — the impl lives in a global class)
+ *   - `lif_*` local interfaces (interfaces only declare methods — there's no
+ *     impl in CCDEF; an `lhc_*`/`lcl_*` class implements them and the call
+ *     site uses that class's prefix instead)
+ */
+function detectLocalHandlerInclude(method) {
+    if (!method.includes('~'))
+        return undefined;
+    const lhs = method.slice(0, method.indexOf('~')).trim().toLowerCase();
+    if (/^(lhc|lcl)_/.test(lhs))
+        return 'implementations';
+    if (/^ltc_/.test(lhs))
+        return 'testclasses';
+    return undefined;
+}
+/** Strip the leading "=== <include> ===\n" header that `client.getClass(name, include)` prepends. */
+function stripIncludeHeader(source) {
+    return source.replace(/^=== \w+ ===\n/, '');
+}
 // ─── SAPWrite Handler ────────────────────────────────────────────────
 async function handleSAPWrite(client, args, config, cachingLayer) {
     const action = String(args.action ?? '');
     const type = normalizeObjectType(String(args.type ?? ''));
     const name = String(args.name ?? '');
     const source = String(args.source ?? '');
+    const hasSource = typeof args.source === 'string';
+    const include = normalizeClassWriteInclude(args.include);
     const transport = args.transport;
     const lintOverride = args.lintBeforeWrite;
     const preflightOverride = args.preflightBeforeWrite;
@@ -2572,6 +2906,23 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
     switch (action) {
         case 'update': {
             const existingPackage = await enforcePackageForExistingObject();
+            // Keep CLAS local include writes ahead of the generic /source/main fallthrough.
+            // If CLAS ever gains separate metadata-update handling, this branch must still
+            // win whenever callers pass include=definitions|implementations|macros|testclasses.
+            if (args.include !== undefined) {
+                if (!include) {
+                    return errorResult(`Invalid CLAS include "${String(args.include)}". Valid values: ${CLASS_WRITE_INCLUDES.join(', ')}.`);
+                }
+                if (type !== 'CLAS') {
+                    return errorResult('SAPWrite include is only supported for action="update" with type="CLAS".');
+                }
+                if (!hasSource) {
+                    return errorResult('"source" is required when updating a CLAS include.');
+                }
+                await safeUpdateSource(client.http, client.safety, objectUrl, classIncludeUrl(name, include), source, transport, cachedFeatures?.abapRelease);
+                invalidateWrittenObject(type, name);
+                return textResult(`Successfully updated ${type} ${name} include ${include}. Active version remains unchanged until activation; read with SAPRead(version="inactive") to verify the draft.`);
+            }
             if (type === 'SKTD') {
                 // KTD update requires the full <sktd:docu> XML envelope with the Markdown
                 // body base64-encoded inside <sktd:text>, PUT with
@@ -2611,14 +2962,47 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
             // "Parameter comment blocks are not allowed" — verified live a4h S/4HANA 2023,
             // issue #250). LLMs frequently emit them out of muscle memory because every
             // released FM has one. Strip and warn rather than fail.
+            //
+            // Issue #252: when `parameters` is supplied as a structured array, splice
+            // it into the FM source as ABAP-source-based signature syntax. If `source`
+            // is omitted entirely, fetch the existing source first to preserve the
+            // body. The structured clause replaces any existing signature region.
             let effectiveSource = source;
             let fmParamStripWarning;
+            let fmParamMergeWarning;
             if (type === 'FUNC') {
-                const stripped = stripFmParamCommentBlock(source);
+                const parameters = args.parameters;
+                if (parameters !== undefined) {
+                    // If caller passed parameters but no source, fetch the current source so
+                    // the body is preserved (the parameters array re-emits only the signature).
+                    let baseSource = source;
+                    if (!baseSource || baseSource.trim() === '') {
+                        const groupName = String(args.group ?? '');
+                        const fetched = await client.getFunction(groupName, name).catch(() => null);
+                        baseSource = fetched?.source ?? `FUNCTION ${name}.\nENDFUNCTION.\n`;
+                    }
+                    else if (!/^\s*FUNCTION\s+/i.test(baseSource)) {
+                        // Body-only source: wrap in FUNCTION/ENDFUNCTION so the splicer has
+                        // something to work with. Common shape from LLMs: just the body.
+                        baseSource = `FUNCTION ${name}.\n${baseSource}\nENDFUNCTION.\n`;
+                    }
+                    try {
+                        effectiveSource = spliceFmSignature(baseSource, name, parameters);
+                    }
+                    catch {
+                        // No FUNCTION token in the supplied source — fall back to user's source.
+                        effectiveSource = baseSource;
+                        fmParamMergeWarning =
+                            'Could not splice structured parameters: source did not start with FUNCTION keyword. Used the supplied source verbatim.';
+                    }
+                }
+                // Defense-in-depth: strip *" comment blocks even after splicing — the
+                // user's body may contain them (e.g. pasted from SAPGUI).
+                const stripped = stripFmParamCommentBlock(effectiveSource);
                 effectiveSource = stripped.source;
                 if (stripped.wasStripped) {
                     fmParamStripWarning =
-                        'Stripped *"…IMPORTING/EXPORTING…*" parameter comment blocks (SAP rejects them on PUT — manage FM parameters via SAPGUI/Eclipse).';
+                        'Stripped *"…IMPORTING/EXPORTING…*" parameter comment blocks (SAP rejects them on PUT — pass `parameters` as a structured array instead).';
                 }
             }
             // Pre-write lint validation (uses sanitized source for FUNC)
@@ -2633,7 +3017,7 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
             invalidateWrittenObject(type, name);
             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, fmParamStripWarning);
+            const warnings = mergePreWriteWarnings(preflightWarnings.warnings, lintWarnings.warnings, checkNotes, cdsUpdateHint, fmParamStripWarning, fmParamMergeWarning);
             return warnings ? textResult(`${msg}\n\n${warnings}`) : textResult(msg);
         }
         case 'create': {
@@ -2802,17 +3186,46 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                     : '';
                 return textResult(`Created ${type} ${name} in package ${pkg}.\n${result}${followUpHint}`);
             }
-            // Step 2: Write source code if provided
-            if (source) {
-                // FUNC: strip SAPGUI parameter comment blocks (see update path for rationale).
-                let createSource = source;
+            // Step 2: Write source code if provided.
+            // Issue #252: FUNC create accepts a structured `parameters` array; if
+            // provided we must follow up with a source PUT even when `source` is
+            // omitted (the array alone synthesizes a minimal FUNCTION/ENDFUNCTION
+            // body containing the signature clause).
+            const funcParameters = type === 'FUNC' ? args.parameters : undefined;
+            const shouldWriteSource = !!source || (funcParameters !== undefined && funcParameters.length > 0);
+            if (shouldWriteSource) {
+                // FUNC: build/splice the signature, then strip SAPGUI parameter comment
+                // blocks as defense-in-depth (see update path for rationale).
+                let createSource = source ?? '';
                 let fmParamStripWarning;
+                let fmParamMergeWarning;
                 if (type === 'FUNC') {
-                    const stripped = stripFmParamCommentBlock(source);
+                    if (funcParameters !== undefined) {
+                        let baseSource;
+                        if (!createSource || createSource.trim() === '') {
+                            baseSource = `FUNCTION ${name}.\nENDFUNCTION.\n`;
+                        }
+                        else if (!/^\s*FUNCTION\s+/i.test(createSource)) {
+                            // Body-only source — wrap so the splicer has a signature region.
+                            baseSource = `FUNCTION ${name}.\n${createSource}\nENDFUNCTION.\n`;
+                        }
+                        else {
+                            baseSource = createSource;
+                        }
+                        try {
+                            createSource = spliceFmSignature(baseSource, name, funcParameters);
+                        }
+                        catch {
+                            createSource = baseSource;
+                            fmParamMergeWarning =
+                                'Could not splice structured parameters: source did not start with FUNCTION keyword. Used the supplied source verbatim.';
+                        }
+                    }
+                    const stripped = stripFmParamCommentBlock(createSource);
                     createSource = stripped.source;
                     if (stripped.wasStripped) {
                         fmParamStripWarning =
-                            'Stripped *"…IMPORTING/EXPORTING…*" parameter comment blocks (manage FM parameters via SAPGUI/Eclipse).';
+                            'Stripped *"…IMPORTING/EXPORTING…*" parameter comment blocks (pass `parameters` as a structured array instead).';
                     }
                 }
                 // Pre-write lint validation
@@ -2823,7 +3236,7 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                 await safeUpdateSource(client.http, client.safety, objectUrl, srcUrl, createSource, effectiveTransport, cachedFeatures?.abapRelease);
                 invalidateWrittenObject(type, name);
                 const msg = `Created ${type} ${name} in package ${pkg} and wrote source code.`;
-                const warnings = mergePreWriteWarnings(preflightWarnings.warnings, lintWarnings.warnings, fmParamStripWarning);
+                const warnings = mergePreWriteWarnings(preflightWarnings.warnings, lintWarnings.warnings, fmParamStripWarning, fmParamMergeWarning);
                 return warnings ? textResult(`${msg}\n\n${warnings}`) : textResult(msg);
             }
             return textResult(`Created ${type} ${name} in package ${pkg}.\n${result}`);
@@ -2837,10 +3250,50 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
             if (type !== 'CLAS')
                 return errorResult('edit_method is only supported for type=CLAS.');
             await enforcePackageForExistingObject();
-            // Fetch current full source (use cache if available)
-            const currentSource = cachingLayer
-                ? (await cachingLayer.getSource('CLAS', name, (ifNoneMatch) => client.getClass(name, undefined, { ifNoneMatch }))).source
-                : (await client.getClass(name)).source;
+            // ── Resolve which class section the method body lives in ──
+            // Order:
+            //   1. Explicit `include` parameter wins (must be a valid CLAS include).
+            //      If the user passed something but normalization rejected it,
+            //      report it the same way `case 'update'` does.
+            //   2. Auto-detect from local-class prefix in `method` specifier
+            //      (lhc_*/lcl_* → implementations, ltc_* → testclasses). This is
+            //      transparent to RAP-skill callers passing `lhc_project~approve_project`.
+            //   3. Fall through to MAIN (existing behavior — covers global classes
+            //      and `zif_order~create` style interface methods).
+            if (args.include !== undefined && !include) {
+                return errorResult(`Invalid CLAS include "${String(args.include)}". Valid values: ${CLASS_WRITE_INCLUDES.join(', ')}.`);
+            }
+            const detectedInclude = include ? undefined : detectLocalHandlerInclude(method);
+            const resolvedInclude = include ?? detectedInclude;
+            // Fetch the source that contains the method.
+            // Note: include reads bypass the source cache because the cache key is
+            // `(type, name, active|inactive)` and does not differentiate by include.
+            // Mixing MAIN and CCIMP bytes under the same key would silently corrupt
+            // subsequent reads. Future enhancement: extend cache key with include.
+            let currentSource;
+            if (resolvedInclude) {
+                // **Draft-aware include reads (PR-D review fix, P1).**
+                // After `SAPWrite update include=...` or `scaffold_rap_handlers`, the
+                // edited CCDEF/CCIMP lives as an inactive draft; the active include
+                // is often still the empty placeholder. Reading "active" here would
+                // splice against stale content (and frequently "method not found").
+                // Use the standard inactive-list lookup to pick the right version —
+                // same auto-resolution semantics SAPRead exposes via `version='auto'`.
+                const { effectiveVersion } = await resolveVersionAndDraftInfo(client, cachingLayer, 'CLAS', name, 'auto');
+                const fetched = await client.getClass(name, resolvedInclude, { version: effectiveVersion });
+                currentSource = stripIncludeHeader(fetched.source);
+                // If the include itself has no draft (only MAIN does), SAP returns the
+                // active include body for `?version=inactive`. That's correct — we
+                // splice whatever the editor would see. If the include source isn't
+                // available at all (response contains the "not available" placeholder
+                // injected by client.getClass on 404), splice will surface a clean
+                // "method not found" with the include name.
+            }
+            else {
+                currentSource = cachingLayer
+                    ? (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)
@@ -2848,18 +3301,40 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
             // Splice in the new method body
             const spliced = spliceMethod(currentSource, name, method, source, abaplintVer);
             if (!spliced.success) {
-                return errorResult(spliced.error ?? `Failed to splice method "${method}" in ${name}.`);
+                // Augment the error with which include was searched, so the LLM can
+                // either correct the method specifier or override include= explicitly.
+                const where = resolvedInclude ? `include "${resolvedInclude}"` : 'main source';
+                const baseError = spliced.error ?? `Failed to splice method "${method}" in ${name}.`;
+                const hint = detectedInclude
+                    ? ` (auto-routed via "${method}" prefix; pass include= explicitly to override).`
+                    : '';
+                return errorResult(`${baseError} Searched ${where} of ${name}.${hint}`);
             }
-            // Pre-write lint validation on the full spliced source
-            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, cachedFeatures?.abapRelease);
+            // Pre-write lint + server-side syntax check on the spliced source.
+            //
+            // Skip BOTH for include= writes. abaplint cannot parse a CCIMP/CCDEF
+            // fragment as a complete class (the DEFINITION/IMPLEMENTATION halves
+            // live in different files), so it would block legitimate writes with
+            // "Expected CLASSDEFINITION" errors. The existing `case 'update'` include=
+            // path also bypasses these checks for the same reason — keep parity.
+            // The full-class activation pass after the write is the authoritative
+            // syntax check.
+            let lintWarnings = { blocked: false };
+            let checkNotes = '';
+            if (!resolvedInclude) {
+                lintWarnings = runPreWriteLint(spliced.newSource, type, name, config, lintOverride);
+                if (lintWarnings.blocked)
+                    return lintWarnings.result;
+                checkNotes = await runPreWriteSyntaxCheck(client, type, spliced.newSource, objectUrl, config, checkOverride);
+            }
+            // Write the full source back (existing lock/modify/unlock flow).
+            // For include writes, the parent class lock auto-applies; the include URL
+            // takes the body. See `compare/eclipse-adt/api/05-lock-create-update-transport.md`.
+            const writeUrl = resolvedInclude ? classIncludeUrl(name, resolvedInclude) : srcUrl;
+            await safeUpdateSource(client.http, client.safety, objectUrl, writeUrl, spliced.newSource, transport, cachedFeatures?.abapRelease);
             invalidateWrittenObject(type, name);
-            const msg = `Successfully updated method "${method}" in ${type} ${name}.`;
+            const where = resolvedInclude ? ` (include: ${resolvedInclude})` : '';
+            const msg = `Successfully updated method "${method}" in ${type} ${name}${where}.`;
             const extras = [lintWarnings.warnings, checkNotes].filter(Boolean).join('\n\n');
             return extras ? textResult(`${msg}\n\n${extras}`) : textResult(msg);
         }
@@ -2965,6 +3440,7 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                     applied: false,
                     hint: unresolvedHint,
                     applyResult: {
+                        skeletons: scaffoldPlan.skeletons,
                         main: scaffoldPlan.signatures.main,
                         definitions: scaffoldPlan.signatures.definitions,
                         implementations: scaffoldPlan.signatures.implementations,
@@ -3029,12 +3505,14 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
             });
             invalidateWrittenObject();
             const msg = `Scaffolded ${scaffoldPlan.insertedSignatureCount} RAP handler signature(s) and ${scaffoldPlan.insertedImplementationStubCount} implementation stub(s) in ${type} ${name} from BDEF ${bdefName}. ` +
+                `Auto-created ${scaffoldPlan.skeletons.createdDefinitions.length + scaffoldPlan.skeletons.createdImplementations.length} handler skeleton section(s). ` +
                 `Updated section(s): ${scaffoldPlan.changedSections.join(', ')}.`;
             const warnings = mergePreWriteWarnings(lintWarningsMain?.warnings, lintWarningsDefinitions?.warnings, lintWarningsImplementations?.warnings);
             const details = JSON.stringify({
                 ...summary,
                 applied: true,
                 applyResult: {
+                    skeletons: scaffoldPlan.skeletons,
                     main: scaffoldPlan.signatures.main,
                     definitions: scaffoldPlan.signatures.definitions,
                     implementations: scaffoldPlan.signatures.implementations,
@@ -3044,6 +3522,44 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
             }, null, 2);
             return warnings ? textResult(`${msg}\n\n${warnings}\n\n${details}`) : textResult(`${msg}\n\n${details}`);
         }
+        case 'generate_behavior_implementation': {
+            // PR-C: high-level RAP one-shot — auto-discover BDEF via class metadata's
+            // rootEntityRef, scaffold every required handler (creating lhc_<alias>
+            // skeletons when missing), write under one lock, and (by default) activate.
+            // Reliable equivalent of Eclipse ADT's "Generate Behavior Implementation"
+            // Cmd+1 quickfix; avoids the broken /sap/bc/adt/quickfixes/proposals/
+            // create_class_implementation server endpoint (HTTP 500 on a4h, verified
+            // live during PR-C research). See docs/plans/add-generate-behavior-implementation.md.
+            if (type !== 'CLAS') {
+                return errorResult('generate_behavior_implementation is only supported for type=CLAS behavior pool classes.');
+            }
+            if (!name) {
+                return errorResult('"name" is required for generate_behavior_implementation.');
+            }
+            const dryRun = args.dryRun === true || String(args.dryRun ?? '') === 'true';
+            const activate = args.activate === undefined ? true : args.activate === true || String(args.activate) === 'true';
+            const explicitBdef = args.bdefName?.trim() || undefined;
+            const targetAlias = args.targetAlias?.trim() || undefined;
+            // Package gate only when we'll actually mutate. dryRun=true is read-only;
+            // bypassing the gate matches the scaffold_rap_handlers preview pattern.
+            if (!dryRun) {
+                await enforcePackageForExistingObject();
+            }
+            const result = await generateBehaviorImplementation(client, name, {
+                bdefName: explicitBdef,
+                targetAlias,
+                activate,
+                dryRun,
+                transport,
+            });
+            invalidateWrittenObject();
+            // MCP result-code mapping via the exported helper — see
+            // `isRapGenerateResultSuccess` for the success/error contract (Codex review on PR #260, P1).
+            // The structured JSON is preserved in both branches so the caller can still see what
+            // was discovered, written, and what activation reported.
+            const json = JSON.stringify(result, null, 2);
+            return isRapGenerateResultSuccess(result) ? textResult(json) : errorResult(json);
+        }
         case 'delete': {
             await enforcePackageForExistingObject();
             // Lock, delete, unlock pattern (works for all types including SKTD) — auto-propagate lock corrNr if no explicit transport
@@ -3085,20 +3601,40 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
             if (!objects || !Array.isArray(objects) || objects.length === 0) {
                 return errorResult('"objects" array is required and must be non-empty for batch_create action.');
             }
-            const pkg = String(args.package ?? '$TMP');
-            // Check package is allowed before starting any creates
-            checkPackage(client.safety, pkg);
-            // Pre-flight transport check for batch_create (same logic as single create)
-            let batchTransport = transport;
-            if (!transport && pkg.toUpperCase() !== '$TMP') {
+            // Opt-in deferred-activation: writes every object as an inactive draft first,
+            // then issues a single terminal activateBatch over the written subset. Use case:
+            // composition-linked DDLS / interdependent RAP graphs where per-object inline
+            // activate() can't resolve cross-references to not-yet-active siblings.
+            const activateAtEnd = args.activateAtEnd === true || String(args.activateAtEnd) === 'true';
+            const defaultPackage = normalizePackageOverride(args.package, '$TMP');
+            const batchPlan = objects.map((obj) => {
+                const objType = normalizeObjectType(String(obj.type ?? ''));
+                const objName = String(obj.name ?? '');
+                const objPackage = normalizePackageOverride(obj.package, defaultPackage);
+                const explicitTransport = normalizeTransportOverride(obj.transport) ?? transport;
+                return { obj, type: objType, name: objName, packageName: objPackage, explicitTransport };
+            });
+            // Check every target package before starting any creates.
+            for (const pkg of new Set(batchPlan.map((item) => item.packageName))) {
+                checkPackage(client.safety, pkg);
+            }
+            // Pre-flight transport check for batch_create (same logic as single create),
+            // but keyed by each effective package because objects can override package.
+            const autoTransportByPackage = new Map();
+            const firstPlanNeedingTransportByPackage = new Map();
+            for (const plan of batchPlan) {
+                if (!plan.explicitTransport &&
+                    plan.packageName.toUpperCase() !== '$TMP' &&
+                    !firstPlanNeedingTransportByPackage.has(plan.packageName)) {
+                    firstPlanNeedingTransportByPackage.set(plan.packageName, plan);
+                }
+            }
+            for (const [pkg, plan] of firstPlanNeedingTransportByPackage) {
                 try {
-                    // Use first object's URL for the transport check
-                    const firstObj = objects[0];
-                    const firstType = normalizeObjectType(String(firstObj?.type ?? ''));
-                    const firstUrl = objectUrlForType(firstType, String(firstObj?.name ?? ''));
+                    const firstUrl = objectUrlForType(plan.type, plan.name);
                     const transportInfo = await getTransportInfo(client.http, client.safety, firstUrl, pkg, 'I');
                     if (transportInfo.lockedTransport) {
-                        batchTransport = transportInfo.lockedTransport;
+                        autoTransportByPackage.set(pkg, transportInfo.lockedTransport);
                     }
                     else if (!transportInfo.isLocal && transportInfo.recording) {
                         const existingList = transportInfo.existingTransports.length > 0
@@ -3115,7 +3651,13 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                             existingList);
                     }
                 }
-                catch {
+                catch (err) {
+                    logger.warn('SAPWrite batch_create transport preflight failed; continuing without auto transport', {
+                        package: pkg,
+                        type: plan.type,
+                        name: plan.name,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
                     // If transportInfo check fails, proceed — SAP will return its own error if needed.
                 }
             }
@@ -3125,9 +3667,12 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
             // guard fires for every MSAG entry, but a batch typically shares one transport — cache
             // the lookup result to avoid one HTTP roundtrip per object.
             const transportLookupCache = new Map();
-            for (const obj of objects) {
-                const objType = normalizeObjectType(String(obj.type ?? ''));
-                const objName = String(obj.name ?? '');
+            // Accumulated objects whose create + source-write phase succeeded — used by the
+            // terminal activateBatch when activateAtEnd=true. Order matches the input order.
+            const writtenObjects = [];
+            for (const plan of batchPlan) {
+                const { obj, type: objType, name: objName, packageName: objPackage } = plan;
+                const objTransport = plan.explicitTransport ?? autoTransportByPackage.get(objPackage);
                 const metadataObject = isMetadataWriteType(objType);
                 const objSource = obj.source ? String(obj.source) : undefined;
                 const objDescription = String(obj.description ?? objName);
@@ -3138,24 +3683,26 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                     results.push({
                         type: objType,
                         name: objName,
+                        packageName: objPackage,
                         status: 'failed',
                         error: `Object name "${objName}" contains lowercase characters. SAP object names must be uppercase (e.g. "${objName.toUpperCase()}"). Source code inside the object can use mixed case.`,
                     });
                     break;
                 }
                 // MSAG transport-vs-task guard (per-batch cache to avoid per-object roundtrip).
-                if (objType === 'MSAG' && batchTransport) {
-                    let tr = transportLookupCache.get(batchTransport);
+                if (objType === 'MSAG' && objTransport) {
+                    let tr = transportLookupCache.get(objTransport);
                     if (tr === undefined) {
-                        tr = await getTransport(client.http, client.safety, batchTransport);
-                        transportLookupCache.set(batchTransport, tr);
+                        tr = await getTransport(client.http, client.safety, objTransport);
+                        transportLookupCache.set(objTransport, tr);
                     }
                     if (!tr) {
                         results.push({
                             type: objType,
                             name: objName,
+                            packageName: objPackage,
                             status: 'failed',
-                            error: `Transport "${batchTransport}" is not a valid transport request. MSAG creation requires a transport request number, not a task number.`,
+                            error: `Transport "${objTransport}" is not a valid transport request. MSAG creation requires a transport request number, not a task number.`,
                         });
                         break;
                     }
@@ -3166,6 +3713,7 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                     results.push({
                         type: objType,
                         name: objName,
+                        packageName: objPackage,
                         status: 'failed',
                         error: `AFF metadata validation failed:\n- ${(affResult.errors ?? []).join('\n- ')}`,
                     });
@@ -3180,6 +3728,7 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                             results.push({
                                 type: objType,
                                 name: objName,
+                                packageName: objPackage,
                                 status: 'failed',
                                 error: preflightWarnings.result.content[0].text,
                             });
@@ -3193,6 +3742,7 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                             results.push({
                                 type: objType,
                                 name: objName,
+                                packageName: objPackage,
                                 status: 'failed',
                                 error: `source rejected by lint: ${lintWarnings.result.content[0].text}`,
                             });
@@ -3203,11 +3753,11 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                     const objUrl = objectUrlForType(objType, objName);
                     const createUrl = objUrl.replace(/\/[^/]+$/, '');
                     const objMetadataProps = getMetadataWriteProperties(obj);
-                    const body = buildCreateXml(objType, objName, pkg, objDescription, objMetadataProps);
+                    const body = buildCreateXml(objType, objName, objPackage, objDescription, objMetadataProps);
                     const contentType = createContentTypeForType(objType);
                     const needsPackageParam = objType === 'BDEF' || objType === 'TABL';
                     try {
-                        await createObject(client.http, client.safety, createUrl, body, contentType, batchTransport, needsPackageParam ? pkg : undefined, cachedFeatures?.abapRelease);
+                        await createObject(client.http, client.safety, createUrl, body, contentType, objTransport, needsPackageParam ? objPackage : undefined, cachedFeatures?.abapRelease);
                     }
                     catch (createErr) {
                         if (createErr instanceof AdtApiError && (createErr.statusCode === 400 || createErr.statusCode === 409)) {
@@ -3222,7 +3772,7 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                     if (objType === 'DTEL' && dtelNeedsPostCreateUpdate(objMetadataProps)) {
                         await client.http.withStatefulSession(async (session) => {
                             const lock = await lockObject(session, client.safety, objUrl, 'MODIFY', cachedFeatures?.abapRelease);
-                            const lockTransport = batchTransport ?? (lock.corrNr || undefined);
+                            const lockTransport = objTransport ?? (lock.corrNr || undefined);
                             try {
                                 await updateObject(session, client.safety, objUrl, body, lock.lockHandle, contentType, lockTransport);
                             }
@@ -3234,26 +3784,58 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                     // Step 2: Write source if provided
                     if (!metadataObject && objSource) {
                         const srcUrl = sourceUrlForType(objType, objName);
-                        await safeUpdateSource(client.http, client.safety, objUrl, srcUrl, objSource, batchTransport, cachedFeatures?.abapRelease);
+                        await safeUpdateSource(client.http, client.safety, objUrl, srcUrl, objSource, objTransport, cachedFeatures?.abapRelease);
                     }
-                    // Step 3: Activate the object
-                    const activationResult = await activate(client.http, client.safety, objUrl);
-                    if (!activationResult.success) {
-                        results.push({
-                            type: objType,
-                            name: objName,
-                            status: 'failed',
-                            error: `activation failed: ${activationResult.messages.join('; ')}`,
-                        });
-                        break;
+                    // Resolve the activation URL up front so both the inline path and the
+                    // deferred terminal-activate path use the same URL. FUNC needs the parent
+                    // function-group baked into the path (issue #250); objectUrlForType throws
+                    // for FUNC so we mirror the FUNC-aware resolver from handleSAPActivate. For
+                    // TABL we keep objUrl (already resolved to /tables/) — DDIC-structure FMs
+                    // aren't a real concept and the create path doesn't expose one.
+                    let activationUrl = objUrl;
+                    if (objType === 'FUNC') {
+                        let group = String(obj.group ?? args.group ?? '').trim();
+                        if (!group) {
+                            const resolved = cachingLayer
+                                ? await cachingLayer.resolveFuncGroup(client, objName)
+                                : await client.resolveFunctionGroup(objName);
+                            if (!resolved) {
+                                throw new Error(`Cannot resolve function group for FM "${objName}" in batch_create activation step. Provide "group" on the FUNC entry.`);
+                            }
+                            group = resolved;
+                        }
+                        const groupLc = encodeURIComponent(group.toLowerCase());
+                        activationUrl = `/sap/bc/adt/functions/groups/${groupLc}/fmodules/${encodeURIComponent(objName.toLowerCase())}`;
+                    }
+                    if (activateAtEnd) {
+                        // Step 3 deferred: track this object for the terminal activateBatch call.
+                        // Cache invalidation also moves to AFTER the terminal activate succeeds —
+                        // invalidating now would let the next read see a draft we couldn't activate.
+                        writtenObjects.push({ type: objType, name: objName, url: activationUrl });
+                        results.push({ type: objType, name: objName, packageName: objPackage, status: 'success' });
+                    }
+                    else {
+                        // Step 3: Activate the object (inline, default behavior).
+                        const activationResult = await activate(client.http, client.safety, activationUrl);
+                        if (!activationResult.success) {
+                            results.push({
+                                type: objType,
+                                name: objName,
+                                packageName: objPackage,
+                                status: 'failed',
+                                error: `activation failed: ${activationResult.messages.join('; ')}`,
+                            });
+                            break;
+                        }
+                        invalidateWrittenObject(objType, objName);
+                        results.push({ type: objType, name: objName, packageName: objPackage, status: 'success' });
                     }
-                    invalidateWrittenObject(objType, objName);
-                    results.push({ type: objType, name: objName, status: 'success' });
                 }
                 catch (err) {
                     results.push({
                         type: objType,
                         name: objName,
+                        packageName: objPackage,
                         status: 'failed',
                         error: err instanceof Error ? err.message : String(err),
                     });
@@ -3262,30 +3844,88 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
             }
             // Add 'skipped' entries for objects that were never attempted due to early break
             for (let i = results.length; i < objects.length; i++) {
-                const skipped = objects[i];
+                const skippedPlan = batchPlan[i];
+                const skipped = skippedPlan?.obj ?? objects[i];
                 results.push({
-                    type: normalizeObjectType(String(skipped?.type ?? '')),
-                    name: String(skipped.name ?? ''),
+                    type: skippedPlan?.type ?? normalizeObjectType(String(skipped?.type ?? '')),
+                    name: skippedPlan?.name ?? String(skipped?.name ?? ''),
+                    packageName: skippedPlan?.packageName ?? normalizePackageOverride(skipped?.package, defaultPackage),
                     status: 'failed',
                     error: 'skipped — stopped after previous failure',
                 });
             }
+            // ── Terminal activateBatch (activateAtEnd=true) ─────────────────────
+            // After every write-phase succeeded (or broke off early), issue ONE batch
+            // activate over the already-written subset. This is the killer feature
+            // for composition-linked DDLS and RAP behavior stacks — SAP's activator
+            // sees the whole graph in a single POST and resolves cross-references
+            // internally, so parent → child siblings activate cleanly.
+            let terminalActivationFailure;
+            if (activateAtEnd && writtenObjects.length > 0) {
+                const activationOutcome = await activateBatch(client.http, client.safety, writtenObjects);
+                if (activationOutcome.success) {
+                    // Defensive: per-object status was already 'success' from the write phase.
+                    // Cache invalidation moves here so a failed terminal activate doesn't strand
+                    // a stale 'active' cache entry. Invalidate inactive-lists once for the user.
+                    for (const o of writtenObjects) {
+                        cachingLayer?.invalidate(o.type, o.name, 'all');
+                    }
+                    cachingLayer?.inactiveLists.invalidate(client.username);
+                }
+                else {
+                    // Flip every written-but-not-yet-activated entry to 'failed', preserving the
+                    // "create + source-write succeeded" context. Reuse the existing per-object
+                    // diagnostic mapper so callers see the activation messages keyed by object name.
+                    const batchStatuses = buildBatchActivationStatuses(writtenObjects, activationOutcome);
+                    const statusDetails = formatBatchActivationStatuses(batchStatuses);
+                    terminalActivationFailure = statusDetails;
+                    const statusByName = new Map(batchStatuses.map((s) => [`${s.type}${s.name}`, s]));
+                    for (const result of results) {
+                        if (result.status !== 'success')
+                            continue;
+                        const key = `${result.type}${result.name}`;
+                        const matched = statusByName.get(key);
+                        if (!matched)
+                            continue;
+                        // Some entries may still report status 'active' if the activator returned
+                        // success: false but had no per-object error details — keep them as 'success'.
+                        if (matched.status === 'active')
+                            continue;
+                        result.status = 'failed';
+                        const detail = matched.messages.length > 0 ? ` — ${matched.messages.join('; ')}` : '';
+                        // Preserve the "create + source-write succeeded" context so the user sees that
+                        // the failure was specifically the activation step, not the write step.
+                        result.error = `${writtenObjects.length}/${writtenObjects.length} written, batch activation failed${detail}`;
+                    }
+                }
+            }
+            // ────────────────────────────────────────────────────────────────────
             const summary = results
-                .map((r) => `${r.name} (${r.type}) ${r.status === 'success' ? '✓' : `✗ — ${r.error}`}`)
+                .map((r) => r.status === 'success'
+                ? `${r.name} (${r.type}) ✓ [${r.packageName}]`
+                : `${r.name} (${r.type}) ✗ [${r.packageName}] — ${r.error}`)
                 .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- ')}` : '';
+            const activateAtEndSuffix = terminalActivationFailure !== undefined ? `\n\nBatch activation diagnostics:${terminalActivationFailure}` : '';
+            const packageNames = [...new Set(batchPlan.map((item) => item.packageName))];
+            const packageSummary = packageNames.length === 1
+                ? `in package ${packageNames[0]}`
+                : packageNames.length <= 3
+                    ? `across packages [${packageNames.join(', ')}]`
+                    : `across ${packageNames.length} packages`;
+            const activateAtEndPrefix = activateAtEnd ? '; activated as a single batch' : '';
             if (hasFailure) {
                 const cleanupHint = successCount > 0
                     ? ` Note: ${successCount} already-created object(s) remain on the SAP system and may need manual cleanup.`
                     : '';
-                return errorResult(`Batch created ${successCount}/${objects.length} objects in package ${pkg}: ${summary}${cleanupHint}${warningSuffix}`);
+                return errorResult(`Batch created ${successCount}/${objects.length} objects ${packageSummary}${activateAtEndPrefix}: ${summary}${cleanupHint}${warningSuffix}${activateAtEndSuffix}`);
             }
-            return textResult(`Batch created ${successCount} objects in package ${pkg}: ${summary}${warningSuffix}`);
+            return textResult(`Batch created ${successCount} objects ${packageSummary}${activateAtEndPrefix}: ${summary}${warningSuffix}${activateAtEndSuffix}`);
         }
         default:
-            return errorResult(`Unknown SAPWrite action: ${action}. Supported: create, update, delete, edit_method, batch_create, scaffold_rap_handlers`);
+            return errorResult(`Unknown SAPWrite action: ${action}. Supported: create, update, delete, edit_method, batch_create, scaffold_rap_handlers, generate_behavior_implementation`);
     }
 }
 /**
@@ -3348,13 +3988,22 @@ function runPreWriteLint(source, type, name, config, perCallOverride) {
     if (!enabled || !source) {
         return { blocked: false };
     }
-    // abaplint supports ABAP source (PROG/CLAS/INTF/FUNC/INCL) and CDS views (DDLS) via
+    // abaplint supports ABAP source (PROG/CLAS/INTF/INCL) and CDS views (DDLS) via
     // its CDS parser. DDLS lint catches syntax errors (cds_parser_error) like missing commas,
     // wrong keywords, and invalid DDL constructs. BDEF/SRVD/SRVB/DDLX are silently ignored
     // by abaplint (no parser for those types — garbage passes without errors). TABL (define
     // table syntax) is not supported by the CDS parser and produces false cds_parser_error.
     // For unsupported types, SAP server-side compilation handles validation.
-    const LINTABLE_TYPES = new Set(['PROG', 'CLAS', 'INTF', 'FUNC', 'INCL', 'DDLS']);
+    //
+    // FUNC is intentionally excluded: abaplint's FM-source parser does not understand
+    // source-based signatures (`FUNCTION X\n  IMPORTING …\n.`) and emits a structural
+    // parser_error that blocks the write. Issue #252 made this visible — once we
+    // started emitting real signatures from structured `parameters`, every FUNC PUT
+    // hit the lint gate. Pre-#252 lint coverage was effectively trivial (only
+    // signature-less FUNCTION/ENDFUNCTION stubs passed). Validation falls back to
+    // SAP's server-side syntax check (opt-in via `SAP_CHECK_BEFORE_WRITE`) and the
+    // activate step.
+    const LINTABLE_TYPES = new Set(['PROG', 'CLAS', 'INTF', 'INCL', 'DDLS']);
     if (!LINTABLE_TYPES.has(type)) {
         return { blocked: false };
     }
@@ -3363,7 +4012,7 @@ function runPreWriteLint(source, type, name, config, perCallOverride) {
         const systemType = cachedFeatures?.systemType ?? (config.systemType !== 'auto' ? config.systemType : undefined);
         const configOptions = {
             systemType,
-            abapRelease: cachedFeatures?.abapRelease,
+            abapRelease: cachedFeatures?.abapRelease ?? config.abapRelease,
             configFile: config.abaplintConfig,
         };
         const result = validateBeforeWrite(source, filename, configOptions);
@@ -3929,8 +4578,24 @@ async function handleSAPDiagnose(client, args) {
             const result = await runAtcCheck(client.http, client.safety, objectUrl, variant);
             return textResult(JSON.stringify(result, null, 2));
         }
+        case 'object_state': {
+            if (!name || !type)
+                return errorResult('"name" and "type" are required for "object_state" action.');
+            const sections = type === 'CLAS'
+                ? [
+                    { section: 'main', uri: sourceUrlForType(type, name) },
+                    { section: 'definitions', uri: classIncludeUrl(name, 'definitions'), optional: true },
+                    { section: 'implementations', uri: classIncludeUrl(name, 'implementations'), optional: true },
+                    { section: 'macros', uri: classIncludeUrl(name, 'macros'), optional: true },
+                    { section: 'testclasses', uri: classIncludeUrl(name, 'testclasses'), optional: true },
+                ]
+                : [{ section: 'main', uri: sourceUrlForType(type, name) }];
+            const result = await getObjectState(client.http, client.safety, { type, name, sections });
+            return textResult(JSON.stringify(result, null, 2));
+        }
         case 'quickfix': {
             const source = args.source;
+            const sourceUri = args.sourceUri;
             if (!name || !type)
                 return errorResult('"name" and "type" are required for "quickfix" action.');
             if (!source)
@@ -3943,13 +4608,15 @@ async function handleSAPDiagnose(client, args) {
                 return errorResult('"line" must be a number for "quickfix" action.');
             if (!Number.isFinite(column))
                 return errorResult('"column" must be a number for "quickfix" action.');
-            const proposals = await getFixProposals(client.http, client.safety, sourceUrlForType(type, name), source, line, column);
+            const proposals = await getFixProposals(client.http, client.safety, sourceUri ?? sourceUrlForType(type, name), source, line, column);
             return textResult(JSON.stringify(proposals, null, 2));
         }
         case 'apply_quickfix': {
             const source = args.source;
+            const sourceUri = args.sourceUri;
             const proposalUri = args.proposalUri;
             const proposalUserContent = args.proposalUserContent;
+            const proposalAffectedObjects = args.proposalAffectedObjects;
             if (!name || !type)
                 return errorResult('"name" and "type" are required for "apply_quickfix" action.');
             if (!source)
@@ -3958,7 +4625,7 @@ async function handleSAPDiagnose(client, args) {
                 return errorResult('"line" is required for "apply_quickfix" action.');
             if (!proposalUri)
                 return errorResult('"proposalUri" is required for "apply_quickfix" action.');
-            if (!proposalUserContent)
+            if (proposalUserContent === undefined)
                 return errorResult('"proposalUserContent" is required for "apply_quickfix" action.');
             const line = Number(args.line);
             const column = Number(args.column ?? 0);
@@ -3972,7 +4639,8 @@ async function handleSAPDiagnose(client, args) {
                 name: '',
                 description: '',
                 userContent: proposalUserContent,
-            }, sourceUrlForType(type, name), source, line, column);
+                ...(proposalAffectedObjects ? { affectedObjects: proposalAffectedObjects } : {}),
+            }, sourceUri ?? sourceUrlForType(type, name), source, line, column);
             return textResult(JSON.stringify(deltas, null, 2));
         }
         case 'dumps': {
@@ -4061,7 +4729,7 @@ async function handleSAPDiagnose(client, args) {
             return textResult(JSON.stringify(errors, null, 2));
         }
         default:
-            return errorResult(`Unknown SAPDiagnose action: ${action}. Supported: syntax, unittest, atc, quickfix, apply_quickfix, dumps, traces, system_messages, gateway_errors`);
+            return errorResult(`Unknown SAPDiagnose action: ${action}. Supported: syntax, unittest, atc, object_state, quickfix, apply_quickfix, dumps, traces, system_messages, gateway_errors`);
     }
 }
 function selectDumpSections(detail, requestedSections) {