@x12i/memorix-service 3.1.0 → 3.2.0

package/dist/pipeline-compile.d.ts

@@ -1,10 +1,12 @@
 /**
  * Authoring pack pipeline → runtime v2 shape (pipelineId / stepId / stepKind / portConfig).
+ * Supports unified step `target` (service | ai-service | connector | pipeline | runx).
  */
-import { type PipelineDefinition } from "@x12i/memorix-pipeline/v2";
+import { type PipelineDefinition, type StepKind } from "@x12i/memorix-pipeline/v2";
 export type ServiceDefSlice = {
     id?: string;
     serviceId?: string;
+    capabilities?: string[];
     memorixAccess?: unknown;
     /** AI-services/v1 binding (type + item); when set, compile stamps FR invoke config. */
     aiService?: {
@@ -22,6 +24,25 @@ export type ServiceDefSlice = {
         itemId?: string;
     };
 };
+/** Authoring step target — same surface as Jobs execution targets + runx. */
+export type AuthoringStepTarget = {
+    kind: "service";
+    serviceId: string;
+} | {
+    kind: "ai-service";
+    aiServiceType: string;
+    itemId: string;
+} | {
+    kind: "connector";
+    connectorId: string;
+    sourceId: string;
+} | {
+    kind: "pipeline";
+    pipelineId: string;
+} | {
+    kind: "runx";
+    capabilityId: string;
+};
 export declare function resolveKnowxWorkerBaseUrl(): string;
 /**
  * Explicit test-only switch for the APS AI Services Simulator.
@@ -43,9 +64,22 @@ export declare function resolveKnowxServiceEndpoint(serviceId: string, opts?: {
     workerBaseUrl?: string;
     endpointEnv?: string;
 }): string;
+/** Prefer behavioral step kind from service capabilities. */
+export declare function preferredStepKindFromCapabilities(caps: string[] | undefined): StepKind;
+/**
+ * Build a directed call graph of pipelines that invoke other pipelines via
+ * `target.pipeline` / `run-pipeline` steps. Detects cycles when ids are known.
+ */
+export declare function detectPipelineCallCycles(pipelines: Array<{
+    id?: string;
+    pipelineId?: string;
+    steps?: Array<Record<string, unknown>>;
+}>): string[];
 export declare function compileAuthoringPipeline(input: unknown, opts?: {
     knownServiceIds?: Set<string>;
     workerBaseUrl?: string;
     serviceDefs?: ServiceDefSlice[];
+    /** When set, validate nested pipeline targets exist. */
+    knownPipelineIds?: Set<string>;
 }): PipelineDefinition;
 //# sourceMappingURL=pipeline-compile.d.ts.map

package/dist/pipeline-compile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline-compile.d.ts","sourceRoot":"","sources":["../src/pipeline-compile.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAGL,KAAK,kBAAkB,EAExB,MAAM,2BAA2B,CAAC;AAmCnC,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,uFAAuF;IACvF,SAAS,CAAC,EAAE;QACV,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,UAAU,CAAC,EAAE;QACX,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,0FAA0F;QAC1F,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,+CAA+C;QAC/C,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;CACH,CAAC;AAEF,wBAAgB,yBAAyB,IAAI,MAAM,CAMlD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAO7C;AAID;;;GAGG;AACH,wBAAgB,4BAA4B,IAAI,MAAM,GAAG,SAAS,CAMjE;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE;IACL,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GACA,MAAM,CAiBR;AAED,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,IAAI,CAAC,EAAE;IACL,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;CACjC,GACA,kBAAkB,CAiJpB"}
+{"version":3,"file":"pipeline-compile.d.ts","sourceRoot":"","sources":["../src/pipeline-compile.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,QAAQ,EACd,MAAM,2BAA2B,CAAC;AA+CnC,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,uFAAuF;IACvF,SAAS,CAAC,EAAE;QACV,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,UAAU,CAAC,EAAE;QACX,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,0FAA0F;QAC1F,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,+CAA+C;QAC/C,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;CACH,CAAC;AAEF,6EAA6E;AAC7E,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3C,wBAAgB,yBAAyB,IAAI,MAAM,CAMlD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAO7C;AAID;;;GAGG;AACH,wBAAgB,4BAA4B,IAAI,MAAM,GAAG,SAAS,CAMjE;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE;IACL,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GACA,MAAM,CAiBR;AAQD,6DAA6D;AAC7D,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,MAAM,EAAE,GAAG,SAAS,GACzB,QAAQ,CAOV;AA2ND;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,KAAK,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACxC,CAAC,GACD,MAAM,EAAE,CAoDV;AAED,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,IAAI,CAAC,EAAE;IACL,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;IAChC,wDAAwD;IACxD,gBAAgB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAChC,GACA,kBAAkB,CAmNpB"}

package/dist/pipeline-compile.js

@@ -1,5 +1,6 @@
 /**
  * Authoring pack pipeline → runtime v2 shape (pipelineId / stepId / stepKind / portConfig).
+ * Supports unified step `target` (service | ai-service | connector | pipeline | runx).
  */
 import { validatePipelineDefinition, STEP_KINDS, } from "@x12i/memorix-pipeline/v2";
 import { defaultEndpointEnvForType, resolveAiServiceOriginUrl, } from "./ai-services/config.js";
@@ -22,6 +23,10 @@ const STEP_ALIASES = {
     validate: "validate",
     "map-normalize": "map-normalize",
     "identity-dedupe": "identity-dedupe",
+    "run-pipeline": "run-pipeline",
+    pipeline: "run-pipeline",
+    "call-pipeline": "run-pipeline",
+    runx: "runx",
 };
 const MUTATING = new Set([
     "persist-raw",
@@ -29,6 +34,13 @@ const MUTATING = new Set([
     "relationship-write",
     "workflow",
     "narrative",
+    "run-pipeline",
+]);
+const BEHAVIORAL = new Set([
+    "enrich",
+    "analyze",
+    "decide",
+    "narrative",
 ]);
 export function resolveKnowxWorkerBaseUrl() {
     return (process.env.KNOWX_WORKER_URL?.trim() ||
@@ -79,6 +91,245 @@ export function resolveKnowxServiceEndpoint(serviceId, opts) {
     }
     return workerDefault;
 }
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** Prefer behavioral step kind from service capabilities. */
+export function preferredStepKindFromCapabilities(caps) {
+    if (!caps?.length)
+        return "analyze";
+    if (caps.includes("enrich"))
+        return "enrich";
+    if (caps.includes("decide"))
+        return "decide";
+    if (caps.includes("narrative"))
+        return "narrative";
+    if (caps.includes("analyze"))
+        return "analyze";
+    return "analyze";
+}
+function parseStepTarget(step, rawKind) {
+    const target = asRecord(step.target);
+    if (target) {
+        const kind = String(target.kind ?? "").trim();
+        if (kind === "service") {
+            const serviceId = String(target.serviceId ?? "").trim();
+            if (serviceId)
+                return { kind: "service", serviceId };
+        }
+        if (kind === "ai-service" || kind === "ai") {
+            const aiServiceType = String(target.aiServiceType ?? "").trim();
+            const itemId = String(target.itemId ?? "").trim();
+            if (aiServiceType && itemId) {
+                return { kind: "ai-service", aiServiceType, itemId };
+            }
+        }
+        if (kind === "connector") {
+            const connectorId = String(target.connectorId ?? "").trim();
+            const sourceId = String(target.sourceId ?? "").trim();
+            if (connectorId && sourceId) {
+                return { kind: "connector", connectorId, sourceId };
+            }
+        }
+        if (kind === "pipeline") {
+            const pipelineId = String(target.pipelineId ?? "").trim();
+            if (pipelineId)
+                return { kind: "pipeline", pipelineId };
+        }
+        if (kind === "runx") {
+            const capabilityId = String(target.capabilityId ?? "").trim();
+            if (capabilityId)
+                return { kind: "runx", capabilityId };
+        }
+    }
+    // Shorthand fields on the step.
+    const pipelineId = String(step.pipelineId ?? "").trim();
+    if (pipelineId &&
+        (rawKind === "run-pipeline" ||
+            rawKind === "pipeline" ||
+            rawKind === "call-pipeline" ||
+            rawKind === "")) {
+        return { kind: "pipeline", pipelineId };
+    }
+    const capabilityId = String(step.capabilityId ??
+        asRecord(step.portConfig)?.capabilityId ??
+        "").trim();
+    if (capabilityId && (rawKind === "runx" || rawKind === "")) {
+        return { kind: "runx", capabilityId };
+    }
+    const sourceId = String(step.sourceId ?? "").trim();
+    const connectorId = String(step.connectorId ??
+        asRecord(step.portConfig)?.connectorId ??
+        "").trim();
+    if (sourceId && connectorId) {
+        return { kind: "connector", connectorId, sourceId };
+    }
+    if (sourceId && (rawKind === "memory-pull" || rawKind === "pull" || rawKind === "collect")) {
+        return {
+            kind: "connector",
+            connectorId: connectorId || "default",
+            sourceId,
+        };
+    }
+    const stepAi = asRecord(step.aiService);
+    if (stepAi) {
+        const aiServiceType = String(stepAi.aiServiceType ?? "").trim();
+        const itemId = String(stepAi.itemId ?? "").trim();
+        if (aiServiceType && itemId) {
+            return { kind: "ai-service", aiServiceType, itemId };
+        }
+    }
+    const serviceId = String(step.serviceId ?? "").trim();
+    if (serviceId) {
+        return { kind: "service", serviceId };
+    }
+    return null;
+}
+function stampAiPortConfig(step, opts) {
+    const endpoint = resolveAiServiceOriginUrl(opts.aiServiceType, {
+        endpoint: opts.endpoint || undefined,
+        endpointEnv: opts.endpointEnv,
+    }) ?? "";
+    if (!endpoint)
+        return false;
+    const existingPc = step.portConfig ?? {};
+    const existingExec = existingPc.execution && typeof existingPc.execution === "object"
+        ? existingPc.execution
+        : {};
+    const skillExec = opts.aiServiceType === "skill"
+        ? defaultSkillExecutionForItem(opts.itemId, {
+            stepId: String(step.stepId ?? step.id ?? ""),
+        })
+        : undefined;
+    step.portConfig = {
+        ...existingPc,
+        serviceId: opts.serviceId,
+        operation: opts.operation,
+        ...(opts.memorixAccess ? { memorixAccess: opts.memorixAccess } : {}),
+        endpoint,
+        aiServiceType: opts.aiServiceType,
+        itemId: opts.itemId,
+        invokeProtocol: "ai-services/1",
+        ...(skillExec || Object.keys(existingExec).length
+            ? {
+                execution: {
+                    ...skillExec,
+                    ...existingExec,
+                },
+            }
+            : {}),
+    };
+    return true;
+}
+function stampServicePortConfig(step, svc, serviceId, opts) {
+    const operation = (typeof svc?.invocation?.operation === "string"
+        ? svc.invocation.operation
+        : undefined) ?? serviceId;
+    const memorixAccess = Array.isArray(svc?.memorixAccess)
+        ? svc.memorixAccess
+        : undefined;
+    const stepAi = step.aiService && typeof step.aiService === "object"
+        ? step.aiService
+        : null;
+    const aiServiceType = String(stepAi?.aiServiceType ??
+        svc?.aiService?.aiServiceType ??
+        svc?.invocation?.aiServiceType ??
+        "").trim();
+    const itemId = String(stepAi?.itemId ?? svc?.aiService?.itemId ?? svc?.invocation?.itemId ?? "").trim();
+    if (aiServiceType && itemId) {
+        const endpointEnv = String(stepAi?.endpointEnv ??
+            svc?.aiService?.endpointEnv ??
+            svc?.invocation?.endpointEnv ??
+            defaultEndpointEnvForType(aiServiceType) ??
+            "").trim() || undefined;
+        const explicitEndpoint = String(stepAi?.endpoint ?? svc?.aiService?.endpoint ?? "").trim();
+        if (stampAiPortConfig(step, {
+            serviceId,
+            operation,
+            memorixAccess,
+            aiServiceType,
+            itemId,
+            endpointEnv,
+            endpoint: explicitEndpoint || undefined,
+        })) {
+            return;
+        }
+        // No companion URL — fall through to worker invocation (offline / CI).
+    }
+    const endpointEnv = typeof svc?.invocation?.endpointEnv === "string"
+        ? svc.invocation.endpointEnv.trim()
+        : serviceId === "knowx-extract"
+            ? "KNOWX_EXTRACT_WORKER_URL"
+            : undefined;
+    const endpoint = resolveKnowxServiceEndpoint(serviceId, {
+        workerBaseUrl: opts?.workerBaseUrl,
+        endpointEnv,
+    });
+    step.portConfig = {
+        ...(step.portConfig ?? {}),
+        serviceId,
+        operation,
+        ...(memorixAccess ? { memorixAccess } : {}),
+        endpoint,
+    };
+}
+/**
+ * Build a directed call graph of pipelines that invoke other pipelines via
+ * `target.pipeline` / `run-pipeline` steps. Detects cycles when ids are known.
+ */
+export function detectPipelineCallCycles(pipelines) {
+    const graph = new Map();
+    for (const p of pipelines) {
+        const id = String(p.pipelineId ?? p.id ?? "").trim();
+        if (!id)
+            continue;
+        if (!graph.has(id))
+            graph.set(id, new Set());
+        for (const step of p.steps ?? []) {
+            const rawKind = String(step.stepKind ?? step.kind ?? step.type ?? "");
+            const target = parseStepTarget(step, rawKind);
+            if (target?.kind === "pipeline") {
+                graph.get(id).add(target.pipelineId);
+            }
+            if (rawKind === "run-pipeline" ||
+                rawKind === "pipeline" ||
+                rawKind === "call-pipeline") {
+                const child = String(step.pipelineId ??
+                    asRecord(step.portConfig)?.pipelineId ??
+                    "").trim();
+                if (child)
+                    graph.get(id).add(child);
+            }
+        }
+    }
+    const issues = [];
+    const visiting = new Set();
+    const visited = new Set();
+    const path = [];
+    function dfs(node) {
+        if (visiting.has(node)) {
+            const cycleStart = path.indexOf(node);
+            const cycle = [...path.slice(cycleStart), node].join(" → ");
+            issues.push(`pipeline call cycle: ${cycle}`);
+            return;
+        }
+        if (visited.has(node))
+            return;
+        visiting.add(node);
+        path.push(node);
+        for (const next of graph.get(node) ?? []) {
+            dfs(next);
+        }
+        path.pop();
+        visiting.delete(node);
+        visited.add(node);
+    }
+    for (const id of graph.keys())
+        dfs(id);
+    return issues;
+}
 export function compileAuthoringPipeline(input, opts) {
     const raw = structuredClone(input);
     if (typeof raw.pipelineId !== "string" || !raw.pipelineId.trim()) {
@@ -96,107 +347,177 @@ export function compileAuthoringPipeline(input, opts) {
     }
     const issues = [];
     for (const step of raw.steps ?? []) {
-        const rawKind = String(step.stepKind ?? step.kind ?? step.type ?? "");
+        const stepLabel = String(step.stepId ?? step.id ?? "step");
+        if (typeof step.stepId !== "string" && typeof step.id === "string") {
+            step.stepId = step.id;
+        }
+        let rawKind = String(step.stepKind ?? step.kind ?? step.type ?? "").trim();
+        const target = parseStepTarget(step, rawKind);
+        // invoke-service alias: only when target/service can be resolved.
         if (rawKind === "invoke-service") {
-            issues.push(`step ${String(step.stepId ?? step.id)} uses unsupported invoke-service`);
-            continue;
+            if (!target) {
+                issues.push(`step ${stepLabel} uses unsupported invoke-service without target/serviceId`);
+                continue;
+            }
+            rawKind = "";
         }
-        const canonical = STEP_ALIASES[rawKind] ??
-            (STEP_KINDS.includes(rawKind) ? rawKind : null);
-        if (!canonical) {
-            issues.push(`step ${String(step.stepId ?? step.id)} has unknown stepKind "${rawKind}"`);
-            continue;
+        // Target-driven kind selection.
+        if (target?.kind === "pipeline") {
+            step.stepKind = "run-pipeline";
+            step.portConfig = {
+                ...(step.portConfig ?? {}),
+                pipelineId: target.pipelineId,
+                wait: true,
+            };
+            if (opts?.knownPipelineIds && !opts.knownPipelineIds.has(target.pipelineId)) {
+                issues.push(`step ${stepLabel} references unknown pipeline "${target.pipelineId}"`);
+            }
         }
-        step.stepKind = canonical;
-        if (typeof step.stepId !== "string" && typeof step.id === "string") {
-            step.stepId = step.id;
+        else if (target?.kind === "runx") {
+            step.stepKind = "runx";
+            step.portConfig = {
+                ...(step.portConfig ?? {}),
+                capabilityId: target.capabilityId,
+                invokeProtocol: "runx/1",
+            };
         }
-        if (MUTATING.has(canonical) && typeof step.idempotencyKeyExpr !== "string") {
-            step.idempotencyKeyExpr = `{{runId}}:${String(step.stepId ?? "step")}`;
+        else if (target?.kind === "connector") {
+            step.stepKind = "memory-pull";
+            if (typeof step.sourceId !== "string")
+                step.sourceId = target.sourceId;
+            step.portConfig = {
+                ...(step.portConfig ?? {}),
+                sourceId: target.sourceId,
+                connectorId: target.connectorId,
+                mode: asRecord(step.portConfig)?.mode ?? "knowledge",
+                trigger: asRecord(step.portConfig)?.trigger ??
+                    "on-demand",
+            };
         }
-        const serviceId = typeof step.serviceId === "string" ? step.serviceId.trim() : "";
-        if (serviceId) {
-            const svc = serviceById.get(serviceId);
-            const operation = (typeof svc?.invocation?.operation === "string"
-                ? svc.invocation.operation
-                : undefined) ?? serviceId;
-            const memorixAccess = Array.isArray(svc?.memorixAccess)
-                ? svc.memorixAccess
-                : undefined;
-            const stepAi = step.aiService && typeof step.aiService === "object"
-                ? step.aiService
-                : null;
-            const aiServiceType = String(stepAi?.aiServiceType ??
-                svc?.aiService?.aiServiceType ??
-                svc?.invocation?.aiServiceType ??
-                "").trim();
-            const itemId = String(stepAi?.itemId ?? svc?.aiService?.itemId ?? svc?.invocation?.itemId ?? "").trim();
-            if (aiServiceType && itemId) {
-                const endpointEnv = String(stepAi?.endpointEnv ??
-                    svc?.aiService?.endpointEnv ??
-                    svc?.invocation?.endpointEnv ??
-                    defaultEndpointEnvForType(aiServiceType) ??
-                    "").trim() || undefined;
-                const explicitEndpoint = String(stepAi?.endpoint ?? svc?.aiService?.endpoint ?? "").trim();
-                const endpoint = resolveAiServiceOriginUrl(aiServiceType, {
-                    endpoint: explicitEndpoint || undefined,
-                    endpointEnv,
-                }) ?? "";
-                if (endpoint) {
-                    const existingPc = step.portConfig ?? {};
-                    const existingExec = existingPc.execution && typeof existingPc.execution === "object"
-                        ? existingPc.execution
-                        : {};
-                    const skillExec = aiServiceType === "skill"
-                        ? defaultSkillExecutionForItem(itemId, {
-                            stepId: String(step.stepId ?? step.id ?? ""),
-                        })
-                        : undefined;
+        else if (target?.kind === "ai-service") {
+            step.stepKind = "analyze";
+            const serviceId = String(step.serviceId ?? "").trim() ||
+                `ai:${target.aiServiceType}:${target.itemId}`;
+            step.serviceId = serviceId;
+            const stamped = stampAiPortConfig(step, {
+                serviceId,
+                operation: serviceId,
+                aiServiceType: target.aiServiceType,
+                itemId: target.itemId,
+                endpointEnv: defaultEndpointEnvForType(target.aiServiceType),
+            });
+            if (!stamped) {
+                step.portConfig = {
+                    ...(step.portConfig ?? {}),
+                    serviceId,
+                    aiServiceType: target.aiServiceType,
+                    itemId: target.itemId,
+                    invokeProtocol: "ai-services/1",
+                };
+            }
+        }
+        else if (target?.kind === "service") {
+            const svc = serviceById.get(target.serviceId);
+            const preferred = preferredStepKindFromCapabilities(svc?.capabilities);
+            let canonical = null;
+            if (rawKind && STEP_ALIASES[rawKind]) {
+                canonical = STEP_ALIASES[rawKind];
+            }
+            else if (rawKind && STEP_KINDS.includes(rawKind)) {
+                canonical = rawKind;
+            }
+            else if (!rawKind || rawKind === "invoke-service") {
+                canonical = preferred;
+            }
+            else {
+                // Unknown kind with serviceId → prefer capabilities.
+                canonical = preferred;
+            }
+            // If author picked a non-behavioral kind with a service, keep it only
+            // when it's an existing non-target kind; otherwise use preferred.
+            if (canonical && !BEHAVIORAL.has(canonical) && rawKind && STEP_ALIASES[rawKind]) {
+                // e.g. write-record + serviceId is invalid remote; still allow pass-through kinds.
+            }
+            else if (!canonical || (rawKind === "" && preferred)) {
+                canonical = preferred;
+            }
+            if (!BEHAVIORAL.has(canonical) && target.kind === "service" && (!rawKind || rawKind === "invoke-service")) {
+                canonical = preferred;
+            }
+            step.stepKind = canonical ?? preferred;
+            step.serviceId = target.serviceId;
+            stampServicePortConfig(step, svc, target.serviceId, {
+                workerBaseUrl: opts?.workerBaseUrl,
+            });
+        }
+        else {
+            // Legacy: stepKind only
+            const canonical = STEP_ALIASES[rawKind] ??
+                (STEP_KINDS.includes(rawKind) ? rawKind : null);
+            if (!canonical) {
+                issues.push(`step ${stepLabel} has unknown stepKind "${rawKind}"`);
+                continue;
+            }
+            step.stepKind = canonical;
+            // memory-pull with sourceId only
+            const sourceId = String(step.sourceId ?? "").trim();
+            if (canonical === "memory-pull" && sourceId) {
+                step.portConfig = {
+                    ...(step.portConfig ?? {}),
+                    sourceId,
+                    mode: asRecord(step.portConfig)?.mode ?? "knowledge",
+                    trigger: asRecord(step.portConfig)?.trigger ??
+                        "on-demand",
+                };
+            }
+            // run-pipeline with pipelineId on step
+            if (canonical === "run-pipeline") {
+                const childId = String(step.pipelineId ??
+                    asRecord(step.portConfig)?.pipelineId ??
+                    "").trim();
+                if (childId) {
                     step.portConfig = {
-                        ...existingPc,
-                        serviceId,
-                        operation,
-                        ...(memorixAccess ? { memorixAccess } : {}),
-                        endpoint,
-                        aiServiceType,
-                        itemId,
-                        invokeProtocol: "ai-services/1",
-                        ...(skillExec || Object.keys(existingExec).length
-                            ? {
-                                execution: {
-                                    ...skillExec,
-                                    ...existingExec,
-                                },
-                            }
-                            : {}),
+                        ...(step.portConfig ?? {}),
+                        pipelineId: childId,
+                        wait: true,
                     };
-                    continue;
                 }
-                // No companion URL — fall through to worker invocation (offline / CI).
-            }
-            const endpointEnv = typeof svc?.invocation?.endpointEnv === "string"
-                ? svc.invocation.endpointEnv.trim()
-                : serviceId === "knowx-extract"
-                    ? "KNOWX_EXTRACT_WORKER_URL"
-                    : undefined;
-            const endpoint = resolveKnowxServiceEndpoint(serviceId, {
-                workerBaseUrl: opts?.workerBaseUrl,
-                endpointEnv,
-            });
-            step.portConfig = {
-                ...(step.portConfig ?? {}),
-                serviceId,
-                operation,
-                ...(memorixAccess ? { memorixAccess } : {}),
-                endpoint,
-            };
+            }
+            // runx with capabilityId on step
+            if (canonical === "runx") {
+                const capId = String(step.capabilityId ??
+                    asRecord(step.portConfig)?.capabilityId ??
+                    "").trim();
+                if (capId) {
+                    step.portConfig = {
+                        ...(step.portConfig ?? {}),
+                        capabilityId: capId,
+                        invokeProtocol: "runx/1",
+                    };
+                }
+            }
+            const serviceId = typeof step.serviceId === "string" ? step.serviceId.trim() : "";
+            if (serviceId) {
+                stampServicePortConfig(step, serviceById.get(serviceId), serviceId, { workerBaseUrl: opts?.workerBaseUrl });
+            }
+        }
+        const finalKind = step.stepKind;
+        if (MUTATING.has(finalKind) && typeof step.idempotencyKeyExpr !== "string") {
+            step.idempotencyKeyExpr = `{{runId}}:${String(step.stepId ?? "step")}`;
         }
     }
     if (issues.length) {
         throw new Error(`compilePipeline failed: ${issues.join("; ")}`);
     }
+    // Allow synthetic AI ids and runx through service validation.
+    const known = new Set(opts?.knownServiceIds ?? []);
+    for (const step of raw.steps ?? []) {
+        const sid = String(step.serviceId ?? "").trim();
+        if (sid)
+            known.add(sid);
+    }
     validatePipelineDefinition(raw, {
-        knownServiceIds: opts?.knownServiceIds,
+        knownServiceIds: known,
     });
     return raw;
 }