common-qa-mcp 0.2.0 → 0.4.0

package/dist/adapters/simplifyqa/adapter.js

@@ -0,0 +1,3097 @@
+import os from 'node:os';
+import { makeClient } from '../http.js';
+import { RemoteMcpAdapter } from '../remoteMcp/adapter.js';
+import { applyCollectionSteps, buildTestcasePayload, deriveTcType, extractParamNames, fromSqaStep, looksSensitive, normalizeSuiteEntry, numericId, paramDefault, pickArray, str, SUITE_UPDATE_ALLOWED_KEYS, TECH_BY_STEPTYPE, toDefectSummary, toEpic, toEpicSummary, toFeature, toFeatureSummary, toFunction, toFunctionSummary, toModuleSummary, toObject, toReleaseSummary, toSavedRef, toSprintSummary, toStory, toStorySummary, toSuite, toSuiteSummary, toTaskSummary, toTcSummary, toTestCase, toVersionEntries, withTotal, } from './mapper.js';
+const PROJECT_URL_SEGMENT = {
+    testcase: 'testcase',
+    suite: 'suite',
+    run: 'reports/execution',
+    function: 'function',
+};
+/** SQA run-row status → neutral RunStatus.state. */
+function mapRunState(s) {
+    switch (s.toUpperCase()) {
+        case 'PASSED': return 'passed';
+        case 'FAILED': return 'failed';
+        case 'STOPPED': return 'stopped';
+        case 'RUNNING': return 'running';
+        case 'QUEUED': return 'queued';
+        default: return 'queued';
+    }
+}
+/** Formula names round-trip with parens on ("FIRST_NAME()") from the backend and sometimes with a full
+ *  signature ("FIRST_NAME(country,sex)") from a caller. Reduce both to the bare identifier. */
+function bareFormulaName(s) {
+    return s.replace(/\s*\(.*\)\s*$/, '').trim();
+}
+/** Query keys /tm/customFormula expects per formula, positionally — they are NOT the formula's declared
+ *  keyNames. Mirrors the SQA UI (wfTestdataView.ts). Anything absent takes at most one arg as `value`.
+ *  ponytail: table, not per-formula handlers — extend a row when a new multi-arg formula shows up. */
+const FORMULA_ARG_KEYS = {
+    FIRST_NAME: ['country', 'sex', 'min_len', 'max_len'],
+    LAST_NAME: ['country', 'sex', 'min_len', 'max_len'],
+    FULL_NAME: ['country', 'sex', 'min_len', 'max_len'],
+    MIDDLE_NAME: ['country', 'sex', 'min_len', 'max_len'],
+    PREFIX: ['sex'],
+    DATE_OF_BIRTH: ['pattern', 'min_age', 'max_age'],
+};
+/** Normalise a formula document from `/tm/syncFormulas/fetch` into the neutral Formula shape. Returns
+ *  null when the doc is missing a name — a nameless formula cannot be called. `scope` is inferred:
+ *  DEFAULT → 'default'; CUSTOM with a matching projectId → 'project'; CUSTOM otherwise → 'customer'. */
+function normalizeFormula(doc, projectId) {
+    if (!doc || typeof doc !== 'object')
+        return null;
+    const name = str(doc, 'name');
+    if (!name)
+        return null;
+    const type = str(doc, 'type') === 'CUSTOM' ? 'CUSTOM' : 'DEFAULT';
+    const docPid = Number(doc.projectId ?? 0);
+    const scope = type === 'DEFAULT' ? 'default' : docPid && docPid === projectId ? 'project' : 'customer';
+    const desc = (doc.description && typeof doc.description === 'object') ? doc.description : {};
+    const params = Array.isArray(desc.parameters)
+        ? desc.parameters
+            .map((p) => (p && typeof p === 'object' && typeof p.keyName === 'string')
+            ? { keyName: p.keyName, description: str(p, 'value', 'description') ?? undefined, dataType: str(p, 'dataType') ?? undefined }
+            : null)
+            .filter((p) => p !== null)
+        : [];
+    return {
+        name,
+        uniqueId: str(doc, 'uniqueId') ?? name,
+        type,
+        scope,
+        signature: str(desc, 'name') ?? `${name}()`,
+        details: str(desc, 'details') ?? undefined,
+        example: str(desc, 'example') ?? undefined,
+        parameters: params,
+    };
+}
+/** SQA per-step status → neutral step status. */
+function mapStepStatus(s) {
+    switch (s.toUpperCase()) {
+        case 'PASSED': return 'pass';
+        case 'FAILED': return 'fail';
+        case 'SKIPPED': return 'skip';
+        case 'STOPPED': return 'stop';
+        default: return s.toLowerCase();
+    }
+}
+/** Allowed keys for save-as-new-version. The update joi validator
+ *  (testcaseValidator.js updateTcBodyValidation, ~line 187) is a STRICT allow-list — a raw doc's
+ *  extras (`code`, `createdBy`, `updatedBy`, `stepCount`, `versions`, ...) crash the save with
+ *  "is not allowed". Kept as string arrays so a schema drift is a one-line fix. */
+const TCFNOBJ_ALLOWED_KEYS = [
+    'id', 'name', 'projectId', 'deleted', 'moduleId', 'userstoryId', 'obsolete', 'tcType', 'mbType',
+    'executionType', 'description', 'prerequisite', 'updateVersion', 'linkedIssues', 'attachments',
+    'tags', 'suiteId', 'defectId', 'customFields', 'reviewApproveStatus', 'copiedFromTcId',
+    'projectLevelCopy', 'originalExecutinType', 'projectLevelcopiedFrom', 'mailersList',
+    'configuration', 'executionPlatform',
+];
+// FN update validator (functionValidator.js `updateFnBodyValidation.tcfnObj`) diverges from the TC
+// one in three ways that MATTER for SAVENEWVERSION: `fnType` REQUIRED (not `tcType`);
+// `obsolete`/`suiteId`/`defectId`/`configuration`/`executionPlatform`/`tcType`/`mbType` NOT
+// allowed; `copiedFromFnId` in place of `copiedFromTcId`. Sending TC's list to `/tm/function`
+// trips joi with "not allowed" on obsolete and "required" on fnType.
+const TCFNOBJ_FN_ALLOWED_KEYS = [
+    'id', 'name', 'projectId', 'deleted', 'moduleId', 'userstoryId', 'fnType',
+    'executionType', 'description', 'prerequisite', 'updateVersion', 'linkedIssues', 'attachments',
+    'tags', 'customFields', 'reviewApproveStatus', 'copiedFromFnId', 'projectLevelCopy',
+    'projectLevelcopiedFrom', 'mailersList', 'originalExecutinType', 'isMigrated', 'oldCode',
+];
+const STEP_ALLOWED_KEYS = [
+    'projectId', 'sharedFnProjectId', 'moduleId', 'apiData', 'lastActiveTab', 'userstoryId',
+    'updateVersion', 'type', 'parentId', 'objectId', 'stepType', 'functionId', 'actionId',
+    'parameterIds', 'objectParameterIds', 'parameterizedParamIds', 'attachments', 'compareFiles',
+    'compareFileType', 'deviceId', 'deleted', 'ignoreObject', 'browserType', 'technologyType', 'seq',
+    'captureScreenshot', 'screenshotEnabled', 'fnVersionId', 'description', 'expectedResult',
+    'conditions', 'stepLevelActions', 'skipParamInReport', 'paramLoopduration', 'showGroups',
+    'isConditional', 'if', 'else', 'loop', 'isLoop', 'loopType', 'startFor', 'endFor',
+    'loopDuration', 'executionType', 'recordedParam', 'switchToAndroidData', 'switchToIOSData',
+    'isDebug', 'manualStepsTopreview', 'sharedFnProjectName', 'isMigrated', 'customFields',
+    // ponytail: id / versionId are in the schema but always stripped for SAVENEWVERSION — the
+    // backend re-assigns them to the fresh version row, and keeping the old id would resurrect it.
+];
+function pick(obj, keys) {
+    const out = {};
+    if (!obj || typeof obj !== 'object')
+        return out;
+    for (const k of keys)
+        if (obj[k] !== undefined)
+            out[k] = obj[k];
+    return out;
+}
+/** Filter a fetched list of source version names by the caller's `requested` subset. Empty request
+ *  or undefined means "all". Unknown names hard-fail with the valid list so the LLM can retry with
+ *  a corrected name instead of silently cloning nothing. Empty request array = user error. */
+function filterVersionNames(available, requested, entityId) {
+    if (requested === undefined)
+        return available;
+    if (requested.length === 0) {
+        throw new Error(`versions: [] is not valid — omit the parameter to clone all versions, or pass at least one name. Source ${entityId} has: ${available.join(', ')}.`);
+    }
+    const availSet = new Set(available);
+    const unknown = requested.filter((n) => !availSet.has(n));
+    if (unknown.length) {
+        throw new Error(`Unknown version name(s) on ${entityId}: ${unknown.join(', ')}. Available versions: ${available.join(', ')}.`);
+    }
+    return [...new Set(requested)];
+}
+/** Guard against feeding an FN business key into a TC-only endpoint (or vice-versa). `numericId`
+ *  strips ANY alpha prefix — so "FN-22" → "22" and would silently target TC-22 if the caller
+ *  routed to the wrong tool. Reject any business key whose prefix doesn't match the expected
+ *  entity kind. Numeric ids and unrecognized-prefix strings pass through (leave that to backend). */
+function assertBusinessKeyKind(id, expected) {
+    const m = id?.match(/^([A-Za-z]+)[_-]\d+$/);
+    if (!m)
+        return;
+    const prefix = m[1].toUpperCase();
+    if ((expected === 'TC' && prefix === 'FN') || (expected === 'FN' && prefix === 'TC')) {
+        const otherTool = expected === 'TC'
+            ? 'this is a function key — use the fn_* tool (fn_clone, fn_save_as_new_version, get_function, delete_function)'
+            : 'this is a test-case key — use the tc_* tool (tc_clone, tc_save_as_new_version, tc_get, tc_delete)';
+        throw new Error(`Refusing to run against ${id}: ${otherTool}.`);
+    }
+}
+/** Coerce a raw {[projectId]: [ids]} map from a dep row into a plain Record<string, number[]>.
+ *  Absent/malformed inputs collapse to `{}`. */
+function toDepMap(v) {
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        return {};
+    const out = {};
+    for (const [k, arr] of Object.entries(v)) {
+        if (Array.isArray(arr))
+            out[k] = arr.filter((n) => Number.isFinite(n));
+    }
+    return out;
+}
+/** Normalise a raw dep row from PUT /tm/tcfnversion/delete into the neutral shape. Key set is
+ *  narrower for FN — the service emits `{tcArr, fnArr, wfArr}` there vs the TC keyset. */
+function normalizeVersionDep(row, parentType) {
+    const id = Number(row?.id ?? 0);
+    if (parentType === 'FN') {
+        return {
+            id,
+            tcArr: toDepMap(row?.tcArr),
+            fnArr: toDepMap(row?.fnArr),
+            wfArr: toDepMap(row?.wfArr),
+        };
+    }
+    const name = typeof row?.versionName === 'string' ? row.versionName : undefined;
+    return {
+        id,
+        ...(name ? { versionName: name } : {}),
+        defectArr: toDepMap(row?.defectArr),
+        suiteArr: toDepMap(row?.suiteArr),
+        epArr: toDepMap(row?.epArr),
+        scenarioArr: toDepMap(row?.scenarioArr),
+        schedulerArr: toDepMap(row?.schedulerArr),
+        pipelineArr: toDepMap(row?.pipelineArr),
+        workflowArr: toDepMap(row?.workflowArr),
+    };
+}
+/** True when every `*Arr` on the row is an empty map — i.e. no references block the delete.
+ *  Mirrors the UI's own check (testcase.component.ts:2142 / function.component.ts:1617). */
+function versionDepIsEmpty(dep) {
+    const maps = 'tcArr' in dep && 'wfArr' in dep && !('defectArr' in dep)
+        ? [dep.tcArr, dep.fnArr, dep.wfArr]
+        : [
+            dep.defectArr, dep.suiteArr,
+            dep.epArr, dep.scenarioArr,
+            dep.schedulerArr, dep.pipelineArr,
+            dep.workflowArr,
+        ];
+    return maps.every((m) => Object.keys(m).length === 0);
+}
+const NEEDS_PROJECT = 'No project selected. Call list_projects to see the available projects, then ' +
+    'qa_switch_project({ projectId }) to choose one — test cases, runs and objects ' +
+    'are all scoped to a project.';
+const HOP_NEEDED_WRITE = 'This SimplifyQA operation is not yet ported to direct REST — set QA_MCP_URL to the SimplifyQA ' +
+    'agent /mcp so common-mcp can hop for it, or open the SimplifyQA UI to perform it there.';
+/**
+ * SimplifyQaAdapter — DIRECT-to-backend REST driver for SimplifyQA, mirroring WalnutAdapter's
+ * design. Reads (list/get for projects/testcases/suites/stories/modules/releases/sprints/objects)
+ * hit the SimplifyQA backend REST directly via a `QaHttp` bound to `cfg.baseUrl`. Anything not yet
+ * ported (writes, testdata, run dispatch, marketplace, and the recording surface) delegates to
+ * the LOCAL AGENT's `/mcp` (`cfg.url`) via a lazily-built RemoteMcpAdapter — same "graceful hop"
+ * pattern walnut uses for recording. When the hop is not configured, unported ops surface a clear
+ * error instead of failing silently.
+ *
+ * This class deliberately does not `implements ProviderAdapter` (walnut trick): the factory casts
+ * it, and tools that call ported methods get direct REST; tools that call unported methods get
+ * the hop (or a clear error). Each porting step replaces one more delegation with a direct call.
+ */
+export class SimplifyQaAdapter {
+    constructor(cfg, transport) {
+        this.cfg = cfg;
+        this.agentHop = null;
+        // Formula list rarely changes during a session; cache the fetch response so the model can call
+        // tc_list_formulas without paying a round trip each time. Instance-scoped: switchProject rebuilds
+        // the adapter (see connection.ts), which drops this cache with it — no manual invalidation needed.
+        // We store the in-flight PROMISE, not the resolved array: several concurrent evaluateFormula calls
+        // (from the Promise.all in saveGeneratedIterations) all await the same fetch instead of each firing
+        // their own /tm/syncFormulas/fetch before the cache is populated.
+        this.formulaCache = null;
+        // ---------------------------------------------------------------------- Automation resolvers
+        /** POST /tm/action/search → per (technology, name) → row (id + objectRequired + objectTemplate).
+         *  Cached per adapter instance: the catalog is customer-wide and rarely changes during a session.
+         *  Keyed by `${technologyType}::${lowerCaseName}` so the same action name across two techs
+         *  (e.g. "click" for WEB + ANDROID) resolves to the right numeric id. */
+        this.actionCatalogCache = null;
+        // ---------------------------------------------------------------------- Objects (read + delete)
+        // list/create/delete now go direct REST (same /tm/object base getObject already uses), mirroring
+        // the testcase/suite search + soft-delete convention.
+        /** name (UPPERCASE) → objecttemplateId. Rarely changes; cached per adapter instance like
+         *  formulaCache. Populated from `POST /tm/objectTemplate/search` (confirmed endpoint,
+         *  api-endpoints.ts `object.search`'s sibling `objectTemplate.search`). */
+        this.objectTemplateCache = null;
+        if (!cfg.baseUrl) {
+            throw new Error('SimplifyQaAdapter requires a baseUrl — set QA_BASE_URL or use a JWT with a `url` claim.');
+        }
+        this.http = makeClient({
+            baseUrl: cfg.baseUrl,
+            headers: () => this.headers(),
+            ...transport,
+        });
+    }
+    // Auth headers mirror the Java RequestContext: bearer + x-project-id. `x-project-id` is only
+    // spread in when a project is selected — a session can be connected before one is chosen.
+    headers() {
+        return {
+            Authorization: `Bearer ${this.cfg.token}`,
+            ...(this.cfg.projectId ? { 'x-project-id': this.cfg.projectId } : {}),
+        };
+    }
+    requireProjectId() {
+        if (!this.cfg.projectId)
+            throw new Error(NEEDS_PROJECT);
+        const n = Number.parseInt(String(this.cfg.projectId).trim(), 10);
+        if (!Number.isFinite(n))
+            throw new Error(`Invalid projectId ${this.cfg.projectId} — expected a numeric id.`);
+        return n;
+    }
+    // Standard SQA `searchFields` payload builder — the SAME shape every /search endpoint expects.
+    // Every list op below uses this instead of hand-writing the same 6-line boilerplate.
+    searchBody(fields, opts = {}) {
+        const body = {
+            searchFields: fields.map((f) => ({
+                column: f.column,
+                value: f.value,
+                ...(f.regEx ? { regEx: true } : {}),
+            })),
+            startIndex: opts.startIndex ?? 0,
+            limit: opts.limit ?? 100,
+        };
+        if (opts.selectFields)
+            body['selectFields'] = opts.selectFields;
+        return body;
+    }
+    // ---------------------------------------------------------------------- Info + projects
+    /** Validates baseUrl + token + (optional) project by running the same list_projects search the
+     *  Java `infoResult` uses to resolve the project name — no separate /info endpoint on SQA.
+     *  `counts` is a best-effort row count per entity type (test cases/suites/stories/objects), read
+     *  from each `/search` endpoint's own `totalCount` (see searchTotalCount) — mirrors what Walnut's
+     *  info() already returns via its own `counts`. */
+    async info() {
+        const projects = await this.listProjects();
+        const projectId = this.cfg.projectId ?? '';
+        const found = projects.find((p) => p.id === projectId);
+        const [testCases, suites, stories, objects] = await Promise.all([
+            this.searchTotalCount('/tm/testcase/search'),
+            this.searchTotalCount('/tm/suites/search'),
+            this.searchTotalCount('/pm/userstory/search'),
+            this.searchTotalCount('/tm/object/search'),
+        ]);
+        return {
+            provider: 'simplifyqa',
+            projectId,
+            projectName: found?.name ?? '',
+            counts: { testCases, suites, stories, objects },
+        };
+    }
+    /** Projects the caller can access. Three code paths in priority order:
+     *
+     *  1. Config-supplied `QA_MCP_USER_ID` (needed for API-key auth — SQA keys are encrypted JWTs
+     *     with no client-decryptable userId, and no whoami endpoint exists yet) → user-scoped
+     *     two-step via `/pm/projectuserrole`.
+     *  2. Session JWT with `userId` claim → same two-step.
+     *  3. Neither → direct `/pm/project/search`; the backend scopes by the token owner where it
+     *     can (may return tenant-wide for API keys). `totalCount` uses `rows.length` (backend's
+     *     top-level `totalCount` is unreliable — counts pre-filter, includes deleted).
+     *
+     *  The two-step avoids both problems: correct user scoping AND an accurate count. */
+    async listProjects() {
+        const userId = this.cfg.userId?.trim() || this.jwtUserId();
+        return userId ? this.listProjectsForUser(userId) : this.listProjectsDirect();
+    }
+    async listProjectsForUser(userId) {
+        const rolesRaw = await this.http.getJson(`/pm/projectuserrole?userId=${encodeURIComponent(userId)}`);
+        const roleRows = pickArray(rolesRaw, 'data', 'content');
+        const projectIds = Array.from(new Set(roleRows.map((r) => str(r, 'projectId')).filter((v) => !!v))).map((s) => Number.parseInt(s, 10)).filter((n) => Number.isFinite(n));
+        if (projectIds.length === 0)
+            return withTotal([], { totalCount: 0 });
+        const body = this.searchBody([
+            { column: 'id', value: projectIds },
+            { column: 'deleted', value: false },
+        ], { selectFields: ['id', 'code', 'name'], limit: projectIds.length });
+        const raw = await this.http.postJson('/pm/project/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'projects');
+        const projects = rows.map((n) => {
+            const code = str(n, 'code');
+            return {
+                id: str(n, 'id', '_id', 'projectId') ?? '',
+                ...(code ? { code } : {}),
+                name: str(n, 'name', 'projectName') ?? '',
+            };
+        });
+        return withTotal(projects, { totalCount: projects.length });
+    }
+    /** Best-effort row count for an entity `/search` endpoint — posts a minimal (limit 1) project-scoped
+     *  search and reads the `totalCount` the backend returns alongside `data` (the same envelope shape
+     *  every /search endpoint in this codebase uses, confirmed via the real sqa-ui
+     *  `{ totalCount: number, data: [...] }` response typing). Never throws — counts are a nice-to-have
+     *  for project_info, not worth failing the whole call over; any failure (or a missing totalCount)
+     *  falls back to 0 / the returned row count. */
+    async searchTotalCount(path) {
+        try {
+            const projectId = this.requireProjectId();
+            const body = this.searchBody([{ column: 'deleted', value: false }, { column: 'projectId', value: projectId }], { limit: 1 });
+            const raw = await this.http.postJson(path, body);
+            if (typeof raw?.totalCount === 'number')
+                return raw.totalCount;
+            return pickArray(raw, 'data', 'content').length;
+        }
+        catch {
+            return 0;
+        }
+    }
+    async listProjectsDirect() {
+        const body = this.searchBody([{ column: 'deleted', value: false }], { selectFields: ['id', 'code', 'name'] });
+        const raw = await this.http.postJson('/pm/project/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'projects');
+        const projects = rows.map((n) => {
+            const code = str(n, 'code');
+            return {
+                id: str(n, 'id', '_id', 'projectId') ?? '',
+                ...(code ? { code } : {}),
+                name: str(n, 'name', 'projectName') ?? '',
+            };
+        });
+        // ponytail: backend `totalCount` on /pm/project/search is unreliable (counts pre-filter). Trust
+        // rows.length instead — accurate for the page we actually returned.
+        return withTotal(projects, { totalCount: projects.length });
+    }
+    /** Decode the `userId` claim from the SQA JWT payload WITHOUT verifying the signature. Backend
+     *  re-verifies on every call; this only needs the id for `/pm/projectuserrole`. Returns undefined
+     *  on any parse failure or when the token isn't a JWT. */
+    jwtUserId() {
+        const token = this.cfg.token;
+        if (!token)
+            return undefined;
+        try {
+            const t = token.startsWith('Bearer ') ? token.slice(7).trim() : token.trim();
+            const seg = t.split('.')[1];
+            if (!seg)
+                return undefined;
+            let b64 = seg.replace(/-/g, '+').replace(/_/g, '/');
+            b64 += '='.repeat((4 - (b64.length % 4)) % 4);
+            const claims = JSON.parse(Buffer.from(b64, 'base64').toString('utf8'));
+            const v = claims['userId'] ?? claims['id'] ?? claims['sub'];
+            if (typeof v === 'string' && v.length)
+                return v;
+            if (typeof v === 'number')
+                return String(v);
+            return undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    // ---------------------------------------------------------------------- Test cases (read)
+    async listTestCases(q) {
+        const projectId = this.requireProjectId();
+        const fields = [
+            { column: 'deleted', value: false },
+            { column: 'projectId', value: projectId },
+        ];
+        if (q.search)
+            fields.push({ column: 'name', value: q.search, regEx: true });
+        if (q.status)
+            fields.push({ column: 'status', value: q.status });
+        const createdBy = this.resolveUserFilter(q.createdBy);
+        if (createdBy != null)
+            fields.push({ column: 'createdBy', value: createdBy });
+        const updatedBy = this.resolveUserFilter(q.updatedBy);
+        if (updatedBy != null)
+            fields.push({ column: 'updatedBy', value: updatedBy });
+        if (q.storyId)
+            fields.push({ column: 'userstoryId', value: Number.parseInt(numericId(q.storyId), 10) });
+        if (q.moduleId)
+            fields.push({ column: 'moduleId', value: Number.parseInt(numericId(q.moduleId), 10) });
+        if (typeof q.obsolete === 'boolean')
+            fields.push({ column: 'obsolete', value: q.obsolete });
+        if (q.filters?.length)
+            fields.push(...q.filters);
+        const body = this.searchBody(fields, {
+            startIndex: q.offset ?? 0,
+            limit: q.limit ?? 100,
+            selectFields: ['id', 'code', 'name', 'priority', 'status', 'stepCount', 'tcType', 'executionType', 'obsolete'],
+        });
+        const raw = await this.http.postJson('/tm/testcase/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'testCases');
+        return withTotal(rows.map(toTcSummary), raw);
+    }
+    /** "me" → cfg.userId (numeric); numeric string → number; anything else → undefined. Callers
+     *  should have resolved a name to a numeric id via `list_users` first. */
+    resolveUserFilter(v) {
+        if (!v)
+            return undefined;
+        const raw = v === 'me' ? (this.cfg.userId?.trim() ?? '') : v.trim();
+        if (!raw)
+            return undefined;
+        const n = Number.parseInt(raw, 10);
+        return Number.isFinite(n) ? n : undefined;
+    }
+    /** Neutral test case, steps included. Accepts numeric id or business code (`TC_123`).
+     *  `versionId` overrides which version's steps to load — omit to accept the TC's currently-
+     *  selected version. When the resolved version differs from the doc's current selection, we
+     *  also patch `currentVersionId` on the returned tc so callers can render "showing version X". */
+    async getTestCase(id, versionId) {
+        const raw = await this.fetchRawTestcase(id);
+        if (!raw || Object.keys(raw).length === 0) {
+            throw new Error(`test case ${id} not found`);
+        }
+        const tc = toTestCase(raw);
+        // If the caller pinned a version, validate it exists on the TC — otherwise the /steps call
+        // just returns an empty array for an unknown id and the user sees "no steps" for a typo.
+        if (versionId) {
+            const known = (tc.versions ?? []).some((v) => v.id === versionId);
+            if (!known)
+                throw new Error(`version ${versionId} not found on test case ${id}`);
+        }
+        let rows = [];
+        try {
+            rows = await this.fetchStepsCollection(id, raw, versionId);
+        }
+        catch { /* fall through — inline steps stay */ }
+        const withSteps = rows.length > 0 ? applyCollectionSteps(tc, rows) : tc;
+        // Overlay currentVersionId to the resolved one and flip isCurrent flags on versions[]. Apply
+        // even when rows are empty — a caller who pinned versionId still expects the header + versions[]
+        // to reflect that choice (a legitimately-empty version shouldn't fall back to the TC's default).
+        const resolvedVer = versionId ?? tc.currentVersionId;
+        const patched = { ...withSteps, ...(resolvedVer ? { currentVersionId: resolvedVer } : {}) };
+        if (resolvedVer && patched.versions?.length) {
+            patched.versions = patched.versions.map((v) => ({ ...v, isCurrent: v.id === resolvedVer }));
+        }
+        if (rows.length > 0) {
+            await Promise.all([
+                this.hydrateFunctionNames(patched),
+                this.hydrateObjectNames(patched),
+            ]);
+        }
+        return patched;
+    }
+    async fetchRawTestcase(id) {
+        const raw = await this.http.getJson(`/tm/testcase/getById/${numericId(id)}`);
+        let doc = raw?.data ?? raw;
+        if (Array.isArray(doc))
+            doc = doc.length > 0 ? doc[0] : {};
+        return doc && typeof doc === 'object' ? doc : {};
+    }
+    async fetchStepsCollection(tcId, rawTc, versionOverride) {
+        const projectId = this.requireProjectId();
+        const tcNum = numericId(tcId);
+        // Resolution order: explicit override → TC's currently-selected version (any of 4 field
+        // names, depending on the read model — Java tries all four) → first entry in versions[].
+        let versionId = versionOverride;
+        if (!versionId) {
+            versionId =
+                str(rawTc, 'versionId', 'selectedVersionId') ??
+                    (rawTc?.versionsDetails && typeof rawTc.versionsDetails === 'object'
+                        ? str(rawTc.versionsDetails, 'id', '_id', 'versionId')
+                        : undefined);
+            if (!versionId && Array.isArray(rawTc?.versions) && rawTc.versions.length > 0) {
+                versionId = str(rawTc.versions[0], 'id', '_id');
+            }
+        }
+        if (!versionId)
+            return [];
+        const path = '/tm/testcase/steps' +
+            `?projectId=${projectId}` +
+            `&tcfnId=${tcNum}` +
+            `&versionId=${encodeURIComponent(versionId)}` +
+            '&type=TC';
+        const body = await this.http.getJson(path);
+        const rows = Array.isArray(body) ? body : Array.isArray(body?.data) ? body.data : [];
+        return rows;
+    }
+    /** For every FUNCTION step, resolve the referenced function's code + name via /tm/function search
+     *  (batched by distinct functionId). Mutates `tc.steps[i].functionCall` in place with
+     *  `testCaseCode`/`testCaseName`. Non-fatal on failure — the raw id still renders. Mirrors the
+     *  Excel export builder in tcfn.service.js:2696-2703. */
+    async hydrateFunctionNames(tc) {
+        const ids = new Set();
+        for (const s of tc.steps) {
+            if (s.stepType === 'function' && s.functionCall?.testCaseId) {
+                ids.add(s.functionCall.testCaseId);
+            }
+        }
+        if (!ids.size)
+            return;
+        try {
+            const projectId = this.requireProjectId();
+            const body = this.searchBody([
+                { column: 'deleted', value: false },
+                { column: 'projectId', value: projectId },
+                { column: 'id', value: [...ids].map((x) => Number.parseInt(x, 10)).filter(Number.isFinite), regEx: false },
+            ]);
+            const raw = await this.http.postJson('/tm/function/search', body);
+            const rows = pickArray(raw, 'data', 'content', 'functions');
+            const byId = new Map();
+            for (const r of rows) {
+                const rid = str(r, 'id', '_id', 'functionId');
+                if (!rid)
+                    continue;
+                byId.set(rid, { code: str(r, 'code'), name: str(r, 'name', 'title') ?? '' });
+            }
+            for (const s of tc.steps) {
+                if (s.stepType !== 'function' || !s.functionCall)
+                    continue;
+                const hit = byId.get(s.functionCall.testCaseId);
+                if (!hit)
+                    continue;
+                if (hit.code)
+                    s.functionCall.testCaseCode = hit.code;
+                if (hit.name)
+                    s.functionCall.testCaseName = hit.name;
+            }
+        }
+        catch {
+            // Non-fatal: fall back to bare id in the render.
+        }
+    }
+    /** For every step with an objectRef, resolve the object's display name (`disname`) via
+     *  /tm/object/search (batched by distinct objectId). Mutates `objectRef.name` in place. Non-fatal
+     *  on failure — the bare id still renders. Mirrors the FE's `defaultFieldsMap.get('objectId').map`
+     *  behavior used by the Excel export (tcfn.service.js:2876) so the tool surface matches the UI. */
+    async hydrateObjectNames(tc) {
+        const ids = new Set();
+        for (const s of tc.steps) {
+            if (s.objectRef?.id && !s.objectRef.name)
+                ids.add(s.objectRef.id);
+        }
+        if (!ids.size)
+            return;
+        try {
+            const projectId = this.requireProjectId();
+            const body = this.searchBody([
+                { column: 'deleted', value: false },
+                { column: 'projectId', value: projectId },
+                { column: 'id', value: [...ids].map((x) => Number.parseInt(x, 10)).filter(Number.isFinite), regEx: false },
+            ]);
+            const raw = await this.http.postJson('/tm/object/search', body);
+            const rows = pickArray(raw, 'data', 'content', 'objects');
+            const byId = new Map();
+            for (const r of rows) {
+                const rid = str(r, 'id', '_id');
+                if (!rid)
+                    continue;
+                const name = str(r, 'disname', 'description', 'placeholder');
+                if (name)
+                    byId.set(rid, name);
+            }
+            for (const s of tc.steps) {
+                if (!s.objectRef?.id || s.objectRef.name)
+                    continue;
+                const name = byId.get(s.objectRef.id);
+                if (name)
+                    s.objectRef.name = name;
+            }
+        }
+        catch {
+            // Non-fatal: fall back to bare id in the render.
+        }
+    }
+    // ---------------------------------------------------------------------- Suites (read)
+    async listSuites() {
+        const projectId = this.requireProjectId();
+        const body = this.searchBody([
+            { column: 'deleted', value: false },
+            { column: 'projectId', value: projectId },
+        ]);
+        const raw = await this.http.postJson('/tm/suites/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'suites');
+        return withTotal(rows.map(toSuiteSummary), raw);
+    }
+    async getSuite(id) {
+        const raw = await this.http.getJson(`/tm/suites/${numericId(id)}`);
+        let doc = raw?.data ?? raw;
+        if (Array.isArray(doc))
+            doc = doc.length > 0 ? doc[0] : {};
+        return toSuite(doc && typeof doc === 'object' ? doc : {});
+    }
+    // ---------------------------------------------------------------------- Stories (read)
+    async listStories(q) {
+        const projectId = this.requireProjectId();
+        const fields = [
+            { column: 'deleted', value: false },
+            { column: 'projectId', value: projectId },
+        ];
+        if (q.search)
+            fields.push({ column: 'name', value: q.search, regEx: true });
+        // SQA's userstory FK for sprint is `iterationId` — spec uses the neutral name `sprintId`.
+        if (q.sprintId)
+            fields.push({ column: 'iterationId', value: Number.parseInt(q.sprintId, 10) });
+        if (q.releaseId)
+            fields.push({ column: 'releaseId', value: Number.parseInt(q.releaseId, 10) });
+        const createdBy = this.resolveUserFilter(q.createdBy);
+        if (createdBy != null)
+            fields.push({ column: 'createdBy', value: createdBy });
+        const updatedBy = this.resolveUserFilter(q.updatedBy);
+        if (updatedBy != null)
+            fields.push({ column: 'updatedBy', value: updatedBy });
+        const ownerId = this.resolveUserFilter(q.ownerId);
+        if (ownerId != null)
+            fields.push({ column: 'ownerId', value: ownerId });
+        if (q.filters?.length)
+            fields.push(...q.filters);
+        const body = this.searchBody(fields, { limit: q.limit ?? 50 });
+        const raw = await this.http.postJson('/pm/userstory/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'userStories', 'stories');
+        return withTotal(rows.map(toStorySummary), raw);
+    }
+    async getStory(id) {
+        const resolvedId = await this.resolveStoryNumericId(id);
+        const raw = await this.http.getJson(`/pm/userstory/${resolvedId}`);
+        const doc = Array.isArray(raw)
+            ? (raw.length > 0 ? raw[0] : {})
+            : (raw?.data && typeof raw.data === 'object' ? raw.data : raw);
+        return toStory(doc && typeof doc === 'object' ? doc : {});
+    }
+    /** A US_XXX business key → the numeric userstoryId via `/pm/userstory/search`. Numeric passes
+     *  through. SQA's GET-by-id parseInts the path, so a raw key would 404. */
+    async resolveStoryNumericId(ref) {
+        if (!ref)
+            return ref;
+        if (/^\d+$/.test(ref))
+            return ref;
+        const body = this.searchBody([{ column: 'code', value: ref }], { startIndex: 0, limit: 1 });
+        const raw = await this.http.postJson('/pm/userstory/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'userStories', 'stories');
+        if (rows.length === 0)
+            throw new Error(`Story not found for business key: ${ref}`);
+        return str(rows[0], 'id', '_id', 'userstoryId') ?? ref;
+    }
+    // ---------------------------------------------------------------------- Defects (read)
+    /** `POST /pm/defect/search` — same searchFields protocol as userstory/testcase search. */
+    async listDefects(q) {
+        const projectId = this.requireProjectId();
+        const fields = [
+            { column: 'deleted', value: false },
+            { column: 'projectId', value: projectId },
+        ];
+        if (q.search)
+            fields.push({ column: 'name', value: q.search, regEx: true });
+        if (q.tcId)
+            fields.push({ column: 'selectedTestCase.testcaseId', value: [Number.parseInt(numericId(q.tcId), 10)] });
+        if (q.storyId)
+            fields.push({ column: 'userstoryId', value: Number.parseInt(numericId(q.storyId), 10) });
+        if (q.state)
+            fields.push({ column: 'state', value: q.state });
+        // ownerId is an array field — match with Mongo $in, not bare equality.
+        const assignedTo = this.resolveUserFilter(q.assignedTo);
+        if (assignedTo != null)
+            fields.push({ column: 'ownerId', value: { $in: [assignedTo] } });
+        const createdBy = this.resolveUserFilter(q.createdBy);
+        if (createdBy != null)
+            fields.push({ column: 'createdBy', value: createdBy });
+        if (q.filters?.length)
+            fields.push(...q.filters);
+        const body = this.searchBody(fields, { limit: q.limit ?? 50, startIndex: q.offset ?? 0 });
+        const raw = await this.http.postJson('/pm/defect/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'defects');
+        return withTotal(rows.map(toDefectSummary), raw);
+    }
+    // ---------------------------------------------------------------------- Tasks (read)
+    /** `POST /pm/task/search` — same searchFields protocol as defect/userstory search. */
+    async listTasks(q) {
+        const projectId = this.requireProjectId();
+        const fields = [
+            { column: 'deleted', value: false },
+            { column: 'projectId', value: projectId },
+        ];
+        if (q.search)
+            fields.push({ column: 'name', value: q.search, regEx: true });
+        if (q.storyId)
+            fields.push({ column: 'userstoryId', value: Number.parseInt(numericId(q.storyId), 10) });
+        if (q.state)
+            fields.push({ column: 'state', value: q.state });
+        const assignedTo = this.resolveUserFilter(q.assignedTo);
+        if (assignedTo != null)
+            fields.push({ column: 'ownerId', value: { $in: [assignedTo] } });
+        const createdBy = this.resolveUserFilter(q.createdBy);
+        if (createdBy != null)
+            fields.push({ column: 'createdBy', value: createdBy });
+        if (q.filters?.length)
+            fields.push(...q.filters);
+        const body = this.searchBody(fields, { limit: q.limit ?? 50, startIndex: q.offset ?? 0 });
+        const raw = await this.http.postJson('/pm/task/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'tasks');
+        return withTotal(rows.map(toTaskSummary), raw);
+    }
+    // ---------------------------------------------------------------------- Stories (write)
+    async createStory(input) {
+        const body = {
+            ...input,
+            // SQA userstory expects a singular numeric projectId; fill from the connected project when omitted.
+            projectId: input.projectId ?? this.requireProjectId(),
+        };
+        const raw = await this.http.postJson('/pm/userstory', body);
+        return toSavedRef(raw, true);
+    }
+    async updateStory(id, patch) {
+        const resolvedId = await this.resolveStoryNumericId(id);
+        const raw = await this.http.putJson(`/pm/userstory/${resolvedId}`, patch);
+        return toSavedRef(raw ?? { id: resolvedId }, false);
+    }
+    // ---------------------------------------------------------------------- Epics
+    async listEpics(q) {
+        const projectId = this.requireProjectId();
+        const fields = [
+            { column: 'deleted', value: false },
+            // Epic is multi-project in SQA — filter for members of the current project via $in.
+            { column: 'projectIds', value: projectId },
+        ];
+        if (q.search)
+            fields.push({ column: 'name', value: q.search, regEx: true });
+        if (q.state)
+            fields.push({ column: 'state', value: q.state });
+        const createdBy = this.resolveUserFilter(q.createdBy);
+        if (createdBy != null)
+            fields.push({ column: 'createdBy', value: createdBy });
+        const updatedBy = this.resolveUserFilter(q.updatedBy);
+        if (updatedBy != null)
+            fields.push({ column: 'updatedBy', value: updatedBy });
+        const ownerId = this.resolveUserFilter(q.ownerId);
+        if (ownerId != null)
+            fields.push({ column: 'ownerId', value: ownerId });
+        const body = this.searchBody(fields, {
+            startIndex: q.offset ?? 0,
+            limit: q.limit ?? 50,
+        });
+        const raw = await this.http.postJson('/pm/epic/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'epics');
+        return withTotal(rows.map(toEpicSummary), raw);
+    }
+    async getEpic(id) {
+        const resolvedId = await this.resolveEpicNumericId(id);
+        const raw = await this.http.getJson(`/pm/epic/${resolvedId}`);
+        const doc = Array.isArray(raw)
+            ? (raw.length > 0 ? raw[0] : {})
+            : (raw?.data && typeof raw.data === 'object' ? raw.data : raw);
+        return toEpic(doc && typeof doc === 'object' ? doc : {});
+    }
+    async createEpic(input) {
+        const body = {
+            ...input,
+            projectIds: input.projectIds ?? [this.requireProjectId()],
+        };
+        const raw = await this.http.postJson('/pm/epic', body);
+        return toSavedRef(raw, true);
+    }
+    async updateEpic(id, patch) {
+        const resolvedId = await this.resolveEpicNumericId(id);
+        const raw = await this.http.putJson(`/pm/epic/${resolvedId}`, patch);
+        return toSavedRef(raw ?? { id: resolvedId }, false);
+    }
+    /** EP_XXX business key → numeric epic id via `/pm/epic/search`. Numeric passes through. */
+    async resolveEpicNumericId(ref) {
+        if (!ref)
+            return ref;
+        if (/^\d+$/.test(ref))
+            return ref;
+        const body = this.searchBody([{ column: 'code', value: ref }], { startIndex: 0, limit: 1 });
+        const raw = await this.http.postJson('/pm/epic/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'epics');
+        if (rows.length === 0)
+            throw new Error(`Epic not found for business key: ${ref}`);
+        return str(rows[0], 'id', '_id', 'epicId') ?? ref;
+    }
+    // ---------------------------------------------------------------------- Features
+    async listFeatures(q) {
+        const projectId = this.requireProjectId();
+        const fields = [
+            { column: 'deleted', value: false },
+            { column: 'projectIds', value: projectId },
+        ];
+        if (q.search)
+            fields.push({ column: 'name', value: q.search, regEx: true });
+        if (q.state)
+            fields.push({ column: 'state', value: q.state });
+        if (q.epicId)
+            fields.push({ column: 'epicId', value: Number.parseInt(q.epicId, 10) });
+        const createdBy = this.resolveUserFilter(q.createdBy);
+        if (createdBy != null)
+            fields.push({ column: 'createdBy', value: createdBy });
+        const updatedBy = this.resolveUserFilter(q.updatedBy);
+        if (updatedBy != null)
+            fields.push({ column: 'updatedBy', value: updatedBy });
+        const ownerId = this.resolveUserFilter(q.ownerId);
+        if (ownerId != null)
+            fields.push({ column: 'ownerId', value: ownerId });
+        const body = this.searchBody(fields, {
+            startIndex: q.offset ?? 0,
+            limit: q.limit ?? 50,
+        });
+        const raw = await this.http.postJson('/pm/feature/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'features');
+        return withTotal(rows.map(toFeatureSummary), raw);
+    }
+    async getFeature(id) {
+        const resolvedId = await this.resolveFeatureNumericId(id);
+        const raw = await this.http.getJson(`/pm/feature/${resolvedId}`);
+        const doc = Array.isArray(raw)
+            ? (raw.length > 0 ? raw[0] : {})
+            : (raw?.data && typeof raw.data === 'object' ? raw.data : raw);
+        return toFeature(doc && typeof doc === 'object' ? doc : {});
+    }
+    async createFeature(input) {
+        const body = {
+            ...input,
+            projectIds: input.projectIds ?? [this.requireProjectId()],
+        };
+        const raw = await this.http.postJson('/pm/feature', body);
+        return toSavedRef(raw, true);
+    }
+    async updateFeature(id, patch) {
+        const resolvedId = await this.resolveFeatureNumericId(id);
+        const raw = await this.http.putJson(`/pm/feature/${resolvedId}`, patch);
+        return toSavedRef(raw ?? { id: resolvedId }, false);
+    }
+    /** FT_XXX business key → numeric feature id via `/pm/feature/search`. Numeric passes through. */
+    async resolveFeatureNumericId(ref) {
+        if (!ref)
+            return ref;
+        if (/^\d+$/.test(ref))
+            return ref;
+        const body = this.searchBody([{ column: 'code', value: ref }], { startIndex: 0, limit: 1 });
+        const raw = await this.http.postJson('/pm/feature/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'features');
+        if (rows.length === 0)
+            throw new Error(`Feature not found for business key: ${ref}`);
+        return str(rows[0], 'id', '_id', 'featureId') ?? ref;
+    }
+    // ---------------------------------------------------------------------- Modules, releases, sprints
+    async listModules() {
+        const projectId = this.requireProjectId();
+        const body = this.searchBody([
+            { column: 'projectId', value: projectId },
+            { column: 'deleted', value: false },
+        ], { selectFields: ['id', 'code', 'name', 'parentId'] });
+        const raw = await this.http.postJson('/pm/module/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'modules');
+        return withTotal(rows.map(toModuleSummary), raw);
+    }
+    /** GET /pm/module/:id — server returns an array; empty array → NotFound. */
+    async getModule(id) {
+        const raw = await this.http.getJson(`/pm/module/${numericId(id)}`);
+        const rows = Array.isArray(raw) ? raw : pickArray(raw, 'data', 'content');
+        const doc = rows[0];
+        if (!doc)
+            throw new Error(`Module ${id} not found.`);
+        const summary = toModuleSummary(doc);
+        const code = str(doc, 'code');
+        const description = str(doc, 'description');
+        const projectId = doc?.projectId != null ? String(doc.projectId) : undefined;
+        const childIds = Array.isArray(doc?.childIds)
+            ? doc.childIds.filter((n) => Number.isFinite(n))
+            : undefined;
+        const isRoot = typeof doc?.isRoot === 'boolean' ? doc.isRoot : undefined;
+        return {
+            ...summary,
+            ...(code ? { code } : {}),
+            ...(description ? { description } : {}),
+            ...(childIds ? { childIds } : {}),
+            ...(projectId ? { projectId } : {}),
+            ...(isRoot !== undefined ? { isRoot } : {}),
+        };
+    }
+    /** POST /pm/module — server validates: name+isRoot+projectId required; parentId ignored when
+     *  isRoot:true. Duplicate name per project is rejected server-side. */
+    async createModule(input) {
+        const payload = {
+            name: input.name,
+            isRoot: input.isRoot,
+            projectId: Number.parseInt(input.projectId, 10),
+        };
+        if (input.description)
+            payload['description'] = input.description;
+        if (!input.isRoot && input.parentId)
+            payload['parentId'] = Number.parseInt(input.parentId, 10);
+        const raw = await this.http.postJson('/pm/module', payload);
+        return toSavedRef(raw, true);
+    }
+    /** PATCH /pm/module — two-phase per module.controller.js:94. `confirm:false` returns the per-id
+     *  dependency footprint (test cases, functions, params, objects, defects, user stories). `confirm:true`
+     *  triggers the actual delete: server drops only ids with EMPTY dependencies; ids with references are
+     *  silently skipped — we still return that list so the caller can act on it.
+     *  ponytail: one method, `confirm` flag; mirrors the backend's two-call contract. */
+    async deleteModule(input) {
+        const numIds = input.ids.map((id) => Number.parseInt(numericId(id), 10));
+        const projectId = Number.parseInt(input.projectId, 10);
+        const isDelete = input.confirm === true;
+        const raw = await this.http.patchJson('/pm/module', { ids: numIds, projectId, isDelete });
+        const arr = Array.isArray(raw) ? raw : pickArray(raw, 'data', 'content');
+        const dependencies = arr
+            .filter((r) => r && typeof r === 'object')
+            .map((r) => ({
+            id: Number(r.id),
+            tcArr: Array.isArray(r.tcArr) ? r.tcArr : [],
+            fnArr: Array.isArray(r.fnArr) ? r.fnArr : [],
+            parameterArr: Array.isArray(r.parameterArr) ? r.parameterArr : [],
+            objArr: Array.isArray(r.objArr) ? r.objArr : [],
+            defectArr: Array.isArray(r.defectArr) ? r.defectArr : [],
+            usArr: Array.isArray(r.usArr) ? r.usArr : [],
+        }));
+        return { dryRun: !isDelete, dependencies };
+    }
+    /** PUT /tm/tcfnversion/delete — soft-delete ONE version of a TC or FN. Two-phase per
+     *  tcfnversion.service.js:30 — `isDelete:false` (or `isDelete:true` with non-empty deps) →
+     *  returns the dependency array unchanged; `isDelete:true` with EMPTY deps → soft-deletes the
+     *  tcfn_version row + its steps + testdata + testdata iterations.
+     *
+     *  ponytail: one method, `confirm` flag. Response shape decides `deleted`: if every dep row is
+     *  fully empty (all `*Arr` are `{}` maps), the server actually deleted; otherwise it refused
+     *  and just handed back the deps. We do not assume — we inspect. */
+    async deleteVersion(input) {
+        const projectId = this.requireProjectId();
+        const parentType = input.kind === 'tc' ? 'TC' : 'FN';
+        const isDelete = input.confirm === true;
+        const body = {
+            id: input.versionId,
+            parentId: Number.parseInt(numericId(input.parentId), 10),
+            parentType,
+            projectId,
+            name: input.versionName,
+            isDelete,
+        };
+        const raw = await this.http.putJson('/tm/tcfnversion/delete', body);
+        const data = raw?.data ?? raw;
+        // Distinguish "dep array" from "delete result": the service returns an ARRAY of dep rows for
+        // the dry-run + refused-delete branches, and a single mongo doc (findOneAndUpdate result) for
+        // the successful delete branch. Array → parse deps; single doc → deleted.
+        if (Array.isArray(data)) {
+            const dependencies = data
+                .filter((r) => r && typeof r === 'object')
+                .map((r) => normalizeVersionDep(r, parentType));
+            const hasBlockers = dependencies.some((d) => !versionDepIsEmpty(d));
+            return { dryRun: !isDelete, deleted: false, dependencies, hasBlockers };
+        }
+        // Single doc → successful delete (or upsert-echo when nothing matched, but the service only
+        // reaches that branch after emptyIds.push).
+        return { dryRun: false, deleted: true, dependencies: [], hasBlockers: false };
+    }
+    async listReleases(q) {
+        const fields = [{ column: 'deleted', value: false }];
+        if (q.scope === 'project')
+            fields.push({ column: 'projectIds', value: this.requireProjectId() });
+        const body = this.searchBody(fields);
+        const raw = await this.http.postJson('/pm/release/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'releases');
+        return withTotal(rows.map(toReleaseSummary), raw);
+    }
+    async listSprints(q) {
+        const fields = [{ column: 'deleted', value: false }];
+        if (q.releaseId)
+            fields.push({ column: 'releaseId', value: Number.parseInt(q.releaseId, 10) });
+        const body = this.searchBody(fields);
+        const raw = await this.http.postJson('/pm/sprint/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'sprints');
+        return withTotal(rows.map(toSprintSummary), raw);
+    }
+    /** POST /pm/users/search — the customer's users (router mounted at `/pm/users`, plural — see
+     *  project-management/express-app.js:181). Backend auto-scopes non-admin callers to users in
+     *  their assigned projects. Optional `projectId` narrows to that project's members; optional
+     *  `search` is a case-insensitive regex over `name`. */
+    async listUsers(q) {
+        const fields = [
+            { column: 'deleted', value: false },
+        ];
+        if (q.search)
+            fields.push({ column: 'name', value: q.search, regEx: true });
+        if (q.projectId)
+            fields.push({ column: 'projectIds', value: Number.parseInt(q.projectId, 10) });
+        const body = this.searchBody(fields, {
+            startIndex: q.offset ?? 0,
+            limit: q.limit ?? 100,
+            selectFields: ['id', 'name', 'email', 'username', 'status'],
+        });
+        const raw = await this.http.postJson('/pm/users/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'users');
+        const users = rows.map((n) => {
+            const name = str(n, 'name');
+            const email = str(n, 'email');
+            const username = str(n, 'username');
+            const status = str(n, 'status');
+            return {
+                id: str(n, 'id', '_id', 'userId') ?? '',
+                ...(name ? { name } : {}),
+                ...(email ? { email } : {}),
+                ...(username ? { username } : {}),
+                ...(status ? { status } : {}),
+            };
+        });
+        return withTotal(users, raw);
+    }
+    // ---------------------------------------------------------------------- Objects (read)
+    async getObject(id) {
+        const raw = await this.http.getJson(`/tm/object/${numericId(id)}`);
+        let doc = raw?.data ?? raw;
+        if (Array.isArray(doc))
+            doc = doc.length > 0 ? doc[0] : {};
+        return toObject(doc && typeof doc === 'object' ? doc : {});
+    }
+    // ---------------------------------------------------------------------- Deep links
+    productUrlFor(entity) {
+        const base = (this.cfg.baseUrl ?? '').replace(/\/+$/, '');
+        return `${base}/${PROJECT_URL_SEGMENT[entity.kind]}/${entity.id}`;
+    }
+    // ---------------------------------------------------------------------- Agent hop (recording + not-yet-ported ops)
+    // Everything below either delegates to the local agent /mcp (recording surface, and writes/testdata/
+    // run dispatch we haven't ported to REST yet) or fails with a clear message when the hop is unset.
+    // As each step of the port lands, the corresponding delegate is replaced with a direct REST impl.
+    hop() {
+        if (!this.cfg.url)
+            return null;
+        if (!this.agentHop)
+            this.agentHop = new RemoteMcpAdapter(this.cfg);
+        return this.agentHop;
+    }
+    requireHop(op) {
+        const h = this.hop();
+        if (!h)
+            throw new Error(`${op}: ${HOP_NEEDED_WRITE}`);
+        return h;
+    }
+    /** Recording tool schemas from the SQA agent — mirrored so the recording passthrough can register
+     *  them. No agent configured → `[]`, so no recording tools get registered. */
+    async listAgentTools() {
+        const h = this.hop();
+        return h ? h.listAgentTools() : [];
+    }
+    /** Forward a recording-tool call to the agent /mcp. Same behavior as walnut. */
+    async callRaw(name, args) {
+        const h = this.hop();
+        if (!h) {
+            throw new Error("Recording needs a local SimplifyQA agent — set QA_MCP_URL to the agent's /mcp endpoint.");
+        }
+        return h.callRaw(name, args);
+    }
+    // ---------------------------------------------------------------------- Test cases (write)  [Step 4]
+    /** Two-step create: (1) resolve every `${name}` token in the steps to a project-scoped parameter id
+     *  (get-or-create) plus, for AUTOMATION, each step's actionId + objectId, (2) POST /tm/testcase
+     *  multipart with the assembled `testcaseObj`. */
+    async createTestCase(tc) {
+        const projectId = this.requireProjectId();
+        const moduleId = Number.parseInt(String(tc.folderOrModule ?? '0'), 10) || 0;
+        const userstoryId = tc.storyRef ? await this.resolveStoryNumericIdOrNull(tc.storyRef) : undefined;
+        const paramIdByName = await this.resolveParamIds(projectId, moduleId, tc);
+        const stepResolutions = tc.category === 'automated'
+            ? await this.resolveAutomationSteps(projectId, moduleId, tc)
+            : undefined;
+        const payload = buildTestcasePayload({
+            projectId, moduleId,
+            ...(userstoryId != null ? { userstoryId } : {}),
+            tc,
+            paramIdByName,
+            ...(stepResolutions ? { stepResolutions } : {}),
+        });
+        const raw = await this.http.postMultipart('/tm/testcase', 'testcaseObj', payload);
+        return toSavedRef(raw, true);
+    }
+    /** Same shape as create, but with `tcfnObj.id` set. */
+    async updateTestCase(id, tc) {
+        const projectId = this.requireProjectId();
+        const moduleId = Number.parseInt(String(tc.folderOrModule ?? '0'), 10) || 0;
+        const userstoryId = tc.storyRef ? await this.resolveStoryNumericIdOrNull(tc.storyRef) : undefined;
+        const paramIdByName = await this.resolveParamIds(projectId, moduleId, tc);
+        const stepResolutions = tc.category === 'automated'
+            ? await this.resolveAutomationSteps(projectId, moduleId, tc)
+            : undefined;
+        const payload = buildTestcasePayload({
+            projectId, moduleId,
+            ...(userstoryId != null ? { userstoryId } : {}),
+            existingId: numericId(id),
+            tc,
+            paramIdByName,
+            ...(stepResolutions ? { stepResolutions } : {}),
+        });
+        // `!` — putMultipart is optional on QaHttp (walnut's wrapper opts out); makeClient always provides it.
+        const raw = await this.http.putMultipart('/tm/testcase', 'testcaseObj', payload);
+        return toSavedRef(raw, false);
+    }
+    /** Snapshot the CURRENT server state of a testcase under a NEW version name — same TC id,
+     *  new `tcfn_version` row with cloned steps. Backed by `PUT /tm/testcase` with
+     *  `operation:"SAVENEWVERSION"` (see tcfn.service.js:115/242/355 for the branches). The steps
+     *  we fetch from the collection are re-POSTed with their `id` stripped so the backend inserts
+     *  fresh rows attached to the new version. When `tdCopy` is true, the source version's
+     *  testdata iterations are cloned across environments via `verData.selVersionId`.
+     *
+     *  Not a mapper roundtrip: we resend the raw tcfnObj/steps we just fetched, so any fields the
+     *  neutral `TestCase` type doesn't carry (custom fields, mailers, exec platform, ...) are
+     *  preserved verbatim — the point of a version is "freeze what's there now". */
+    async saveAsNewVersion(id, opts) {
+        assertBusinessKeyKind(id, 'TC');
+        const projectId = this.requireProjectId();
+        const versionName = opts.versionName?.trim();
+        if (!versionName)
+            throw new Error('versionName is required.');
+        const rawTc = await this.fetchRawTestcase(id);
+        if (!rawTc || Object.keys(rawTc).length === 0) {
+            throw new Error(`test case ${id} not found`);
+        }
+        // Resolve source version: caller override → current versionId on the TC → versionsDetails.id
+        // → first entry in versions[]. Falls through to '' (empty) if none — backend then skips tdCopy.
+        let sourceVersionId = opts.sourceVersionId;
+        if (!sourceVersionId) {
+            sourceVersionId = str(rawTc, 'versionId', 'selectedVersionId', 'selVersion');
+            if (!sourceVersionId && rawTc?.versionsDetails && typeof rawTc.versionsDetails === 'object') {
+                sourceVersionId = str(rawTc.versionsDetails, 'id', '_id', 'versionId');
+            }
+            if (!sourceVersionId && Array.isArray(rawTc?.versions) && rawTc.versions.length > 0) {
+                sourceVersionId = str(rawTc.versions[0], 'id', '_id');
+            }
+        }
+        const rawSteps = await this.fetchStepsCollection(id, rawTc);
+        const automationSteps = [];
+        const manualSteps = [];
+        for (const s of rawSteps) {
+            // Project down to the step joi allow-list (testcaseValidator.js:244-306 + :307-367). Backend
+            // re-assigns id/versionId/parentId under the new version row, so drop those regardless.
+            const step = pick(s, STEP_ALLOWED_KEYS);
+            const et = typeof step['executionType'] === 'string' ? String(step['executionType']).toUpperCase() : '';
+            if (et === 'MANUAL')
+                manualSteps.push(step);
+            else
+                automationSteps.push(step);
+        }
+        // Project down to the tcfnObj joi allow-list (testcaseValidator.js:189-227). Anything else on
+        // the raw doc (code, createdBy, updatedBy, stepCount, etc.) trips "is not allowed".
+        const tcfnObj = pick(rawTc, TCFNOBJ_ALLOWED_KEYS);
+        tcfnObj['deleted'] = false;
+        tcfnObj['projectId'] = typeof tcfnObj['projectId'] === 'number' ? tcfnObj['projectId'] : projectId;
+        // Required-but-boolean fields on the update schema. Coerce so the presence is guaranteed.
+        if (typeof tcfnObj['obsolete'] !== 'boolean')
+            tcfnObj['obsolete'] = false;
+        // Version stub: empty `id` tells the backend to create a fresh row. SYNCOFF normalised to
+        // '' matches the FE (testcase.component.ts:1399) — it's a client-side "don't inherit"
+        // marker, not a server value.
+        const prevSync = rawTc?.versionsDetails && typeof rawTc.versionsDetails === 'object'
+            ? str(rawTc.versionsDetails, 'syncONOFF')
+            : undefined;
+        const versionsDetails = {
+            name: versionName,
+            id: '',
+            syncONOFF: prevSync === 'SYNCOFF' ? '' : (prevSync ?? ''),
+            deleted: false,
+            executionType: str(rawTc, 'executionType') ?? 'AUTOMATION',
+            functionProjectIds: [projectId],
+            reviewApproveStatus: '',
+        };
+        const verData = {
+            tdCopy: !!opts.tdCopy,
+            ...(sourceVersionId ? { selVersionId: sourceVersionId } : {}),
+        };
+        const payload = {
+            tcfnObj,
+            steps: { automationSteps, manualSteps },
+            versionsDetails,
+            operation: 'SAVENEWVERSION',
+            type: 'TC',
+            verData,
+        };
+        const raw = await this.http.putMultipart('/tm/testcase', 'testcaseObj', payload);
+        const flat = raw?.data ?? raw ?? {};
+        const savedId = str(flat, 'id', '_id', 'testcaseId') ?? numericId(id);
+        const newVersionId = str(flat, 'versionId') ??
+            (flat?.versionsDetails && typeof flat.versionsDetails === 'object'
+                ? str(flat.versionsDetails, 'id')
+                : undefined);
+        return {
+            id: savedId,
+            created: false,
+            productUrl: this.productUrlFor({ kind: 'testcase', id: savedId }),
+            ...(newVersionId ? { artifacts: [`versionId=${newVersionId}`] } : {}),
+        };
+    }
+    /** STEPSTOFN — mirrors the FE "Save as function" flow (create-new-fn-modal.component.ts:88-197):
+     *  pick a subset of the TC's steps, retype to FN, POST /tm/function multipart with the
+     *  `functionObj` payload. Backend re-assigns step ids/versionId under the newly created FN version.
+     *
+     *  ponytail: file attachments (STEP_ATTACMENTS / STEP_COMAPAREFILES multipart entries) are NOT
+     *  forwarded — MCP callers don't ship blobs. Add if a real caller needs them.
+     *  ponytail: sub-step flattening (FE lines 124-127) is skipped — `/tm/testcase/steps` returns
+     *  flat top-level rows; nested FN expansions aren't in that read. Handle if that changes. */
+    async saveStepsAsFunction(tcId, opts) {
+        const projectId = this.requireProjectId();
+        const name = opts.name?.trim();
+        if (!name)
+            throw new Error('name is required.');
+        if (!opts.moduleId)
+            throw new Error('moduleId is required.');
+        const seqSet = new Set(opts.stepSeqs);
+        if (seqSet.size === 0)
+            throw new Error('stepSeqs is required.');
+        const rawTc = await this.fetchRawTestcase(tcId);
+        if (!rawTc || Object.keys(rawTc).length === 0) {
+            throw new Error(`test case ${tcId} not found`);
+        }
+        const sourceVersionId = str(rawTc, 'versionId', 'selectedVersionId') ??
+            (rawTc?.versionsDetails && typeof rawTc.versionsDetails === 'object'
+                ? str(rawTc.versionsDetails, 'id', '_id', 'versionId')
+                : undefined) ??
+            (Array.isArray(rawTc?.versions) && rawTc.versions.length > 0
+                ? str(rawTc.versions[0], 'id', '_id')
+                : undefined);
+        const rawSteps = await this.fetchStepsCollection(tcId, rawTc);
+        const picked = rawSteps
+            .filter((s) => seqSet.has(Number(s.seq)))
+            .sort((a, b) => Number(a.seq) - Number(b.seq));
+        if (picked.length === 0) {
+            throw new Error(`no steps on ${tcId} match stepSeqs [${opts.stepSeqs.join(',')}]`);
+        }
+        const automationSteps = [];
+        const manualSteps = [];
+        let newSeq = 0;
+        for (const s of picked) {
+            const step = { ...s };
+            // Server-assigned refs stripped so backend re-creates them under the new FN version.
+            delete step.id;
+            delete step._id;
+            delete step.versionId;
+            delete step.parentId;
+            delete step.subSteps;
+            delete step.deleted;
+            delete step.isFunctionEdit;
+            delete step.sharedFNsteps;
+            delete step.sharedFnProjectId;
+            step.type = 'FN';
+            step.moduleId = opts.moduleId;
+            step.seq = ++newSeq;
+            // FE mirror (line 129-134): TM only accepts numeric parameterIds.
+            if (Array.isArray(step.parameterIds)) {
+                step.parameterIds = step.parameterIds.filter((p) => typeof p === 'number');
+            }
+            // FE mirror (line 136-150): shed conditional-step UI expansion.
+            if (step.conditions?.children?.length) {
+                for (const c of step.conditions.children) {
+                    delete c.groupedActions;
+                    delete c.stepActions;
+                    delete c.objectOfparameters;
+                    if (Array.isArray(c.parameterIds)) {
+                        c.parameterIds = c.parameterIds.filter((p) => typeof p === 'number');
+                    }
+                }
+            }
+            const forced = opts.executionType;
+            const bucket = forced
+                ?? (String(step.executionType ?? '').toUpperCase() === 'MANUAL' ? 'MANUAL' : 'AUTOMATION');
+            if (bucket === 'MANUAL')
+                manualSteps.push(step);
+            else
+                automationSteps.push(step);
+        }
+        // FE mirror (line 192): DUO iff both buckets populated.
+        const execType = automationSteps.length && manualSteps.length
+            ? 'DUO'
+            : manualSteps.length ? 'MANUAL' : 'AUTOMATION';
+        // FE mirror (line 271-276): all steps share technologyType → use that, else fall back to TC's.
+        const techs = new Set(picked.map((s) => str(s, 'technologyType')).filter(Boolean));
+        const fnType = techs.size === 1
+            ? [...techs][0]
+            : (str(rawTc, 'tcType') ?? 'WEB');
+        const tcfnObj = {
+            name,
+            projectId,
+            moduleId: opts.moduleId,
+            executionType: execType,
+            fnType,
+            reviewApproveStatus: '',
+        };
+        // FE default (function.model.ts:68) — backend requires versionsDetails.name.
+        const versionsDetails = { name: 'v1.0', id: '', syncONOFF: '' };
+        // testcaseId MUST be numeric here — tcfn.service.js:1124 uses it in a Mongo query
+        // against `testdata_iteration.testcaseId` (stored as a Number). A string "42" won't
+        // match `42`, so tdCopy silently returns zero source iterations. FE sends a number
+        // (create-new-fn-modal.component.ts:31 `@Input('tcfnId') _tcfnId: number`).
+        const verData = {
+            tdCopy: !!opts.copyTestData,
+            testcaseId: Number.parseInt(numericId(tcId), 10),
+            fromParent: 'TC',
+            ...(sourceVersionId ? { selVersionId: sourceVersionId } : {}),
+        };
+        const payload = {
+            tcfnObj,
+            steps: { automationSteps, manualSteps },
+            versionsDetails,
+            operation: 'STEPSTOFN',
+            type: 'FN',
+            verData,
+        };
+        const raw = await this.http.postMultipart('/tm/function', 'functionObj', payload);
+        return toSavedRef(raw, true);
+    }
+    /** Look up the freshly-created FN's version id — STEPSTOFN's response inlines the FN but not its
+     *  version, and the replace-in-TC step needs `fnVersionId`. Mirrors the FE
+     *  (`create-new-fn-modal.component.ts:getFnVersion`): search `tcfnversion` by parentType=FN
+     *  ordered by createdAt asc, take the first. */
+    async fetchFnVersionId(fnId) {
+        const projectId = this.requireProjectId();
+        const body = {
+            searchFields: [
+                { column: 'createdAt', sort: 'asc' },
+                { column: 'deleted', value: false, regEx: false },
+                { column: 'projectId', value: projectId, regEx: false },
+                { column: 'parentType', value: 'FN', regEx: false },
+                { column: 'parentId', value: Number.parseInt(numericId(fnId), 10), regEx: false },
+            ],
+            startIndex: 0,
+            limit: 10000,
+        };
+        const raw = await this.http.postJson('/tm/tcfnversion/search', body);
+        const rows = pickArray(raw, 'data', 'content');
+        const versionId = rows.length > 0 ? str(rows[0], 'id', '_id') : undefined;
+        if (!versionId)
+            throw new Error(`could not resolve fnVersionId for function ${fnId}`);
+        return versionId;
+    }
+    /** Second half of extract-to-function-and-replace-in-source (FE
+     *  `testcase.component.ts:createNewFns → onSave`): after the FN exists, PUT the source TC with the
+     *  extracted step rows marked `deleted:true` and a synthetic FUNCTION + FUNCTION_END pair inserted
+     *  at the first extracted position. The backend automatically:
+     *   - drops testdata columns for params only the deleted steps referenced (allParameters skips
+     *     `step.deleted:true` at tcfn.service.js:411)
+     *   - injects a per-env FN cell into every TC iteration row using the FN's default iteration
+     *     (tcfn.service.js:1032-1085) — so testdata rewiring is free.
+     *
+     *  ponytail: refuses DUO / SYNCON test cases and picks that span control-flow or nested FN
+     *  brackets. Those cases (v2) need parallel mirroring into the other execution-type array and
+     *  bracket-aware validation — out of scope for the first pass. */
+    async replaceStepsWithFunctionCall(tcId, opts) {
+        const projectId = this.requireProjectId();
+        const seqSet = new Set(opts.extractedSeqs);
+        if (seqSet.size === 0)
+            throw new Error('extractedSeqs is required.');
+        const sortedSeqs = [...seqSet].sort((a, b) => a - b);
+        // FE `checkStepsContinueOrNot`: picks must be a contiguous seq range or the resulting FN would
+        // be non-executable and the TC layout would fracture.
+        for (let i = 1; i < sortedSeqs.length; i++) {
+            if (sortedSeqs[i] !== sortedSeqs[i - 1] + 1) {
+                throw new Error(`extractedSeqs must be contiguous — got [${sortedSeqs.join(',')}]`);
+            }
+        }
+        const rawTc = await this.fetchRawTestcase(tcId);
+        if (!rawTc || Object.keys(rawTc).length === 0)
+            throw new Error(`test case ${tcId} not found`);
+        const execType = String(str(rawTc, 'executionType') ?? '').toUpperCase();
+        if (execType === 'DUO') {
+            throw new Error('DUO test cases are not yet supported for replaceInSource — split the extraction into AUTOMATION-only or MANUAL-only first.');
+        }
+        const versionsDetailsRaw = rawTc?.versionsDetails && typeof rawTc.versionsDetails === 'object' ? rawTc.versionsDetails : {};
+        const syncOnOff = str(versionsDetailsRaw, 'syncONOFF');
+        if (syncOnOff === 'SYNCON') {
+            throw new Error('SYNCON (mirrored automation/manual) test cases are not yet supported for replaceInSource.');
+        }
+        const sourceVersionId = str(rawTc, 'versionId', 'selectedVersionId') ??
+            str(versionsDetailsRaw, 'id', '_id', 'versionId') ??
+            (Array.isArray(rawTc?.versions) && rawTc.versions.length > 0
+                ? str(rawTc.versions[0], 'id', '_id')
+                : undefined);
+        if (!sourceVersionId)
+            throw new Error(`test case ${tcId} has no versionId — cannot save`);
+        const rawSteps = await this.fetchStepsCollection(tcId, rawTc);
+        // Refuse picks that would break brackets. FUNCTION/FUNCTION_END pairs must not be half-picked;
+        // control-flow starts (IF/WHILE_START/FOR_START/…) must not span the range partially.
+        const CONTROL_TYPES = new Set([
+            'FUNCTION', 'FUNCTION_END', 'IF', 'ELSE_IF', 'ELSE', 'IF_END',
+            'FOR_START', 'FOR_END', 'WHILE_START', 'WHILE_END', 'DO', 'DO_WHILE_END',
+            'ITERATOR_START', 'ITERATOR_END', 'LOOP_ITERATION_START', 'LOOP_ITERATION_END',
+        ]);
+        for (const s of rawSteps) {
+            if (!seqSet.has(Number(s.seq)))
+                continue;
+            const t = String(s.stepType ?? '').toUpperCase();
+            if (CONTROL_TYPES.has(t)) {
+                throw new Error(`step seq ${s.seq} is a control-flow/FN bracket step (${t}) — extract a plain step range`);
+            }
+        }
+        const insertAt = sortedSeqs[0];
+        // Build the FUNCTION + FUNCTION_END pair. FE parent (testcase.component.ts:1953+1988-1994)
+        // overrides `type` from 'FN' to 'TC' before splicing — the FN-call lives inside a TC, so it's
+        // typed accordingly. `id`/`versionId` omitted so backend creates fresh rows.
+        const stepLevelActions = {
+            skip: false, captureScreenshot: false, continueOnFailure: false, skippedReport: false,
+        };
+        const fnCallStep = {
+            seq: insertAt,
+            stepType: 'FUNCTION',
+            type: 'TC',
+            functionId: Number.parseInt(numericId(opts.functionId), 10),
+            fnVersionId: opts.fnVersionId,
+            description: '',
+            projectId,
+            moduleId: opts.fnModuleId,
+            executionType: execType || 'AUTOMATION',
+            technologyType: opts.technologyType,
+            stepLevelActions,
+        };
+        const fnEndStep = {
+            seq: insertAt + 1,
+            stepType: 'FUNCTION_END',
+            type: 'TC',
+            projectId,
+            moduleId: opts.fnModuleId,
+            executionType: execType || 'AUTOMATION',
+            technologyType: opts.technologyType,
+            stepLevelActions,
+        };
+        // Kept steps: preserve id/versionId/parentId (this is an update, not a fresh save) and pass
+        // through as-is. Extracted steps: same, plus `deleted:true` — the backend's param collector
+        // (tcfn.service.js:411) skips deleted rows, so their paramIds automatically drop from the TC's
+        // rebuilt testdata columns. Do NOT strip parameterIds / objectParameterIds / parameterizedParamIds
+        // from the deleted rows — those are what `allParameters` compares against to know what to prune.
+        const kept = [];
+        const deleted = [];
+        for (const s of rawSteps) {
+            const step = { ...s };
+            delete step.subSteps; // transient — flat-only per the STEPSTOFN comment
+            if (seqSet.has(Number(step.seq))) {
+                step.deleted = true;
+                delete step.objectOfparameters; // FE mirror (testcase.component.ts:1272)
+                deleted.push(step);
+            }
+            else {
+                kept.push(step);
+            }
+        }
+        kept.sort((a, b) => Number(a.seq) - Number(b.seq));
+        // Splice fn-call pair at the insert position. seqs 1..N are re-assigned at the end so nothing
+        // downstream can misalign.
+        const afterInsert = kept.filter((k) => Number(k.seq) > sortedSeqs[sortedSeqs.length - 1]);
+        const beforeInsert = kept.filter((k) => Number(k.seq) < insertAt);
+        const orderedLive = [...beforeInsert, fnCallStep, fnEndStep, ...afterInsert];
+        let seq = 1;
+        for (const s of orderedLive) {
+            s.seq = seq++;
+        }
+        // Backend expects both automationSteps and manualSteps buckets. Live steps route by their
+        // executionType; deleted steps come along in their own bucket (FE mirror lines 1268-1284).
+        const automationSteps = [];
+        const manualSteps = [];
+        const bucketFor = (s) => {
+            const et = String(s?.executionType ?? '').toUpperCase();
+            return et === 'MANUAL' ? 'MANUAL' : 'AUTOMATION';
+        };
+        for (const s of orderedLive)
+            (bucketFor(s) === 'MANUAL' ? manualSteps : automationSteps).push(s);
+        for (const s of deleted)
+            (bucketFor(s) === 'MANUAL' ? manualSteps : automationSteps).push(s);
+        // tcfnObj: strict allow-list — extras trip the joi validator. Backend mirrors the FE's normal
+        // update PUT (testcase.component.ts:1376+1495): `operation:"TC"`, `type:"TC"`, same versionsDetails.
+        const tcfnObj = pick(rawTc, TCFNOBJ_ALLOWED_KEYS);
+        tcfnObj['deleted'] = false;
+        tcfnObj['id'] = Number.parseInt(numericId(tcId), 10);
+        tcfnObj['projectId'] = typeof tcfnObj['projectId'] === 'number' ? tcfnObj['projectId'] : projectId;
+        if (typeof tcfnObj['obsolete'] !== 'boolean')
+            tcfnObj['obsolete'] = false;
+        // Backend joi validator refuses an empty versionsDetails.name (BADREQUEST from /tm/testcase). The
+        // name isn't always inlined on the raw TC's `versionsDetails` — for TCs opened via search or
+        // certain list endpoints, only `versionsDetails.id` is present. Walk the version list to find
+        // the row whose id matches sourceVersionId and use ITS name; fall back to 'v1.0' (the SQA
+        // default set by project.service.js when a version is first created).
+        let versionName = str(versionsDetailsRaw, 'name');
+        if (!versionName && Array.isArray(rawTc?.versions)) {
+            const match = rawTc.versions.find((v) => str(v, 'id', '_id') === sourceVersionId);
+            versionName = match ? str(match, 'name') : undefined;
+        }
+        if (!versionName)
+            versionName = 'v1.0';
+        const versionsDetails = {
+            name: versionName,
+            id: sourceVersionId,
+            deleted: false,
+            syncONOFF: syncOnOff ?? '',
+            executionType: execType || 'AUTOMATION',
+            functionProjectIds: [projectId],
+            reviewApproveStatus: str(versionsDetailsRaw, 'reviewApproveStatus') ?? '',
+        };
+        const payload = {
+            tcfnObj,
+            steps: { automationSteps, manualSteps },
+            versionsDetails,
+            operation: 'TC',
+            type: 'TC',
+        };
+        const raw = await this.http.putMultipart('/tm/testcase', 'testcaseObj', payload);
+        const flat = raw?.data ?? raw ?? {};
+        const savedId = str(flat, 'id', '_id', 'testcaseId') ?? numericId(tcId);
+        return {
+            id: savedId,
+            created: false,
+            productUrl: this.productUrlFor({ kind: 'testcase', id: savedId }),
+        };
+    }
+    /** One-shot extract-to-function-and-replace. Chains STEPSTOFN → fetch fn version id → replace in
+     *  source TC. If step 2 or 3 fails after step 1 succeeded, the caller sees the fn id in the error
+     *  so they can retry or clean up the phantom function. */
+    async extractStepsAsFunctionAndReplace(tcId, opts) {
+        const fnRef = await this.saveStepsAsFunction(tcId, opts);
+        let fnVersionId;
+        try {
+            fnVersionId = await this.fetchFnVersionId(fnRef.id);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new Error(`Function ${fnRef.id} was created but its version lookup failed — the source TC was NOT modified. ${msg}`);
+        }
+        // Reuse tech detection from saveStepsAsFunction (same rule: single tech across picks → that
+        // tech, else fall back to the source TC's tcType).
+        const rawTc = await this.fetchRawTestcase(tcId);
+        const rawSteps = await this.fetchStepsCollection(tcId, rawTc);
+        const picked = rawSteps.filter((s) => opts.stepSeqs.includes(Number(s.seq)));
+        const techs = new Set(picked.map((s) => str(s, 'technologyType')).filter(Boolean));
+        const technologyType = techs.size === 1 ? [...techs][0] : (str(rawTc, 'tcType') ?? 'WEB');
+        try {
+            const tcRef = await this.replaceStepsWithFunctionCall(tcId, {
+                extractedSeqs: opts.stepSeqs,
+                functionId: fnRef.id,
+                fnVersionId,
+                fnModuleId: opts.moduleId,
+                technologyType,
+            });
+            return { ...tcRef, fnId: fnRef.id, fnVersionId };
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new Error(`Function ${fnRef.id} (version ${fnVersionId}) was created but replacing steps in ${tcId} failed — clean up the function or retry with tc_replace_steps_with_function. ${msg}`);
+        }
+    }
+    /** Soft-delete. `/tm/testcase/delete` returns HTTP 200 either way — its `data` is `true` on real
+     *  delete, or an array of dependency records when the TC is still referenced by a defect, suite,
+     *  execution plan, scenario, workflow, pipeline, or scheduler (nothing was deleted). Inspect the
+     *  shape and throw so the tool surfaces it as a failure instead of a fake success. */
+    async deleteTestCase(id) {
+        const projectId = this.requireProjectId();
+        const raw = await this.http.postJson('/tm/testcase/delete', {
+            ids: [Number.parseInt(numericId(id), 10)],
+            projectId,
+            isDelete: true,
+        });
+        const data = raw?.data;
+        if (data === true)
+            return;
+        const deps = Array.isArray(data) ? data[0] : undefined;
+        const list = (m) => m && typeof m === 'object' ? Object.values(m).flat().map(String) : [];
+        const refs = [];
+        const groups = [
+            ['defectArr', 'defects'], ['suiteArr', 'suites'], ['epArr', 'execution plans'],
+            ['scenarioArr', 'scenarios'], ['wfArr', 'workflows'], ['pipelineArr', 'pipelines'],
+            ['schedulerArr', 'schedulers'],
+        ];
+        for (const [key, label] of groups) {
+            const ids = list(deps?.[key]);
+            if (ids.length)
+                refs.push(`${label} (${ids.join(', ')})`);
+        }
+        throw new Error(refs.length
+            ? `Not deleted — test case is still referenced by ${refs.join('; ')}. Remove those references first.`
+            : 'Not deleted — the backend reported blocking dependencies.');
+    }
+    /** Clone a testcase in place (same project + module) with all steps, versions, testdata,
+     *  parameters, object refs, and nested function calls carried over. Backed by the SQA native
+     *  `/tm/tcfnCopy/copytc` endpoint (see test-management/src/controllers/tcfnCopy.controller.js).
+     *
+     *  Requires the `copy_testcase_across_project` privilege on the current project — enforced
+     *  server-side regardless of whether the copy is in-project or across projects.
+     *
+     *  When `newTitle` is omitted the backend auto-names the copy as `{sourceName}_copy1`,
+     *  `_copy2`, etc. When provided, a follow-up PUT renames the freshly-created TC to that name.
+     *
+     *  IMPORTANT — the copy endpoint's `selversions` and `selectedEnv` fields are FILTERS, not
+     *  wildcards. Passing empty arrays makes the backend copy the TC shell only (no steps, no
+     *  testdata, since both live under versions and per-env iterations). So we fetch the source
+     *  TC's version names AND the project's environment names first and pass them explicitly. */
+    async cloneTestCase(id, newTitle, versions) {
+        assertBusinessKeyKind(id, 'TC');
+        const projectId = this.requireProjectId();
+        const src = await this.fetchRawTestcase(id);
+        if (!src || Object.keys(src).length === 0)
+            throw new Error(`test case ${id} not found`);
+        const sourceId = Number.parseInt(numericId(id), 10);
+        const sourceProjId = typeof src.projectId === 'number' ? src.projectId : projectId;
+        const sourceModuleId = typeof src.moduleId === 'number' ? src.moduleId : 0;
+        // Fetch source's version names — required, empty means no versions get copied.
+        const versionsRaw = await this.http.getJson(`/tm/testcase/version/${sourceId}/${sourceProjId}`);
+        const versionsArr = Array.isArray(versionsRaw) ? versionsRaw : (versionsRaw?.data ?? []);
+        const availableNames = versionsArr
+            .map((v) => str(v, 'name'))
+            .filter((n) => !!n);
+        if (availableNames.length === 0) {
+            throw new Error(`Cannot clone ${id}: source has no versions to copy.`);
+        }
+        const versionNames = filterVersionNames(availableNames, versions, id);
+        // Fetch project's environment names — empty means per-env testdata rows are dropped
+        // (only the "general" fallback iteration survives).
+        const envsRaw = await this.http.getJson(`/pm/fields/8?projectId=${sourceProjId}&fieldType=environment`);
+        const envsArr = Array.isArray(envsRaw) ? envsRaw : (envsRaw?.data ?? []);
+        const envNames = envsArr
+            .map((e) => str(e, 'name'))
+            .filter((n) => !!n);
+        await this.http.postJson('/tm/tcfnCopy/copytc', {
+            type: 'TC',
+            tcfnList: [{ id: sourceId, selversions: versionNames }],
+            sourceProjId,
+            sourceModuleId,
+            destinationProjId: sourceProjId,
+            destinationModuleId: sourceModuleId,
+            selectedEnv: envNames,
+        });
+        // Find the newly-created copy: highest-id TC whose `projectLevelcopiedFrom.id` matches. Not
+        // going through `searchBody` because the SQA search protocol lets a searchField have EITHER a
+        // `value` (filter) OR a `sort` (ordering) — the helper only builds value entries.
+        const searchRaw = await this.http.postJson('/tm/testcase/search', {
+            searchFields: [
+                { column: 'deleted', value: false },
+                { column: 'projectId', value: sourceProjId },
+                { column: 'projectLevelcopiedFrom.id', value: sourceId },
+                { column: 'id', sort: 'dsc' },
+            ],
+            startIndex: 0,
+            limit: 1,
+            selectFields: ['id', 'code', 'name'],
+        });
+        const rows = pickArray(searchRaw, 'data', 'content', 'testCases');
+        if (rows.length === 0) {
+            throw new Error('Clone was requested but the newly-created testcase could not be located afterwards. ' +
+                'The backend may still be processing the copy, or the caller may lack the ' +
+                '`copy_testcase_across_project` privilege on this project.');
+        }
+        const created = rows[0];
+        const newIdNum = Number.parseInt(str(created, 'id', '_id') ?? '', 10);
+        // Optional rename: PUT /tm/testcase/:id with { name, projectId }.
+        if (newTitle && newTitle.trim() && Number.isFinite(newIdNum)) {
+            await this.http.putJson(`/tm/testcase/${newIdNum}`, {
+                name: newTitle.trim(),
+                projectId: sourceProjId,
+            });
+            created.name = newTitle.trim();
+        }
+        return {
+            id: String(newIdNum),
+            created: true,
+            productUrl: this.productUrlFor({ kind: 'testcase', id: String(newIdNum) }),
+        };
+    }
+    // ---------------------------------------------------------------------- Functions (reusable)
+    // Same tcfnObj collection as testcases — type='FN' instead of 'TC'. Search / getById / delete /
+    // steps all mirror the testcase endpoints one-to-one.
+    async listFunctions(q) {
+        const projectId = this.requireProjectId();
+        const fields = [
+            { column: 'deleted', value: false },
+            { column: 'projectId', value: projectId },
+        ];
+        if (q.search)
+            fields.push({ column: 'name', value: q.search, regEx: true });
+        if (q.fnType)
+            fields.push({ column: 'fnType', value: q.fnType });
+        if (q.executionType)
+            fields.push({ column: 'executionType', value: q.executionType });
+        if (q.moduleId)
+            fields.push({ column: 'moduleId', value: Number.parseInt(numericId(q.moduleId), 10) });
+        const createdBy = this.resolveUserFilter(q.createdBy);
+        if (createdBy != null)
+            fields.push({ column: 'createdBy', value: createdBy });
+        const updatedBy = this.resolveUserFilter(q.updatedBy);
+        if (updatedBy != null)
+            fields.push({ column: 'updatedBy', value: updatedBy });
+        const body = this.searchBody(fields, {
+            startIndex: q.offset ?? 0,
+            limit: q.limit ?? 100,
+            selectFields: ['id', 'code', 'name', 'description', 'fnType', 'executionType',
+                'reviewApproveStatus', 'stepCount'],
+        });
+        const raw = await this.http.postJson('/tm/function/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'functions');
+        return withTotal(rows.map(toFunctionSummary), raw);
+    }
+    async getFunction(id) {
+        const projectId = this.requireProjectId();
+        const fnNum = numericId(id);
+        const raw = await this.http.getJson(`/tm/function/${fnNum}/${projectId}`);
+        let doc = raw?.data ?? raw;
+        if (Array.isArray(doc))
+            doc = doc.length > 0 ? doc[0] : {};
+        if (!doc || typeof doc !== 'object' || Object.keys(doc).length === 0) {
+            throw new Error(`function ${id} not found`);
+        }
+        const fn = toFunction(doc);
+        // Fetch version rows ONCE — reused to (a) pick the newest for the steps call and (b) hydrate
+        // `fn.versions` for the caller. The FN doc from `/tm/function/:id/:pid` has NO inline versions[]
+        // (unlike TC's getById), so this sibling endpoint is the only source. Non-fatal on failure.
+        let versionRows = [];
+        try {
+            versionRows = await this.fetchFunctionVersionRows(fnNum);
+        }
+        catch { /* leave empty */ }
+        const currentVersionId = versionRows.length
+            ? str(versionRows[0], 'id', '_id', 'versionId')
+            : undefined;
+        if (versionRows.length)
+            fn.versions = toVersionEntries(versionRows, currentVersionId);
+        if (currentVersionId) {
+            try {
+                const rows = await this.fetchFunctionStepsForVersion(fnNum, currentVersionId);
+                if (rows.length > 0)
+                    fn.steps = rows.map((s, i) => fromSqaStep(s, i + 1));
+            }
+            catch { /* leave steps empty */ }
+        }
+        return fn;
+    }
+    /** Steps for one FN version. Unlike TC docs, the FN doc from `/tm/function/:id/:projectId`
+     *  doesn't carry a versionId inline — callers resolve the target versionId (usually the newest,
+     *  from `fetchFunctionVersionRows`) and pass it here. */
+    async fetchFunctionStepsForVersion(fnNum, versionId) {
+        const projectId = this.requireProjectId();
+        const path = '/tm/function/steps' +
+            `?projectId=${projectId}` +
+            `&tcfnId=${fnNum}` +
+            `&versionId=${encodeURIComponent(versionId)}` +
+            '&type=FN';
+        const body = await this.http.getJson(path);
+        return Array.isArray(body) ? body : Array.isArray(body?.data) ? body.data : [];
+    }
+    /** The function's version rows, newest-first. */
+    async fetchFunctionVersionRows(fnNum) {
+        const projectId = this.requireProjectId();
+        const raw = await this.http.getJson(`/tm/function/version/${fnNum}/${projectId}`);
+        const rows = pickArray(raw, 'data', 'content', 'versions');
+        if (!rows.length)
+            return [];
+        return [...rows].sort((a, b) => Number(b?.versionNumber ?? 0) - Number(a?.versionNumber ?? 0));
+    }
+    /** Soft-delete a function. `/tm/function/delete` returns HTTP 200 either way — its `data` is
+     *  `true` on real delete, or an array of dependency records when the FN is still referenced by a
+     *  TC / FN / workflow (nothing was deleted). Inspect the shape and throw so the tool surfaces it
+     *  as a failure instead of a fake success. */
+    async deleteFunction(id) {
+        const projectId = this.requireProjectId();
+        const raw = await this.http.postJson('/tm/function/delete', {
+            ids: [Number.parseInt(numericId(id), 10)],
+            projectId,
+            isDelete: true,
+        });
+        const data = raw?.data;
+        if (data === true)
+            return;
+        const deps = Array.isArray(data) ? data[0] : undefined;
+        const list = (m) => m && typeof m === 'object' ? Object.values(m).flat().map(String) : [];
+        const tcs = list(deps?.tcArr);
+        const fns = list(deps?.fnArr);
+        const wfs = list(deps?.wfArr);
+        const refs = [];
+        if (tcs.length)
+            refs.push(`test cases (${tcs.join(', ')})`);
+        if (fns.length)
+            refs.push(`functions (${fns.join(', ')})`);
+        if (wfs.length)
+            refs.push(`workflows (${wfs.join(', ')})`);
+        throw new Error(refs.length
+            ? `Not deleted — function is still referenced by ${refs.join('; ')}. Remove those references first.`
+            : 'Not deleted — the backend reported blocking dependencies.');
+    }
+    /** Copy a function in place — new tcfnObj row, all versions/steps/testdata carried over. Same
+     *  shape as `cloneTestCase`: version names + env names come from the source, then POST to
+     *  `/tm/tcfnCopy/copytc` with `type:'FN'` (backend enforces `copy_function_across_projects`).
+     *  When `newTitle` is omitted the backend auto-names as `{sourceName}_copy1`, etc.; when
+     *  provided a follow-up PUT `/tm/function/:id` renames the freshly-created FN. */
+    async cloneFunction(id, newTitle, versions) {
+        assertBusinessKeyKind(id, 'FN');
+        const projectId = this.requireProjectId();
+        const fnNum = numericId(id);
+        const rawFn = await this.http.getJson(`/tm/function/${fnNum}/${projectId}`);
+        let src = rawFn?.data ?? rawFn;
+        if (Array.isArray(src))
+            src = src.length > 0 ? src[0] : {};
+        if (!src || typeof src !== 'object' || Object.keys(src).length === 0) {
+            throw new Error(`function ${id} not found`);
+        }
+        const sourceId = Number.parseInt(fnNum, 10);
+        const sourceProjId = typeof src.projectId === 'number' ? src.projectId : projectId;
+        const sourceModuleId = typeof src.moduleId === 'number' ? src.moduleId : 0;
+        // Fetch source's version names — required, empty means no versions get copied.
+        const versionsRaw = await this.http.getJson(`/tm/function/version/${sourceId}/${sourceProjId}`);
+        const versionsArr = Array.isArray(versionsRaw) ? versionsRaw : (versionsRaw?.data ?? []);
+        const availableNames = versionsArr
+            .map((v) => str(v, 'name'))
+            .filter((n) => !!n);
+        if (availableNames.length === 0) {
+            throw new Error(`Cannot clone ${id}: source has no versions to copy.`);
+        }
+        const versionNames = filterVersionNames(availableNames, versions, id);
+        // Same environment fetch as cloneTestCase — empty means per-env testdata rows are dropped.
+        const envsRaw = await this.http.getJson(`/pm/fields/8?projectId=${sourceProjId}&fieldType=environment`);
+        const envsArr = Array.isArray(envsRaw) ? envsRaw : (envsRaw?.data ?? []);
+        const envNames = envsArr
+            .map((e) => str(e, 'name'))
+            .filter((n) => !!n);
+        await this.http.postJson('/tm/tcfnCopy/copytc', {
+            type: 'FN',
+            tcfnList: [{ id: sourceId, selversions: versionNames }],
+            sourceProjId,
+            sourceModuleId,
+            destinationProjId: sourceProjId,
+            destinationModuleId: sourceModuleId,
+            selectedEnv: envNames,
+        });
+        // Find the newly-created copy: highest-id FN whose `projectLevelcopiedFrom.id` matches source.
+        const searchRaw = await this.http.postJson('/tm/function/search', {
+            searchFields: [
+                { column: 'deleted', value: false },
+                { column: 'projectId', value: sourceProjId },
+                { column: 'projectLevelcopiedFrom.id', value: sourceId },
+                { column: 'id', sort: 'dsc' },
+            ],
+            startIndex: 0,
+            limit: 1,
+            selectFields: ['id', 'code', 'name'],
+        });
+        const rows = pickArray(searchRaw, 'data', 'content', 'functions');
+        if (rows.length === 0) {
+            throw new Error('Clone was requested but the newly-created function could not be located afterwards. ' +
+                'The backend may still be processing the copy, or the caller may lack the ' +
+                '`copy_function_across_projects` privilege on this project.');
+        }
+        const created = rows[0];
+        const newIdNum = Number.parseInt(str(created, 'id', '_id') ?? '', 10);
+        // Optional rename: PUT /tm/function/:id — inline validator accepts { name } only (no projectId).
+        if (newTitle && newTitle.trim() && Number.isFinite(newIdNum)) {
+            await this.http.putJson(`/tm/function/${newIdNum}`, {
+                name: newTitle.trim(),
+            });
+            created.name = newTitle.trim();
+        }
+        return {
+            id: String(newIdNum),
+            created: true,
+            productUrl: this.productUrlFor({ kind: 'function', id: String(newIdNum) }),
+        };
+    }
+    /** Snapshot the CURRENT server state of a function under a NEW version name — same FN id, new
+     *  `tcfn_version` row with cloned steps. Mirrors `saveAsNewVersion` (see there for the shape
+     *  rationale) with `type:'FN'` and the multipart route `PUT /tm/function` / key `functionObj`.
+     *  Source-version resolution goes through the FN's `/tm/function/version/:id/:pid` list — the
+     *  FN doc has no inline versionId. */
+    async saveAsNewFunctionVersion(id, opts) {
+        assertBusinessKeyKind(id, 'FN');
+        const projectId = this.requireProjectId();
+        const versionName = opts.versionName?.trim();
+        if (!versionName)
+            throw new Error('versionName is required.');
+        const fnNum = numericId(id);
+        const rawFn = await this.http.getJson(`/tm/function/${fnNum}/${projectId}`);
+        let rawTc = rawFn?.data ?? rawFn;
+        if (Array.isArray(rawTc))
+            rawTc = rawTc.length > 0 ? rawTc[0] : {};
+        if (!rawTc || typeof rawTc !== 'object' || Object.keys(rawTc).length === 0) {
+            throw new Error(`function ${id} not found`);
+        }
+        // FN doc has no inline versionId — resolve from the version list. Caller override wins.
+        let sourceVersionId = opts.sourceVersionId;
+        if (!sourceVersionId) {
+            const versionRows = await this.fetchFunctionVersionRows(fnNum);
+            if (versionRows.length > 0)
+                sourceVersionId = str(versionRows[0], 'id', '_id', 'versionId');
+        }
+        // Fetch steps under the resolved (or newest) version.
+        const rawSteps = sourceVersionId
+            ? await this.http.getJson('/tm/function/steps' +
+                `?projectId=${projectId}` +
+                `&tcfnId=${fnNum}` +
+                `&versionId=${encodeURIComponent(sourceVersionId)}` +
+                '&type=FN').then((body) => (Array.isArray(body) ? body : Array.isArray(body?.data) ? body.data : []))
+            : [];
+        const automationSteps = [];
+        const manualSteps = [];
+        for (const s of rawSteps) {
+            const step = pick(s, STEP_ALLOWED_KEYS);
+            const et = typeof step['executionType'] === 'string' ? String(step['executionType']).toUpperCase() : '';
+            if (et === 'MANUAL')
+                manualSteps.push(step);
+            else
+                automationSteps.push(step);
+        }
+        const tcfnObj = pick(rawTc, TCFNOBJ_FN_ALLOWED_KEYS);
+        tcfnObj['deleted'] = false;
+        tcfnObj['projectId'] = typeof tcfnObj['projectId'] === 'number' ? tcfnObj['projectId'] : projectId;
+        // FN update joi REQUIRES `fnType` and REJECTS `obsolete`. Guarantee fnType from the raw doc
+        // (falls through to legacy `tcType` if a pre-migration FN row is missing fnType); never set
+        // obsolete.
+        if (typeof tcfnObj['fnType'] !== 'string' || !tcfnObj['fnType']) {
+            const fallback = str(rawTc, 'fnType', 'tcType') ?? 'WEB';
+            tcfnObj['fnType'] = fallback;
+        }
+        // Version stub mirrors function.component.ts:900-907 — empty id tells the backend to create a
+        // fresh row; SYNCOFF is normalised to '' the same way as the TC path. FN update joi REJECTS
+        // `functionProjectIds` (allowed on TC's versionsDetails but not FN's — see functionValidator.js
+        // updateFnBodyValidation.versionsDetails), so don't include it.
+        const prevSync = rawTc?.versionsDetails && typeof rawTc.versionsDetails === 'object'
+            ? str(rawTc.versionsDetails, 'syncONOFF')
+            : undefined;
+        const versionsDetails = {
+            name: versionName,
+            id: '',
+            syncONOFF: prevSync === 'SYNCOFF' ? '' : (prevSync ?? ''),
+            deleted: false,
+            executionType: str(rawTc, 'executionType') ?? 'AUTOMATION',
+            reviewApproveStatus: '',
+        };
+        const verData = {
+            tdCopy: !!opts.tdCopy,
+            ...(sourceVersionId ? { selVersionId: sourceVersionId } : {}),
+        };
+        const payload = {
+            tcfnObj,
+            steps: { automationSteps, manualSteps },
+            versionsDetails,
+            operation: 'SAVENEWVERSION',
+            type: 'FN',
+            verData,
+        };
+        const raw = await this.http.putMultipart('/tm/function', 'functionObj', payload);
+        const flat = raw?.data ?? raw ?? {};
+        const savedId = str(flat, 'id', '_id', 'functionId', 'testcaseId') ?? fnNum;
+        const newVersionId = str(flat, 'versionId') ??
+            (flat?.versionsDetails && typeof flat.versionsDetails === 'object'
+                ? str(flat.versionsDetails, 'id')
+                : undefined);
+        return {
+            id: savedId,
+            created: false,
+            productUrl: this.productUrlFor({ kind: 'function', id: savedId }),
+            ...(newVersionId ? { artifacts: [`versionId=${newVersionId}`] } : {}),
+        };
+    }
+    /** Never throw on unresolvable storyRef — the Java code logs and moves on so the save still lands. */
+    async resolveStoryNumericIdOrNull(storyRef) {
+        try {
+            const s = await this.resolveStoryNumericId(storyRef);
+            const n = Number.parseInt(s, 10);
+            return Number.isFinite(n) ? n : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Resolve every param name referenced by the TC to a SQA parameter id via get-or-create.
+     *  Sources: (a) `${name}` tokens in every step's description (manual + automation), and
+     *  (b) keys of every automation step's `recordedParam` (action-argument names like
+     *  "packageName", "activity", "keys"). Name-uniqueness is project-wide on the backend, so
+     *  get-or-create means every TC using `${appUrl}` (or the same "packageName" recorded param)
+     *  links to the same parameter row. */
+    async resolveParamIds(projectId, moduleId, tc) {
+        const paramIdByName = new Map();
+        const steps = Array.isArray(tc.steps) ? tc.steps : [];
+        for (const s of steps) {
+            for (const name of extractParamNames(s.description)) {
+                if (paramIdByName.has(name))
+                    continue;
+                const defaultValue = paramDefault(name, tc.data, s.value);
+                const id = await this.getOrCreateParameter(projectId, moduleId, name, defaultValue);
+                paramIdByName.set(name, id);
+            }
+            if (s.recordedParam) {
+                for (const [name, value] of Object.entries(s.recordedParam)) {
+                    if (paramIdByName.has(name))
+                        continue;
+                    const id = await this.getOrCreateParameter(projectId, moduleId, name, String(value ?? ''));
+                    paramIdByName.set(name, id);
+                }
+            }
+        }
+        return paramIdByName;
+    }
+    actionCatalog() {
+        if (this.actionCatalogCache)
+            return this.actionCatalogCache;
+        const projectId = this.requireProjectId();
+        this.actionCatalogCache = (async () => {
+            // `projectId in [0, projectId]` — 0 is the customer-wide default catalog, projectId is the
+            // per-project overrides layered on top. Same filter the SQA UI uses (steps.model.ts:59).
+            const body = {
+                searchFields: [
+                    { column: 'deleted', value: false },
+                    { column: 'projectId', value: { $in: [0, projectId] } },
+                ],
+                startIndex: 0,
+                limit: 100000,
+                selectFields: ['id', 'name', 'technology', 'objectTemplate', 'objectRequired'],
+            };
+            const raw = await this.http.postJson('/tm/action/search', body);
+            const rows = pickArray(raw, 'data', 'content', 'actions');
+            const map = new Map();
+            for (const row of rows) {
+                const idStr = str(row, 'id', '_id', 'actionId');
+                const name = str(row, 'name');
+                const tech = str(row, 'technology');
+                if (!idStr || !name || !tech)
+                    continue;
+                const id = Number.parseInt(idStr, 10);
+                if (!Number.isFinite(id))
+                    continue;
+                const objectRequired = row?.objectRequired === true;
+                const otRaw = row?.objectTemplate;
+                const objectTemplate = typeof otRaw === 'number' ? otRaw
+                    : typeof otRaw === 'string' && /^\d+$/.test(otRaw) ? Number.parseInt(otRaw, 10)
+                        : undefined;
+                // Prefer the higher-priority project override when the same (tech, name) has both a
+                // default and a project row: last write wins if we sort defaults first. Backend returns
+                // whichever ordering; we resolve determinism by preferring a non-zero projectId row.
+                const key = `${tech.toUpperCase()}::${name.toLowerCase()}`;
+                const prev = map.get(key);
+                const isProjectOverride = typeof row?.projectId === 'number' && row.projectId !== 0;
+                if (!prev || isProjectOverride)
+                    map.set(key, { id, objectRequired, objectTemplate });
+            }
+            return map;
+        })().catch((e) => { this.actionCatalogCache = null; throw e; });
+        return this.actionCatalogCache;
+    }
+    /** POST /tm/object/createObjectSeq — get-or-create the shared object row by locator match. The
+     *  backend does the dedup (`object.controller.js:268-370`) — same-locators reuses, same-disname-
+     *  different-locators creates a suffixed one. Returns the numeric object id.
+     *
+     *  ponytail: minimum body — no thumbnail_url / pageScreenShot_url / parameterId. The recording
+     *  path enriches these; the tc_save path doesn't have screenshots to attach, and the object
+     *  works for execution without them. */
+    async resolveObjectId(objectRef, projectId, moduleId, technology, objectTemplateId) {
+        const attributes = (objectRef.locators ?? []).map((l) => ({
+            name: l.name,
+            value: l.value,
+            ...(l.unique === true ? { unique: true } : {}),
+        }));
+        const body = {
+            projectId,
+            moduleId,
+            objecttemplateId: objectTemplateId,
+            technology,
+            disname: objectRef.name ?? '',
+            attributes,
+            parameterId: [],
+            description: '',
+        };
+        const raw = await this.http.postJson('/tm/object/createObjectSeq', body);
+        const flat = raw?.data ?? raw;
+        const id = str(flat, 'id', '_id', 'objectId');
+        if (!id)
+            throw new Error(`createObjectSeq returned no id for object "${objectRef.name}": ${JSON.stringify(raw)}`);
+        return Number.parseInt(id, 10);
+    }
+    /** For every automation step, resolve `actionId` (from action name + technology) and
+     *  `objectId` (via createObjectSeq get-or-create) so the mapper can emit a valid step. Runs
+     *  once per save, aligned by step index. */
+    async resolveAutomationSteps(projectId, moduleId, tc) {
+        const catalog = await this.actionCatalog();
+        const steps = Array.isArray(tc.steps) ? tc.steps : [];
+        const out = [];
+        for (let i = 0; i < steps.length; i++) {
+            const s = steps[i];
+            const tech = (TECH_BY_STEPTYPE[s.stepType] ?? deriveTcType(tc)).toUpperCase();
+            const name = (s.actionType ?? '').trim();
+            if (!name) {
+                throw new Error(`Automation step ${i + 1} ("${s.description}"): missing actionType — the neutral Step.actionType must name an SQA action (e.g. "Click", "Type Text", "Launch Application").`);
+            }
+            const meta = catalog.get(`${tech}::${name.toLowerCase()}`);
+            if (!meta) {
+                throw new Error(`Automation step ${i + 1}: no SQA action named "${name}" for technology ${tech}. Check the action catalog in the SQA UI.`);
+            }
+            let objectId = null;
+            if (meta.objectRequired) {
+                if (!s.objectRef || !s.objectRef.name || !(s.objectRef.locators?.length)) {
+                    throw new Error(`Automation step ${i + 1} ("${name}"): action requires an object but Step.objectRef is missing name/locators. Provide objectRef:{name, locators:[{name, value}]}.`);
+                }
+                if (meta.objectTemplate == null) {
+                    throw new Error(`Automation step ${i + 1} ("${name}"): action ${meta.id} has no objectTemplate — cannot create/reuse an object without knowing which template it belongs to.`);
+                }
+                objectId = await this.resolveObjectId(s.objectRef, projectId, moduleId, tech, meta.objectTemplate);
+            }
+            out.push({ actionId: meta.id, objectId });
+        }
+        return out;
+    }
+    /** Case-insensitive project-scoped exact-name lookup. Backend duplicate-name check uses Mongo
+     *  collation strength:2, so a case-sensitive search here misses params stored under different
+     *  casing — the next POST then trips "Duplicate Name Error". Returns null when not found. */
+    async findParameterId(projectId, name) {
+        const body = this.searchBody([
+            { column: 'name', value: name },
+            { column: 'projectId', value: projectId },
+        ], { startIndex: 0, limit: 10 });
+        // The `searchFields` shape supports `ignorecase:true` per-field; searchBody doesn't emit it,
+        // so add it inline for the name column.
+        body['searchFields'][0]['ignorecase'] = true;
+        const raw = await this.http.postJson('/tm/parameter/search', body);
+        const rows = pickArray(raw, 'data', 'content');
+        for (const row of rows) {
+            const rowName = str(row, 'name');
+            if (rowName === name) {
+                const id = str(row, 'id', '_id', 'parameterId');
+                if (id)
+                    return Number.parseInt(id, 10);
+            }
+        }
+        return null;
+    }
+    async getOrCreateParameter(projectId, moduleId, name, defaultValue) {
+        const existing = await this.findParameterId(projectId, name);
+        if (existing != null)
+            return existing;
+        const body = {
+            name,
+            projectId,
+            protected: looksSensitive(name),
+            ...(moduleId > 0 ? { moduleId } : {}),
+            defaultValue,
+            // Match the SQA UI's Add-Parameter defaults so API-created params render identically. Without
+            // these the UI shows "Parameter Type*" empty and refuses to save edits.
+            type: 'Local',
+            parameterType: 'Alphanumeric',
+            description: '',
+            unique: false,
+            concat: '',
+            paramAttributes: { minLength: 0, maxLength: 0, prefix: '', suffix: '' },
+        };
+        let raw;
+        try {
+            raw = await this.http.postJson('/tm/parameter', body);
+        }
+        catch (e) {
+            // Backend rejects a race-lost duplicate with 500 "Duplicate Name" when the concurrent search
+            // missed the just-created row. Recover by re-querying — same name, project-scoped.
+            const msg = e instanceof Error ? e.message : String(e);
+            if (/Duplicate Name|BADREQUEST/i.test(msg)) {
+                const after = await this.findParameterId(projectId, name);
+                if (after != null)
+                    return after;
+            }
+            throw e;
+        }
+        // The id lives at various nesting levels depending on which path the backend took (bare doc,
+        // `data`, or `message[0]` for a race-lost duplicate). Try all three.
+        let id = str(raw, 'id', '_id', 'parameterId') ?? str(raw?.data, 'id', '_id', 'parameterId');
+        if (!id) {
+            const m = raw?.message;
+            if (Array.isArray(m) && m.length > 0)
+                id = str(m[0], 'id', '_id', 'parameterId');
+            else if (m && typeof m === 'object')
+                id = str(m, 'id', '_id', 'parameterId');
+        }
+        if (!id)
+            throw new Error(`getOrCreateParameter: no id in response: ${JSON.stringify(raw)}`);
+        return Number.parseInt(id, 10);
+    }
+    // ---------------------------------------------------------------------- Suites (write)  [Step 4]
+    async createSuite(s) {
+        // Java stubs this out ("create_suite is not supported yet on SimplifyQA"). Mirror that.
+        if (this.hop())
+            return this.requireHop('create_suite').createSuite(s);
+        throw new Error('create_suite is not supported yet on SimplifyQA — create the suite in the SimplifyQA UI, ' +
+            'then add test cases via suite_add_testcases.');
+    }
+    /** Fetch raw suite, apply add/remove/reorder ops in memory, then PUT the whole doc back with a
+     *  STRICT allow-listed payload (the SQA update validator rejects unknown keys on both suite-level
+     *  and testCases[] entries). */
+    async updateSuiteMembers(id, ops) {
+        if (!Array.isArray(ops))
+            throw new Error('ops must be an array');
+        const raw = await this.fetchRawSuite(id);
+        if (Object.keys(raw).length === 0)
+            throw new Error(`suite ${id} not found`);
+        const currentRows = Array.isArray(raw['testCases']) ? raw['testCases'] : [];
+        const members = currentRows.map(normalizeSuiteEntry);
+        for (const op of ops) {
+            const tcNum = numericId(String(op.tcId));
+            switch (op.op) {
+                case 'add': {
+                    const already = members.some((m) => String(m['testcaseId']) === tcNum);
+                    if (!already)
+                        members.push(await this.buildSuiteEntryFromTestcase(tcNum));
+                    break;
+                }
+                case 'remove': {
+                    for (let i = members.length - 1; i >= 0; i--) {
+                        if (String(members[i]['testcaseId']) === tcNum)
+                            members.splice(i, 1);
+                    }
+                    break;
+                }
+                case 'reorder': {
+                    const newOrder = op.order ?? -1;
+                    const idx = members.findIndex((m) => String(m['testcaseId']) === tcNum);
+                    if (idx < 0 || newOrder < 1 || newOrder > members.length)
+                        break;
+                    const [moved] = members.splice(idx, 1);
+                    if (moved)
+                        members.splice(newOrder - 1, 0, moved);
+                    break;
+                }
+                default: throw new Error(`suite op '${op.op}' not supported (add|remove|reorder)`);
+            }
+        }
+        // Renumber `seq` contiguously from 1 after any mutation.
+        members.forEach((m, i) => { m['seq'] = i + 1; });
+        const payload = {};
+        for (const k of SUITE_UPDATE_ALLOWED_KEYS) {
+            if (raw[k] !== undefined)
+                payload[k] = raw[k];
+        }
+        payload['tcChanged'] = true;
+        payload['testCases'] = members;
+        await this.http.putMultipart(`/tm/suites/${numericId(id)}`, 'suiteObj', payload);
+        return this.getSuite(id);
+    }
+    /** Soft-delete via `isDelete:true`. `isDelete:false` restores. */
+    async deleteSuite(id) {
+        const projectId = this.requireProjectId();
+        await this.http.patchJson('/tm/suites', {
+            ids: [Number.parseInt(numericId(id), 10)],
+            projectId,
+            isDelete: true,
+        });
+    }
+    async fetchRawSuite(id) {
+        const raw = await this.http.getJson(`/tm/suites/${numericId(id)}`);
+        let doc = raw?.data ?? raw;
+        if (Array.isArray(doc))
+            doc = doc.length > 0 ? doc[0] : {};
+        return doc && typeof doc === 'object' ? doc : {};
+    }
+    /** Assemble the strict allow-listed suite entry for an ADD op. Required fields per the SQA
+     *  validator: testcaseId, code, seq (set by the caller), version, versionId, tcType. */
+    async buildSuiteEntryFromTestcase(tcNum) {
+        const raw = await this.fetchRawTestcase(tcNum);
+        if (Object.keys(raw).length === 0)
+            throw new Error(`test case ${tcNum} not found (cannot add to suite)`);
+        const code = str(raw, 'code', 'tcCode') ?? `TC_${tcNum}`;
+        const tcType = str(raw, 'tcType') ?? 'WEB';
+        let versionName = str(raw, 'versionName', 'selectedVersionName');
+        let versionId = str(raw, 'versionId', 'selectedVersionId');
+        if ((!versionName || !versionId) && Array.isArray(raw?.versions) && raw.versions.length > 0) {
+            const v = raw.versions[0];
+            versionName ?? (versionName = str(v, 'name'));
+            versionId ?? (versionId = str(v, 'id', '_id'));
+        }
+        return {
+            testcaseId: Number.parseInt(tcNum, 10),
+            code,
+            tcType,
+            ...(raw?.projectId !== undefined ? { projectId: raw.projectId } : {}),
+            version: versionName ?? 'v1.0',
+            versionId: versionId ?? '',
+            executionPlatform: { LOCAL: {}, REMOTE: {}, CLOUD: {} },
+        };
+    }
+    async resolveObjectTemplateId(technology) {
+        if (!this.objectTemplateCache) {
+            this.objectTemplateCache = (async () => {
+                const body = this.searchBody([{ column: 'deleted', value: false }], { limit: 1000 });
+                const raw = await this.http.postJson('/tm/objectTemplate/search', body);
+                const rows = pickArray(raw, 'data', 'content', 'objectTemplates');
+                const map = new Map();
+                for (const r of rows) {
+                    const name = str(r, 'name');
+                    const id = str(r, 'id', '_id');
+                    if (name && id)
+                        map.set(name.toUpperCase(), Number.parseInt(id, 10));
+                }
+                return map;
+            })().catch((e) => {
+                this.objectTemplateCache = null; // failure isn't memoised — a retry actually retries
+                throw e;
+            });
+        }
+        const map = await this.objectTemplateCache;
+        const id = map.get(technology.toUpperCase());
+        if (id == null) {
+            throw new Error(`Unknown object type/technology "${technology}"` +
+                (map.size ? ` — known: ${[...map.keys()].join(', ')}.` : ' — no object templates found in this project.'));
+        }
+        return id;
+    }
+    /** `POST /tm/object/search` — objects visible in the current project. `q.query` free-text searches
+     *  `disname` — the UI's "Name" column (confirmed against the real sqa-ui Object Repository grid;
+     *  `description` is a separate, optional field and is NOT what users mean by an object's name). */
+    async searchObjects(q) {
+        const projectId = this.requireProjectId();
+        const fields = [
+            { column: 'deleted', value: false },
+            { column: 'projectId', value: projectId },
+        ];
+        if (q.query)
+            fields.push({ column: 'disname', value: q.query, regEx: true });
+        const body = this.searchBody(fields, { startIndex: q.offset ?? 0, limit: q.limit ?? 100 });
+        const raw = await this.http.postJson('/tm/object/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'objects');
+        return rows.map(toObject);
+    }
+    /**
+     * Create a new object — `POST /tm/object`, plain JSON (NOT multipart, unlike testcase/suite writes;
+     * confirmed against the real sqa-ui ObjectService.saveNewObject). `o.objectType` is REQUIRED: it
+     * resolves to the object's `objecttemplateId` — structural, and (per updateObject's contract) not
+     * editable after creation. `moduleId` auto-resolves to the project's "Default Module" (matching the
+     * real UI's `object.component.ts` `openForm()`, which pre-selects it for every new object) — best
+     * effort, never blocks creation if no such module exists or the lookup fails.
+     */
+    async createObject(o) {
+        if (!o.objectType) {
+            throw new Error('createObject: objectType is required (e.g. "WEB", "ANDROID") — it selects the object template ' +
+                'and cannot be changed after the object is created.');
+        }
+        const projectId = this.requireProjectId();
+        const objecttemplateId = await this.resolveObjectTemplateId(o.objectType);
+        const moduleId = await this.resolveDefaultModuleId();
+        const body = {
+            disname: o.name,
+            objecttemplateId,
+            parameterId: [],
+            projectId,
+            technology: o.objectType,
+            ...(moduleId != null ? { moduleId } : {}),
+            attributes: o.locators.map((l) => ({ name: l.name, value: l.value, ...(l.unique ? { unique: true } : {}) })),
+        };
+        const raw = await this.http.postJson('/tm/object', body);
+        const doc = (raw?.data && typeof raw.data === 'object' ? raw.data : raw) ?? {};
+        return toObject(doc);
+    }
+    /** The current project's module literally named "Default Module" (case-insensitive) — mirrors the
+     *  real sqa-ui `object.component.ts` `openForm()` auto-selection. Best-effort: returns undefined
+     *  (never throws) when no such module exists or the lookup fails, so object creation still proceeds
+     *  without a module rather than being blocked by this convenience. */
+    async resolveDefaultModuleId() {
+        try {
+            const modules = await this.listModules();
+            const found = modules.find((m) => m.name?.toLowerCase() === 'default module');
+            return found ? Number.parseInt(found.id, 10) : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Soft-delete — `PATCH /tm/object` (NOT POST .../delete like testcase/suite; confirmed against the
+     * real sqa-ui ObjectService.deleteObject), body `{ids, projectId, isDelete:true}`.
+     *
+     * DEPENDENCY-CHECKED first: the SAME route with `isDelete:false` is a DRY RUN that returns, per
+     * object, which test cases / functions / workflows still reference it (`tcArr`/`fnArr`/`wfArr`, each
+     * keyed by projectId → an array of referencing ids — mirrors the real UI's
+     * deleteDependencyForObject flow, object.component.html/.ts). If anything still references it, the
+     * delete is refused rather than silently breaking those test cases; only a dependency-free object
+     * gets the real `isDelete:true` call.
+     */
+    async deleteObject(id) {
+        const projectId = this.requireProjectId();
+        const numId = Number.parseInt(numericId(id), 10);
+        const checkRes = await this.http.patchJson('/tm/object', { ids: [numId], projectId, isDelete: false });
+        const row = checkRes?.data?.[0];
+        const countRefs = (m) => m ? Object.values(m).reduce((n, arr) => n + (Array.isArray(arr) ? arr.length : 0), 0) : 0;
+        const tcCount = countRefs(row?.tcArr);
+        const fnCount = countRefs(row?.fnArr);
+        const wfCount = countRefs(row?.wfArr);
+        if (tcCount || fnCount || wfCount) {
+            const parts = [];
+            if (tcCount)
+                parts.push(`${tcCount} test case${tcCount === 1 ? '' : 's'}`);
+            if (fnCount)
+                parts.push(`${fnCount} function${fnCount === 1 ? '' : 's'}`);
+            if (wfCount)
+                parts.push(`${wfCount} workflow${wfCount === 1 ? '' : 's'}`);
+            throw new Error(`Cannot delete object ${id} — still used by ${parts.join(', ')}. Remove those references first ` +
+                '(or review/delete them in the SimplifyQA UI, which shows exactly which ones).');
+        }
+        await this.http.patchJson('/tm/object', { ids: [numId], projectId, isDelete: true });
+    }
+    /**
+     * Update an object — `PUT /tm/object/:id`, plain JSON (NOT multipart, unlike testcase/suite writes;
+     * confirmed against the real sqa-ui ObjectService.update). The backend expects the FULL document
+     * back, so this reads the current one first and echoes every field it doesn't touch
+     * (disname/description/objecttemplateId/parameterId/moduleId/technology/updateVersion — the
+     * optimistic-concurrency token the real form also round-trips).
+     *
+     * `changes.locators` UPSERTS by locator name into the existing attribute list — an entry with a
+     * matching name gets its value/unique updated in place, everything else on the object is left alone,
+     * and a name with no existing match is appended as a new locator.
+     *
+     * `technology` (object type) and `objecttemplateId` are DELIBERATELY never taken from `changes` —
+     * they are always echoed back from the existing doc. Both are structural (they determine which
+     * attribute set is even valid for this object), so editing them here — outside the create flow — is
+     * out of scope; changing them means creating a new object, not "updating" this one.
+     */
+    async updateObject(id, changes) {
+        const numId = numericId(id);
+        const raw = await this.http.getJson(`/tm/object/${numId}`);
+        const doc = (raw?.data && typeof raw.data === 'object' ? raw.data : raw) ?? {};
+        if (!doc || typeof doc !== 'object' || Object.keys(doc).length === 0) {
+            throw new Error(`object ${id} not found`);
+        }
+        const attributes = Array.isArray(doc.attributes)
+            ? doc.attributes.map((a) => ({
+                name: String(a?.name ?? ''),
+                value: String(a?.value ?? ''),
+                ...(a?.unique === true ? { unique: true } : {}),
+            }))
+            : [];
+        for (const loc of changes.locators ?? []) {
+            const idx = attributes.findIndex((a) => a.name === loc.name);
+            const merged = { name: loc.name, value: loc.value, ...(loc.unique !== undefined ? { unique: loc.unique } : {}) };
+            if (idx >= 0)
+                attributes[idx] = { ...attributes[idx], ...merged };
+            else
+                attributes.push(merged);
+        }
+        const body = {
+            disname: changes.name ?? doc.disname,
+            description: doc.description,
+            objecttemplateId: doc.objecttemplateId,
+            parameterId: doc.parameterId ?? [],
+            moduleId: doc.moduleId,
+            technology: doc.technology,
+            attributes,
+            projectId: this.requireProjectId(),
+            updateVersion: doc.updateVersion ?? 0,
+        };
+        const res = await this.http.putJson(`/tm/object/${numId}`, body);
+        const updated = (res?.data && typeof res.data === 'object' ? res.data : res) ?? doc;
+        return toObject(updated);
+    }
+    // ---------------------------------------------------------------------- Actions catalog
+    async actionsCatalog(platform) {
+        return this.requireHop('actions_catalog').actionsCatalog(platform);
+    }
+    // ---------------------------------------------------------------------- Testdata generation  [Step 3]
+    /** Fetch the default (template) iteration row for a TC. Fills gaps from the raw TC:
+     *   - versionId: falls back through versionId → selectedVersionId → versionsDetails.id → versions[0].id
+     *   - executionType (required by the backend Mongo filter): read from raw TC, default AUTOMATION
+     *   - environmentType: caller value wins; else /pm/fields/8 first configured env; else 'general' */
+    async getDefaultIteration(q) {
+        const projectId = this.requireProjectId();
+        const tcNum = numericId(q.tcId);
+        let versionId = q.versionId;
+        let execType;
+        if (!versionId || !execType) {
+            const raw = await this.fetchRawTestcase(q.tcId);
+            if (!versionId) {
+                versionId = str(raw, 'versionId', 'selectedVersionId', 'selVersion');
+                if (!versionId && raw?.versionsDetails && typeof raw.versionsDetails === 'object') {
+                    versionId = str(raw.versionsDetails, 'id', '_id', 'versionId');
+                }
+                if (!versionId && Array.isArray(raw?.versions) && raw.versions.length > 0) {
+                    versionId = str(raw.versions[0], 'id', '_id');
+                }
+            }
+            execType = str(raw, 'executionType');
+            if (!versionId)
+                throw new Error(`test case ${q.tcId} has no versionId — pass one explicitly`);
+        }
+        if (!execType)
+            execType = 'AUTOMATION';
+        const env = await this.resolveEnvironment(projectId, q.environmentType);
+        const path = '/tm/testdata/getDefaultItr' +
+            `?projectId=${projectId}` +
+            `&testcaseId=${tcNum}` +
+            `&versionId=${encodeURIComponent(versionId)}` +
+            `&environmentType=${encodeURIComponent(env)}` +
+            '&collection=TC' +
+            `&executionType=${encodeURIComponent(execType)}`;
+        const raw = await this.http.getJson(path);
+        const paramsMap = raw?.data?.parametersData;
+        const parameters = [];
+        if (paramsMap && typeof paramsMap === 'object' && !Array.isArray(paramsMap)) {
+            for (const [key, value] of Object.entries(paramsMap)) {
+                const pid = Number.parseInt(key, 10);
+                if (!Number.isFinite(pid))
+                    continue;
+                // Protected params get masked below — never assign this raw value to `seed` unmasked.
+                const rawValue = String(value?.value ?? '');
+                const meta = await this.fetchParameterMeta(pid);
+                if (!meta)
+                    continue; // parameter deleted — skip
+                const seed = meta.protected ? (rawValue ? '*****' : '(empty)') : rawValue;
+                parameters.push({ paramId: pid, name: meta.name, seed, ...(meta.protected ? { protected: true } : {}) });
+            }
+        }
+        return { tcId: q.tcId, versionId: versionId, environmentType: env, parameters };
+    }
+    /** Persist N generated iteration rows. Rebuilds the name → paramId map from a fresh template
+     *  fetch — no cache, because a stale id would silently write to the wrong parameter. */
+    async saveGeneratedIterations(payload) {
+        if (!payload.rows || payload.rows.length === 0)
+            throw new Error('rows[] required and non-empty');
+        if (!payload.versionId)
+            throw new Error('versionId required — call get_default_iteration first');
+        const projectId = this.requireProjectId();
+        const tcNum = numericId(payload.tcId);
+        const env = payload.environmentType || 'general';
+        // Reuse the caller's already-fetched template when supplied — the tc_generate_testdata tool
+        // fetches it just before calling us. Skipping the re-fetch avoids a duplicate /getDefaultItr +
+        // N /tm/parameter/{id} round trips per save.
+        const tplParams = payload.parameters ?? (await this.getDefaultIteration({
+            tcId: payload.tcId,
+            versionId: payload.versionId,
+            environmentType: env,
+        })).parameters;
+        const nameToId = new Map();
+        for (const p of tplParams)
+            nameToId.set(p.name, p.paramId);
+        const formulas = payload.formulas ?? {};
+        const formulaNames = Object.keys(formulas);
+        // Per-row: evaluate the row's formula columns concurrently. The compute endpoint mints RANDOM
+        // values so each call must still happen (no dedup across rows), but within a row the calls are
+        // independent — Promise.all cuts wall time roughly by the formula count.
+        // ponytail: per-row concurrency only. Firing all rows × formulas at once would work but might
+        // stress the external DATA_GENERATION_URL proxy; scale wider only if the row-level speedup is not enough.
+        const iterations = [];
+        for (const row of payload.rows) {
+            const data = [];
+            for (const [k, v] of Object.entries(row)) {
+                if (formulaNames.includes(k))
+                    continue; // a formula covers this column — its value wins
+                const pid = nameToId.get(k);
+                if (pid == null)
+                    continue; // unknown param name — silently skip
+                data.push({ paramId: pid, value: String(v ?? '') });
+            }
+            const evaluated = await Promise.all(formulaNames.map(async (name) => {
+                const pid = nameToId.get(name);
+                if (pid == null)
+                    return null;
+                const { value, expression } = await this.evaluateFormula(formulas[name]);
+                return { paramId: pid, value, formulaValue: expression };
+            }));
+            for (const cell of evaluated)
+                if (cell)
+                    data.push(cell);
+            iterations.push({ isChecked: true, data });
+        }
+        const body = {
+            projectId,
+            data: [
+                {
+                    type: 'TC',
+                    id: Number.parseInt(tcNum, 10),
+                    versionId: payload.versionId,
+                    environmentType: env,
+                    projectId,
+                    iterations,
+                },
+            ],
+        };
+        await this.http.postJson('/tm/testdata/saveItrForDataGen', body);
+        return { tcId: payload.tcId, inserted: iterations.length };
+    }
+    /** Environment key: caller wins; else fetch the project's configured envs and pick the first;
+     *  else 'general' (matches the SQA UI fallback). */
+    async resolveEnvironment(projectId, requested) {
+        if (requested && requested.length > 0)
+            return requested;
+        try {
+            const envs = await this.http.getJson(`/pm/fields/8?projectId=${projectId}&fieldType=environment`);
+            if (Array.isArray(envs) && envs.length > 0) {
+                const key = str(envs[0], 'key', 'value', 'name');
+                if (key)
+                    return key;
+            }
+        }
+        catch { /* fall through */ }
+        return 'general';
+    }
+    /** Parameter name + protected-flag lookup. Null when the parameter is deleted or cross-project. */
+    async fetchParameterMeta(paramId) {
+        let raw;
+        try {
+            raw = await this.http.getJson(`/tm/parameter/${paramId}`);
+        }
+        catch {
+            return null;
+        }
+        let n = raw?.data ?? raw;
+        if (Array.isArray(n))
+            n = n.length > 0 ? n[0] : null;
+        if (!n || typeof n !== 'object')
+            return null;
+        const name = str(n, 'name');
+        if (!name)
+            return null;
+        return { name, protected: n?.protected === true };
+    }
+    // ---------------------------------------------------------------------- Formulas  [Step 3b]
+    /** List every formula the current project can use — DEFAULT (customer-wide prefabs) unioned with
+     *  CUSTOM entries scoped to the customer or this project. The backend endpoint already returns the
+     *  union when called with `projectId`; we just normalise the doc shape and derive `scope` from
+     *  (type + projectId). Cached per adapter instance. */
+    async listFormulas() {
+        if (this.formulaCache)
+            return this.formulaCache;
+        const projectId = this.requireProjectId();
+        const pending = (async () => {
+            const raw = await this.http.getJson(`/tm/syncFormulas/fetch?projectId=${projectId}`);
+            const list = Array.isArray(raw?.data) ? raw.data : Array.isArray(raw) ? raw : [];
+            const out = [];
+            for (const doc of list) {
+                const f = normalizeFormula(doc, projectId);
+                if (f)
+                    out.push(f);
+            }
+            return out;
+        })().catch((e) => {
+            // On failure, drop the memoised promise so a retry actually retries.
+            this.formulaCache = null;
+            throw e;
+        });
+        this.formulaCache = pending;
+        return pending;
+    }
+    /** Evaluate one formula call and return { value, expression }. Order args by the formula's declared
+     *  parameter list so the stored `formulaValue` string is positional (`=NAME("a","b")`) — that's
+     *  what the SQA UI writes, and the backend just reads it verbatim on save. */
+    async evaluateFormula(call) {
+        const all = await this.listFormulas();
+        // Both sides carry parens: the backend stores DEFAULT names as "FIRST_NAME()", and models copy the
+        // SIGNATURE format ("FIRST_NAME(country name,sex,min,max)"). Strip on both, compare case-insensitively.
+        const needle = bareFormulaName(call.name).toUpperCase();
+        const meta = all.find((f) => bareFormulaName(f.name).toUpperCase() === needle);
+        if (!meta) {
+            throw new Error(`Unknown formula "${call.name}" — call tc_list_formulas to see what is available.`);
+        }
+        const fname = bareFormulaName(meta.name);
+        // Arg keys arrive with trailing colons/whitespace ("country name:", " sex ") from both the model AND
+        // the formula's own declared keyName. Normalise both sides before binding.
+        const argKey = (k) => k.replace(/:$/, '').trim();
+        const args = {};
+        for (const [k, v] of Object.entries(call.args ?? {}))
+            args[argKey(k)] = v;
+        const ordered = meta.parameters.map((p) => args[argKey(p.keyName)] ?? '');
+        // /tm/customFormula takes its OWN positional query keys, not the formula's display keyNames.
+        const qs = new URLSearchParams({ formulaName: fname });
+        const apiKeys = FORMULA_ARG_KEYS[fname.toUpperCase()] ?? ['value'];
+        ordered.forEach((v, i) => { if (v !== '' && apiKeys[i])
+            qs.append(apiKeys[i], v); });
+        // ponytail: the compute endpoint's response envelope varies between formula types
+        // (`{data:{value}}` for person-info, plain string for a few); coerce defensively.
+        const resp = await this.http.getJson(`/tm/customFormula?${qs.toString()}`);
+        const value = String(resp?.data?.value ?? resp?.value ?? resp?.data ?? resp ?? '');
+        const quoted = ordered.map((a) => `"${String(a).replace(/"/g, '\\"')}"`).join(',');
+        const expression = `=${fname}(${quoted})`;
+        return { value, expression };
+    }
+    // ---------------------------------------------------------------------- Run status  [Step 6]
+    /** Real status of a run — reads step-level results direct from SQA REST because the desktop agent's
+     *  get_run only returns queue state (often stale). start/stop still hop for v1. */
+    async getRun(runId) {
+        const projectId = this.requireProjectId();
+        const base = (this.cfg.baseUrl ?? '').replace(/\/+$/, '');
+        // GET /exec/report/{runId}/{projectId} — the run rows the /reports page reads.
+        const runs = await this.http.getJson(`/exec/report/${runId}/${projectId}`);
+        if (!Array.isArray(runs) || runs.length === 0) {
+            return { runId, state: 'queued' };
+        }
+        // Multi-TC runs return several rows; pick the first FAILED so tc_heal has a failing step to diagnose.
+        let chosen = runs[0];
+        for (const r of runs) {
+            if (typeof r?.status === 'string' && r.status.toUpperCase() === 'FAILED') {
+                chosen = r;
+                break;
+            }
+        }
+        const executionRunId = str(chosen, 'id', '_id') ?? '';
+        const parentId = Number(chosen?.executionItemId ?? 0);
+        const stepsResp = await this.http.postJson('/reports/execution/getstepResult', {
+            executionId: Number.parseInt(numericId(runId), 10),
+            executionRunId,
+            parentId,
+            projectId,
+        });
+        const rawSteps = Array.isArray(stepsResp?.data) ? stepsResp.data : [];
+        const stepResults = rawSteps.map((s) => {
+            const step = {
+                n: typeof s?.seq === 'number' ? s.seq : 0,
+                description: String(s?.description ?? ''),
+                status: mapStepStatus(str(s, 'status') ?? ''),
+            };
+            const exc = str(s, 'exception');
+            if (exc && exc.length > 0) {
+                step.error = exc;
+            }
+            else {
+                // SQA leaves `exception` null even on FAILED. The real cause sits in ERROR log lines
+                // (e.g. "No Such Element Exception: ..."). Send ALL ERROR lines joined — a trailing
+                // "JS disabled" line would otherwise mask the real NoSuchElement above it.
+                const logs = s?.executionLogData?.executionLogs;
+                if (Array.isArray(logs) && logs.length > 0) {
+                    const errorLines = [];
+                    for (const l of logs) {
+                        const t = String(l ?? '');
+                        if (t.includes('ERROR'))
+                            errorLines.push(t);
+                    }
+                    if (errorLines.length > 0)
+                        step.error = errorLines.join('\n');
+                    else
+                        step.error = String(logs[logs.length - 1] ?? '');
+                }
+            }
+            return step;
+        });
+        return {
+            runId,
+            state: mapRunState(str(chosen, 'status') ?? ''),
+            stepResults,
+            reportUrl: `${base}/reports/execution/${runId}`,
+        };
+    }
+    /** Targeted name lookup for a single project by numeric id — the whole-list `listProjects`
+     *  is paged (default 100) and API-key scoping can hide the selected project, which left
+     *  callers with an empty projectName. */
+    async lookupProjectName(projectId) {
+        try {
+            const body = this.searchBody([{ column: 'id', value: projectId }, { column: 'deleted', value: false }], { selectFields: ['id', 'name'], limit: 1 });
+            const raw = await this.http.postJson('/pm/project/search', body);
+            const rows = pickArray(raw, 'data', 'content', 'projects');
+            return str(rows[0], 'name', 'projectName') ?? '';
+        }
+        catch {
+            return '';
+        }
+    }
+    // --- Run dispatch (direct REST) --------------------------------------------
+    // Trigger, stop, and local-agent roster all speak the SQA gateway directly.
+    // The desktop agent still runs the actual TC — backend RPUSHes to Redis and the
+    // agent's poll loop picks it up — but the KICKOFF event no longer hops through
+    // /mcp:4040. Spec: common-mcp/plan/sqa-execution-trigger.md. Cloud runners and
+    // SUITE runs are not yet ported and still hop (or error clearly).
+    async startRun(target, opts) {
+        const projectId = this.requireProjectId();
+        if (!target.tcId) {
+            if (target.suiteId) {
+                throw new Error('startRun: SUITE runs are not yet ported to direct REST — set QA_MCP_URL so common-mcp ' +
+                    'can hop to the SimplifyQA agent for suite dispatch, or run a single TC.');
+            }
+            throw new Error('startRun: target.tcId (or target.suiteId) is required.');
+        }
+        const tcId = target.tcId;
+        const tcNum = Number.parseInt(numericId(tcId), 10);
+        if (!Number.isFinite(tcNum))
+            throw new Error(`startRun: could not resolve numeric id for ${tcId}.`);
+        const mode = (opts.mode ?? 'local').toUpperCase();
+        const rawTc = await this.fetchRawTestcase(tcId);
+        if (!rawTc || Object.keys(rawTc).length === 0) {
+            throw new Error(`startRun: test case ${tcId} not found.`);
+        }
+        // Version resolution — same fallback chain buildTestcasePayload/getDefaultIteration use.
+        // Caller override (opts.versionId) wins; the name is looked up in the TC's versions[] so the
+        // exec payload's versionName matches the picked versionId.
+        let versionName;
+        let versionId;
+        if (opts.versionId) {
+            versionId = opts.versionId;
+            if (Array.isArray(rawTc?.versions)) {
+                const picked = rawTc.versions.find((v) => str(v, 'id', '_id') === opts.versionId);
+                if (picked)
+                    versionName = str(picked, 'name');
+            }
+        }
+        versionName ?? (versionName = str(rawTc, 'versionName', 'selectedVersionName'));
+        versionId ?? (versionId = str(rawTc, 'versionId', 'selectedVersionId'));
+        if ((!versionName || !versionId) && rawTc?.versionsDetails && typeof rawTc.versionsDetails === 'object') {
+            versionName ?? (versionName = str(rawTc.versionsDetails, 'name'));
+            versionId ?? (versionId = str(rawTc.versionsDetails, 'id', '_id', 'versionId'));
+        }
+        if ((!versionName || !versionId) && Array.isArray(rawTc?.versions) && rawTc.versions.length > 0) {
+            const v = rawTc.versions[0];
+            versionName ?? (versionName = str(v, 'name'));
+            versionId ?? (versionId = str(v, 'id', '_id'));
+        }
+        versionName ?? (versionName = 'v1.0');
+        versionId ?? (versionId = '');
+        // ponytail: was `this.info()` — 5 round-trips (list_projects + 4 counts) for one field, and
+        // returned projectName="" when the current project wasn't in the first 100-row page or was
+        // filtered by API-key scope, which the /exec/execution endpoint rejects with HTTP 400.
+        const projectName = await this.lookupProjectName(projectId);
+        if (!projectName) {
+            throw new Error(`startRun: could not resolve project name for projectId=${projectId}. ` +
+                `The token may not have read access to this project.`);
+        }
+        const env = await this.resolveEnvironment(projectId, opts.environment);
+        const tcType = String(str(rawTc, 'tcType') ?? 'WEB').toUpperCase();
+        const executionType = String(str(rawTc, 'executionType') ?? 'AUTOMATION').toUpperCase();
+        const code = str(rawTc, 'code') ?? '';
+        const name = str(rawTc, 'name', 'title') ?? '';
+        const description = str(rawTc, 'description') ?? '';
+        const prerequisite = str(rawTc, 'prerequisite', 'preconditions') ?? '';
+        const moduleIdNum = typeof rawTc?.moduleId === 'number' ? rawTc.moduleId : 0;
+        const userstoryIdNum = typeof rawTc?.userstoryId === 'number' ? rawTc.userstoryId : 0;
+        const tags = Array.isArray(rawTc?.tags) ? rawTc.tags : [];
+        // Best-effort module name — targeted id lookup (not a full listModules scan, which now caps
+        // at the default 100). Story name deliberately left empty; adds a per-run round-trip for a
+        // cosmetic field. ponytail: enrich if a caller ever complains.
+        let moduleName = '';
+        if (moduleIdNum > 0) {
+            try {
+                const body = this.searchBody([{ column: 'id', value: moduleIdNum }, { column: 'deleted', value: false }], { selectFields: ['id', 'name'], limit: 1 });
+                const raw = await this.http.postJson('/pm/module/search', body);
+                const rows = pickArray(raw, 'data', 'content', 'modules');
+                moduleName = str(rows[0], 'name') ?? '';
+            }
+            catch { /* leave empty */ }
+        }
+        const agentId = mode === 'LOCAL' ? await this.resolveLocalAgentId(opts.agentId) : null;
+        const platform = this.buildRunPlatform(tcType, mode, opts.browser, opts.deviceId);
+        // UI uses `Math.random().toString(26).substr(5,6)` — plan doc confirms any string works.
+        const stepId = Math.random().toString(36).slice(2, 8).padEnd(6, '0');
+        const body = {
+            projectId,
+            agentId,
+            environmentType: env,
+            executionStyle: (opts.strategy ?? 'serial').toUpperCase(),
+            executionOS: this.detectExecutionOS(),
+            executionTypeId: tcNum,
+            executionTypeName: name,
+            executionTypeCode: code,
+            mailersList: {},
+            cloudType: mode === 'CLOUD' ? 'VM' : 'NONE',
+            mode,
+            executionCategory: 'EXECUTION',
+            releaseId: opts.releaseId ? Number.parseInt(opts.releaseId, 10) || 0 : 0,
+            iterationId: opts.sprintId ? Number.parseInt(opts.sprintId, 10) || 0 : 0,
+            executionTime: '',
+            status: 'INPROGRESS',
+            iterationsSelected: [],
+            result: '',
+            globalConfiguration: {},
+            isRecordingEnabled: false,
+            offset: -(new Date().getTimezoneOffset()),
+            type: 'TESTCASE',
+            executionType,
+            executionItems: [{
+                    id: tcNum,
+                    name,
+                    description,
+                    versionId,
+                    versionName,
+                    seq: 1,
+                    stepId,
+                    stepCount: 0,
+                    technologyType: tcType,
+                    type: 'TC',
+                    platform,
+                    projectId,
+                    projectName,
+                    configuration: {},
+                    iterationsSelected: [],
+                    moduleId: moduleIdNum,
+                    userstoryId: userstoryIdNum,
+                    tags,
+                    code,
+                    prerequisite,
+                    moduleName,
+                    userstoryName: '',
+                }],
+        };
+        const resp = await this.http.postJson('/exec/execution', body);
+        const d = resp?.data ?? resp;
+        const runId = str(d, 'id', 'executionId', '_id') ??
+            (typeof d?.id === 'number' ? String(d.id) : undefined) ??
+            (typeof d?.executionId === 'number' ? String(d.executionId) : undefined);
+        if (!runId)
+            throw new Error('startRun: backend accepted trigger but returned no run id.');
+        return { runId };
+    }
+    async stopRun(runId) {
+        const projectId = this.requireProjectId();
+        const executionId = Number.parseInt(numericId(runId), 10);
+        if (!Number.isFinite(executionId))
+            throw new Error(`stopRun: invalid runId ${runId}.`);
+        await this.http.postJson('/exec/execution/stopExecution', {
+            projectId,
+            executionId,
+            killType: 'STOP_EXECUTION',
+        });
+    }
+    async listCloudRunners() {
+        const projectId = this.requireProjectId();
+        const body = this.searchBody([{ column: 'projectId', value: projectId }], { limit: 1000 });
+        const raw = await this.http.postJson('/pm/machineResources/search', body);
+        const rows = pickArray(raw, 'data', 'content');
+        return rows.map((n) => {
+            const id = str(n, 'id', '_id') ?? '';
+            const status = str(n, 'status') ?? '';
+            const parentId = str(n, 'parentId');
+            const type = str(n, 'type');
+            const os = [parentId ? `CM-${parentId}` : null, type].filter(Boolean).join(' · ') || undefined;
+            return {
+                id,
+                name: str(n, 'displayName', 'name') ?? id,
+                online: status === 'IDLE',
+                ...(status ? { status } : {}),
+                ...(os ? { os } : {}),
+            };
+        });
+    }
+    async listLocalAgents() {
+        // ponytail: no projectId filter — machine_registration.projectId is never written by
+        // test-management/services/machine_registration.service.js (create only stamps
+        // machineName/systemName/macAddress/ipAddress/platform/customerId). Filtering by projectId
+        // strips every legacy row. customerId scoping is still applied server-side from the JWT.
+        const body = this.searchBody([{ column: 'deleted', value: false }], { limit: 1000 });
+        const raw = await this.http.postJson('/tm/machineRegistration/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'agents', 'machines');
+        // ponytail: hostname override, same trick sqa-ui uses at
+        // sqa-ui/.../machine-registration.component.ts:169. The DB `active` flag is only
+        // written to `true` on first registration (fire-and-forget in executions/services/
+        // executionQueue.service.js:49) and back to `false` by a 7s-stale cron. Every other poll
+        // is a no-op, so a still-polling agent frequently shows `active:false`. When the row's
+        // machineName matches THIS box's hostname, MCP is running on the same machine as the
+        // agent — trust that over the stale DB flag. Upgrade path: if the backend adds a live
+        // Redis-presence endpoint (ZSCORE SQAAGENTTRACKER), consult that here instead.
+        const hostFull = os.hostname().toLowerCase();
+        // Bare hostname: strip trailing .local/.lan/.localdomain AND take the first label. Handles
+        // both directions of "short vs FQDN" mismatch — the agent may register as `Pratiks-MBP`
+        // while os.hostname() returns `pratiks-mbp.local`, or vice-versa.
+        const hostBare = hostFull.replace(/\.(local|lan|localdomain)$/, '').split('.')[0] ?? hostFull;
+        return rows.map((n) => {
+            const id = str(n, 'id', '_id', 'agentId') ?? '';
+            const agentName = str(n, 'machineName', 'name', 'host');
+            const owner = str(n, 'owner', 'userName', 'createdBy');
+            const hostAddr = str(n, 'macAddress', 'hostAddress');
+            const dbActive = typeof n?.active === 'boolean' ? n.active : false;
+            const nameLc = agentName?.toLowerCase() ?? '';
+            const isMyBox = nameLc.length > 0 && hostBare.length > 0 && nameLc.includes(hostBare);
+            return {
+                id,
+                ...(agentName ? { name: agentName } : {}),
+                online: dbActive || isMyBox,
+                ...(owner ? { owner } : {}),
+                ...(hostAddr ? { host: hostAddr } : {}),
+            };
+        });
+    }
+    /**
+     * Pick THE ACTING USER'S OWN active agent — never row [0] of a shared-tenant roster (which
+     * would silently dispatch a local run to a teammate's box, and the run would sit queued until
+     * TTL because it lands in a Redis key that no local agent on the caller's machine polls).
+     *
+     * SQA's `machineRegistration` row carries no owner_user_id column (unlike walnut, which matches
+     * the JWT `id` claim to `owner_user_id`), so we identify "your" agent by hostname: common-mcp
+     * runs on the caller's own box in the typical MCP setup, and SQA `machineName` is either the
+     * bare OS hostname or a bracketed display form (`USER.NAME [ Hostname.local ]`) — both contain
+     * `os.hostname()`. Filter → active only → hostname substring match → return the single hit.
+     * Zero/many matches refuse honestly; a silent guess would just repeat the exact bug we're fixing.
+     *
+     * ponytail: hostname heuristic. Upgrade to owner-user-id match if the backend adds that column
+     * to machineRegistration (mirror walnut's `resolveLocalAgentCredential` at that point).
+     */
+    async resolveLocalAgentId(preferred) {
+        if (preferred && preferred.length > 0)
+            return preferred;
+        const agents = await this.listLocalAgents();
+        if (agents.length === 0) {
+            throw new Error('startRun (LOCAL): no local agent registered. Register a machine in the SimplifyQA UI ' +
+                'first, or pass mode: "cloud" if a cloud runner is provisioned.');
+        }
+        const active = agents.filter((a) => a.online);
+        if (active.length === 0) {
+            throw new Error('startRun (LOCAL): no local agent is currently active (polling). Launch your SimplifyQA ' +
+                'desktop agent and retry — or pass `agentId` explicitly if you know the credential id.');
+        }
+        const hostFull = os.hostname().toLowerCase();
+        // Same short-vs-FQDN handling as listLocalAgents — see the ponytail note there.
+        const host = hostFull.replace(/\.(local|lan|localdomain)$/, '').split('.')[0] ?? hostFull;
+        const mine = active.filter((a) => host.length > 0 && (a.name ?? '').toLowerCase().includes(host));
+        if (mine.length === 1)
+            return mine[0].id;
+        const listing = (arr) => arr.map((a) => `  - ${a.name ?? a.id} \`${a.id}\``).join('\n');
+        if (mine.length > 1) {
+            throw new Error(`startRun (LOCAL): multiple active agents match this machine (${host}). Pass \`agentId\` ` +
+                `to pick one:\n${listing(mine)}`);
+        }
+        throw new Error(`startRun (LOCAL): could not auto-pick your local agent — no active agent's name matches ` +
+            `this hostname (${host}). Pass \`agentId\` explicitly. Active agents:\n${listing(active)}`);
+    }
+    detectExecutionOS() {
+        if (process.platform === 'win32')
+            return 'WINDOWS';
+        if (process.platform === 'darwin')
+            return 'MAC';
+        return 'LINUX';
+    }
+    buildRunPlatform(tcType, mode, browser, deviceId) {
+        const t = tcType.toUpperCase();
+        if (t === 'WEB') {
+            if (mode === 'CLOUD') {
+                const key = `${(browser ?? 'CHROME').toUpperCase()}_HEADLESS`;
+                return [{ name: key, id: key, technologyType: 'WEB', type: 'NONE' }];
+            }
+            const b = (browser ?? 'CHROME').toUpperCase();
+            return [{ name: b, id: b, technologyType: 'WEB', type: 'NONE' }];
+        }
+        if (t === 'ANDROID' || t === 'IOS') {
+            // Executor's AndroidSessionFactory.buildLocal calls requireDeviceId — no default. Fail
+            // loud so the caller sees the fix (list devices, pick one) instead of a queued/error hang.
+            if (!deviceId) {
+                throw new Error(`${t} test cases need \`deviceId\`. Call android_list_devices to see the available ` +
+                    `devices, then re-run with \`deviceId\` set to the adb serial (LOCAL) or marketplace ` +
+                    `device name (CLOUD).`);
+            }
+            // ponytail: CLOUD path still ships `cloudDeviceType: undefined` — the executor needs it
+            // (BROWSER_STACK / SAUCE_LABS / LAMBDA_INTEGRATION / SQA_DEVICE_FARM) to know which farm
+            // to route to. Deferred with the marketplace port; LOCAL runs unaffected.
+            return [{
+                    name: deviceId, id: deviceId, technologyType: t,
+                    type: mode === 'CLOUD' ? 'CLOUD_DEVICE' : 'NONE',
+                }];
+        }
+        return [{ name: t, id: t, technologyType: t, type: 'NONE' }];
+    }
+    // --- Environments + datasets -------------------------------------------
+    /** Direct REST — same endpoint `resolveEnvironment` uses. Works without an agent hop.
+     *  `key` is what testdata iterations store as `environmentType`; `id` is the uuid used by run dispatch. */
+    async listEnvironments() {
+        const projectId = this.requireProjectId();
+        // Let fetch failures propagate rather than reading as "zero environments".
+        const raw = await this.http.getJson(`/pm/fields/8?projectId=${projectId}&fieldType=environment`);
+        const arr = Array.isArray(raw) ? raw : Array.isArray(raw?.data) ? raw.data : [];
+        const out = [];
+        for (const e of arr) {
+            if (!e || typeof e !== 'object' || e.deleted)
+                continue;
+            const key = str(e, 'key', 'value') ?? '';
+            const name = str(e, 'name', 'label') ?? key;
+            const id = str(e, 'id', '_id') ?? key;
+            if (!key && !name)
+                continue;
+            out.push({ id, name, key, ...(key === 'general' ? { isDefault: true } : {}) });
+        }
+        return out;
+    }
+    async listDatasets(tcId) {
+        const h = this.hop();
+        return h?.listDatasets ? h.listDatasets(tcId) : [];
+    }
+    // --- Journal (recording seed lives on the agent's FS) ------------------
+    async readJournal(tcId) {
+        return this.requireHop('read_journal').readJournal(tcId);
+    }
+    async editJournal(tcId, ops) {
+        return this.requireHop('edit_journal').editJournal(tcId, ops);
+    }
+}
+//# sourceMappingURL=adapter.js.map