@x12i/memorix-service 3.0.6 → 3.2.0

package/dist/org-sources.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Helpers for org-scoped runtime sources vs Magit/pack sources.
+ */
+import type { MetadataPack, SourceDefinition } from "@x12i/memorix-metadata";
+/** True for user/org folder sources that must never enter Magit packs. */
+export declare function isOrgRuntimeFolderSource(entry: {
+    id?: string;
+    kind?: string;
+    connectorRef?: string;
+} | null | undefined): boolean;
+/** Strip org folder sources from a metadata pack (Magit / disk install hygiene). */
+export declare function stripOrgRuntimeSourcesFromPack<T extends MetadataPack>(pack: T): T;
+export declare function asSourceDefinition(raw: Record<string, unknown>, sourceId: string): SourceDefinition;
+//# sourceMappingURL=org-sources.d.ts.map

package/dist/org-sources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"org-sources.d.ts","sourceRoot":"","sources":["../src/org-sources.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE7E,0EAA0E;AAC1E,wBAAgB,wBAAwB,CACtC,KAAK,EAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GAC9E,OAAO,CAUT;AAED,oFAAoF;AACpF,wBAAgB,8BAA8B,CAAC,CAAC,SAAS,YAAY,EACnE,IAAI,EAAE,CAAC,GACN,CAAC,CAKH;AAED,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,QAAQ,EAAE,MAAM,GACf,gBAAgB,CAOlB"}

package/dist/org-sources.js

@@ -0,0 +1,31 @@
+/**
+ * Helpers for org-scoped runtime sources vs Magit/pack sources.
+ */
+/** True for user/org folder sources that must never enter Magit packs. */
+export function isOrgRuntimeFolderSource(entry) {
+    if (!entry || typeof entry !== "object")
+        return false;
+    const kind = String(entry.kind ?? "");
+    const connectorRef = String(entry.connectorRef ?? "");
+    const id = String(entry.id ?? "");
+    return (kind === "knowx-folder" ||
+        connectorRef === "knowx-folder" ||
+        /^src_/i.test(id));
+}
+/** Strip org folder sources from a metadata pack (Magit / disk install hygiene). */
+export function stripOrgRuntimeSourcesFromPack(pack) {
+    const sources = Array.isArray(pack.sources) ? pack.sources : [];
+    const kept = sources.filter((s) => !isOrgRuntimeFolderSource(s));
+    if (kept.length === sources.length)
+        return pack;
+    return { ...pack, sources: kept };
+}
+export function asSourceDefinition(raw, sourceId) {
+    return {
+        ...raw,
+        id: String(raw.id ?? sourceId).trim() || sourceId,
+        name: String(raw.name ?? sourceId),
+        kind: String(raw.kind ?? "knowx-folder"),
+    };
+}
+//# sourceMappingURL=org-sources.js.map

package/dist/org-sources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"org-sources.js","sourceRoot":"","sources":["../src/org-sources.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,0EAA0E;AAC1E,MAAM,UAAU,wBAAwB,CACtC,KAA+E;IAE/E,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACtD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IACtC,MAAM,YAAY,GAAG,MAAM,CAAC,KAAK,CAAC,YAAY,IAAI,EAAE,CAAC,CAAC;IACtD,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;IAClC,OAAO,CACL,IAAI,KAAK,cAAc;QACvB,YAAY,KAAK,cAAc;QAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAClB,CAAC;AACJ,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,8BAA8B,CAC5C,IAAO;IAEP,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IAChE,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,wBAAwB,CAAC,CAAC,CAAC,CAAC,CAAC;IACjE,IAAI,IAAI,CAAC,MAAM,KAAK,OAAO,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAChD,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,GAA4B,EAC5B,QAAgB;IAEhB,OAAO;QACL,GAAI,GAAwB;QAC5B,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,IAAI,QAAQ,CAAC,CAAC,IAAI,EAAE,IAAI,QAAQ;QACjD,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI,QAAQ,CAAC;QAClC,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI,cAAc,CAAC;KACzC,CAAC;AACJ,CAAC"}

package/dist/pipeline-compile.d.ts

