arc-1 0.9.20 → 0.9.21

package/dist/adt/diagnostics.js

@@ -2,15 +2,15 @@
  * Runtime diagnostics for SAP ADT.
  *
  * - Short dumps (ST22): list and read ABAP runtime errors
- * - ABAP traces: list and analyze profiler trace files
+ * - ABAP traces: list/analyze recorded profiler traces, and arm/list/cancel trace requests
  *
- * All operations are read-only (GET requests).
- * Follows the same pure-function pattern as devtools.ts.
+ * Most operations are read-only (GET); arming/cancelling a trace request and changing ST05 SQL-trace
+ * state mutate server state via OperationType.Update. Follows the same pure-function pattern as devtools.ts.
  */
 import { createHash } from 'node:crypto';
 import { AdtApiError } from './errors.js';
 import { checkOperation, OperationType } from './safety.js';
-import { findDeepNodes, parseXml } from './xml-parser.js';
+import { escapeXmlAttr, findDeepNodes, parseXml } from './xml-parser.js';
 // ─── Short Dumps ────────────────────────────────────────────────────
 const DEFAULT_DUMP_MAX_RESULTS = 50;
 const DEFAULT_SYSTEM_MESSAGE_MAX_RESULTS = 50;
@@ -115,7 +115,7 @@ export async function listDumps(http, safety, options) {
  */
 export async function getDump(http, safety, dumpId) {
     checkOperation(safety, OperationType.Read, 'GetDump');
-    const safeId = normalizeDumpId(dumpId);
+    const safeId = normalizeAdtPathSegment(dumpId);
     // Fetch XML metadata and formatted text in parallel
     const [xmlResp, textResp] = await Promise.all([
         http.get(`/sap/bc/adt/runtime/dump/${safeId}`, {
@@ -133,8 +133,8 @@ export async function getDump(http, safety, dumpId) {
  * `%20` for spaces); otherwise we encode it once. Trims surrounding
  * whitespace which would otherwise be encoded as `%20` and break lookup.
  */
-function normalizeDumpId(dumpId) {
-    const trimmed = String(dumpId ?? '').trim();
+function normalizeAdtPathSegment(value) {
+    const trimmed = String(value ?? '').trim();
     if (!trimmed)
         return '';
     return trimmed.includes('%') ? trimmed : encodeURIComponent(trimmed);
@@ -209,7 +209,8 @@ export async function listTraces(http, safety) {
  */
 export async function getTraceHitlist(http, safety, traceId) {
     checkOperation(safety, OperationType.Read, 'GetTraceHitlist');
-    const resp = await http.get(`/sap/bc/adt/runtime/traces/abaptraces/${traceId}/hitlist`, {
+    const safeTraceId = normalizeAdtPathSegment(traceId);
+    const resp = await http.get(`/sap/bc/adt/runtime/traces/abaptraces/${safeTraceId}/hitlist`, {
         Accept: 'application/xml',
     });
     return parseTraceHitlist(resp.body);
@@ -221,7 +222,8 @@ export async function getTraceHitlist(http, safety, traceId) {
  */
 export async function getTraceStatements(http, safety, traceId) {
     checkOperation(safety, OperationType.Read, 'GetTraceStatements');
-    const resp = await http.get(`/sap/bc/adt/runtime/traces/abaptraces/${traceId}/statements`, {
+    const safeTraceId = normalizeAdtPathSegment(traceId);
+    const resp = await http.get(`/sap/bc/adt/runtime/traces/abaptraces/${safeTraceId}/statements`, {
         Accept: 'application/xml',
     });
     return parseTraceStatements(resp.body);
@@ -233,11 +235,213 @@ export async function getTraceStatements(http, safety, traceId) {
  */
 export async function getTraceDbAccesses(http, safety, traceId) {
     checkOperation(safety, OperationType.Read, 'GetTraceDbAccesses');
-    const resp = await http.get(`/sap/bc/adt/runtime/traces/abaptraces/${traceId}/dbAccesses`, {
+    const safeTraceId = normalizeAdtPathSegment(traceId);
+    const resp = await http.get(`/sap/bc/adt/runtime/traces/abaptraces/${safeTraceId}/dbAccesses`, {
         Accept: 'application/xml',
     });
     return parseTraceDbAccesses(resp.body);
 }
+// ─── ABAP Trace Requests (arm a profiler trace, then read it back) ───
+const TRACE_BASE = '/sap/bc/adt/runtime/traces/abaptraces';
+const TRACE_PROCESS_TYPE_URIS = {
+    any: `${TRACE_BASE}/processtypes/any`,
+    http: `${TRACE_BASE}/processtypes/http`,
+    dialog: `${TRACE_BASE}/processtypes/dialog`,
+    batch: `${TRACE_BASE}/processtypes/batch`,
+    rfc: `${TRACE_BASE}/processtypes/rfc`,
+};
+const TRACE_OBJECT_TYPE_URIS = {
+    any: `${TRACE_BASE}/objecttypes/any`,
+    url: `${TRACE_BASE}/objecttypes/url`,
+    transaction: `${TRACE_BASE}/objecttypes/transaction`,
+    report: `${TRACE_BASE}/objecttypes/report`,
+    functionModule: `${TRACE_BASE}/objecttypes/functionmodule`,
+};
+/** Object types valid per process type; the first entry is the sensible default. */
+const TRACE_PROCESS_OBJECTS = {
+    any: ['any', 'url', 'transaction', 'report', 'functionModule'],
+    http: ['url'],
+    dialog: ['transaction', 'report'],
+    batch: ['report'],
+    rfc: ['functionModule'],
+};
+/**
+ * Build the trc:parameters body. Procedural units stay on (hitlist/statements); SQL/aggregate per opts.
+ * allDbEvents follows sqlTrace: without it the `dbAccesses` analysis comes back EMPTY (only kernel summary
+ * rows) — live-verified — so the whole point of the trace (which tables/joins were hit) is lost.
+ */
+function buildTraceParametersXml(p) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<trc:parameters xmlns:trc="http://www.sap.com/adt/runtime/traces/abaptraces">
+  <trc:allMiscAbapStatements value="false"/>
+  <trc:allProceduralUnits value="true"/>
+  <trc:allInternalTableEvents value="false"/>
+  <trc:allDynproEvents value="false"/>
+  <trc:description value="${escapeXmlAttr(p.description)}"/>
+  <trc:aggregate value="${p.aggregate}"/>
+  <trc:explicitOnOff value="false"/>
+  <trc:withRfcTracing value="false"/>
+  <trc:allSystemKernelEvents value="false"/>
+  <trc:sqlTrace value="${p.sqlTrace}"/>
+  <trc:allDbEvents value="${p.sqlTrace}"/>
+  <trc:maxSizeForTraceFile value="100"/>
+  <trc:maxTimeForTracing value="600"/>
+</trc:parameters>`;
+}
+/**
+ * Arm a profiler trace request. The next execution matching {traceUser, processType, objectType} is
+ * recorded; read it back later via listTraces + the analysis sub-resources (dbAccesses needs sqlTrace).
+ * Two ADT POSTs: parameters (capture flags → parametersId in Location) then requests (when/who).
+ */
+export async function createTraceRequest(http, safety, connectedUser, client, opts = {}) {
+    checkOperation(safety, OperationType.Update, 'CreateTraceRequest');
+    const processType = opts.processType ?? 'http';
+    const validObjects = TRACE_PROCESS_OBJECTS[processType];
+    const objectType = opts.objectType ?? validObjects[0];
+    if (!validObjects.includes(objectType)) {
+        throw new AdtApiError(`Invalid objectType "${objectType}" for processType "${processType}". Valid: ${validObjects.join(', ')}.`, 400, `${TRACE_BASE}/requests`);
+    }
+    const traceUser = (opts.traceUser ?? connectedUser).toUpperCase();
+    const sqlTrace = opts.sqlTrace !== false; // default true
+    const aggregate = opts.aggregate !== false; // default true
+    const maxExecutions = Math.max(1, Math.floor(opts.maxExecutions ?? 1));
+    const expiresHours = opts.expiresHours ?? 24;
+    if (!Number.isFinite(expiresHours) || expiresHours <= 0) {
+        throw new AdtApiError('expiresHours must be a positive number of hours.', 400, `${TRACE_BASE}/requests`);
+    }
+    const expires = new Date(Date.now() + expiresHours * 3_600_000).toISOString().replace(/\.\d+Z$/, 'Z');
+    const description = opts.description ?? `arc-1 ${processType}/${objectType} trace`;
+    // 1) capture parameters → parametersId (Location header)
+    const paramsResp = await http.post(`${TRACE_BASE}/parameters`, buildTraceParametersXml({ description, aggregate, sqlTrace }), 'application/xml');
+    const parametersId = paramsResp.headers.location;
+    if (!parametersId) {
+        throw new AdtApiError('Trace parameters POST returned no Location header (parametersId).', paramsResp.statusCode, `${TRACE_BASE}/parameters`, paramsResp.body);
+    }
+    // 2) create the request (when/who)
+    const qs = new URLSearchParams({
+        server: '*',
+        description,
+        traceUser,
+        traceClient: client,
+        processType: TRACE_PROCESS_TYPE_URIS[processType],
+        objectType: TRACE_OBJECT_TYPE_URIS[objectType],
+        expires,
+        maximalExecutions: String(maxExecutions),
+        parametersId,
+    }).toString();
+    const resp = await http.post(`${TRACE_BASE}/requests?${qs}`, '', 'application/xml');
+    const created = parseTraceRequestFeed(resp.body)[0];
+    if (!created?.id) {
+        throw new AdtApiError('Trace request POST returned no usable request entry (missing id).', resp.statusCode, `${TRACE_BASE}/requests`, resp.body);
+    }
+    return created;
+}
+/** List armed trace requests for a user (read-only). */
+export async function listTraceRequests(http, safety, user) {
+    checkOperation(safety, OperationType.Read, 'ListTraceRequests');
+    const resp = await http.get(`${TRACE_BASE}/requests?user=${encodeURIComponent(user.toUpperCase())}`, {
+        Accept: 'application/atom+xml;type=feed',
+    });
+    return parseTraceRequestFeed(resp.body);
+}
+/** Cancel (delete) an armed trace request by id (the full ADT path from a request entry). */
+export async function deleteTraceRequest(http, safety, id) {
+    checkOperation(safety, OperationType.Update, 'DeleteTraceRequest');
+    await http.delete(traceRequestPath(id));
+}
+// Normalize full-path, absolute-URL, or bare trace-request ids without creating an arbitrary DELETE primitive.
+function traceRequestPath(id) {
+    const prefix = `${TRACE_BASE}/requests/`;
+    const trimmed = String(id ?? '').trim();
+    if (!trimmed)
+        throw new AdtApiError('Refusing to cancel an empty trace-request id.', 400, prefix);
+    if (trimmed.includes('\\'))
+        throw new AdtApiError(`Refusing to cancel "${id}": malformed trace-request id.`, 400, trimmed);
+    const isAbsoluteUrl = /^https?:\/\//i.test(trimmed);
+    let raw = '';
+    try {
+        if (isAbsoluteUrl)
+            new URL(trimmed);
+        raw = isAbsoluteUrl
+            ? (trimmed.match(/^https?:\/\/[^/?#]*(\/[^?#]*)?/i)?.[1] ?? '/')
+            : trimmed.startsWith('/')
+                ? trimmed
+                : `${prefix}${trimmed}`;
+    }
+    catch {
+        throw new AdtApiError(`Refusing to cancel "${id}": malformed trace-request id.`, 400, trimmed);
+    }
+    const decoded = decodeTraceRequestPath(raw, id);
+    const tail = decoded.startsWith(prefix) ? decoded.slice(prefix.length) : '';
+    if (!tail || tail !== tail.trim() || /[\\/?#\s]/.test(tail) || tail === '.' || tail === '..') {
+        throw new AdtApiError(`Refusing to cancel "${id}": not an abaptraces trace-request id (expected ${prefix}<id>).`, 400, decoded);
+    }
+    return raw;
+}
+function decodeTraceRequestPath(path, originalId) {
+    let decoded = path;
+    for (let i = 0; i < 5; i++) {
+        try {
+            const next = decodeURIComponent(decoded);
+            if (next === decoded)
+                return decoded;
+            decoded = next;
+        }
+        catch {
+            throw new AdtApiError(`Refusing to cancel "${originalId}": malformed trace-request id.`, 400, decoded);
+        }
+    }
+    throw new AdtApiError(`Refusing to cancel "${originalId}": over-encoded trace-request id.`, 400, decoded);
+}
+/** Pick the value of a node that repeats per role (admin/trace); prefer `trace`, else the first. */
+function pickTraceRole(node, valueKey) {
+    const arr = toRecordArray(node);
+    const match = arr.find((n) => n['@_role'] === 'trace') ?? arr[0];
+    const value = match?.[valueKey];
+    return value != null ? String(value) : undefined;
+}
+/**
+ * Parse the abaptraces/requests atom feed into TraceRequest[] (used for both list + create responses).
+ * Request id = the `<atom:id>` element (full ADT path with URL-encoded commas) → passed verbatim to DELETE.
+ */
+export function parseTraceRequestFeed(xml) {
+    if (!xml || xml.trim().length === 0)
+        return [];
+    const parsed = parseXml(xml);
+    const entries = findDeepNodes(parsed, 'entry');
+    return entries.map((entry) => {
+        const ext = (entry.extendedData ?? {});
+        const executions = (ext.executions ?? {});
+        const processType = (ext.processType ?? {});
+        const object = (ext.object ?? {});
+        const content = (entry.content ?? {});
+        const req = {
+            id: String(entry.id ?? content['@_src'] ?? ''),
+            title: String(entry.title ?? ext.description ?? ''),
+        };
+        const user = pickTraceRole(entry.author, 'name');
+        if (user)
+            req.user = user;
+        const client = pickTraceRole(ext.client, '#text');
+        if (client)
+            req.client = client;
+        if (ext.expires != null)
+            req.expires = String(ext.expires);
+        if (processType['@_processTypeId'] != null)
+            req.processType = String(processType['@_processTypeId']);
+        if (object['@_objectTypeId'] != null)
+            req.objectType = String(object['@_objectTypeId']);
+        const maximal = Number(executions['@_maximal']);
+        if (Number.isFinite(maximal))
+            req.maxExecutions = maximal;
+        const completed = Number(executions['@_completed']);
+        if (Number.isFinite(completed))
+            req.completedExecutions = completed;
+        if (ext.host != null)
+            req.host = String(ext.host);
+        return req;
+    });
+}
 // ─── Parsers ────────────────────────────────────────────────────────
 /**
  * Parse dump listing Atom feed.
@@ -577,6 +781,235 @@ export function parseTraceDbAccesses(xml) {
         accessTime: Number(node['@_accessTime'] ?? 0),
     }));
 }
+/** Parse the `sap-statistics` header (`k=v,k=v,…`) into a numeric map. Tolerates missing/extra fields. */
+export function parseSapStatistics(header) {
+    const out = {};
+    for (const pair of header.split(',')) {
+        const idx = pair.indexOf('=');
+        if (idx <= 0)
+            continue;
+        const key = pair.slice(0, idx).trim();
+        const val = Number(pair.slice(idx + 1).trim());
+        if (key && Number.isFinite(val))
+            out[key] = val;
+    }
+    return out;
+}
+/** Route to the dominant time component so the LLM picks the right deeper signal. */
+export function verdictFromStatistics(m) {
+    const total = m.gwtotal ?? m.total ?? 0;
+    if (total <= 0) {
+        return {
+            bound: 'unknown',
+            note: 'No Gateway timing in sap-statistics — ensure the URL is an OData/Gateway service on the SAP host ARC-1 connects to.',
+        };
+    }
+    const db = m.gwappdb ?? 0;
+    const candidates = [
+        [
+            'db',
+            db,
+            'DB-bound: the CDS/SQL query dominates. Inspect the generated SQL with SAPDiagnose(action="cds_sql"), measure it with SAPQuery (queryExecutionTime), or arm an ST05 SQL trace.',
+        ],
+        [
+            'app',
+            Math.max((m.gwapp ?? 0) - db, 0),
+            'ABAP/SADL-bound: application logic dominates, not the DB (an $expand N+1 is the classic cause) — do not ST05-hunt for a slow query. Find the OData implementation (the CDS behind a V4/RAP binding, or the SEGW Gateway DPC class) and arm a profiler trace via SAPDiagnose(action="trace_start"), then read it with action="traces" analysis="dbAccesses". Note: for HTTP/OData traces the ABAP hitlist/statements are usually empty — use ST12/SAT in SAP GUI for the call tree.',
+        ],
+        [
+            // gwfw (GW framework) and gwhub (GW hub processing) both measure framework time; older
+            // releases (e.g. NW 7.50) report only gwhub, so take whichever is present.
+            'framework',
+            Math.max(m.gwfw ?? 0, m.gwhub ?? 0),
+            'Gateway-framework-bound: likely metadata/first-call (cold-cache) cost. Re-probe to compare warm vs cold.',
+        ],
+        ['auth', m.icfauth ?? 0, 'Auth-bound: ICF/DCL authorization overhead dominates.'],
+    ];
+    candidates.sort((a, b) => b[1] - a[1]);
+    const [bound, top, note] = candidates[0];
+    // Gateway reported a total but no component is > 0 (the release didn't break it down) — don't
+    // guess "db". Report the total as undifferentiated Gateway time and point to the deeper traces.
+    if (top <= 0) {
+        return {
+            bound: 'unknown',
+            note: `Gateway total ${total}ms, but sap-statistics didn't break it into components on this release (no gwappdb/gwapp/gwfw). Treat it as Gateway processing; arm an ST05 SQL trace or ABAP profiler trace (SAPDiagnose action="traces") for the breakdown.`,
+        };
+    }
+    return { bound, note };
+}
+/**
+ * GET an OData URL with `?sap-statistics=true` + a wall-clock timer → server-side timing split + verdict.
+ * Security: `url` must be a host-relative path on the configured SAP system (no absolute URLs / SSRF).
+ */
+export async function probeODataPerformance(http, safety, url) {
+    checkOperation(safety, OperationType.Query, 'ProbeODataPerformance');
+    assertODataPerfUrl(url);
+    const withStat = url.includes('?') ? `${url}&sap-statistics=true` : `${url}?sap-statistics=true`;
+    const t0 = Date.now();
+    const resp = await http.get(withStat);
+    const wallClockMs = Date.now() - t0;
+    const statistics = parseSapStatistics(resp.headers['sap-statistics'] ?? '');
+    const fesrec = Number(resp.headers['sap-perf-fesrec']);
+    return {
+        url: withStat,
+        statusCode: resp.statusCode,
+        wallClockMs,
+        statistics,
+        fesrecMicros: Number.isFinite(fesrec) ? fesrec : undefined,
+        responseBytes: Buffer.byteLength(resp.body ?? ''),
+        verdict: verdictFromStatistics(statistics),
+    };
+}
+function assertODataPerfUrl(url) {
+    const rawPath = url.split(/[?#]/, 1)[0] ?? '';
+    let parsed;
+    try {
+        parsed = new URL(url, 'https://arc1.invalid');
+    }
+    catch {
+        throw invalidODataPerfUrl();
+    }
+    if (url.length > 4096 ||
+        !url.startsWith('/') ||
+        url.startsWith('//') ||
+        url.includes('://') ||
+        url.includes('\\') ||
+        url.includes('#') ||
+        /(?:^|\/)(?:\.|%2e)(?:\/|$)/i.test(rawPath) ||
+        /(?:^|\/)(?:\.|%2e){2}(?:\/|$)/i.test(rawPath) ||
+        /%5c/i.test(rawPath) ||
+        parsed.origin !== 'https://arc1.invalid' ||
+        !isODataPath(parsed.pathname)) {
+        throw invalidODataPerfUrl();
+    }
+}
+function isODataPath(pathname) {
+    return (pathname === '/sap/opu/odata' ||
+        pathname.startsWith('/sap/opu/odata/') ||
+        pathname === '/sap/opu/odata4' ||
+        pathname.startsWith('/sap/opu/odata4/'));
+}
+function invalidODataPerfUrl() {
+    return new Error('odata_perf url must be a host-relative OData path on the configured SAP system (e.g. "/sap/opu/odata4/.../Entity?$filter=..."); absolute URLs and non-OData SAP paths are not allowed.');
+}
+function nodeText(value) {
+    // `statement` is an ARRAY_TAG in the XML parser, so a single <ddl:statement> arrives as [text].
+    if (Array.isArray(value))
+        return value.map(nodeText).join('\n');
+    if (typeof value === 'string')
+        return value;
+    if (value && typeof value === 'object')
+        return String(value['#text'] ?? '');
+    return '';
+}
+/** Parse the `ddl:createStatements` response → the native SQL each CDS view compiles to. */
+export function parseCdsCreateStatements(xml, fallbackName = '') {
+    const parsed = parseXml(xml);
+    const sourceNodes = findDeepNodes(parsed, 'source');
+    const name = sourceNodes.length > 0 && sourceNodes[0]['@_name'] != null ? String(sourceNodes[0]['@_name']) : fallbackName;
+    const statements = findDeepNodes(parsed, 'createStatement')
+        .map((node) => ({
+        name: node['@_name'] != null ? String(node['@_name']) : undefined,
+        type: node['@_type'] != null ? String(node['@_type']) : undefined,
+        state: node['@_state'] != null ? String(node['@_state']) : undefined,
+        sql: nodeText(node.statement).trim(),
+    }))
+        .filter((s) => s.sql.length > 0);
+    return { name, statements };
+}
+/**
+ * Return the native SQL `CREATE VIEW` statements a CDS view (DDLS) generates.
+ * POST-only + CSRF (auto-managed) + a dedicated Accept type. May 404/405 on releases without the
+ * modern CDS DDL stack (e.g. NW 7.50) — let that surface so the caller learns the feature is absent.
+ */
+export async function getCdsCreateStatements(http, safety, name) {
+    checkOperation(safety, OperationType.Read, 'GetCdsCreateStatements');
+    const resp = await http.post(`/sap/bc/adt/ddic/ddl/createstatements/${encodeURIComponent(name)}`, '', undefined, {
+        Accept: 'application/vnd.sap.adt.ddl.createStatements+xml',
+    });
+    return parseCdsCreateStatements(resp.body, name);
+}
+// ─── ST05 SQL-trace state control ───────────────────────────────────
+const ST05_STATE_URL = '/sap/bc/adt/st05/trace/state';
+const ST05_DIRECTORY_URL = '/sap/bc/adt/st05/trace/directory';
+const ST05_STATE_CONTENT_TYPE = 'application/vnd.sap.adt.perf.trace.state.v1+xml';
+function boolText(value) {
+    return nodeText(value).trim().toLowerCase() === 'true';
+}
+function optText(value) {
+    const t = nodeText(value).trim();
+    return t.length > 0 ? t : undefined;
+}
+/** Parse the `ts:traceStateInstanceTable` (ST05 trace on/off per instance + filter). */
+export function parseSqlTraceState(xml) {
+    const parsed = parseXml(xml);
+    return findDeepNodes(parsed, 'traceStateInstance').map((node) => {
+        const tt = (node.traceTypes ?? {});
+        const f = (node.traceFilter ?? {});
+        return {
+            instance: nodeText(node.instance),
+            host: optText(node.host),
+            isLocal: boolText(node.isLocal),
+            isSelected: boolText(node.isSelected),
+            traceTypes: {
+                sql: boolText(tt.sqlOn),
+                buf: boolText(tt.bufOn),
+                enq: boolText(tt.enqOn),
+                rfc: boolText(tt.rfcOn),
+                http: boolText(tt.httpOn),
+                apc: boolText(tt.apcOn),
+                amc: boolText(tt.amcOn),
+                auth: boolText(tt.authOn),
+            },
+            filter: {
+                user: optText(f.traceUser),
+                transactionCode: optText(f.transactionCode),
+                program: optText(f.program),
+                rfcFunction: optText(f.rfcFunction),
+                url: optText(f.url),
+                wpId: optText(f.wpId),
+            },
+        };
+    });
+}
+/** Parse `td:traceDirectory` — SAP returns the TMC "SQL Trace Analysis" deep-link (no ADT record API). */
+export function parseSqlTraceDirectory(xml) {
+    const parsed = parseXml(xml);
+    const dir = findDeepNodes(parsed, 'traceDirectory')[0];
+    const url = dir ? optText(dir.uri) : undefined;
+    return {
+        recordViewerUrl: url,
+        note: url
+            ? 'SAP returns the SQL Trace Analysis (Technical Monitoring Cockpit) deep-link as the place to read the recorded SQL — there is no ADT SQL-record API. Open this URL in a browser (needs the /sap/bc/stmc SICF service active).'
+            : 'No trace-directory URL returned by ADT on this system.',
+    };
+}
+export async function getSqlTraceState(http, safety) {
+    checkOperation(safety, OperationType.Read, 'GetSqlTraceState');
+    const resp = await http.get(ST05_STATE_URL, { Accept: ST05_STATE_CONTENT_TYPE });
+    return parseSqlTraceState(resp.body);
+}
+export async function getSqlTraceDirectory(http, safety) {
+    checkOperation(safety, OperationType.Read, 'GetSqlTraceDirectory');
+    const resp = await http.get(ST05_DIRECTORY_URL, { Accept: 'application/*' });
+    return parseSqlTraceDirectory(resp.body);
+}
+/** Arm/disarm the ST05 SQL trace (optionally filtered to one user): GET the state, edit, PUT it back. */
+export async function setSqlTraceState(http, safety, opts) {
+    checkOperation(safety, OperationType.Update, 'SetSqlTraceState');
+    const current = await http.get(ST05_STATE_URL, { Accept: ST05_STATE_CONTENT_TYPE });
+    // Known ceiling: targeted replace on the raw state XML preserves SAP's exact element set/order and any
+    // fields ARC-1 doesn't model; flips ALL instances (add per-instance targeting only if a multi-instance
+    // system needs it).
+    let body = current.body.replace(/<ts:sqlOn>[^<]*<\/ts:sqlOn>/g, () => `<ts:sqlOn>${opts.sqlOn}</ts:sqlOn>`);
+    if (opts.traceUser !== undefined) {
+        const u = opts.traceUser.trim();
+        const repl = u.length > 0 ? `<ts:traceUser>${escapeXmlAttr(u)}</ts:traceUser>` : '<ts:traceUser/>';
+        body = body.replace(/<ts:traceUser\/>|<ts:traceUser>[^<]*<\/ts:traceUser>/g, () => repl);
+    }
+    const resp = await http.put(ST05_STATE_URL, body, ST05_STATE_CONTENT_TYPE);
+    return parseSqlTraceState(resp.body);
+}
 // ─── Helpers ────────────────────────────────────────────────────────
 function buildFeedQueryString(options, defaultMaxResults, userAttribute) {
     const params = [];