@@ -1,19 +1,85 @@
 /**
  * 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?: {
+        aiServiceType?: string;
+        itemId?: string;
+        endpointEnv?: string;
+        endpoint?: string;
+    };
     invocation?: {
         operation?: string;
+        /** Env var name holding a per-service worker base URL (e.g. KNOWX_EXTRACT_WORKER_URL). */
+        endpointEnv?: string;
+        /** Alias under invocation for pack authors. */
+        aiServiceType?: string;
+        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.
+ * Default OFF — production / normal local stack always uses the real KnowX worker
+ * for knowx-extract. Set KNOWX_AI_SIM=1 (or true/on/yes) to enable routing.
+ */
+export declare function isKnowxAiSimEnabled(): boolean;
+/**
+ * AI-sim base URL for knowx-extract — only when {@link isKnowxAiSimEnabled}.
+ * Optional override: KNOWX_EXTRACT_WORKER_URL / MEMORIX_KNOWX_EXTRACT_WORKER_URL.
+ */
+export declare function resolveKnowxExtractWorkerUrl(): string | undefined;
+/**
+ * Resolve analyze-step worker endpoint.
+ * knowx-extract → APS AI sim only when KNOWX_AI_SIM=1 (test-only); otherwise
+ * all services use the KnowX control-plane worker.
+ */
+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;AA8BnC,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,UAAU,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACrC,CAAC;AAEF,wBAAgB,yBAAyB,IAAI,MAAM,CAMlD;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,CAuEpB"}
+{"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,7 +1,10 @@
 /**
  * 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";
+import { defaultSkillExecutionForItem } from "./ai-services/skill-execution.js";
 const STEP_ALIASES = {
     "memory-pull": "memory-pull",
     pull: "memory-pull",
@@ -20,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",
@@ -27,12 +34,302 @@ 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() ||
         process.env.MEMORIX_KNOWX_WORKER_URL?.trim() ||
         `http://127.0.0.1:${process.env.KNOWX_PORT?.trim() || "5110"}`).replace(/\/+$/, "");
 }
+/**
+ * Explicit test-only switch for the APS AI Services Simulator.
+ * Default OFF — production / normal local stack always uses the real KnowX worker
+ * for knowx-extract. Set KNOWX_AI_SIM=1 (or true/on/yes) to enable routing.
+ */
+export function isKnowxAiSimEnabled() {
+    const raw = (process.env.KNOWX_AI_SIM?.trim() ||
+        process.env.MEMORIX_KNOWX_AI_SIM?.trim() ||
+        "").toLowerCase();
+    return raw === "1" || raw === "true" || raw === "on" || raw === "yes";
+}
+const KNOWX_AI_SIM_DEFAULT_URL = "http://127.0.0.1:5112";
+/**
+ * AI-sim base URL for knowx-extract — only when {@link isKnowxAiSimEnabled}.
+ * Optional override: KNOWX_EXTRACT_WORKER_URL / MEMORIX_KNOWX_EXTRACT_WORKER_URL.
+ */
+export function resolveKnowxExtractWorkerUrl() {
+    if (!isKnowxAiSimEnabled())
+        return undefined;
+    const fromEnv = process.env.KNOWX_EXTRACT_WORKER_URL?.trim() ||
+        process.env.MEMORIX_KNOWX_EXTRACT_WORKER_URL?.trim();
+    return (fromEnv || KNOWX_AI_SIM_DEFAULT_URL).replace(/\/+$/, "");
+}
+/**
+ * Resolve analyze-step worker endpoint.
+ * knowx-extract → APS AI sim only when KNOWX_AI_SIM=1 (test-only); otherwise
+ * all services use the KnowX control-plane worker.
+ */
+export function resolveKnowxServiceEndpoint(serviceId, opts) {
+    const workerDefault = (opts?.workerBaseUrl ?? resolveKnowxWorkerBaseUrl()).replace(/\/+$/, "");
+    if (serviceId === "knowx-extract") {
+        const extract = resolveKnowxExtractWorkerUrl();
+        if (extract)
+            return extract;
+        return workerDefault;
+    }
+    // Non-extract services: optional per-service URL env (not the AI-sim toggle).
+    if (opts?.endpointEnv && opts.endpointEnv !== "KNOWX_EXTRACT_WORKER_URL") {
+        const named = process.env[opts.endpointEnv]?.trim();
+        if (named)
+            return named.replace(/\/+$/, "");
+    }
+    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()) {
@@ -50,48 +347,177 @@ export function compileAuthoringPipeline(input, opts) {
     }
     const issues = [];
     for (const step of raw.steps ?? []) {
-        const rawKind = String(step.stepKind ?? step.kind ?? step.type ?? "");
-        if (rawKind === "invoke-service") {
-            issues.push(`step ${String(step.stepId ?? step.id)} uses unsupported invoke-service`);
-            continue;
-        }
-        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;
-        }
-        step.stepKind = canonical;
+        const stepLabel = String(step.stepId ?? step.id ?? "step");
         if (typeof step.stepId !== "string" && typeof step.id === "string") {
             step.stepId = step.id;
         }
-        if (MUTATING.has(canonical) && typeof step.idempotencyKeyExpr !== "string") {
-            step.idempotencyKeyExpr = `{{runId}}:${String(step.stepId ?? "step")}`;
+        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") {
+            if (!target) {
+                issues.push(`step ${stepLabel} uses unsupported invoke-service without target/serviceId`);
+                continue;
+            }
+            rawKind = "";
         }
-        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 endpoint = (opts?.workerBaseUrl ?? resolveKnowxWorkerBaseUrl()).replace(/\/+$/, "");
+        // Target-driven kind selection.
+        if (target?.kind === "pipeline") {
+            step.stepKind = "run-pipeline";
             step.portConfig = {
                 ...(step.portConfig ?? {}),
-                serviceId,
-                operation,
-                ...(memorixAccess ? { memorixAccess } : {}),
-                endpoint,
+                pipelineId: target.pipelineId,
+                wait: true,
+            };
+            if (opts?.knownPipelineIds && !opts.knownPipelineIds.has(target.pipelineId)) {
+                issues.push(`step ${stepLabel} references unknown pipeline "${target.pipelineId}"`);
+            }
+        }
+        else if (target?.kind === "runx") {
+            step.stepKind = "runx";
+            step.portConfig = {
+                ...(step.portConfig ?? {}),
+                capabilityId: target.capabilityId,
+                invokeProtocol: "runx/1",
+            };
+        }
+        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",
             };
         }
+        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 = {
+                        ...(step.portConfig ?? {}),
+                        pipelineId: childId,
+                        wait: true,
+                    };
+                }
+            }
+            // 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;
 }